Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone > Class Template Reference

The Environment model provides a non-uniform, dynamic parameter background. More...

#include <Environment.hh>

Inheritance diagram for Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >:

Collaboration diagram for Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >:

Classes
struct	DummyCellManager
	A dummy CellManager type that is used in standalone mode. More...

Public Types
using	Self = Environment< EnvParam, EnvCellState, standalone >
	Type of this class.
using	Base = Model< Self, ModelTypes >
	The type of the Model base class of this derived class.
using	DataGroup = typename Base::DataGroup
	Data type of the group to write model data to, holding datasets.
using	DataSet = typename Base::DataSet
	Data type for a dataset.
using	CellTraits = Utopia::CellTraits< EnvCellState, Update::manual >
	Cell traits specialization using the state type.
using	CellManager = Utopia::CellManager< CellTraits, Self >
	The type of the cell manager.
using	EnvCellContainer = CellContainer< typename CellManager::Cell >
	The type of the EnvCellContainer.
using	Time = typename Base::Time
	The type of the model time.
using	EnvParamFunc = typename std::function< double()>
	The type of the environment parameter functions.
using	EnvParamFuncBundle = FuncBundle::ParamFuncBundle< EnvParamFunc, Time >
	The type wrapping EnvParamFunc with metadata.
using	EnvStateFunc = typename CellManager::RuleFunc
	The type of the environment state functions; basically a rule function.
using	EnvStateFuncBundle = FuncBundle::RuleFuncBundle< EnvStateFunc, Time, EnvCellContainer >
	The type wrapping EnvStateFunc with metadata.
using	Config = DataIO::Config
	Configuration node type alias.
Public Types inherited from Utopia::Model< Derived, ModelTypes >
using	Config = typename ModelTypes::Config
	Data type that holds the configuration.
using	DataManager = DataIO::Default::DefaultDataManager< Derived >
	The data manager to use, specialized with the derived model.
using	DataGroup = typename ModelTypes::DataGroup
	Data type that is used for storing datasets.
using	DataSet = typename ModelTypes::DataSet
	Data type that is used for storing data.
using	RNG = typename ModelTypes::RNG
	Data type of the shared RNG.
using	Space = typename ModelTypes::Space
	Data type of the space this model resides in.
using	Time = typename ModelTypes::Time
	Data type for the model time.
using	Monitor = typename ModelTypes::Monitor
	Data type for the monitor.
using	MonitorManager = typename ModelTypes::MonitorManager
	Data type for the monitor manager.
using	Level = typename ModelTypes::Level
	Data type for the hierarchical level.

Public Member Functions
template<class ParentModel , class CellManager >
	Environment (const std::string &name, ParentModel &parent_model, CellManager &&associate_cm, const DataIO::Config &custom_cfg={})
	Construct the Environment model associated to a CellManager.
template<typename ParentModel >
	Environment (const std::string name, ParentModel &parent)
	Construct Environment without associated CellManager.
void	perform_step ()
	Iterate a single step.
void	monitor ()
	Monitor model information.
void	write_data ()
	Write data.
double	get_parameter (const std::string &param_name) const
	Return the current value of the parameter with param_name.
void	set_parameter (const std::string &param_name, double value)
	Change the current value of the parameter with param_name.
const auto &	cm () const
	Return a const reference to the cell manager.
template<class EPFB >
void	add_env_param_func (EPFB &&epfb)
	Add a rule function at the end of the sequence of parameter functions.
void	add_env_param_func (const std::string &name, const EnvParamFunc &epf, const std::string &param_name, std::tuple< bool, bool, std::set< Time > > times_tuple)
	Add a param function at the end of the sequence of env functions.
void	add_env_param_func_from_cfg (const std::string &name, const EnvParamFunc &epf, const std::string &param_name, const Config &cfg={})
	Add a param function at the end of the sequence of env functions.
template<bool add_to_initial = false, class ESFB >
void	add_env_state_func (ESFB &&esfb)
	Add a rule function at the end of the sequence of state functions.
template<bool add_to_initial = false>
void	add_env_state_func (const std::string &name, const EnvStateFunc &esf, const Update &update=Update::sync, std::pair< bool, std::set< Time > > times_pair={true, {}}, Config select_cfg={})
	Add a rule function at the end of the sequence of environment functions.
template<bool add_to_initial = false>
void	add_env_state_func_from_cfg (const std::string &name, const EnvStateFunc &esf, const Update &update=Update::sync, const Config &cfg={})
	Add a rule function at the end of the sequence of environment functions.
