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

#include <model.hh>

Inheritance diagram for Utopia::Model< Derived, ModelTypes >:

[legend]

Collaboration diagram for Utopia::Model< Derived, ModelTypes >:

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

Protected Member Functions
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
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
static constexpr WriteMode	_write_mode = ModelTypes::write_mode
	Which data-writing mode the base model should use.

Private Member Functions
template<class Parent >
auto	setup_logger (const Parent &parent_model) const
	Constructs this models logger instance from the parent.

auto	setup_space () const
	Constructs the Space from configuration or uses the default Space.

void	__attach_sig_handlers () const
	Attaches signal handlers: SIGINT, SIGTERM, SIGUSR1.

Detailed Description

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

Base class interface for Models using the CRT Pattern.

Template Parameters

Derived	Type of the derived model class
ModelTypes	Traits 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

ParentModel The parent model's type

Parameters

name	The name of this model instance, ideally used only once on the current hierarchical level
parent_model	The parent model object from which the corresponding config node, the group, the RNG, and the parent log level are extracted.
custom_cfg	If given, will use this configuration node instead of trying to extract one from the parent model's configuration.
w_args	Passed on to DataManager constructor. If not given, the DataManager will still be constructed. Take care to also set the WriteMode accordingly.
w_deciders	Map which associates names with factory functions for deciders of signature factory()shared_ptr<Decider<Derived>>
w_triggers	Map which associates names with factory functions for triggers of signature factory()shared_ptr<Trigger<Derived>>

                                   {},
        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 >
        )
    :
        // First thing: setup name and position within model hierarchy
        _name(name),
        _full_name(parent_model.get_full_name() + "." + name),
        _level(parent_model.get_level() + 1),
 
        // Retrieve the appropriate configuration entry from the parent model
        _cfg(custom_cfg.size() ? custom_cfg
             : get_as<Config>(_name, parent_model.get_cfg())),
 
        // Construct infrastructure objects using information from parent
        _rng(parent_model.get_rng()),
        _log(setup_logger(parent_model)),
 
        // Determine space and time
        _space(setup_space()),
        _time(0),
        _time_max(_level == 1 ? parent_model.get_time_max()
                  : get_as<Time>("num_steps", _cfg,
                                 std::numeric_limits<Time>::max())),
 
        // Extract the other information from the parent model object
        _hdfgrp(parent_model.get_hdfgrp()->open_group(_name)),
        _write_start(get_as<Time>("write_start", _cfg,
                                  parent_model.get_write_start())),
        _write_every(get_as<Time>("write_every", _cfg,
                                  parent_model.get_write_every())),
 
        // Set up the monitor, using the parent model's monitor to place it in
        // a hierarchy equivalent to the model hierarchy
        _monitor(_name, parent_model.get_monitor()),
 
        // Default-construct the data maanger; only used if needed, see below.
        _datamanager()
    {
        // Provide some information, also depending on write mode
        _log->info("Model base constructor for '{}' finished.", _name);
        _log->info("  full_name:   {}", _full_name);
        _log->info("  level:       {}", _level);
        _log->info("  time_max:    {:7d}", _time_max);
 
        if constexpr (_write_mode == WriteMode::basic) {
            _log->info("  write_mode:  {:>7s}", "basic");
            _log->info("  write_start: {:7d}", _write_start);
            _log->info("  write_every: {:7d}", _write_every);
            _log->info("  #writes:     {:7d}", get_remaining_num_writes());
 
            // Store relevant info in base group attributes
            _hdfgrp->add_attribute("write_mode", "basic");
            _hdfgrp->add_attribute("write_start", _write_start);
            _hdfgrp->add_attribute("write_every", _write_every);
            _hdfgrp->add_attribute("time_max",    _time_max);
        }
        else if constexpr (_write_mode == WriteMode::manual) {
            _log->info("  write_mode:  {:>7s}", "manual");
            _hdfgrp->add_attribute("write_mode", "manual");
        }
        else if constexpr (_write_mode == WriteMode::off) {
            _log->info("  write_mode:  {:>7s}", "off");
            _hdfgrp->add_attribute("write_mode", "off");
        }
        else if constexpr (_write_mode == WriteMode::managed) {
            static_assert(sizeof...(WriterArgs) > 0,
                          "No arguments to construct write_tasks given!");
 
            _log->info("  write_mode:  {:>7s}", "managed");
 
            // Store relevant info in base group attributes
            _hdfgrp->add_attribute("write_mode", "managed");
 
            // Some convenience key checks for nicer error messages.
            if (not _cfg["data_manager"]) {
                throw KeyError("data_manager", _cfg,
                               "Cannot set up DataManager!");
            }
            const auto dm_cfg = _cfg["data_manager"];
 
            if (not dm_cfg["tasks"]) {
                throw KeyError("tasks", dm_cfg,
                               "Cannot set up DataManager tasks!");
            }
            if (not dm_cfg["deciders"]) {
                throw KeyError("deciders", dm_cfg,
                               "Cannot set up DataManager deciders!");
            }
            if (not dm_cfg["triggers"]) {
                throw KeyError("triggers", dm_cfg,
                               "Cannot set up DataManager triggers!");
            }
 
            _log->info("Invoking DataManager task factory ...");
 
            _datamanager = DataIO::DataManagerFactory<Derived>()(
                dm_cfg, w_args, w_deciders, w_triggers
            );
 
            _log->info("DataManager set up with {} task(s), {} decider(s), "
                       "and {} trigger(s).", _datamanager.get_tasks().size(),
                       _datamanager.get_deciders().size(),
                       _datamanager.get_triggers().size());
        }
    }

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.

                                       {
        _log->debug("Attaching signal handlers for SIGINT and SIGTERM ...");
 
        attach_signal_handler(SIGINT);
        attach_signal_handler(SIGTERM);
 
        _log->debug("Attaching signal handler for stop conditions, triggered "
                    "by SIGUSR1 ({:d}) ...", SIGUSR1);
        attach_signal_handler(SIGUSR1);
 
        _log->debug("Signal handlers attached.");
    }

