SORTIE Core C++ Documentation
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
clSimManager Class Reference

SIMULATION MANAGER - Version 1.0. More...

#include <SimManager.h>

Public Types

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

Public Member Functions

 clSimManager (int iMajorVersion, int iMinorVersion, const std::string sAppPath)
 Constructor. More...
 
 ~clSimManager ()
 Destructor. More...
 
std::string GetAppPath ()
 Gets the path of the application. More...
 
int GetBatchNumber ()
 Returns the batch number of the current run. More...
 
std::string GetParFilename ()
 Returns the parameter file path and name. More...
 
int GetMajorVersion ()
 Returns the model major version number. More...
 
int GetMinorVersion ()
 Returns the model minor version number. More...
 
int GetNumberOfYearsPerTimestep ()
 Returns the number of years per timestep. More...
 
int GetParameterFileRandomSeed ()
 Returns the random seed as read in from the parameter file. More...
 
long * GetRandomSeed ()
 Returns the actual random seed, which is what should be used as the seed for the random number generator. More...
 
int GetNumberOfTimesteps ()
 Returns the number of timesteps specified in the parameter file. More...
 
int GetCurrentTimestep ()
 Returns the current timestep being executed. More...
 
void SetCurrentTimestep (int iTimestep)
 Sets the current timestep. More...
 
int GetSimState ()
 Returns the current state of the Simulation Manager. More...
 
int GetNumberOfBehaviors ()
 Returns the number of behavior objects for this run. More...
 
int GetNumberOfGrids ()
 Returns the number of grid objects for this run. More...
 
int GetNumberOfPopulations ()
 Returns the number of population objects for this run. More...
 
void ReadFile (std::string sFileName)
 Attempts to open and read a file's contents into SORTIE. More...
 
fileType GetFileType (std::string sFileName)
 Attempts to determine what kind of file a file is. More...
 
fileType GetFileType (xercesc::DOMDocument *p_oDoc)
 Attempts to determine what kind of file produced a particular parsed DOM tree. More...
 
unsigned long RunSim (int iNumStepsToRun=0)
 Runs the simulation. More...
 
clPopulationBaseGetPopulationObject (std::string sPopName)
 Returns a population object. More...
 
clPopulationBaseGetPopulationObject (int iIndex)
 Returns a population object. More...
 
clGridGetGridObject (const char *cGridName)
 Returns a grid object. More...
 
clGridGetGridObject (int iIndex)
 Returns a grid object. More...
 
clBehaviorBaseGetBehaviorObject (int iIndex)
 Returns a behavior object. More...
 
clBehaviorBaseGetBehaviorObject (std::string sBehaviorName)
 Returns a behavior object. More...
 
clPlotGetPlotObject ()
 Returns the plot object. More...
 
void RunBatch (std::string sBatchFile)
 Executes a batch run as specified in a batch file. More...
 
clGridCreateGrid (std::string sGridName, short int iNumIntVals, short int iNumFloatVals, short int iNumCharVals, short int iNumBoolVals, float fXCellLength=0, float fYCellLength=0)
 Creates a new grid object. More...
 

Protected Member Functions

void TimestepCleanup ()
 Triggers the timestep cleanup functions of each of the object managers. More...
 
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. More...
 
void ReadParameterFile (xercesc::DOMDocument *p_oDoc, fileType iFileType)
 Reads a parsed parameter file. More...
 
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. More...
 
void ReadMapFile (xercesc::DOMDocument *p_oDoc, fileType iFileType)
 Inputs a parsed map file. More...
 
void DoSetup (xercesc::DOMDocument *p_oDoc)
 Reads in the simulation manager's needed values from the parameter file. More...
 
void GoToNoDataState ()
 Performs the transition to the No_Data state from any other state. More...
 

Protected Attributes

std::string m_sAppPath
 Path to this application. More...
 
long m_iActualSeed
 The actual random seed that was used. More...
 
int m_iNumYearsPerTimestep
 Number of years per timestep. More...
 
int m_iMajorVersion
 Model's major version number. More...
 
int m_iMinorVersion
 Model's minor version number. More...
 
int m_iRandomSeed
 Seed for the random number generator. More...
 
int m_iNumTimesteps
 Number of timesteps for the run. More...
 
int m_iCurrentTimestep
 Timestep that the model is currently on. More...
 
int m_iTargetTimestep
 If the model was paused this holds the original target timestep so it can resume. More...
 