void	track_parameter (const std::string &key)
	Mark a parameter as being tracked, i.e. store its data in write_data.
void	track_parameters (const std::vector< std::string > &keys)
	Track multiple parameters.
void	track_state (const std::string &key)
	Mark a state as being tracked, i.e. store its data in write_data.
void	track_states (const std::vector< std::string > &keys)
	Track multiple states.
Public Member Functions inherited from Utopia::Model< Derived, ModelTypes >
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.
const std::shared_ptr< Space > &	get_space () const
	Return the space this model resides in.
Time	get_time () const
	Return the current time of this model.
Time	get_time_max () const
	Return the maximum time possible for this model.
Config	get_cfg () const
	Return the config node of this model.
std::string	get_name () const
	Return the name of this model instance.
std::string	get_full_name () const
	Return the full name of this model within the model hierarchy.
std::shared_ptr< DataGroup >	get_hdfgrp () const
	Return a pointer to the HDF group this model stores data in.
Time	get_write_start () const
	Return the parameter that controls when write_data is called first.
Time	get_write_every () const
	Return the parameter that controls how often write_data is called.
DataManager	get_datamanager () const
	return the datamanager
hsize_t	get_remaining_num_writes () const
	Return the number of remaining write_data calls this model will make.
std::shared_ptr< RNG >	get_rng () const
	Return a pointer to the shared RNG.
std::shared_ptr< spdlog::logger >	get_logger () const
	Return a pointer to the logger of this model.
Monitor	get_monitor () const
	Return the monitor of this model.
std::shared_ptr< MonitorManager >	get_monitor_manager () const
	Get the monitor manager of the root model.
Level	get_level () const
	Return the hierarchical level within the model hierarchy.
virtual void	prolog ()
	A function that is called before starting model iteration.
virtual void	epilog ()
	A function that is called after the last iteration of a model.
void	iterate ()
	Iterate one (time) step of this model.
void	run ()
	Run the model from the current time to the maximum time.
std::shared_ptr< DataSet >	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={})
	Create a new dataset within the given group.
std::shared_ptr< DataSet >	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={})
	Create a new dataset within the model's base data group.
template<class CellManager >
std::shared_ptr< DataSet >	create_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.
template<class AgentManager >
std::shared_ptr< DataSet >	create_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.

Private Member Functions
void	setup_env_param_funcs (const Config &cfg)
	Construct the rule funcs sequencefor EnvParam from cfg.
template<bool add_to_initial = false>
void	setup_env_state_funcs (const Config &cfg)
	Construct the rule funcs sequence from cfg.
template<class EPFB >
void	apply_env_param_func (EPFB &&epfb, bool initialization=false)
	Apply a given environment parameter function.
template<class ESFB >
void	apply_env_state_func (ESFB &&esfb)
	Apply a given environment state function.

Private Attributes
CellManager	_cm
	The cell manager.
EnvParam	_params
	The environment parameters.
std::vector< EnvParamFuncBundle >	_env_param_funcs
	Container of functions that are invoked every time step.
std::vector< EnvStateFuncBundle >	_init_env_state_funcs
	Container of rule functions that are invoked once at initialisation.
std::vector< EnvStateFuncBundle >	_env_state_funcs
	Container of rule functions that are invoked every time step.
std::unordered_map< std::string, std::shared_ptr< DataSet > >	_dsets_state
	Dynamically generated map of datasets of cell states.
std::unordered_map< std::string, std::shared_ptr< DataSet > >	_dsets_param
	Dynamically generated map of datasets of parameters.

Additional Inherited Members
Protected Member Functions inherited from Utopia::Model< Derived, ModelTypes >
void	__perform_step ()
	Perform the computation of a step.
void	__monitor ()
	Monitor information in the terminal.
void	__write_data ()
	Write data; calls the implementation's write_data method.
void	__write_initial_state ()
	Write the initial state.
void	increment_time (const Time dt=1)
	Increment time.
void	__prolog ()
	The default prolog of a model.
void	__epilog ()
	The default epilog of a model.
Derived &	impl ()
	cast to the derived class
const Derived &	impl () const
	const cast to the derived interface
Protected Attributes inherited from Utopia::Model< Derived, ModelTypes >
const std::string	_name
	Name of the model instance.
const std::string	_full_name
	The full name within the model hierarchy.
