An entry in the simulator database. More...

#include <SimulatorDBEntry.h>

Inheritance diagram for Menge::SimulatorDBEntry:

Public Member Functions
virtual ::std::string	briefDescription () const =0
	Gives a brief description of the simulator. More...

virtual ::std::string	longDescription () const =0
	Gives a long description of the simulator. More...

virtual ::std::string	viewerName () const =0
	Gives a label to apply to the interactive viewer. More...

virtual ::std::string	commandLineName () const =0
	Gives a unique name to be used as a command-line parameter. More...

virtual Agents::SimulatorInterface *	getNewSimulator ()=0
	Returns a pointer to this model's Simulator instance. More...

SimSystem *	getSimulatorSystem (size_t &agentCount, float &simTimeStep, size_t subSteps, float simDuration, const std::string &behaveFile, const std::string &sceneFile, const std::string &outFile, const std::string &scbVersion, bool visualize, bool VERBOSE)
	Returns a simulator system that can be attached to a SceneGraph::GLScene and advanced by a Viewer. More...

void	populateScene (SimSystem system, SceneGraph::GLScene scene)
	Populates the given GLScene with visualization entities tracked in the system. More...

BaseAgentContext *	getAgentContext (SimSystem *system)
	Returns a pointer to an agent context appropriate to the corresponding simulator. More...

float	simDuration () const
	Reports the current run-time of an instantiated simulation. More...

Protected Member Functions
virtual BaseAgentContext *	contextFromSystem (SimSystem *simSystem)
	Returns a pointer to an agent context appropriate to the corresponding simulator. More...

virtual Agents::AgentInitializer *	getAgentInitalizer () const
	Provides an AgentInitializer appropriate to this simulator class. More...

Agents::SimulatorInterface *	initSimulator (const std::string &sceneFileName, bool VERBOSE)
	Creates the simulator. More...

BFSM::FSM *	initFSM (const std::string &behaveFile, Agents::SimulatorInterface *sim, bool VERBOSE)
	Creates the finite state machine and finalizes simulator and fsm. More...

bool	finalize (Agents::SimulatorInterface sim, BFSM::FSM fsm)
	Finalizes the finite state machine and simulator in preparation for execution. More...

virtual SimSystem *	createSimSystem (bool visualize, float duration)
	Creates an instance of a SimSystem to populate. More...

Protected Attributes
Agents::SimulatorInterface *	_sim
	A pointer to the simulator. The database entry is not responsible for deleting it unless there is an error in initialization.

BFSM::FSM *	_fsm
	A pointer to the behavior finite state machine. The database entry is not responsible for deleting it unless there is an error in initialization.

Detailed Description

An entry in the simulator database.