◆ __epilog()

template<class Derived , typename ModelTypes >

void Utopia::Model< Derived, ModelTypes >::__epilog ( )

inlineprotected

The default epilog of a model.

Default tasks: None

                     {
        this->_log->debug("Epilog finished.");
    }

◆ __monitor()

template<class Derived , typename ModelTypes >

void Utopia::Model< Derived, ModelTypes >::__monitor ( )

inlineprotected

Monitor information in the terminal.

                      {
        if (_monitor.get_monitor_manager()->emit_enabled()) {
            // Perform actions that should only happen once by the monitor at
            // the highest level of the model hierarchy.
            if (_level == 1){
                // Supply the global time. When reaching this point, all sub-
                // models will also have reached this time.
                _monitor.get_monitor_manager()->set_time_entries(_time,
                                                                 _time_max);
                // This method also sets the other top level entries
            }
 
            // Call the child's implementation of the monitor functions.
            impl().monitor();
        }
    }

◆ __perform_step()

template<class Derived , typename ModelTypes >

void Utopia::Model< Derived, ModelTypes >::__perform_step ( )

inlineprotected

Perform the computation of a step.

                           {
        impl().perform_step();
    }

◆ __prolog()

template<class Derived , typename ModelTypes >

void Utopia::Model< Derived, ModelTypes >::__prolog ( )

inlineprotected

The default prolog of a model.

Default tasks:

call __write_initial_state

                     {
        __write_initial_state();
 
        this->_log->debug("Prolog finished.");
    }

◆ __write_data()

template<class Derived , typename ModelTypes >

void Utopia::Model< Derived, ModelTypes >::__write_data ( )

inlineprotected

Write data; calls the implementation's write_data method.

                         {
        _log->trace("Calling write_data ...");
        impl().write_data();
    }

◆ __write_initial_state()

template<class Derived , typename ModelTypes >

void Utopia::Model< Derived, ModelTypes >::__write_initial_state ( )

inlineprotected

Write the initial state.

                                  {
        // Select the required WriteMode
        // Decide on whether the initial state needs to be written
        if constexpr (_write_mode == WriteMode::basic) {
            if (_write_start == _time) {
                _log->info("Writing initial state ...");
                __write_data();
            }
        }
        else if constexpr (_write_mode == WriteMode::manual) {
            __write_data();
        }
        else if constexpr (_write_mode == WriteMode::managed) {
            _datamanager(static_cast<Derived&>(*this));
        }
 
    }

