Utopia  2
Framework for studying models of complex & adaptive systems.
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | Private Member Functions | List of all members
Utopia::Model< Derived, ModelTypes > Class Template Reference

Base class interface for Models using the CRT Pattern. More...

#include <model.hh>

Collaboration diagram for Utopia::Model< Derived, ModelTypes >:
Collaboration graph
[legend]

Public Types

using Config = typename ModelTypes::Config
 Data type that holds the configuration. More...
 
using DataManager = DataIO::Default::DefaultDataManager< Derived >
 The data manager to use, specialized with the derived model. More...
 
using DataGroup = typename ModelTypes::DataGroup
 Data type that is used for storing datasets. More...
 
using DataSet = typename ModelTypes::DataSet
 Data type that is used for storing data. More...
 
using RNG = typename ModelTypes::RNG
 Data type of the shared RNG. More...
 
using Space = typename ModelTypes::Space
 Data type of the space this model resides in. More...
 
using Time = typename ModelTypes::Time
 Data type for the model time. More...
 
using Monitor = typename ModelTypes::Monitor
 Data type for the monitor. More...
 
using MonitorManager = typename ModelTypes::MonitorManager
 Data type for the monitor manager. More...
 
using Level = typename ModelTypes::Level
 Data type for the hierarchical level. More...
 

Public Member Functions

template<class ParentModel , class... WriterArgs>
 Model (const std::string &name, const ParentModel &parent_model, const Config &custom_cfg={}, std::tuple< WriterArgs... > w_args={}, const DataIO::Default::DefaultDecidermap< Derived > &w_deciders=DataIO::Default::default_deciders< Derived >, const DataIO::Default::DefaultTriggermap< Derived > &w_triggers=DataIO::Default::default_triggers< Derived >)
 Constructs a Model instance. More...
 
const std::shared_ptr< Space > & get_space () const
 Return the space this model resides in. More...
 
Time get_time () const
 Return the current time of this model. More...
 
Time get_time_max () const
 Return the maximum time possible for this model. More...
 
Config get_cfg () const
 Return the config node of this model. More...
 
std::string get_name () const
 Return the name of this model instance. More...
 
std::string get_full_name () const
 Return the full name of this model within the model hierarchy. More...
 
std::shared_ptr< DataGroupget_hdfgrp () const
 Return a pointer to the HDF group this model stores data in. More...
 
Time get_write_start () const
 Return the parameter that controls when write_data is called first. More...
 
Time get_write_every () const
 Return the parameter that controls how often write_data is called. More...
 
DataManager get_datamanager () const
 return the datamanager More...
 
hsize_t get_remaining_num_writes () const
 Return the number of remaining write_data calls this model will make. More...
 
std::shared_ptr< RNGget_rng () const
 Return a pointer to the shared RNG. More...
 
std::shared_ptr< spdlog::logger > get_logger () const
 Return a pointer to the logger of this model. More...
 
Monitor get_monitor () const
 Return the monitor of this model. More...
 
std::shared_ptr< MonitorManagerget_monitor_manager () const
 Get the monitor manager of the root model. More...
 
Level get_level () const
 Return the hierarchical level within the model hierarchy. More...
 
virtual void prolog ()
 A function that is called before starting model iteration. More...
 
virtual void epilog ()
 A function that is called after the last iteration of a model. More...
 
void iterate ()
 Iterate one (time) step of this model. More...
 
void run ()
 Run the model from the current time to the maximum time. More...
 
std::shared_ptr< DataSetcreate_dset (const std::string name, const std::shared_ptr< DataGroup > &hdfgrp, std::vector< hsize_t > add_write_shape, const std::size_t compression_level=1, const std::vector< hsize_t > chunksize={})
 Create a new dataset within the given group. More...
 
std::shared_ptr< DataSetcreate_dset (const std::string name, const std::vector< hsize_t > add_write_shape, const std::size_t compression_level=1, const std::vector< hsize_t > chunksize={})
 Create a new dataset within the model's base data group. More...
 