Every pedestrian model must define and register a SimulatorDBEntry. The entry provides brief and long descriptions of the pedestrian model to display in response to command-line queries. Furthermore, they are responsible for instantiating simulators, behavior FSM, and SimSystem (although, this is done in the base class and not the derived classes.

A derived class should do the following:

Inherit from the SimulatorDBEntry
Implement the following functions:
- SimulatorDBEntry::briefDescription
- SimulatorDBEntry::longDescription
- SimulatorDBEntry::viewName
- SimulatorDBEntry::commandLineName
- SimulatorDBEntry::getNewSimulator
Optionally implement the following functionsl
- SimulatorDBEntry::contextFromSystem if the pedestrian model provides a unique sub-class of Agents::BaseAgentContext.
- SimulatorDBEntry::getAgentInitalizer if the pedestrian model has custom per-agent attributes to parse (in addition to the common parameters).

Member Function Documentation

virtual ::std::string Menge::SimulatorDBEntry::briefDescription ( ) const

pure virtual

Gives a brief description of the simulator.

Returns: A brief description of the simulator and pedestrian model.

Implemented in ORCA::DBEntry, and PedVO::DBEntry.

virtual ::std::string Menge::SimulatorDBEntry::commandLineName ( ) const

pure virtual

Gives a unique name to be used as a command-line parameter.

This name MUST satisfy two constraints:

It must contain no spaces.
It must be unique from that used by all other simulators.

Returns: A single string (with no spaces) that can be used as a command line parameter to uniquely identify this model.

Implemented in ORCA::DBEntry, and PedVO::DBEntry.

BaseAgentContext * Menge::SimulatorDBEntry::contextFromSystem ( SimSystem * simSystem )

protectedvirtual

Returns a pointer to an agent context appropriate to the corresponding simulator.

If the provided system is not, in fact, a pointer to a SimSystem for the appropriate simulator type, this function will report failure. Furthermore, the default implementation is to return a BaseAgentContext. If the simulator comes with a novel context, this function should be overridden in the derived SimulatorDBEntry.

Parameters

simSystem The system which tracks the agents. This should be the same system which was returned by a call to SimulatorDBEntry::getSimulatorSystem.

Returns: A pointer to the appropriate agent context. If the system is of the wrong type (or if there is any other problem), NULL is returned.

Reimplemented in ORCA::DBEntry, and PedVO::DBEntry.

SimSystem * Menge::SimulatorDBEntry::createSimSystem	(	bool	visualize,
		float	duration
	)

protectedvirtual

Creates an instance of a SimSystem to populate.

This is the mechanism by which pedestrian plug-ins can override the behavior of the SimSystem based on models, by sub-classing the SimSystem and providing an alternative implementation.

Parameters

visualize	True if the SimSystem will be connected to a visualizer (such as a Vis::GLViewer).
duration	The maximum duration (in simulation time) the system will run.

Returns: A pointer to a new SimSystem.

bool Menge::SimulatorDBEntry::finalize	(	Agents::SimulatorInterface *	sim,
		BFSM::FSM *	fsm
	)

protected

Finalizes the finite state machine and simulator in preparation for execution.

Parameters

sim	A pointer to the simulator.
fsm	The finite state machine that goes with the simulator.

Returns: A boolean reporting if finalization was successful (true) or not (false).

BaseAgentContext * Menge::SimulatorDBEntry::getAgentContext ( SimSystem * system )

Returns a pointer to an agent context appropriate to the corresponding simulator.

Parameters

system The system which tracks the agents. This should be the same system which was returned by a call to SimulatorDBEntry::getSimulatorSystem.

Returns: A pointer to the appropriate agent context.

Agents::AgentInitializer * Menge::SimulatorDBEntry::getAgentInitalizer ( ) const

protectedvirtual

Provides an AgentInitializer appropriate to this simulator class.

Each derived database entry must provide the appropriate AgentInitializer for its simulator type, in order to fully process all of the corresponding XML data to initialize the agent population.

Returns: A pointer to an agent initializer. The caller is responsible for freeing up the memory.

Reimplemented in ORCA::DBEntry, and PedVO::DBEntry.

virtual Agents::SimulatorInterface* Menge::SimulatorDBEntry::getNewSimulator ( )

pure virtual

Returns a pointer to this model's Simulator instance.

This must be overridden by a derived class

Returns: A newly instantiated simulator instance of a type appropriate for this database entry.

Implemented in ORCA::DBEntry, and PedVO::DBEntry.

SimSystem * Menge::SimulatorDBEntry::getSimulatorSystem	(	size_t &	agentCount,
		float &	simTimeStep,
		size_t	subSteps,
		float	simDuration,
		const std::string &	behaveFile,
		const std::string &	sceneFile,
		const std::string &	outFile,
		const std::string &	scbVersion,
		bool	visualize,
		bool	VERBOSE
	)

Returns a simulator system that can be attached to a SceneGraph::GLScene and advanced by a Viewer.

Parameters

agentCount	The number of the agents in the system.
simTimeStep	The simulator's time step (for updating the sim system).
subSteps	The number of computation sub-steps to take.
simDuration	The maximum duration to allow the simulation to run.
behaveFile	The full path to the xml behavior specification.
sceneFile	The full path to the xml scene specification.
outFile	The full path to the output file to write the agent trajectories. If the empty string, no output file will be written.
scbVersion	The scb version to write.
visualize	Determines if this simulator is to be visualized.
VERBOSE	Determines if the initialization process prints status and information to the console. True ouputs, false does not.

Returns: A pointer to the resultant System for running the simulation. If there is an error, NULL is returned.

BFSM::FSM * Menge::SimulatorDBEntry::initFSM	(	const std::string &	behaveFile,
		Agents::SimulatorInterface *	sim,
		bool	VERBOSE
	)

protected

Creates the finite state machine and finalizes simulator and fsm.

Parameters

behaveFile	string containing the full path to the behavior file
sim	pointer to the simulator interface to be used in conjunction with the FSM
VERBOSE	boolean flag for verbose output

Returns: A pointer to the instantiated finite state machine for the simulator. If there is an error, NULL is returned.

Agents::SimulatorInterface * Menge::SimulatorDBEntry::initSimulator	(	const std::string &	sceneFileName,
		bool	VERBOSE
	)

protected

Creates the simulator.

Parameters

sceneFileName	The full path to the simulation scene specification.
VERBOSE	Determines if the initialization outputs status and information to the console. True outputs, false remains silent.

Returns: A pointer to the instantiated simulator. If there is an error, NULL is returned.

virtual ::std::string Menge::SimulatorDBEntry::longDescription ( ) const

pure virtual

Gives a long description of the simulator.

Returns: A long description of the simulator and pedestrian model.

Implemented in ORCA::DBEntry, and PedVO::DBEntry.

void Menge::SimulatorDBEntry::populateScene	(	SimSystem *	system,
		SceneGraph::GLScene *	scene
	)

Populates the given GLScene with visualization entities tracked in the system.

Parameters

system	The system which tracks the agents. This should be the same system which was returned by a call to SimulatorDBEntry::getSimulatorSystem.
scene	The scene to populate with visual elements.

float Menge::SimulatorDBEntry::simDuration ( ) const

Reports the current run-time of an instantiated simulation.

This is only meaningful if called after getSimulatorSystem.

Returns: The current run-time of the instantiated simulation. If no simulation has been instantiated, -1 is returned.

virtual ::std::string Menge::SimulatorDBEntry::viewerName ( ) const

pure virtual

Gives a label to apply to the interactive viewer.

Returns: The name for display on the interactive viewer.; A newly instantiated simulator instance of a type appropriate for this database entry.

Implemented in ORCA::DBEntry, and PedVO::DBEntry.

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

src/menge/MengeCore/Runtime/SimulatorDBEntry.h
src/menge/MengeCore/Runtime/SimulatorDBEntry.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation