clSimManager Class Reference

SIMULATION MANAGER - Version 1.0. More...

#include <SimManager.h>

List of all members.

Public Types

enum  simState { No_Data, Initialized, Paused, Run_Complete }
 Enum for simulation states. More...

Public Member Functions

 clSimManager (int iMajorVersion, int iMinorVersion, char *cAppPath)
 Constructor.
 ~clSimManager ()
 Destructor.
char * GetAppPath ()
 Gets the path of the application.
int GetObjectVersion ()
 Returns the version number of the clSimManager class.
char * GetParFilename ()
 Returns the parameter file path and name.
int GetMajorVersion ()
 Returns the model major version number.
int GetMinorVersion ()
 Returns the model minor version number.
float GetNumberOfYearsPerTimestep ()
 Returns the number of years per timestep.
int GetParameterFileRandomSeed ()
 Returns the random seed as read in from the parameter file.
long * GetRandomSeed ()
 Returns the actual random seed, which is what should be used as the seed for the random number generator.
int GetNumberOfTimesteps ()
 Returns the number of timesteps specified in the parameter file.
int GetCurrentTimestep ()
 Returns the current timestep being executed.
void SetCurrentTimestep (int iTimestep)
 Sets the current timestep.
int GetSimState ()
 Returns the current state of the Simulation Manager.
int GetNumberOfBehaviors ()
 Returns the number of behavior objects for this run.
int GetNumberOfGrids ()
 Returns the number of grid objects for this run.
int GetNumberOfPopulations ()
 Returns the number of population objects for this run.
void ReadFile (char *cFileName)
 Attempts to open and read a file's contents into SORTIE.
fileType GetFileType (char *cFileName)
 Attempts to determine what kind of file a file is.
fileType GetFileType (xercesc::DOMDocument *p_oDoc)
 Attempts to determine what kind of file produced a particular parsed DOM tree.
unsigned long RunSim (int iNumStepsToRun=0)
 Runs the simulation.
clPopulationBaseGetPopulationObject (char *cPopName)
 Returns a population object.
clPopulationBaseGetPopulationObject (int iIndex)
 Returns a population object.
clGridBaseGetGridObject (char *cGridName)
 Returns a grid object.
clGridBaseGetGridObject (int iIndex)
 Returns a grid object.
clBehaviorBaseGetBehaviorObject (int iIndex)
 Returns a behavior object.
clBehaviorBaseGetBehaviorObject (char *cBehaviorName)
 Returns a behavior object.
clPlotGetPlotObject ()
 Returns the plot object.
bool DoCommand (char *cCommand, char *cArguments)
 Accepts a command on behalf of an object.
void RegisterCommand (char *cCommand, clWorkerBase *p_oObject)
 Registers a command with the Simulation Manager.
void RunBatch (char *cBatchFile)
 Executes a batch run as specified in a batch file.
clGridBaseCreateGrid (char *cGridName, short int iNumIntVals, short int iNumFloatVals, short int iNumCharVals, short int iNumBoolVals, float fXCellLength=0, float fYCellLength=0)
 Creates a new grid object.

Protected Member Functions

void TimestepCleanup ()
 Triggers the timestep cleanup functions of each of the object managers.
void EndOfRunCleanup ()
 Performs any cleanup necessary at the end of a run and triggers the end-of-run cleanup functions of each of the object managers.
void ReadParameterFile (xercesc::DOMDocument *p_oDoc, fileType iFileType)
 Reads a parsed parameter file.
void ReadTreeFile (xercesc::DOMDocument *p_oDoc, fileType iFileType)
 Passes a parsed tree file off to the tree population object to read it as it will.
void ReadMapFile (xercesc::DOMDocument *p_oDoc, fileType iFileType)
 Inputs a parsed map file.
void DoSetup (xercesc::DOMDocument *p_oDoc)
 Reads in the simulation manager's needed values from the parameter file.
void GoToNoDataState ()
 Performs the transition to the No_Data state from any other state.

Protected Attributes