const Level	_level
	The level within the model hierarchy.
const Config	_cfg
	Config node belonging to this model instance.
const std::shared_ptr< RNG >	_rng
	The RNG shared between models.
const std::shared_ptr< spdlog::logger >	_log
	The (model) logger.
std::shared_ptr< Space >	_space
	The space this model resides in.
Time	_time
	Model-internal current time stamp.
const Time	_time_max
	Model-internal maximum time stamp.
const std::shared_ptr< DataGroup >	_hdfgrp
	The HDF group this model instance should write its data to.
const Time	_write_start
	First time at which write_data is called.
const Time	_write_every
	How often to call write_data from iterate.
Monitor	_monitor
	The monitor.
DataManager	_datamanager
	Manager object for handling data output; see DataManager.
Static Protected Attributes inherited from Utopia::Model< Derived, ModelTypes >
static constexpr WriteMode	_write_mode = ModelTypes::write_mode
	Which data-writing mode the base model should use.

Detailed Description

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>
class Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >

The Environment model provides a non-uniform, dynamic parameter background.

This happens by coupling to another model's CellManager. Additionally, global parameters can also be changed.

Template Parameters

EnvParam	The parameter type of the environment
EnvCellState	The cell state type of the environment cells
standalone	Whether to have the model as a standalone model

Member Typedef Documentation

Base

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::Base = Model<Self, ModelTypes>

The type of the Model base class of this derived class.

CellManager

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::CellManager = Utopia::CellManager<CellTraits, Self>

The type of the cell manager.

CellTraits

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::CellTraits = Utopia::CellTraits<EnvCellState, Update::manual>

Cell traits specialization using the state type.

Config

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::Config = DataIO::Config

Configuration node type alias.

DataGroup

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::DataGroup = typename Base::DataGroup

Data type of the group to write model data to, holding datasets.

DataSet

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::DataSet = typename Base::DataSet

Data type for a dataset.

EnvCellContainer

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::EnvCellContainer = CellContainer<typename CellManager::Cell>

The type of the EnvCellContainer.

EnvParamFunc

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::EnvParamFunc = typename std::function<double()>

The type of the environment parameter functions.

EnvParamFuncBundle

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::EnvParamFuncBundle = FuncBundle::ParamFuncBundle<EnvParamFunc, Time>

The type wrapping EnvParamFunc with metadata.

EnvStateFunc

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::EnvStateFunc = typename CellManager::RuleFunc

The type of the environment state functions; basically a rule function.

EnvStateFuncBundle

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::EnvStateFuncBundle = FuncBundle::RuleFuncBundle<EnvStateFunc, Time, EnvCellContainer>

The type wrapping EnvStateFunc with metadata.

Self

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::Self = Environment<EnvParam, EnvCellState, standalone>

Type of this class.

Time

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

using Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::Time = typename Base::Time

The type of the model time.

Constructor & Destructor Documentation

Environment() [1/2]

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

template<class ParentModel , class CellManager >

Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::Environment ( const std::string &  name, ParentModel &  parent_model, CellManager &&  associate_cm, const DataIO::Config &  custom_cfg = {}  )

inline

Construct the Environment model associated to a CellManager.

Parameters

name	Name of this model instance
parent_model	The parent model this model instance resides in
associate_cm	The CellManager of the associate (i.e. parent) model. The Environment model's CellManager will use the configuration of that CellManager.
custom_cfg	A custom configuration to use instead of the one extracted from the parent model using the instance name

                                         {}
    )
    :
        // Initialize first via base model
        Base(name, parent_model, custom_cfg),
 
        // Set up the internal CellManager
        _cm(*this, associate_cm.cfg()),
        // NOTE If called from the standalone constructor, the .cfg() call
        //      always returns an empty configuration which leads to this
        //      internal CellManager being set up from _cfg["cell_manager"]
 
        //set up the environment params
        _params(this->_cfg),
 
        // Set up environment function bundle containers empty
        _env_param_funcs{},
        _init_env_state_funcs{},
        _env_state_funcs{},
 
        // Map of datasets; empty until states are set to be tracked
        _dsets_state{},
        _dsets_param{}
    {
        // Associate the CellManager's cells with each other
        if constexpr (not std::is_same<CellManager, DummyCellManager>()) {
            for (std::size_t i=0; i < _cm.cells().size(); i++) {
                associate_cm.cells()[i]->custom_links().env = _cm.cells()[i];
            }
 
            this->_log->info(
                "Associated '{}' cells with those of the parent model '{}'.",
                this->_name, parent_model.get_name()
            );
        }
        else if constexpr (not standalone) {
            // Only allow coupled models without coupled cellmanagers when
            // a EnvCellState is the dummy type
            static_assert(std::is_same<EnvCellState, DummyEnvCellState>(),
                          "The cm for association of environment cells cannot "
                          "be the DummyCellManager! \n"
                          "Setup the model with type DummyEnvCellState for "
                          "standalone model or pass a cell manager for "
                          "associated model.");
 
            this->_log->info("Setting up '{}' as coupled model without "
                             "associated cell manager.", this->_name);
        }
        else {
            this->_log->info("Setting up '{}' as standalone model ...",
                             this->_name);
        }
 
        // Check inheritance of EnvCellState; needed for position cache
        static_assert(std::is_base_of<BaseEnvCellState, EnvCellState>::value,
                      "The model's EnvCellState must derive from "
                      "Utopia::Models::Environment::BaseEnvCellState!");
 
        // Check inheritance of EnvParam; needed for getters and setters
        static_assert(std::is_base_of<BaseEnvParam, EnvParam>::value,
                      "The model's EnvParam must derive from "
                      "Utopia::Models::Environment::BaseEnvParam!");
 
        // Store positions
        apply_rule<Update::sync>(
            [this](const auto& cell){
                auto& state = cell->state;
                state.position = this->_cm.barycenter_of(cell);
                return state;
            },
            this->_cm.cells()
        );
        this->_log->debug("Cell barycenters cached.");
 
 
        // Now set up the actual environment parameter functions
        if (this->_cfg["env_param_funcs"]) {
            setup_env_param_funcs(this->_cfg["env_param_funcs"]);
        }
 
        // Apply the env_param_funcs for initialization
        this->_log->debug("Applying {} initial environment param function{} ...",
                         _env_param_funcs.size(),
                         _env_param_funcs.size() != 1 ? "s" : "");
        for (auto& epfb : _env_param_funcs) {
            if (epfb.invoke_at_initialization) {
                apply_env_param_func(epfb, true);
            }
        }
 
        // Now set up the actual environment state functions
        if (this->_cfg["init_env_state_funcs"]) {
            setup_env_state_funcs<true>(this->_cfg["init_env_state_funcs"]);
        }
        if (this->_cfg["env_state_funcs"]) {
            setup_env_state_funcs<false>(this->_cfg["env_state_funcs"]);
        }
 
        // Apply the env_state_funcs for initialization
        this->_log->info("Applying {} initial environment state function{} ...",
                         _init_env_state_funcs.size(),
                         _init_env_state_funcs.size() != 1 ? "s" : "");
        for (auto& esfb : _init_env_state_funcs) {
            apply_env_state_func(esfb);
        }
 
        this->_log->info("{} set up.", this->_name);
    }

Environment() [2/2]

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

template<typename ParentModel >

Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::Environment ( const std::string  name, ParentModel &  parent  )

inline

Construct Environment without associated CellManager.

Note

This constructor can be used to set up a Environment as a standalone model or with only the EnvParam. In the case of standalone the standalone template parameter needs to be set to true. In the the other case the EnvCellState needs to be the default dummy type DummyEnvCellState and the standalone template parameter needs to be false (default).

    :
        // Use existing constructor, passing a _DummyCellManager instance that
        // ensures that no configuration is carried over.
        Environment(name, parent, DummyCellManager())
    { }

Member Function Documentation

add_env_param_func() [1/2]

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::add_env_param_func ( const std::string &  name, const EnvParamFunc &  epf, const std::string &  param_name, std::tuple< bool, bool, std::set< Time > >  times_tuple  )

inline

Add a param function at the end of the sequence of env functions.

Parameters

epf	EnvParamFunc that is applied to all cm.cells()
times_tuple	invoke_at_initialization, invoke_always, set of times when to invoke the function

    {
        add_env_param_func(
            EnvParamFuncBundle(name, epf, param_name, times_tuple)
        );
    }

add_env_param_func() [2/2]

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

template<class EPFB >

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::add_env_param_func ( EPFB &&  epfb )

inline

Add a rule function at the end of the sequence of parameter functions.

Parameters

epfb	The EnvParamFuncBundle of environment parameter function that is to be added and its metadata.

                                         {
        _env_param_funcs.push_back(epfb);
        this->_log->debug("Added environment param function '{}'.", epfb.name);
    }

add_env_param_func_from_cfg()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::add_env_param_func_from_cfg ( const std::string &  name, const EnvParamFunc &  epf, const std::string &  param_name, const Config &  cfg = {}  )

inline

Add a param function at the end of the sequence of env functions.

Parameters

epf	EnvParamFunc that is applied to all cm.cells()
cfg	From which invoke_at_initialization and times to invoke the function is extracted

                                {})
    {
        auto invoke_times_tuple = extract_times_and_initialization<Time>(cfg);
        add_env_param_func(name, epf, param_name, invoke_times_tuple);
    }

add_env_state_func() [1/2]

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

template<bool add_to_initial = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::add_env_state_func ( const std::string &  name, const EnvStateFunc &  esf, const Update &  update = Update::sync, std::pair< bool, std::set< Time > >  times_pair = {true, {}}, Config  select_cfg = {}  )

inline

Add a rule function at the end of the sequence of environment functions.

Parameters

esf	EnvStateFunc that is applied to all cm.cells()
update	The Update mode to use with apply_rule(esf, cm.cells)
times_pair	invoke_always, Set of times at which to invoke function.
select_cfg	Config passed to _cm.select_cells

                                                     {true, {}},
            Config select_cfg = {})
    {
        // resolve select option
        bool fix_selection;
        EnvCellContainer cell_selection = {};
        if (not select_cfg.IsNull()) {
            std::string generate = get_as<std::string>("generate", select_cfg);
            if (generate == "once") {
                fix_selection = true;
            }
            else if (generate == "always") {
                fix_selection = false;
            }
            else {
                throw std::invalid_argument("Key 'generate' in 'select' "
                        "feature of environment state function '"
                        + name + "' must be 'once' to fix selection or "
                        "'always' to generate it on the fly, but was '"
                        + generate + "'!");
            }
 
            if (fix_selection) {
                this->_log->debug("Generating a selection of cells and fixing "
                                  "it for the rule '{}'.", name);
                cell_selection = _cm.select_cells(select_cfg);
            }
        }
        else {
            fix_selection = false;
        }
 
        add_env_state_func<add_to_initial>(
            EnvStateFuncBundle(name, esf, update, add_to_initial, times_pair,
                               {fix_selection, cell_selection, select_cfg})
        );
    }

add_env_state_func() [2/2]

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

template<bool add_to_initial = false, class ESFB >

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::add_env_state_func ( ESFB &&  esfb )

inline

Add a rule function at the end of the sequence of state functions.

Parameters

esfb	The EnvStateFuncBundle of environment state function that is to be added and its metadata.

                                         {
        if constexpr (add_to_initial) {
            _init_env_state_funcs.push_back(esfb);
        }
        else {
            _env_state_funcs.push_back(esfb);
        }
        this->_log->debug("Added {}environment function '{}'.",
                          add_to_initial ? "initial " : "", esfb.name);
    }

add_env_state_func_from_cfg()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

template<bool add_to_initial = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::add_env_state_func_from_cfg ( const std::string &  name, const EnvStateFunc &  esf, const Update &  update = Update::sync, const Config &  cfg = {}  )

inline

Add a rule function at the end of the sequence of environment functions.

Parameters

esf	EnvStateFunc that is applied to all cm.cells()
update	The Update mode to use with apply_rule(esf, cm.cells)
cfg	The config of the state_func. Here, times and select are extracted; All other entries ignored. Defaults are invoke always and select all cells.

                            {})
    {
        auto times_pair = extract_times<Time>(cfg);
        Config select_cfg = {};
        if (cfg.IsMap()) {
            select_cfg = get_as<Config>("select", cfg, {});
        }
 
        add_env_state_func<add_to_initial>(name, esf, update, times_pair,
                                           select_cfg);
    }

apply_env_param_func()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

template<class EPFB >

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::apply_env_param_func ( EPFB &&  epfb, bool  initialization = false  )

inlineprivate

Apply a given environment parameter function.

Parameters

esf	EnvParamFunc that is applied

                                                                        {
        // Check whether to invoke
        if (initialization) {
            if (not epfb.invoke_at_initialization) {
                this->_log->trace("Not invoking environment function '{}' at "
                                  "initialization.", epfb.name);
                return;
            }
        }
        else if (not epfb.invoke_always) {
            // Compare to first element of the times set
            // NOTE This approach has a low and constant complexity as no tree
            //      traversal in the set takes place. This, however, relies on
            //      the ordering of the set and that the first element is
            //      never smaller than (current time + 1), which would lead to
            //      clogging of the erasure ...
            if (    epfb.times.size()
                and *epfb.times.begin() == (this->_time + 1))
            {
                // Invoke at this time; pop element corresponding to this time
                epfb.times.erase(epfb.times.begin());
            }
            else {
                this->_log->trace("Not invoking environment function '{}' in "
                                  "this iteration.", epfb.name);
                return;
            }
        }
 
        this->_log->debug("Applying environment parameter function '{}' ...",
                          epfb.name);
        this->_params.set_env(epfb.param_name, epfb.func());
    }

apply_env_state_func()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

template<class ESFB >

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::apply_env_state_func ( ESFB &&  esfb )

inlineprivate

Apply a given environment state function.

Parameters

esf	EnvStateFunc that is applied to _cm.cells()

                                           {
        // Check whether to invoke
        if (not esfb.invoke_always) {
            // Compare to first element of the times set
            // NOTE This approach has a low and constant complexity as no tree
            //      traversal in the set takes place. This, however, relies on
            //      the ordering of the set and that the first element is
            //      never smaller than (current time + 1), which would lead to
            //      clogging of the erasure ...
            if (    esfb.times.size()
                and *esfb.times.begin() == (this->_time + 1))
            {
                // Invoke at this time; pop element corresponding to this time
                esfb.times.erase(esfb.times.begin());
            }
            else {
                this->_log->trace("Not invoking environment function '{}' in "
                                  "this iteration.", esfb.name);
                return;
            }
        }
 
        this->_log->debug("Applying environment state function '{}' ...",
                          esfb.name);
 
        // get EnvCellContainer over which to apply the function
        EnvCellContainer cell_selection = {};
        if (esfb.fix_selection) {
            cell_selection = esfb.cell_selection;
        }
        else if (not esfb.select_cfg.IsNull()) {
            this->_log->debug("Generating a new selection of cells for "
                              "environment state function '{}' ...", esfb.name);
            cell_selection = _cm.select_cells(esfb.select_cfg);
        }
        else {
            cell_selection = _cm.cells();
        }
 
        this->_log->debug("Applying to {} cells ...",
                          (cell_selection.size() == _cm.cells().size() ?
                           "all" : std::to_string(cell_selection.size())));
 
        // Need to distinguish by update mode
        if (esfb.update == Update::sync) {
            apply_rule<Update::sync>(esfb.func, cell_selection);
        }
        else if (esfb.update == Update::async) {
            apply_rule<Update::async>(esfb.func, cell_selection, *this->_rng);
        }
        else {
            // Throw in case the Update enum gets extended and an unexpected
            // value is passed ...
            throw std::invalid_argument("Unsupported `update` argument!");
        }
    }

cm()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

const auto & Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::cm ( ) const

inline

Return a const reference to the cell manager.

                           {
        return this->_cm;
    }

get_parameter()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

double Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::get_parameter ( const std::string &  param_name ) const

inline

Return the current value of the parameter with param_name.

                                                            {
        return this->_params.get_env(param_name);
    }

monitor()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::monitor ( )

inline

Monitor model information.

                    {
    }

perform_step()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::perform_step ( )

inline

Iterate a single step.

                         {
        for (auto& epfb : _env_param_funcs) {
            apply_env_param_func(epfb);
        }
        for (auto& esfb : _env_state_funcs) {
            apply_env_state_func(esfb);
        }
    }

set_parameter()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::set_parameter ( const std::string &  param_name, double  value  )

inline

Change the current value of the parameter with param_name.

                                                                  {
        this->_params.set_env(param_name, value);
    }

setup_env_param_funcs()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::setup_env_param_funcs ( const Config &  cfg )

inlineprivate