int m_iBatchGroup
 If this is a batch run, this is the ith parameter file group of the current batch file. More...
 
int m_iBatchNumber
 If this is a batch run, this is the ith run of the current parameter file. More...
 
clBehaviorManagermp_oBehaviorManager
 The behavior object manager. More...
 
clPopulationManagermp_oPopulationManager
 The population object manager. More...
 
clGridManagermp_oGridManager
 The grid object manager. More...
 
clPlotmp_oPlot
 The plot object. More...
 
std::string m_sParFilename
 File path and name of the parameter file. More...
 
std::string m_sBatchFilename
 File path and name of the parameter file, if using. More...
 
bool m_bUserQuit
 Flag for if a user is quitting the app. More...
 
bool m_bUserPaused
 Flag for if a user has paused the app. More...
 
xercesc::XercesDOMParser * mp_oXMLParser
 Xerces file parser. More...
 
enum simState m_eSimState
 Current state of the Simulation Manager. More...
 

Friends

class clTestSimManager
 For automated testing. 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.

Copyright 2011 Charles D. Canham.

Author
Lora E. Murphy


Edit history:
--------------—
October 20, 2011 - Wiped the slate clean for SORTIE 7.0 (LEM)

Member Enumeration Documentation

◆ 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::clSimManager ( int  iMajorVersion,
int  iMinorVersion,
const std::string  sAppPath 
)

Constructor.

Parameters
iMajorVersionMajor model version number.
iMinorVersionMinor model version number.
sAppPathPath of the application

◆ ~clSimManager()

clSimManager::~clSimManager ( )

Destructor.

Member Function Documentation

◆ CreateGrid()