template<class CellManager >
std::shared_ptr< DataSetcreate_cm_dset (const std::string name, const CellManager &cm, const std::size_t compression_level=1, const std::vector< hsize_t > chunksize={})
 Create a dataset storing data from a CellManager. More...
 
template<class AgentManager >
std::shared_ptr< DataSetcreate_am_dset (const std::string name, const AgentManager &am, const std::size_t compression_level=1, const std::vector< hsize_t > chunksize={})
 Create a dataset storing data from a AgentManager. More...
 

Protected Member Functions

void __perform_step ()
 Perform the computation of a step. More...
 
void __monitor ()
 Monitor information in the terminal. More...
 
void __write_data ()
 Write data; calls the implementation's write_data method. More...
 
void __write_initial_state ()
 Write the initial state. More...
 
void increment_time (const Time dt=1)
 Increment time. More...
 
void __prolog ()
 The default prolog of a model. More...
 
void __epilog ()
 The default epilog of a model. More...
 
Derived & impl ()
 cast to the derived class More...
 
const Derived & impl () const
 const cast to the derived interface More...
 

Protected Attributes

const std::string _name
 Name of the model instance. More...
 
const std::string _full_name
 The full name within the model hierarchy. More...
 
const Level _level
 The level within the model hierarchy. More...
 
const Config _cfg
 Config node belonging to this model instance. More...
 
const std::shared_ptr< RNG_rng
 The RNG shared between models. More...
 
const std::shared_ptr< spdlog::logger > _log
 The (model) logger. More...
 
std::shared_ptr< Space_space
 The space this model resides in. More...
 
Time _time
 Model-internal current time stamp. More...
 
const Time _time_max
 Model-internal maximum time stamp. More...
 
const std::shared_ptr< DataGroup_hdfgrp
 The HDF group this model instance should write its data to. More...
 
const Time _write_start
 First time at which write_data is called. More...
 
const Time _write_every
 How often to call write_data from iterate. More...
 
Monitor _monitor
 The monitor. More...
 
DataManager _datamanager
 Manager object for handling data output; see DataManager. More...
 

Static Protected Attributes

static constexpr WriteMode _write_mode = ModelTypes::write_mode
 Which data-writing mode the base model should use. More...
 

Private Member Functions

template<class Parent >
auto setup_logger (const Parent &parent_model) const
 Constructs this models logger instance from the parent. More...
 
auto setup_space () const
 Constructs the Space from configuration or uses the default Space. More...
 
void __attach_sig_handlers () const
 Attaches signal handlers: SIGINT, SIGTERM, SIGUSR1. More...
 

Detailed Description

template<class Derived, typename ModelTypes>
class Utopia::Model< Derived, ModelTypes >

Base class interface for Models using the CRT Pattern.

Template Parameters
DerivedType of the derived model class
ModelTypesTraits of this model, can be used for specializing

Member Typedef Documentation

◆ Config

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::Config = typename ModelTypes::Config

Data type that holds the configuration.

◆ DataGroup

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::DataGroup = typename ModelTypes::DataGroup

Data type that is used for storing datasets.

◆ DataManager

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::DataManager = DataIO::Default::DefaultDataManager<Derived>

The data manager to use, specialized with the derived model.

◆ DataSet

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::DataSet = typename ModelTypes::DataSet

Data type that is used for storing data.

◆ Level

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::Level = typename ModelTypes::Level

Data type for the hierarchical level.

◆ Monitor

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::Monitor = typename ModelTypes::Monitor

Data type for the monitor.

◆ MonitorManager

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::MonitorManager = typename ModelTypes::MonitorManager

Data type for the monitor manager.

◆ RNG

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::RNG = typename ModelTypes::RNG

Data type of the shared RNG.

◆ Space

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::Space = typename ModelTypes::Space

Data type of the space this model resides in.

◆ Time

template<class Derived , typename ModelTypes >
using Utopia::Model< Derived, ModelTypes >::Time = typename ModelTypes::Time

Data type for the model time.

Constructor & Destructor Documentation

