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

clPopulationBase *	GetPopulationObject (std::string sPopName)
	Returns a population object. More...

clPopulationBase *	GetPopulationObject (int iIndex)
	Returns a population object. More...

clGrid *	GetGridObject (const char *cGridName)
	Returns a grid object. More...

clGrid *	GetGridObject (int iIndex)
	Returns a grid object. More...

clBehaviorBase *	GetBehaviorObject (int iIndex)
	Returns a behavior object. More...

clBehaviorBase *	GetBehaviorObject (std::string sBehaviorName)
	Returns a behavior object. More...

clPlot *	GetPlotObject ()
	Returns the plot object. More...

void	RunBatch (std::string sBatchFile)
	Executes a batch run as specified in a batch file. More...

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

clBehaviorManager *	mp_oBehaviorManager
	The behavior object manager. More...

clPopulationManager *	mp_oPopulationManager
	The population object manager. More...

clGridManager *	mp_oGridManager
	The grid object manager. More...

clPlot *	mp_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.

Author: Lora E. Murphy

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

Member Enumeration Documentation

◆ simState

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

Constructor.

Parameters

iMajorVersion	Major model version number.
iMinorVersion	Minor model version number.
sAppPath	Path 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

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

◆ DoSetup()

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.

◆ 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

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.

◆ GetBehaviorObject() [2/2]

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

Returns a behavior object.

Parameters

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

◆ 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

sFileName Path 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_oDoc Pointer 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

cGridName Grid'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

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.

◆ 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

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

◆ GetPopulationObject() [2/2]

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.

◆ 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

sFileName Path 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_oDoc	Pointer to the DOM tree of the parsed file.
iFileType	The 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_oDoc	Pointer to the DOM tree of the parsed file.
iFileType	The 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_oDoc	Pointer to the DOM tree of the parsed file.
iFileType	The type of file that was parsed.

◆ RunBatch()

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

Executes a batch run as specified in a batch file.

Parameters

sBatchFile File 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

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.

◆ 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

iTimestep Current 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:

SimManager.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ simState

Constructor & Destructor Documentation

◆ clSimManager()

◆ ~clSimManager()

Member Function Documentation

◆ CreateGrid()

◆ DoSetup()

◆ EndOfRunCleanup()

◆ GetAppPath()

◆ GetBatchNumber()

◆ GetBehaviorObject() [1/2]

◆ GetBehaviorObject() [2/2]

◆ GetCurrentTimestep()

◆ GetFileType() [1/2]

◆ GetFileType() [2/2]

◆ GetGridObject() [1/2]

◆ GetGridObject() [2/2]

◆ GetMajorVersion()

◆ GetMinorVersion()

◆ GetNumberOfBehaviors()

◆ GetNumberOfGrids()

◆ GetNumberOfPopulations()

◆ GetNumberOfTimesteps()

◆ GetNumberOfYearsPerTimestep()

◆ GetParameterFileRandomSeed()

◆ GetParFilename()

◆ GetPlotObject()

◆ GetPopulationObject() [1/2]

◆ GetPopulationObject() [2/2]

◆ GetRandomSeed()

◆ GetSimState()

◆ GoToNoDataState()

◆ ReadFile()

◆ ReadMapFile()

◆ ReadParameterFile()

◆ ReadTreeFile()

◆ RunBatch()

◆ RunSim()

◆ SetCurrentTimestep()

◆ TimestepCleanup()

Friends And Related Function Documentation

◆ clTestSimManager

Member Data Documentation

◆ m_bUserPaused

◆ m_bUserQuit

◆ m_eSimState

◆ m_iActualSeed

◆ m_iBatchGroup

◆ m_iBatchNumber

◆ m_iCurrentTimestep

◆ m_iMajorVersion

◆ m_iMinorVersion

◆ m_iNumTimesteps

◆ m_iNumYearsPerTimestep

◆ m_iRandomSeed

◆ m_iTargetTimestep

◆ m_sAppPath

◆ m_sBatchFilename

◆ m_sParFilename

◆ mp_oBehaviorManager

◆ mp_oGridManager

◆ mp_oPlot

◆ mp_oPopulationManager

◆ mp_oXMLParser