char m_cAppPath [MAX_FILENAME_SIZE]
 Path to this application, terminated by path separator.
long m_iActualSeed
 The actual random seed that was used.
float m_fNumYearsPerTimestep
 Number of years per timestep - could be fractional or less than 1.
int m_iMajorVersion
 Model's major version number.
int m_iMinorVersion
 Model's minor version number.
int m_iRandomSeed
 Seed for the random number generator.
int m_iNumTimesteps
 Number of timesteps for the run.
int m_iCurrentTimestep
 Timestep that the model is currently on.
int m_iTargetTimestep
 If the model was paused this holds the original target timestep so it can resume.
clBehaviorManagermp_oBehaviorManager
 The behavior object manager.
clPopulationManagermp_oPopulationManager
 The population object manager.
clGridManagermp_oGridManager
 The grid object manager.
clPlotmp_oPlot
 The plot object.
char m_cParFilename [MAX_FILENAME_SIZE]
 File path and name of the parameter file.
clSimManager::stcCommandListmp_commands
 Holds command information.List of commands registered by objects.
short int m_iNumCommands
 Number of commands registered by objects.
bool m_bUserQuit
 Flag for if a user is quitting the app.
xercesc::DOMBuilder * mp_oXMLParser
 Xerces file parser.
clXercesErrorHandlermp_oXMLErrorHandler
 Custom error handler for Xerces file parser.
enum simState m_eSimState
 Current state of the Simulation Manager.

Friends

class TestSimManager
 For automated testing.

Classes

struct  stcCommandList
 Holds command information. More...


Detailed Description

SIMULATION MANAGER - Version 1.0.

The Simulation Manager is responsible for managing the run process. It accepts input files and causes them to be entered. It also triggers a run.

Objects within the run access each other through the Simulation Manager. An object may have direct access to no other object, but they always have access to the Simulation Manager and from there can get to (almost) any other object.

The Sim Manager has four states: No_Data, Initialized, Paused, and Run_Complete. These are described in more detail below. The state in which the Sim Manager is in controls what actions are allowed and how actions are performed (for instance, starting a run is not allowed in the No_Data state).

The Simulation Manager takes care of all XML input file parsing. DTDs do exist but parsed files are not validated - they are merely checked for well- formedness. This is because I can't get Xerces' validation to work with a DTD I specify - something that should be possible but has a bug in the current version of the libraries. This should be fixed at some point.

Todo:
Validate input XML files against DTDs.
The simulation manager can also accept commands on behalf of behaviors and populations under its control. This allows for user interaction directly with these objects not in the context of a run (for instance, for producing a GLI map). Currently, there are no commands registered nor tested and this feature may not work right off the bat - but there is at least nominal support for it.

Copyright 2003 Charles D. Canham.

Author:
Lora E. Murphy

Edit history:
-----------------
April 28, 2004 - Submitted as beta (LEM)
February 20, 2005 - Added model math object (LEM)


Member Enumeration Documentation

enum clSimManager::simState
 

Enum for simulation states.

Enumerator:
No_Data  Object managers are created but have no objects - system is ready to receive data.
Initialized  Sufficient input data has been received - a run is possible.
Paused  There is an unfinished run in process.
Run_Complete  A run is complete.


Constructor & Destructor Documentation

clSimManager::clSimManager int  iMajorVersion,
int  iMinorVersion,
char *  cAppPath
 

Constructor.

Parameters:
iMajorVersion Major model version number.
iMinorVersion Minor model version number.
cAppPath Path of the application, sized a max of MAX_FILENAME_SIZE and ending with the path separator.


Member Function Documentation

clGridBase* clSimManager::CreateGrid char *  cGridName,
short int  iNumIntVals,
short int  iNumFloatVals,
short int  iNumCharVals,
short int  iNumBoolVals,
float  fXCellLength = 0,
float  fYCellLength = 0
 

Creates a new grid object.

This function merely passes along the request to the grid manager.