◆ Model()

template<class Derived , typename ModelTypes >
template<class ParentModel , class... WriterArgs>
Utopia::Model< Derived, ModelTypes >::Model ( const std::string &  name,
const ParentModel< Derived, ModelTypes > &  parent_model,
const Config custom_cfg = {},
std::tuple< WriterArgs... >  w_args = {},
const DataIO::Default::DefaultDecidermap< Derived > &  w_deciders = DataIO::Default::default_deciders< Derived >,
const DataIO::Default::DefaultTriggermap< Derived > &  w_triggers = DataIO::Default::default_triggers< Derived > 
)
inline

Constructs a Model instance.

Uses information from a parent model to create a model instance.

Template Parameters
ParentModelThe parent model's type
Parameters
nameThe name of this model instance, ideally used only once on the current hierarchical level
parent_modelThe parent model object from which the corresponding config node, the group, the RNG, and the parent log level are extracted.
custom_cfgIf given, will use this configuration node instead of trying to extract one from the parent model's configuration.
w_argsPassed on to DataManager constructor. If not given, the DataManager will still be constructed. Take care to also set the WriteMode accordingly.
w_decidersMap which associates names with factory functions for deciders of signature factory()::shared_ptr<Decider<Derived>>
w_triggersMap which associates names with factory functions for triggers of signature factory()::shared_ptr<Trigger<Derived>>

Member Function Documentation

◆ __attach_sig_handlers()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::__attach_sig_handlers ( ) const
inlineprivate

Attaches signal handlers: SIGINT, SIGTERM, SIGUSR1.

These signals are caught and handled such that the run method is able to finish in an ordered manner, preventing data corruption. This is done by invoking attach_signal_handler and attaching the default_signal_handler to them.

The SIGUSR1 signal is sent by the frontend if the stop conditions for this simulation are all fulfilled. It will likewise lead to the invocation of the default_signal_handler.

◆ __epilog()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::__epilog ( )
inlineprotected

The default epilog of a model.

Default tasks: None

◆ __monitor()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::__monitor ( )
inlineprotected

Monitor information in the terminal.

◆ __perform_step()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::__perform_step ( )
inlineprotected

Perform the computation of a step.

◆ __prolog()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::__prolog ( )
inlineprotected

The default prolog of a model.

Default tasks:

  1. call __write_initial_state

◆ __write_data()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::__write_data ( )
inlineprotected

Write data; calls the implementation's write_data method.

◆ __write_initial_state()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::__write_initial_state ( )
inlineprotected

Write the initial state.

◆ create_am_dset()

template<class Derived , typename ModelTypes >
template<class AgentManager >
std::shared_ptr<DataSet> Utopia::Model< Derived, ModelTypes >::create_am_dset ( const std::string  name,
const AgentManager am,
const std::size_t  compression_level = 1,
const std::vector< hsize_t >  chunksize = {} 
)
inline

Create a dataset storing data from a AgentManager.

The required capacity - the shape of the dataset - is calculated using both data from the model and the AgentManager. Additionally, dimension and coordinate labels are added.

Agents are also labelled with a (trivial) ID, starting from zero.

Note
For the time dimension, the coordinates assume that data is written the first time at time 0 and then every _write_every. Time coordinates will be wrong if the model does not write the data this way. For such cases, it is advised to suppress writing of attributes by setting the config entry write_dim_labels_and_coords entry to false.
Warning
The number of agents present at the time this method is called determine the dataset's capacity. If the agent number increases beyond that point during the runtime of the simulation, data writing will fail because the datasets capacity will be too small!
Parameters
nameThe name of the dataset
amThe AgentManager whose agents' states are to be stored in the dataset
compression_levelThe compression level
chunksizeThe chunk size
Returns
std::shared_ptr<DataSet> The newly created HDFDataset

◆ create_cm_dset()

template<class Derived , typename ModelTypes >
template<class CellManager >
std::shared_ptr<DataSet> Utopia::Model< Derived, ModelTypes >::create_cm_dset ( const std::string  name,
const CellManager cm,
const std::size_t  compression_level = 1,
const std::vector< hsize_t >  chunksize = {} 
)
inline