◆ 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

name	The name of the dataset
am	The AgentManager whose agents' states are to be stored in the dataset
compression_level	The compression level
chunksize	The chunk size

Returns: std::shared_ptr<DataSet> The newly created HDFDataset

                                                            {})    
    {
        // Forward to the main create_dset function
        const auto dset = create_dset(
            name,
            _hdfgrp,
            {am.agents().size()},  // --> 2D: time, agents
            compression_level,
            chunksize
        );
 
        // Set attribute to store the agent managers' extent of space
        dset->add_attribute("space_extent", am.space()->extent);
        _log->debug("Added attribute to dataset '{}' to store space extent",
                    name);
        
        // Write additional attributes, if not specifically suppressed.
        if (get_as<bool>("write_dim_labels_and_coords", _cfg, true)) {
            // We know that the dimensions here refer to (time, agent ids). The
            // time information is already added in create_dset; add only ID
            // information here. Note that this assumes trivial and constant
            // agent IDs!
            dset->add_attribute("dim_name__1", "ids");
 
            // For ids, the dimensions are trivial
            dset->add_attribute("coords_mode__ids", "trivial");
                                 
           _log->debug("Added agent index dimension labels and coordinates "
                       "to dataset '{}'.", name);
        }
 
        return dset;
    }

◆ 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

name	The name of the dataset
cm	The CellManager whose cells' states are to be stored in the dataset
compression_level	The compression level
chunksize	The chunk size

Returns: std::shared_ptr<DataSet> The newly created HDFDataset

                                                          {})
    {
        // Forward to the main create_dset function
        const auto dset = create_dset(
            name,
            _hdfgrp,
            {cm.cells().size()}, // -> 2D dataset
            compression_level,
            chunksize
        );
 
        // Set attributes to mark this dataset as containing grid data
        dset->add_attribute("content", "grid");
 
        // Need further attributes to denote the grid structure, size, etc.
        const auto grid_structure = cm.grid()->structure_name();
        dset->add_attribute("grid_structure", grid_structure);
        dset->add_attribute("grid_shape", cm.grid()->shape());
        dset->add_attribute("space_extent", cm.grid()->space()->extent);
        dset->add_attribute("periodic_space", cm.grid()->space()->periodic);
 
        if (grid_structure == "hexagonal") {
            // ... some additional info is needed, which is dependent on the
            // way the HexagonalGrid maps cells
            dset->add_attribute("coordinate_mode", "offset");
            dset->add_attribute("offset_mode", "even");
            dset->add_attribute("pointy_top", true);
        }
 
        // The CellManager uses "column-style" index ordering, also called
        // "Fortran-style". This is relevant for assigning the correct IDs.
        dset->add_attribute("index_order", "F");
 
        _log->debug("Added attributes to dataset '{}' to mark it as storing "
                    "grid data.", name);
 
        // Write additional attributes, if not specifically suppressed.
        if (get_as<bool>("write_dim_labels_and_coords", _cfg, true)) {
            // We know that the dimensions here refer to (time, cell ids).
            // The time information is already added in create_dset; only need
            // to add the ID information here
            dset->add_attribute("dim_name__1", "ids");
 
            // For ids, the dimensions are trivial
            dset->add_attribute("coords_mode__ids", "range");
            dset->add_attribute("coords__ids",
                                std::vector<std::size_t>{cm.cells().size()});
 
            _log->debug("Added cell ID dimension labels and coordinates to "
                        "dataset '{}'.", name);
        }
 
        return dset;
    }

◆ 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

name	The name of the dataset
hdfgrp	The parent HDFGroup
add_write_shape	Additional 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_level	The compression level
chunksize	The chunk size