Note that a grid may have already been created in a grid map in a parameter file by the time a behavior is ready to set up. This function would overwrite any existing grids, so if a behavior is able to take advantage of grid map values, it should check for the existence of the grid before creating a new one.

Parameters:
cGridName The new grid's namestring.
iNumIntVals Number of integer data members in a grid cell record. Can be 0.
iNumFloatVals Number of float data members in a grid cell record. Can be 0.
iNumCharVals Number of char data members in a grid cell record. Can be 0.
iNumBoolVals Number of bool data members in a grid cell record. Can be 0.
fXCellLength The length of a grid cell in the X direction, in meters. Not required. If ommitted this will default to the plot's cell length.
fYCellLength The length of a grid cell in the Y direction, in meters. Not required. If this is ommitted (i.e. = 0), it is assumed the grid cells are square and the value for the X length is used.
Returns:
A pointer to the new grid object.

bool clSimManager::DoCommand char *  cCommand,
char *  cArguments
 

Accepts a command on behalf of an object.

If the command is recognized as one which has been registered by an object, the command is passed to that object for execution. If the command is unrecognized, nothing happens.

Any expected errors caught will not cause the model state to reset. Unexpected errors will cause reset.

Parameters:
cCommand Command name.
cArguments Any arguments to the command.
Returns:
True if the command was recognized and performed, or false if the command was unrecognized.

void clSimManager::DoSetup xercesc::DOMDocument *  p_oDoc  )  [protected]
 

Reads in the simulation manager's needed values from the parameter file.

Parameters:
p_oDoc Pointer to the DOM tree of the parsed file.

char* clSimManager::GetAppPath  )  [inline]
 

Gets the path of the application.

Returns:
Path to the application, sized MAX_FILENAME_SIZE and ending with the path separator.

clBehaviorBase* clSimManager::GetBehaviorObject char *  cBehaviorName  ) 
 

Returns a behavior object.

Parameters:
cBehaviorName Behavior's namestring.
Returns:
The behavior object, or NULL if there is no such index. For most purposes, it will be necessary to cast the pointer to the particular behavior class desired.

clBehaviorBase* clSimManager::GetBehaviorObject int  iIndex  ) 
 

Returns a behavior object.

Parameters:
iIndex Behavior's zero-based index number in the behavior manager's object array.
Returns:
The behavior object, or NULL if there is no such index. For most purposes, it will be necessary to cast the pointer to the particular behavior class desired.

int clSimManager::GetCurrentTimestep  )  [inline]
 

Returns the current timestep being executed.

Returns:
Current timestep, or 0 if a run is not underway.

fileType clSimManager::GetFileType xercesc::DOMDocument *  p_oDoc  ) 
 

Attempts to determine what kind of file produced a particular parsed DOM tree.

This doesn't dig too deeply; if the file code indicates a recognized file type, this function believes them. If the file code is absent, the filetype returned is notrecognized.

The XML file code is an 8-character string divided into four sets of two characters. The first set of two characters is the model major version; the second set of two characters is the minor versions; the third set of two characters is the file type; and the fourth set is the file version.

Parameters:
p_oDoc Pointer to the DOM tree of the parsed file.
Returns:
A fileType enum value.

fileType clSimManager::GetFileType char *  cFileName  ) 
 

Attempts to determine what kind of file a file is.

This doesn't dig too deeply; if the file extension and file code indicate a particular file type, this function believes them. This function can recognize old SORTIE file extensions and XML files. If a file is XML, this function looks for a filecode, which all SORTIE XML files should have.

The XML file code is an 8-character string divided into four sets of two characters. The first set of two characters is the model major version; the second set of two characters is the minor versions; the third set of two characters is the file type; and the fourth set is the file version.

Parameters:
cFileName Path and name of file to read.
Returns:
A fileType enum value.

clGridBase* clSimManager::GetGridObject int  iIndex  ) 
 

Returns a grid object.

Parameters:
iIndex Grid's zero-based index number in the grid manager's object array.
Returns:
The grid object, or NULL if there is no such object.

clGridBase* clSimManager::GetGridObject char *  cGridName  ) 
 