Create a dataset storing data from a CellManager.

The required capacity - the shape of the dataset - is calculated using both data from the model and the CellManager. Additionally, dimension and coordinate labels are added.

Note
For the time dimension, the coordinates assume that data is written the first time at time 0 and then every _write_every. Time coordinates will be wrong if the model does not write the data this way. For such cases, it is advised to suppress writing of attributes by setting the _cfg['write_dim_labels_and_coords'] entry to false.
Parameters
nameThe name of the dataset
cmThe CellManager whose cells' states are to be stored in the dataset
compression_levelThe compression level
chunksizeThe chunk size
Returns
std::shared_ptr<DataSet> The newly created HDFDataset

◆ create_dset() [1/2]

template<class Derived , typename ModelTypes >
std::shared_ptr<DataSet> Utopia::Model< Derived, ModelTypes >::create_dset ( const std::string  name,
const std::shared_ptr< DataGroup > &  hdfgrp,
std::vector< hsize_t >  add_write_shape,
const std::size_t  compression_level = 1,
const std::vector< hsize_t >  chunksize = {} 
)
inline

Create a new dataset within the given group.

The capacity - the shape of the dataset - is calculated automatically from the num_steps and write_every parameter. Additionally, dataset attributes are set that carry information on dimension labels and coordinates.

Note
The attributes are only written for the time dimension, as that is the only one that is known in this method. Furthermore, this assumes that it writes at write_every and - importantly - has the first write operation at time zero. Coordinates will be wrong if that is not the case! For such cases, it is advised to suppress writing of these attributes by setting the configuration entry _cfg['write_dim_labels_and_coords'] to false.
Parameters
nameThe name of the dataset
hdfgrpThe parent HDFGroup
add_write_shapeAdditional write shape which, together with the number of time steps, is used to calculate the capacity of the dataset: (capacity = (num_time_steps, add_write_shape)).
compression_levelThe compression level
chunksizeThe chunk size
Returns
std::shared_ptr<DataSet> The hdf dataset

◆ create_dset() [2/2]

template<class Derived , typename ModelTypes >
std::shared_ptr<DataSet> Utopia::Model< Derived, ModelTypes >::create_dset ( const std::string  name,
const std::vector< hsize_t >  add_write_shape,
const std::size_t  compression_level = 1,
const std::vector< hsize_t >  chunksize = {} 
)
inline

Create a new dataset within the model's base data group.

The capacity - the shape of the dataset - is calculated automatically from the num_steps and write_every parameter. Additionally, dataset attributes are set that carry information on dimension labels and coordinates.

Note
The attributes are only written for the time dimension, as that is the only one that is known in this method. Furthermore, this assumes that it writes at write_every and - importantly - has the first write operation at time zero. Coordinates will be wrong if that is not the case! For such cases, it is advised to suppress writing of these attributes by setting the configuration entry _cfg['write_dim_labels_and_coords'] to false.
Parameters
nameThe name of the dataset
add_write_shapeAdditional write shape which, together with the number of time steps, is used to calculate the capacity of the dataset: (capacity = (num_time_steps, add_write_shape)).
compression_levelThe compression level
chunksizeThe chunk size
Returns
std::shared_ptr<DataSet> The hdf dataset

◆ epilog()

template<class Derived , typename ModelTypes >
virtual void Utopia::Model< Derived, ModelTypes >::epilog ( )
inlinevirtual

A function that is called after the last iteration of a model.

See __epilog() for default tasks

◆ get_cfg()

template<class Derived , typename ModelTypes >
Config Utopia::Model< Derived, ModelTypes >::get_cfg ( ) const
inline

Return the config node of this model.

◆ get_datamanager()

template<class Derived , typename ModelTypes >
DataManager Utopia::Model< Derived, ModelTypes >::get_datamanager ( ) const
inline

return the datamanager

◆ get_full_name()