Construct the rule funcs sequencefor EnvParam from cfg.

                                                  {
        this->_log->info("Setting up environment param function sequence "
                         "from {} configuration entr{} ...",
                         cfg.size(), cfg.size() != 1 ? "ies" : "y");
 
        // For zombie or empty configurations, return empty container
        if (not cfg or not cfg.size()) {
            return;
        }
        // Otherwise, require a sequence
        if (not cfg.IsSequence()) {
            throw std::invalid_argument("The config for initializing the "
                "environment functions must be a sequence!");
        }
 
        // Iterate over the sequence of mappings
        for (const auto& epfs : cfg) {
            // epfs.IsMap() == true
            // The top `epfs` keys are now the names of the desired environment
            // functions. Iterate over those ...
            for (const auto& epf_pair : epfs) {
                // epf_pair is a pair of (key node, value node)
                // Find out the name of the rule function
                const auto epf_name = epf_pair.first.as<std::string>();
 
                this->_log->trace("  Function name:  {}", epf_name);
 
                // Now iterate over the (param name, param cfg) pairs
                for (const auto& kv_pair : epf_pair.second) {
                    // Get the parameter name and configuration
                    const auto param_name = kv_pair.first.as<std::string>();
                    const auto& epf_cfg = kv_pair.second;
 
                    // Distinguish by name of rule function
                    if (epf_name == "increment") {
                        auto epf = epf_increment(*this, param_name, epf_cfg);
                        add_env_param_func_from_cfg(
                            epf_name+"."+param_name, epf, param_name, epf_cfg
                        );
                    }
                    else if (epf_name == "random") {
                        auto epf = epf_random(*this, param_name, epf_cfg);
                        add_env_param_func_from_cfg(
                            epf_name+"."+param_name, epf, param_name, epf_cfg
                        );
                    }
                    else if (epf_name == "rectangular") {
                        auto epf = epf_rectangular(*this, epf_cfg);
                        add_env_param_func_from_cfg(
                            epf_name+"."+param_name, epf, param_name, epf_cfg
                        );
                    }
                    else if (epf_name == "set") {
                        auto epf = epf_set(*this, epf_cfg);
                        add_env_param_func_from_cfg(
                            epf_name+"."+param_name, epf, param_name, epf_cfg
                        );
                    }
                    else if (epf_name == "sinusoidal") {
                        auto epf = epf_sinusoidal(*this, epf_cfg);
                        add_env_param_func_from_cfg(
                            epf_name+"."+param_name, epf, param_name, epf_cfg
                        );
                    }
                    // .. can add more rule functions here (alphabetic order).
                    //    Add also in invalid_argument message below ..
                    else if (epf_name != "void") {
                        throw std::invalid_argument("No environment parameter "
                            "function '" + epf_name + "' available to "
                            "construct! Choose from: increment, random, "
                            "rectangular, set, sinusoidal.");
                    }
 
                    this->_log->debug("Added '{}' environment parameter "
                        "function for parameter '{}'.", epf_name, param_name);
                }
            }
        }
    };

setup_env_state_funcs()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

template<bool add_to_initial = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::setup_env_state_funcs ( const Config &  cfg )

inlineprivate

Construct the rule funcs sequence from cfg.

                                                  {
        this->_log->info("Setting up {}environment state function sequence "
                         "from {} configuration entr{} ...",
                         add_to_initial ? "initial " : "",
                         cfg.size(), cfg.size() != 1 ? "ies" : "y");
 
        // For zombie or empty configurations, return empty container
        if (not cfg or not cfg.size()) {
            return;
        }
        // Otherwise, require a sequence
        if (not cfg.IsSequence()) {
            throw std::invalid_argument("The config for initializing the "
                "environment state functions must be a sequence!");
        }
 
        // Iterate over the sequence of mappings
        for (const auto& esfs : cfg) {
            // esfs.IsMap() == true
            // The top `esfs` keys are now the names of the desired environment
            // functions. Iterate over those ...
            for (const auto& esf_pair : esfs) {
                // esf_pair is a pair of (key node, value node)
                // Find out the name of the rule function
                const auto esf_name = esf_pair.first.as<std::string>();
 
                this->_log->trace("  Function name:  {}", esf_name);
 
                // Now iterate over the (param name, param cfg) pairs
                for (const auto& kv_pair : esf_pair.second) {
                    // Get the parameter name and configuration
                    const auto param_name = kv_pair.first.as<std::string>();
                    const auto& esf_cfg = kv_pair.second;
 
                    // Distinguish by name of rule function
                    if (esf_name == "noise") {
                        auto esf_update_pair = esf_noise(*this, param_name,
                                                         esf_cfg);
                        add_env_state_func_from_cfg<add_to_initial>(
                            "noise."+param_name, esf_update_pair.first,
                            esf_update_pair.second, esf_cfg
                        );
                    }
                    else if (esf_name == "slope") {
                        auto esf_update_pair = esf_slope(*this, param_name,
                                                         esf_cfg,
                                                         _cm.space()->extent);
                        add_env_state_func_from_cfg<add_to_initial>(
                            "slope."+param_name, esf_update_pair.first,
                            esf_update_pair.second, esf_cfg
                        );
                    }
                    else if (esf_name == "steps") {
                        auto esf_update_pair = esf_steps(*this, param_name,
                                                         esf_cfg);
                        add_env_state_func_from_cfg<add_to_initial>(
                            "steps."+param_name, esf_update_pair.first,
                            esf_update_pair.second, esf_cfg
                        );
                    }
                    else if (esf_name == "uniform") {
                        auto esf_update_pair = esf_uniform(*this, param_name,
                                                           esf_cfg);
                        add_env_state_func_from_cfg<add_to_initial>(
                            "uniform."+param_name, esf_update_pair.first,
                            esf_update_pair.second, esf_cfg
                        );
                    }
                    // .. can add more rule functions here ..
                    else if (esf_name != "void") {
                        throw std::invalid_argument("No environment state "
                            "function '" + esf_name + "' available to "
                            "construct! Choose from: noise, slope, steps, "
                            "uniform.");
                    }
 
                    this->_log->trace("Added '{}' environment state"
                        "function for parameter '{}'.", esf_name, param_name);
                }
            }
        }
    };