clGrid* clSimManager::CreateGrid ( std::string  sGridName,
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
sGridNameThe new grid's namestring.
iNumIntValsNumber of integer data members in a grid cell record. Can be 0.
iNumFloatValsNumber of float data members in a grid cell record. Can be 0.
iNumCharValsNumber of char data members in a grid cell record. Can be 0.
iNumBoolValsNumber of bool data members in a grid cell record. Can be 0.
fXCellLengthThe length of a grid cell in the X direction, in meters. Not required. If ommitted this will default to the plot's cell length.
fYCellLengthThe 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.

◆ DoSetup()

void clSimManager::DoSetup ( xercesc::DOMDocument *  p_oDoc)
protected

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

Parameters
p_oDocPointer to the DOM tree of the parsed file.

◆ EndOfRunCleanup()

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.

◆ GetAppPath()

std::string clSimManager::GetAppPath ( )
inline

Gets the path of the application.

Returns
Path to the application.

◆ GetBatchNumber()

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.

◆ GetBehaviorObject() [1/2]

clBehaviorBase* clSimManager::GetBehaviorObject ( int  iIndex)

Returns a behavior object.

Parameters
iIndexBehavior'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.

◆ GetBehaviorObject() [2/2]

clBehaviorBase* clSimManager::GetBehaviorObject ( std::string  sBehaviorName)

Returns a behavior object.

Parameters
sBehaviorNameBehavior'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.

◆ GetCurrentTimestep()

int clSimManager::GetCurrentTimestep ( )
inline

Returns the current timestep being executed.

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

◆ GetFileType() [1/2]

fileType clSimManager::GetFileType ( std::string  sFileName)

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
sFileNamePath and name of file to read.
Returns
A fileType enum value.

◆ GetFileType() [2/2]

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_oDocPointer to the DOM tree of the parsed file.
Returns
A fileType enum value.

◆ GetGridObject() [1/2]

clGrid* clSimManager::GetGridObject ( const char *  cGridName)

Returns a grid object.

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

◆ GetGridObject() [2/2]

clGrid* clSimManager::GetGridObject ( int  iIndex)

Returns a grid object.

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

◆ GetMajorVersion()

int clSimManager::GetMajorVersion ( )
inline

Returns the model major version number.

Returns
Model major version number.

◆ GetMinorVersion()

int clSimManager::GetMinorVersion ( )
inline

Returns the model minor version number.

Returns
Model minor version number.

◆ GetNumberOfBehaviors()

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.

◆ GetNumberOfGrids()

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.

◆ GetNumberOfPopulations()

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.

◆ GetNumberOfTimesteps()

int clSimManager::GetNumberOfTimesteps ( )
inline

Returns the number of timesteps specified in the parameter file.

Returns
Number of timesteps for the run.

◆ GetNumberOfYearsPerTimestep()

int clSimManager::GetNumberOfYearsPerTimestep ( )
inline

Returns the number of years per timestep.

Returns
Number of years per timestep. Could be fractional.

◆ GetParameterFileRandomSeed()

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.

◆ GetParFilename()

std::string clSimManager::GetParFilename ( )
inline

Returns the parameter file path and name.

Returns
Parameter file path and name.

◆ GetPlotObject()

clPlot* clSimManager::GetPlotObject ( )
inline

Returns the plot object.

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

◆ GetPopulationObject() [1/2]

clPopulationBase* clSimManager::GetPopulationObject ( std::string  sPopName)

Returns a population object.

Parameters
sPopNamePopulation'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.

◆ GetPopulationObject() [2/2]

clPopulationBase* clSimManager::GetPopulationObject ( int  iIndex)

Returns a population object.

Parameters
iIndexPopulation'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.

◆ GetRandomSeed()

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.

◆ GetSimState()

int clSimManager::GetSimState ( )
inline

Returns the current state of the Simulation Manager.

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

◆ GoToNoDataState()

void clSimManager::GoToNoDataState ( )
protected

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

◆ ReadFile()

void clSimManager::ReadFile ( std::string  sFileName)

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
sFileNamePath and name of file to read.

◆ ReadMapFile()

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_oDocPointer to the DOM tree of the parsed file.
iFileTypeThe type of file that was parsed.

◆ ReadParameterFile()

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_oDocPointer to the DOM tree of the parsed file.
iFileTypeThe type of file that was parsed.

◆ ReadTreeFile()

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_oDocPointer to the DOM tree of the parsed file.
iFileTypeThe type of file that was parsed.

◆ RunBatch()

void clSimManager::RunBatch ( std::string  sBatchFile)

Executes a batch run as specified in a batch file.

Parameters
sBatchFileFile path and name to the batch file to execute.

◆ RunSim()

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

◆ SetCurrentTimestep()

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
iTimestepCurrent timestep to set.

◆ TimestepCleanup()

void clSimManager::TimestepCleanup ( )
protected

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

Friends And Related Function Documentation

◆ clTestSimManager

friend class clTestSimManager
friend

For automated testing.

Member Data Documentation

◆ m_bUserPaused

bool clSimManager::m_bUserPaused
protected

Flag for if a user has paused the app.

◆ m_bUserQuit

bool clSimManager::m_bUserQuit
protected

Flag for if a user is quitting the app.

◆ m_eSimState

enum simState clSimManager::m_eSimState
protected

Current state of the Simulation Manager.

◆ m_iActualSeed

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.

◆ m_iBatchGroup

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.

◆ m_iBatchNumber

int clSimManager::m_iBatchNumber
protected

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

If not in batch mode, this is 0.

◆ m_iCurrentTimestep

int clSimManager::m_iCurrentTimestep
protected

Timestep that the model is currently on.

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

◆ m_iMajorVersion

int clSimManager::m_iMajorVersion
protected

Model's major version number.

For version control.

◆ m_iMinorVersion

int clSimManager::m_iMinorVersion
protected

Model's minor version number.

For version control.

◆ m_iNumTimesteps

int clSimManager::m_iNumTimesteps
protected

Number of timesteps for the run.

◆ m_iNumYearsPerTimestep

int clSimManager::m_iNumYearsPerTimestep
protected

Number of years per timestep.

◆ m_iRandomSeed

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.

◆ m_iTargetTimestep

int clSimManager::m_iTargetTimestep
protected

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

◆ m_sAppPath

std::string clSimManager::m_sAppPath
protected

Path to this application.

Not a const because we have to set this at runtime

◆ m_sBatchFilename

std::string clSimManager::m_sBatchFilename
protected

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

◆ m_sParFilename

std::string clSimManager::m_sParFilename
protected

File path and name of the parameter file.

◆ mp_oBehaviorManager

clBehaviorManager* clSimManager::mp_oBehaviorManager
protected

The behavior object manager.

◆ mp_oGridManager

clGridManager* clSimManager::mp_oGridManager
protected

The grid object manager.

◆ mp_oPlot

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.

◆ mp_oPopulationManager

clPopulationManager* clSimManager::mp_oPopulationManager
protected

The population object manager.

◆ mp_oXMLParser

xercesc::XercesDOMParser* clSimManager::mp_oXMLParser
protected

Xerces file parser.


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