template<class Derived , typename ModelTypes >
std::string Utopia::Model< Derived, ModelTypes >::get_full_name ( ) const
inline

Return the full name of this model within the model hierarchy.

◆ get_hdfgrp()

template<class Derived , typename ModelTypes >
std::shared_ptr<DataGroup> Utopia::Model< Derived, ModelTypes >::get_hdfgrp ( ) const
inline

Return a pointer to the HDF group this model stores data in.

◆ get_level()

template<class Derived , typename ModelTypes >
Level Utopia::Model< Derived, ModelTypes >::get_level ( ) const
inline

Return the hierarchical level within the model hierarchy.

◆ get_logger()

template<class Derived , typename ModelTypes >
std::shared_ptr<spdlog::logger> Utopia::Model< Derived, ModelTypes >::get_logger ( ) const
inline

Return a pointer to the logger of this model.

◆ get_monitor()

template<class Derived , typename ModelTypes >
Monitor Utopia::Model< Derived, ModelTypes >::get_monitor ( ) const
inline

Return the monitor of this model.

◆ get_monitor_manager()

template<class Derived , typename ModelTypes >
std::shared_ptr<MonitorManager> Utopia::Model< Derived, ModelTypes >::get_monitor_manager ( ) const
inline

Get the monitor manager of the root model.

◆ get_name()

template<class Derived , typename ModelTypes >
std::string Utopia::Model< Derived, ModelTypes >::get_name ( ) const
inline

Return the name of this model instance.

◆ get_remaining_num_writes()

template<class Derived , typename ModelTypes >
hsize_t Utopia::Model< Derived, ModelTypes >::get_remaining_num_writes ( ) const
inline

Return the number of remaining write_data calls this model will make.

The 'remaining' refers to the current time being included into the calculation, e.g.: when writing every time, currently at time == 42 and time_max == 43, it will return the value 2, i.e. for the write operations at times 42 and 43

◆ get_rng()

template<class Derived , typename ModelTypes >
std::shared_ptr<RNG> Utopia::Model< Derived, ModelTypes >::get_rng ( ) const
inline

Return a pointer to the shared RNG.

◆ get_space()

template<class Derived , typename ModelTypes >
const std::shared_ptr<Space>& Utopia::Model< Derived, ModelTypes >::get_space ( ) const
inline

Return the space this model resides in.

◆ get_time()

template<class Derived , typename ModelTypes >
Time Utopia::Model< Derived, ModelTypes >::get_time ( ) const
inline

Return the current time of this model.

◆ get_time_max()

template<class Derived , typename ModelTypes >
Time Utopia::Model< Derived, ModelTypes >::get_time_max ( ) const
inline

Return the maximum time possible for this model.

Note
Will emit a warning via the logger if the this was set to the maximum possible value, e.g. because this model is run as a submodel of another model and the maximum time has no relevance in such a context.

◆ get_write_every()

template<class Derived , typename ModelTypes >
Time Utopia::Model< Derived, ModelTypes >::get_write_every ( ) const
inline

Return the parameter that controls how often write_data is called.

◆ get_write_start()

template<class Derived , typename ModelTypes >
Time Utopia::Model< Derived, ModelTypes >::get_write_start ( ) const
inline

Return the parameter that controls when write_data is called first.

◆ impl() [1/2]

template<class Derived , typename ModelTypes >
Derived& Utopia::Model< Derived, ModelTypes >::impl ( )
inlineprotected

cast to the derived class

◆ impl() [2/2]

template<class Derived , typename ModelTypes >
const Derived& Utopia::Model< Derived, ModelTypes >::impl ( ) const
inlineprotected

const cast to the derived interface

◆ increment_time()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::increment_time ( const Time  dt = 1)
inlineprotected

Increment time.

Parameters
dtTime increment, defaults to 1

◆ iterate()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::iterate ( )
inline

Iterate one (time) step of this model.

Increment time, perform step, emit monitor data, and write data. Monitoring is performed differently depending on the model level. The write_data method is called depending on the configured value for the write_mode (template parameter) and (if in mode basic): the configuration parameters write_start and write_every.