Returns: std::shared_ptr<DataSet> The hdf dataset

                                                       {})
    {
        _log->debug("Creating dataset '{}' in group '{}' ...",
                    name, hdfgrp->get_path());
 
        // Calculate the number of time steps to be written
        const hsize_t num_write_ops = get_remaining_num_writes();
 
        // Calculate the shape of the dataset
        add_write_shape.insert(add_write_shape.begin(), num_write_ops);
        auto capacity = add_write_shape;
 
        // Create the dataset and return it.
        const auto dset = hdfgrp->open_dataset(name, capacity,
                                               chunksize, compression_level);
        _log->debug("Successfully created dataset '{}'.", name);
 
        // Write further attributes, if not specifically suppressed
        if (get_as<bool>("write_dim_labels_and_coords", _cfg, true)) {
            // We know that dimension 0 is the time dimension. Add the
            // attributes that specify dimension names and coordinates:
            dset->add_attribute("dim_name__0", "time");
            dset->add_attribute("coords_mode__time", "start_and_step");
            dset->add_attribute("coords__time",
                                std::vector<std::size_t>{_write_start,
                                                         _write_every});
            _log->debug("Added time dimension labels and coordinates to "
                        "dataset '{}'.", name);
        }
 
        return dset;
    }

◆ 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

name	The name of the dataset
add_write_shape	Additional 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_level	The compression level
chunksize	The chunk size

Returns: std::shared_ptr<DataSet> The hdf dataset

                                                       {})
    {
        // Forward to the main create_dset function
        return create_dset(name,
                           _hdfgrp, // The base group for this model
                           add_write_shape, compression_level, chunksize);
    }

◆ 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

                           {
        __epilog();
    }

◆ get_cfg()

template<class Derived , typename ModelTypes >

Config Utopia::Model< Derived, ModelTypes >::get_cfg ( ) const

inline

Return the config node of this model.

                           {
        return _cfg;
    }

◆ get_datamanager()

template<class Derived , typename ModelTypes >

DataManager Utopia::Model< Derived, ModelTypes >::get_datamanager ( ) const

inline