track_parameter()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::track_parameter ( const std::string &  key )

inline

Mark a parameter as being tracked, i.e. store its data in write_data.

                                               {
        if (_dsets_param.find(key) != _dsets_param.end()) {
            throw std::invalid_argument("Parameter '" + key + "' is already "
                                        "being tracked!");
        }
        _dsets_param.insert({key, this->create_dset(key, {})});
    }

track_parameters()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::track_parameters ( const std::vector< std::string > &  keys )

inline

Track multiple parameters.

Invokes track_state for each entry

                                                            {
        for (const auto& key : keys) {
            track_parameter(key);
        }
    }

track_state()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::track_state ( const std::string &  key )

inline

Mark a state as being tracked, i.e. store its data in write_data.

                                           {
        if (_dsets_state.find(key) != _dsets_state.end()) {
            throw std::invalid_argument("State '" + key + "' is already "
                                        "being tracked!");
        }
        _dsets_state.insert({key, this->create_cm_dset(key, _cm)});
    }

track_states()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::track_states ( const std::vector< std::string > &  keys )

inline

Track multiple states.

Invokes track_state for each entry

                                                        {
        for (const auto& key : keys) {
            track_state(key);
        }
    }

write_data()

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

void Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::write_data ( )

inline

Write data.

For all parameters and states registered for writing, writes the values to the corresponding dataset.

Note

To register keys, use track_parameter and track_state method, respectively

                       {
        // write parameters
        for (auto& [key, dset] : _dsets_param) {
            dset->write(_params.get_env(key));
        }
 
        // write states
        for (auto& param_dset_pair : _dsets_state) {
            const auto key = std::get<0>(param_dset_pair);
            auto& dset = std::get<1>(param_dset_pair);
 
            dset->write(_cm.cells().begin(), _cm.cells().end(),
                [key](const auto& cell) {
                    return cell->state.get_env(key);
                }
            );
        }
    }

Member Data Documentation

_cm

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

CellManager Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::_cm

private

The cell manager.

_dsets_param

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

std::unordered_map<std::string, std::shared_ptr<DataSet> > Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::_dsets_param

private

Dynamically generated map of datasets of parameters.

_dsets_state

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

std::unordered_map<std::string, std::shared_ptr<DataSet> > Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::_dsets_state

private

Dynamically generated map of datasets of cell states.

_env_param_funcs

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

std::vector<EnvParamFuncBundle> Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::_env_param_funcs

private

Container of functions that are invoked every time step.

Functions changing a parameter

_env_state_funcs

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

std::vector<EnvStateFuncBundle> Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::_env_state_funcs

private

Container of rule functions that are invoked every time step.

Functions changing a state

_init_env_state_funcs

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

std::vector<EnvStateFuncBundle> Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::_init_env_state_funcs

private

Container of rule functions that are invoked once at initialisation.

Functions changing a state

_params

template<typename EnvParam = DummyEnvParam, typename EnvCellState = DummyEnvCellState, bool standalone = false>

EnvParam Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >::_params

private

The environment parameters.

---

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

• src/utopia/models/Environment/Environment.hh