Returns a grid object.

Parameters:
cGridName Grid's namestring.
Returns:
The grid object, or NULL if there is no such object.

int clSimManager::GetMajorVersion  )  [inline]
 

Returns the model major version number.

Returns:
Model major version number.

int clSimManager::GetMinorVersion  )  [inline]
 

Returns the model minor version number.

Returns:
Model minor version number.

int clSimManager::GetNumberOfBehaviors  ) 
 

Returns the number of behavior objects for this run.

Returns:
Number of behavior objects for the currently defined run, or 0 if a run is not currently defined.

int clSimManager::GetNumberOfGrids  ) 
 

Returns the number of grid objects for this run.

Returns:
Number of grid objects for the currently defined run, or 0 if a run is not currently defined.

int clSimManager::GetNumberOfPopulations  ) 
 

Returns the number of population objects for this run.

Returns:
Number of population objects for the currently defined run, or 0 if a run is not currently defined.

int clSimManager::GetNumberOfTimesteps  )  [inline]
 

Returns the number of timesteps specified in the parameter file.

Returns:
Number of timesteps for the run.

float clSimManager::GetNumberOfYearsPerTimestep  )  [inline]
 

Returns the number of years per timestep.

Returns:
Number of years per timestep. Could be fractional.

int clSimManager::GetObjectVersion  )  [inline]
 

Returns the version number of the clSimManager class.

Returns:
clSimManager class version number.

int clSimManager::GetParameterFileRandomSeed  )  [inline]
 

Returns the random seed as read in from the parameter file.

DON'T USE THIS AS INPUT TO THE RANDOM NUMBER GENERATOR!

Returns:
Parameter file random seed.

char* clSimManager::GetParFilename  )  [inline]
 

Returns the parameter file path and name.

Returns:
Parameter file path and name.

clPlot* clSimManager::GetPlotObject  )  [inline]
 

Returns the plot object.

Returns:
The plot object, or NULL if it has not been created.

clPopulationBase* clSimManager::GetPopulationObject int  iIndex  ) 
 

Returns a population object.

Parameters:
iIndex Population's zero-based index number in the population manager's object array.
Returns:
The population object, or NULL if there is no such index. For most purposes, it will be necessary to cast the pointer to the particular population class desired.

clPopulationBase* clSimManager::GetPopulationObject char *  cPopName  ) 
 

Returns a population object.

Parameters:
cPopName Population's namestring.
Returns:
The population object, or NULL if there is no such object. For most purposes, it will be necessary to cast the pointer to the particular population class desired.

long* clSimManager::GetRandomSeed  )  [inline]
 

Returns the actual random seed, which is what should be used as the seed for the random number generator.

Returns:
Actual random seed.

int clSimManager::GetSimState  )  [inline]
 

Returns the current state of the Simulation Manager.

Returns:
State of the Simulation Manager, as a simState enum value.

void clSimManager::ReadFile char *  cFileName  ) 
 

Attempts to open and read a file's contents into SORTIE.

The file type code that is expected in all SORTIE XML files is checked to seee what type of file this is, and to decide what to do with it. If the file is a non-SORTIE file, the state of the sim manager is not changed. If the file is a SORTIE file and there is a problem reading the file, any damage caused by attempting to read is cleaned up and the state of the sim manager is set to "Intialized." If damage could not be cleaned up the state is set to "Not_Initialized" and the only thing to do will be to start over with a new file.

On catching an error, this function does not automatically reset the model state. Some files which are read may produce non-fatal errors from which the system can recover. If functions called by this function can trap and handle these errors, fine. An error which is not handled by the time it reaches this function gets passed further up the chain and will probably call a reset of the model state to No_Data.

Parameters:
cFileName Path and name of file to read.

void clSimManager::ReadMapFile xercesc::DOMDocument *  p_oDoc,
fileType  iFileType
[protected]
 

Inputs a parsed map file.

It passes off the document object to the grid manager to find a grid to read it.

Any expected errors caught will not cause the model state to reset. Unexpected errors will cause reset.