return the datamanager

                                        {
        return _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.

                                    {
        return _full_name;
    }

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

                                                {
        return _hdfgrp;
    }

◆ get_level()

template<class Derived , typename ModelTypes >

Level Utopia::Model< Derived, ModelTypes >::get_level ( ) const

inline

Return the hierarchical level within the model hierarchy.

                            {
        return _level;
    }

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

                                                   {
        return _log;
    }

◆ get_monitor()

template<class Derived , typename ModelTypes >

Monitor Utopia::Model< Derived, ModelTypes >::get_monitor ( ) const

inline

Return the monitor of this model.

                                {
        return _monitor;
    }

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

                                                              {
        return _monitor.get_monitor_manager();
    }

◆ get_name()

template<class Derived , typename ModelTypes >

std::string Utopia::Model< Derived, ModelTypes >::get_name ( ) const

inline

Return the name of this model instance.

                               {
        return _name;
    }

◆ 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

                                             {
        static_assert(
            _write_mode == WriteMode::basic or
            _write_mode == WriteMode::manual or
            _write_mode == WriteMode::off or
            _write_mode == WriteMode::managed
        );
 
        if constexpr (_write_mode == WriteMode::basic) {
            if (_time_max == std::numeric_limits<hsize_t>::max()) {
                return std::numeric_limits<hsize_t>::max();
            }
            return (  (_time_max - std::max(_time, _write_start))
                    / _write_every) + 1;
        }
        else if constexpr (_write_mode == WriteMode::manual) {
            if (_time_max - _time == std::numeric_limits<hsize_t>::max()) {
                return std::numeric_limits<hsize_t>::max();
            }
            return _time_max - _time + 1;
        }
        else {
            return 0;
        }
 
    }

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

                                       {
        return _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.

                                                  {
        return _space;
    }

◆ get_time()

template<class Derived , typename ModelTypes >

Time Utopia::Model< Derived, ModelTypes >::get_time ( ) const

inline

Return the current time of this model.

                          {
        return _time;
    }

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

                              {
        if (_time_max == std::numeric_limits<Time>::max()) {
            this->_log->warn("Accessing the `time_max` of (sub-)model {} with "
                "unlimited value!", this->get_full_name());
        }
        return _time_max;
    }

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

                                 {
        return _write_every;
    }

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

                                 {
        return _write_start;
    }

◆ impl() [1/2]

template<class Derived , typename ModelTypes >

Derived & Utopia::Model< Derived, ModelTypes >::impl ( )

inlineprotected

cast to the derived class

                     {
        return static_cast<Derived&>(*this);
    }

◆ impl() [2/2]

template<class Derived , typename ModelTypes >

const Derived & Utopia::Model< Derived, ModelTypes >::impl ( ) const

inlineprotected

const cast to the derived interface

                                 {
        return static_cast<const Derived&>(*this);
    }

◆ increment_time()

template<class Derived , typename ModelTypes >

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

inlineprotected

Increment time.

Parameters

dt	Time increment, defaults to 1

                                          {
        _time += dt;
    }

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

                    {
        // -- Perform the simulation step
        __perform_step();
        increment_time();
 
        // -- Monitoring
        /* If the model is at the first hierarchical level, check whether the
         * monitor entries should be collected and emitted. This leads to a
         * flag being set in the monitor manager, such that the submodels do
         * not have to do the check against the timer as well and that all
         * collected data stems from the same time step.
         */
        if (_level == 1) {
            _monitor.get_monitor_manager()->check_timer();
            __monitor();
 
            // If enabled for this step, perform the emission of monitor data
            // NOTE At this point, we can be sure that all submodels have
            //      already run, because their iterate functions were called
            //      in the perform_step of the level 1 model.
            _monitor.get_monitor_manager()->emit_if_enabled();
        }
        else {
            __monitor();
        }
 
        // -- Data output
        if constexpr (_write_mode == WriteMode::basic) {
            if (    (_time >= _write_start)
                and (_time - _write_start) % _write_every == 0) {
                __write_data();
            }
        }
        else if constexpr (_write_mode == WriteMode::manual) {
            __write_data();
        }
        else if constexpr (_write_mode == WriteMode::managed) {
            _datamanager(static_cast<Derived&>(*this));
        }
 
        if (_level == 1) {
            _log->debug("Finished iteration: {:7d} / {:d}", _time, _time_max);
        }
        else {
            _log->debug("Finished iteration: {:7d}", _time);
        }
    }

◆ 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

                           {
        __prolog();
    }

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

                {
        if (_level > 1 and get_time_max() == std::numeric_limits<Time>::max()) {
            throw std::runtime_error(fmt::format("Cannot perform run on "
                "(sub-)model {} with unlimited `time_max`. You need to provide "
                "`num_steps` to the model's configuration in order to use the "
                "`run` method. See the nested models guide for further "
                "information!", get_full_name()));
        }
 
        // First, attach the signal handler, such that the while loop below can
        // be left upon receiving of a signal.
        __attach_sig_handlers();
 
        // call the prolog of the model
        prolog();
 
        // Now, let's go repeatedly iterate the model ...
        _log->info("Running from current time  {}  to  {}  ...",
                   _time, _time_max);
 
        while (_time < _time_max) {
            iterate();
 
            if (stop_now.load()) {
                const auto signum = received_signum.load();
 
                if (signum == SIGUSR1) {
                    _log->warn("The stop condition for this run is fulfilled. "
                               "Not iterating further ...");
                }
                else {
                    _log->warn("Was told to stop. Not iterating further ...");
                }
 
                _log->info("Invoking epilog ...");
                epilog();
 
                throw GotSignal(received_signum.load());
            }
        }
 
        _log->info("Run finished. Current time:  {}", _time);
 
        // call the epilog of the model
        epilog();
    }

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

                                                        {
        auto log = spdlog::stdout_color_mt(
            parent_model.get_logger()->name() + "." + _name
        );
 
        // Set this model instance's log level
        if (_cfg["log_level"]) {
            // Via value given in configuration
            const auto lvl = get_as<std::string>("log_level", _cfg);
            log->debug("Setting log level to '{}' ...", lvl);
            log->set_level(spdlog::level::from_str(lvl));
        }
        else {
            // No config value given; use the level of the parent's logger
            log->set_level(parent_model.get_logger()->level());
        }
 
        log->info("Model logger initialized.");
        return log;
    }

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

                             {
        if (_cfg["space"]) {
            auto space = std::make_shared<Space>(_cfg["space"]);
            _log->info(
                "Using {}periodic space with extent {}.",
                space->periodic ? "" : "non-", Utils::str(space->extent)
            );
            return space;
        }
        else {
            _log->debug(
                "No model-level space configured; using default space."
            );
            return std::make_shared<Space>();
        }
    }