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 GetBatchNumber ()
 Returns the batch number of the current run.
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.
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.
int m_iBatchGroup
 If this is a batch run, this is the ith parameter file group of the current batch file.
int m_iBatchNumber
 If this is a batch run, this is the ith run of the current parameter file.
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.
char m_cBatchFilename [MAX_FILENAME_SIZE]
 File path and name of the parameter file, if using.
bool m_bUserQuit
 Flag for if a user is quitting the app.
bool m_bUserPaused
 Flag for if a user has paused 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.


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.
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 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.

clSimManager::~clSimManager (  ) 

Destructor.


Member Function Documentation

void clSimManager::TimestepCleanup (  )  [protected]

Triggers the timestep cleanup functions of each of the object managers.

void clSimManager::EndOfRunCleanup (  )  [protected]

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 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::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::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.

void clSimManager::GoToNoDataState (  )  [protected]

Performs the transition to the No_Data state from any other state.

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.

int clSimManager::GetBatchNumber (  )  [inline]

Returns the batch number of the current run.

Returns:
Batch number for the current parameter file, or 0 if not in a batch run.

char* clSimManager::GetParFilename (  )  [inline]

Returns the parameter file path and name.

Returns:
Parameter file path and name.

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.

float clSimManager::GetNumberOfYearsPerTimestep (  )  [inline]

Returns the number of years per timestep.

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

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.

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::GetNumberOfTimesteps (  )  [inline]

Returns the number of timesteps specified in the parameter file.

Returns:
Number of timesteps for the run.

int clSimManager::GetCurrentTimestep (  )  [inline]

Returns the current timestep being executed.

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

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.

int clSimManager::GetSimState (  )  [inline]

Returns the current state of the Simulation Manager.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

clPlot* clSimManager::GetPlotObject (  )  [inline]

Returns the plot object.

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

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.

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.


Friends And Related Function Documentation

friend class TestSimManager [friend]

For automated testing.


Member Data Documentation

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.

Number of years per timestep - could be fractional or less than 1.

Model's major version number.

For version control.

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.

Number of timesteps for the run.

Timestep that the model is currently on.

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

If the model was paused this holds the original target timestep so it can resume.

int clSimManager::m_iBatchGroup [protected]

If this is a batch run, this is the ith parameter file group of the current batch file.

If not in batch mode, this is 0.

If this is a batch run, this is the ith run of the current parameter file.

If not in batch mode, this is 0.

The behavior object manager.

The population object manager.

The grid object manager.

The plot object.

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

File path and name of the parameter file.

File path and name of the parameter file, if using.

bool clSimManager::m_bUserQuit [protected]

Flag for if a user is quitting the app.

bool clSimManager::m_bUserPaused [protected]

Flag for if a user has paused the app.

xercesc::DOMBuilder* clSimManager::mp_oXMLParser [protected]

Xerces file parser.

Custom error handler for Xerces file parser.

Current state of the Simulation Manager.


The documentation for this class was generated from the following file:

Generated on Tue Apr 19 13:56:16 2011 for SORTIE Core C++ Documentation by  doxygen 1.5.6