Parameters:
p_oDoc Pointer to the DOM tree of the parsed file.
iFileType The type of file that was parsed.

void clSimManager::ReadParameterFile xercesc::DOMDocument *  p_oDoc,
fileType  iFileType
[protected]
 

Reads a parsed parameter file.

After the simulation manager is done, the file is passed off to the object managers to give to the objects under their management.

This does not error-trap robustly; it assumes that in the parsing process the document is established to be well-formed and valid. This, of course, is a fallacy; the documents are not currently validated against a DTD but should be. I'm counting on the fact that is unlikely that an invalid file will get past the objects without triggering some sort of recoverable error.

If there is an error during the parameter file reading process, all objects are destroyed.

Parameters:
p_oDoc Pointer to the DOM tree of the parsed file.
iFileType The type of file that was parsed.

void clSimManager::ReadTreeFile xercesc::DOMDocument *  p_oDoc,
fileType  iFileType
[protected]
 

Passes a parsed tree file off to the tree population object to read it as it will.

Any expected errors caught will not cause the model state to reset. Unexpected errors will cause reset.

Parameters:
p_oDoc Pointer to the DOM tree of the parsed file.
iFileType The type of file that was parsed.

void clSimManager::RegisterCommand char *  cCommand,
clWorkerBase p_oObject
 

Registers a command with the Simulation Manager.

An object uses which wishes to be able to perform an action initiated by the user and not in the context of a run uses this function to notify the Simulation Manager of this.

A duplicate command will overwrite an existing one.

Currently this functionality has not been used, or adequately tested.

Parameters:
cCommand The command string.
p_oObject A pointer to the object that will execute this command.

void clSimManager::RunBatch char *  cBatchFile  ) 
 

Executes a batch run as specified in a batch file.

Parameters:
cBatchFile File path and name to the batch file to execute.

unsigned long clSimManager::RunSim int  iNumStepsToRun = 0  ) 
 

Runs the simulation.

If the Simulation Manager state is Initialized or Paused, the run goes forward from the current point. If the state is Run_Complete, the run is reset and run from the beginning. If the state is No_Data, an error is thrown.

Parameters:
iNumStepsToRun Number of timesteps to run (optional). A value of 0 runs the model to the end. A value greater than the number of timesteps left just runs the model to the end.
Returns:
The length of the run, in seconds.

void clSimManager::SetCurrentTimestep int  iTimestep  )  [inline]
 

Sets the current timestep.

This is mostly for my convenience, for testing purposes. Mess with this at your peril.

Parameters:
iTimestep Current timestep to set.


Member Data Documentation

char clSimManager::m_cAppPath[MAX_FILENAME_SIZE] [protected]
 

Path to this application, terminated by path separator.

Not a const because we have to set this at runtime

long clSimManager::m_iActualSeed [protected]
 

The actual random seed that was used.

This is only needed in case random seed in the parameter file is zero - this allows capture for re-creation if needed.

int clSimManager::m_iCurrentTimestep [protected]
 

Timestep that the model is currently on.

If the model is paused this is the timestep just finished.

int clSimManager::m_iMajorVersion [protected]
 

Model's major version number.

For version control.

int clSimManager::m_iMinorVersion [protected]
 

Model's minor version number.

For version contro.

int clSimManager::m_iRandomSeed [protected]
 

Seed for the random number generator.

This is read from the parameter file. It must be negative; if entered as a positive, it's negativized. If it's 0, a negative integer is chosen.

struct clSimManager::stcCommandList * clSimManager::mp_commands [protected]
 

Holds command information.List of commands registered by objects.

This is currently not used by anyone. It's either going to become an interesting feature or end up deprecated.

clPlot* clSimManager::mp_oPlot [protected]
 

The plot object.

This does not have its own object manager - it remains in the purview of the simulation manager.


The documentation for this class was generated from the following file:
Generated on Mon Mar 27 12:51:21 2006 for SORTIE Core C++ Documentation by  doxygen 1.4.6-NO