◆ prolog()

template<class Derived , typename ModelTypes >
virtual void Utopia::Model< Derived, ModelTypes >::prolog ( )
inlinevirtual

A function that is called before starting model iteration.

See __prolog() for default tasks

◆ run()

template<class Derived , typename ModelTypes >
void Utopia::Model< Derived, ModelTypes >::run ( )
inline

Run the model from the current time to the maximum time.

This repeatedly calls the iterate method until the maximum time is reached. Additionally, it calls the __write_data method to allow it to write the initial state. In write mode basic, this is only done if _write_start == _time.

◆ setup_logger()

template<class Derived , typename ModelTypes >
template<class Parent >
auto Utopia::Model< Derived, ModelTypes >::setup_logger ( const Parent &  parent_model) const
inlineprivate

Constructs this models logger instance from the parent.

Also directly sets the log level from the log_level config entry.

◆ setup_space()

template<class Derived , typename ModelTypes >
auto Utopia::Model< Derived, ModelTypes >::setup_space ( ) const
inlineprivate

Constructs the Space from configuration or uses the default Space.

Member Data Documentation

◆ _cfg

template<class Derived , typename ModelTypes >
const Config Utopia::Model< Derived, ModelTypes >::_cfg
protected

Config node belonging to this model instance.

◆ _datamanager

template<class Derived , typename ModelTypes >
DataManager Utopia::Model< Derived, ModelTypes >::_datamanager
protected

Manager object for handling data output; see DataManager.

Note
The data manager is always constructed, but only used if the _write_mode was set to WriteMode::managed.

◆ _full_name

template<class Derived , typename ModelTypes >
const std::string Utopia::Model< Derived, ModelTypes >::_full_name
protected

The full name within the model hierarchy.

◆ _hdfgrp

template<class Derived , typename ModelTypes >
const std::shared_ptr<DataGroup> Utopia::Model< Derived, ModelTypes >::_hdfgrp
protected

The HDF group this model instance should write its data to.

◆ _level

template<class Derived , typename ModelTypes >
const Level Utopia::Model< Derived, ModelTypes >::_level
protected

The level within the model hierarchy.

◆ _log

template<class Derived , typename ModelTypes >
const std::shared_ptr<spdlog::logger> Utopia::Model< Derived, ModelTypes >::_log
protected

The (model) logger.

◆ _monitor

template<class Derived , typename ModelTypes >
Monitor Utopia::Model< Derived, ModelTypes >::_monitor
protected

The monitor.

◆ _name

template<class Derived , typename ModelTypes >
const std::string Utopia::Model< Derived, ModelTypes >::_name
protected

Name of the model instance.

◆ _rng

template<class Derived , typename ModelTypes >
const std::shared_ptr<RNG> Utopia::Model< Derived, ModelTypes >::_rng
protected

The RNG shared between models.

◆ _space

template<class Derived , typename ModelTypes >
std::shared_ptr<Space> Utopia::Model< Derived, ModelTypes >::_space
protected

The space this model resides in.

◆ _time

template<class Derived , typename ModelTypes >
Time Utopia::Model< Derived, ModelTypes >::_time
protected

Model-internal current time stamp.

◆ _time_max

template<class Derived , typename ModelTypes >
const Time Utopia::Model< Derived, ModelTypes >::_time_max
protected

Model-internal maximum time stamp.

◆ _write_every

template<class Derived , typename ModelTypes >
const Time Utopia::Model< Derived, ModelTypes >::_write_every
protected

How often to call write_data from iterate.

◆ _write_mode

template<class Derived , typename ModelTypes >
constexpr WriteMode Utopia::Model< Derived, ModelTypes >::_write_mode = ModelTypes::write_mode
staticconstexprprotected

Which data-writing mode the base model should use.

◆ _write_start

template<class Derived , typename ModelTypes >
const Time Utopia::Model< Derived, ModelTypes >::_write_start
protected

First time at which write_data is called.


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