Utopia::Models::ContDisease::ContDisease Class Reference

Contagious disease model on a grid. More...

#include <ContDisease.hh>

Inheritance diagram for Utopia::Models::ContDisease::ContDisease:

Collaboration diagram for Utopia::Models::ContDisease::ContDisease:

Public Types
using	Base = Model< ContDisease, CDTypes >
	The base model type.
using	DataGroup = typename Base::DataGroup
	Data type for a data group.
using	DataSet = typename Base::DataSet
	Data type for a dataset.
using	CellManager = Utopia::CellManager< CDCellTraits, ContDisease >
	Type of the CellManager to use.
using	Cell = typename CellManager::Cell
	Type of a cell.
using	CellContainer = Utopia::CellContainer< Cell >
	Type of a container of shared pointers to cells.
using	RuleFunc = typename CellManager::RuleFunc
	Rule function type.
Public Types inherited from Utopia::Model< ContDisease, CDTypes >
using	Config = typename ModelTypes::Config
	Data type that holds the configuration.
using	DataManager = DataIO::Default::DefaultDataManager< ContDisease >
	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 >
	ContDisease (const std::string &name, ParentModel &parent_model, const DataIO::Config &custom_cfg={})
	Construct the ContDisease model.
void	perform_step ()
	Iterate a single time step.
void	monitor ()
	Monitor model information.
void	write_data ()
	Write data.
Public Member Functions inherited from Utopia::Model< ContDisease, CDTypes >
	Model (const std::string &name, const ParentModel &parent_model, const Config &custom_cfg={}, std::tuple< WriterArgs... > w_args={}, const DataIO::Default::DefaultDecidermap< ContDisease > &w_deciders=DataIO::Default::default_deciders< ContDisease >, const DataIO::Default::DefaultTriggermap< ContDisease > &w_triggers=DataIO::Default::default_triggers< ContDisease >)
	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.
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.
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	update_densities ()
	Update the densities array.
void	identify_clusters ()
	Identify clusters.
void	infection_control ()
	Apply infection control.
Protected Member Functions inherited from Utopia::Model< ContDisease, CDTypes >
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.
ContDisease &	impl ()
	cast to the derived class
const ContDisease &	impl () const
	const cast to the derived interface

Protected Attributes
RuleFunc	_update
	Define the update rule.
RuleFunc	_identify_cluster
	Identify each cluster of trees.
Protected Attributes inherited from Utopia::Model< ContDisease, CDTypes >
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.

Private Attributes
CellManager	_cm
	The cell manager.
const Params	_params
	Model parameters.
std::uniform_real_distribution< double >	_prob_distr
	The range [0, 1] distribution to use for probability checks.
unsigned int	_cluster_id_cnt
	The incremental cluster tag.
std::vector< std::shared_ptr< CellManager::Cell > >	_cluster_members
	A temporary container for use in cluster identification.
std::array< double, 5 >	_densities
	Densities for all states.
bool	_write_only_densities
std::shared_ptr< DataSet >	_dset_densities
	2D dataset (densities array and time) of density values
std::shared_ptr< DataSet >	_dset_kind
	2D dataset (cell ID and time) of cell kinds
std::shared_ptr< DataSet >	_dset_age
	2D dataset (tree age and time) of cells
std::shared_ptr< DataSet >	_dset_cluster_id
	The dataset for storing the cluster ID associated with each cell.

Additional Inherited Members
Static Protected Attributes inherited from Utopia::Model< ContDisease, CDTypes >
static constexpr WriteMode	_write_mode
	Which data-writing mode the base model should use.

Detailed Description

Contagious disease model on a grid.

In this model, we model the spread of a disease through a forest on a 2D grid. Each cell can have one of five different states: empty, tree, infected, source or empty. Each time step, cells update their state according to the update rules. Empty cells will convert with a certain probability to tress, while trees represent cells that can be infected. Infection can happen either through a neighboring cells, or through random point infection. An infected cells reverts back to empty after one time step. Stones represent cells that can not be infected, therefore represent a blockade for the spread of the infection. Infection sources are cells that continuously spread infection without dying themselves. Different starting conditions, and update mechanisms can be configured.

Member Typedef Documentation

Base

using Utopia::Models::ContDisease::ContDisease::Base = Model<ContDisease, CDTypes>

The base model type.

Cell

using Utopia::Models::ContDisease::ContDisease::Cell = typename CellManager::Cell

Type of a cell.

CellContainer

using Utopia::Models::ContDisease::ContDisease::CellContainer = Utopia::CellContainer<Cell>

Type of a container of shared pointers to cells.

CellManager

using Utopia::Models::ContDisease::ContDisease::CellManager = Utopia::CellManager<CDCellTraits, ContDisease>

Type of the CellManager to use.

DataGroup

using Utopia::Models::ContDisease::ContDisease::DataGroup = typename Base::DataGroup

Data type for a data group.

DataSet

using Utopia::Models::ContDisease::ContDisease::DataSet = typename Base::DataSet

Data type for a dataset.

RuleFunc

using Utopia::Models::ContDisease::ContDisease::RuleFunc = typename CellManager::RuleFunc

Rule function type.

Constructor & Destructor Documentation

ContDisease()

template<class ParentModel >

Utopia::Models::ContDisease::ContDisease::ContDisease ( const std::string &  name, ParentModel &  parent_model, const DataIO::Config &  custom_cfg = {}  )

inline

Construct the ContDisease model.

Parameters

name	Name of this model instance; is used to extract the configuration from the parent model and set up a HDFGroup for this instance
parent_model	The parent model this model instance resides in
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),
 
        // Initialize the cell manager, binding it to this model
        _cm(*this),
 
        // Carry over Parameters
        _params(this->_cfg),
 
        // Initialize remaining members
        _prob_distr(0., 1.),
        _cluster_id_cnt(),
        _cluster_members(),
        _densities{},  // undefined here, will be set in constructor body
        _write_only_densities(get_as<bool>("write_only_densities",
                                           this->_cfg)),
 
        // Create the dataset for the densities; shape is known
        _dset_densities(this->create_dset("densities", {5})),
 
        // Create dataset for cell states
        _dset_kind(this->create_cm_dset("kind", _cm)),
 
        // Create dataset for tree age
        _dset_age(this->create_cm_dset("age", _cm)),
 
        // Create dataset for cluster id
        _dset_cluster_id(this->create_cm_dset("cluster_id", _cm))
    {
        // Make sure the densities are not undefined
        _densities.fill(std::numeric_limits<double>::quiet_NaN());
 
        // Cells are already set up by the CellManager.
        // Remaining initialization steps regard only macroscopic quantities,
        // e.g. the setup of heterogeneities: Stones and infection source.
 
        // Stones
        if (_cfg["stones"] and get_as<bool>("enabled", _cfg["stones"])) {
            this->_log->info("Setting cells to be stones ...");
 
            // Get the container
            auto to_turn_to_stone = _cm.select_cells(_cfg["stones"]);
 
            // Apply a rule to all cells of that container: turn to stone
            apply_rule<Update::async, Shuffle::off>(
                [](const auto& cell){
                    auto& state = cell->state;
                    state.kind = Kind::stone;
                    return state;
                },
                to_turn_to_stone
            );
 
            this->_log->info("Set {} cells to be stones using selection mode "
                             "'{}'.", to_turn_to_stone.size(),
                             get_as<std::string>("mode", _cfg["stones"]));
        }
        
        // Ignite some cells permanently: fire sources
        if (    _cfg["infection_source"]
            and get_as<bool>("enabled", _cfg["infection_source"]))
        {
            this->_log->info("Setting cells to be infection sources ...");
            auto source_cells = _cm.select_cells(_cfg["infection_source"]);
 
            apply_rule<Update::async, Shuffle::off>(
                [](const auto& cell){
                    auto& state = cell->state;
                    state.kind = Kind::source;
                    return state;
                },
                source_cells
            );
 
            this->_log->info("Set {} cells to be infection sources using "
                "selection mode '{}'.", source_cells.size(),
                get_as<std::string>("mode", _cfg["infection_source"]));
        }
 
        // Add attributes to density dataset that provide coordinates
        _dset_densities->add_attribute("dim_name__1", "kind");
        _dset_densities->add_attribute("coords_mode__kind", "values");
        _dset_densities->add_attribute("coords__kind",
            std::vector<std::string>{
                "empty", "tree", "infected", "source", "stone"
            });
        this->_log->debug("Added coordinates to densities dataset.");
 
        // Initialization should be finished here.
        this->_log->debug("{} model fully set up.", this->_name);
    }

Member Function Documentation

identify_clusters()

void Utopia::Models::ContDisease::ContDisease::identify_clusters ( )

inlineprotected

Identify clusters.

This function identifies clusters and updates the cell specific cluster_id as well as the member variable cluster_id_cnt that counts the number of ids

                            {
        // reset cluster counter
        _cluster_id_cnt = 0;
        apply_rule<Update::async, Shuffle::off>(_identify_cluster, 
                                                _cm.cells());
    }

infection_control()

void Utopia::Models::ContDisease::ContDisease::infection_control ( )

inlineprotected

Apply infection control.

Add infections if the iteration step matches the ones specified in the configuration. There are two available modes of infection control that are applied, if provided, in this order:

1. At specified times (parameter: at_times) a number of additional infections is added (parameter: num_additional_infections)
2. The parameter p_infect is changed to a new value at given times. This can happen multiple times. Parameter: change_p_infect

                            {
        // Check that time matches the first element of the sorted queue of 
        // time steps at which to apply the given number of infections.
        if (not _params.infection_control.at_times.empty()){
            // Check whether time has come for infections
            if (this->_time == _params.infection_control.at_times.front()){
                // Select cells that are trees 
                // (not empty, stones, infected, or source)
                const auto cells_pool =
                    _cm.select_cells<SelectionMode::condition>(
                        [&](const auto& cell){
                            return (cell->state.kind == Kind::tree);
                        }
                    );
 
                // Sample cells from the pool and ...
                CellContainer sample{};
                std::sample(
                    cells_pool.begin(), cells_pool.end(),
                    std::back_inserter(sample),
                    _params.infection_control.num_additional_infections,
                    *this->_rng
                );
                
                // ... and infect the sampled cells
                for (const auto& cell : sample){
                    cell->state.kind = Kind::infected;
                }
 
                // Done. Can now remove first element of the queue.
                _params.infection_control.at_times.pop();
            }
        }
 
        // Change p_infect if the iteration step matches the ones
        // specified in the configuration. This leads to constant time lookup.
        if (not _params.infection_control.change_p_infect.empty()) {
            const auto change_p_infect =
                _params.infection_control.change_p_infect.front();
 
            if (this->_time == change_p_infect.first) {
                _params.p_infect = change_p_infect.second;
 
                // Done. Can now remove the element from the queue.
                _params.infection_control.change_p_infect.pop();
            }
        }
    }

monitor()

void Utopia::Models::ContDisease::ContDisease::monitor ( )

inline

Monitor model information.

Supplies the densities array to the monitor.

                    {
        update_densities();
        this->_monitor.set_entry("densities", _densities);
    }

perform_step()

void Utopia::Models::ContDisease::ContDisease::perform_step ( )

inline

Iterate a single time step.

This updates all cells (synchronously) according to the _update rule. For specifics, see there.

If infection control is activated, the cells are first modified according to the specific infection control parameters.

                         {
        // Apply infection control if enabled
        if (_params.infection_control.enabled){
            infection_control();
        }
 
        // Apply the update rule to all cells.
        apply_rule<Update::sync>(_update, _cm.cells());
        // NOTE The cell state is updated synchronously, i.e.: only after all
        //      cells have been visited and know their state for the next step
    }

update_densities()

void Utopia::Models::ContDisease::ContDisease::update_densities ( )

inlineprotected

Update the densities array.

Each density is calculated by counting the number of state occurrences and afterwards dividing by the total number of cells.

Attention

It is possible that rounding errors occur due to the division, thus, it is not guaranteed that the densities exactly add up to 1. The errors should be negligible.

                            {
        // Temporarily overwrite every entry in the densities with zeroes
        _densities.fill(0);
 
        // Count the occurrence of each possible state. Use the _densities
        // member for that in order to not create a new array.
        for (const auto& cell : this->_cm.cells()) {
            // Cast enum to integer to arrive at the corresponding index
            ++_densities[static_cast<char>(cell->state.kind)];
        }
        // The _densities array now contains the counts.
 
        // Calculate the actual densities by dividing the counts by the total
        // number of cells.
        for (auto&& d : _densities){
            d /= static_cast<double>(this->_cm.cells().size());
        }
    };

write_data()

void Utopia::Models::ContDisease::ContDisease::write_data ( )

inline

Write data.

Writes out the cell state and the densities of cells with the states empty, tree, or infected (i.e.: those that may change)

                       {
        // Update densities and write them
        update_densities();
        _dset_densities->write(_densities);
        // NOTE Although stones and source density are not changing, they are
        //      calculated anyway and writing them again is not a big cost
        //      (two doubles) while making analysis much easier.
 
        // If only the densities are to be written, can stop here.
        if (_write_only_densities) {
            return;
        }
 
        // Write the cell state
        _dset_kind->write(_cm.cells().begin(), _cm.cells().end(),
            [](const auto& cell) {
                return static_cast<char>(cell->state.kind);
            }
        );
 
        // Write the tree ages
        _dset_age->write(_cm.cells().begin(), _cm.cells().end(),
            [](const auto& cell) {
                return static_cast<unsigned short int>(cell->state.age);
            }
        );
 
        // Identify clusters and write them out
        identify_clusters();
        _dset_cluster_id->write(_cm.cells().begin(), _cm.cells().end(),
            [](const auto& cell) {
                return cell->state.cluster_id;
        });
    }

Member Data Documentation

_cluster_id_cnt

unsigned int Utopia::Models::ContDisease::ContDisease::_cluster_id_cnt

private

The incremental cluster tag.

_cluster_members

std::vector<std::shared_ptr<CellManager::Cell> > Utopia::Models::ContDisease::ContDisease::_cluster_members

private

A temporary container for use in cluster identification.

_cm

CellManager Utopia::Models::ContDisease::ContDisease::_cm

private

The cell manager.

_densities

std::array<double, 5> Utopia::Models::ContDisease::ContDisease::_densities

private

Densities for all states.

Array indices are linked to Utopia::Models::ContDisease::Kind

Warning

This array is used for temporary storage; it is not automatically updated but only upon write operations.

_dset_age

std::shared_ptr<DataSet> Utopia::Models::ContDisease::ContDisease::_dset_age

private

2D dataset (tree age and time) of cells

_dset_cluster_id

std::shared_ptr<DataSet> Utopia::Models::ContDisease::ContDisease::_dset_cluster_id

private

The dataset for storing the cluster ID associated with each cell.

_dset_densities

std::shared_ptr<DataSet> Utopia::Models::ContDisease::ContDisease::_dset_densities

private

2D dataset (densities array and time) of density values

_dset_kind

std::shared_ptr<DataSet> Utopia::Models::ContDisease::ContDisease::_dset_kind

private

2D dataset (cell ID and time) of cell kinds

_identify_cluster

RuleFunc Utopia::Models::ContDisease::ContDisease::_identify_cluster

protected

Identify each cluster of trees.

                                                         {
        if (cell->state.cluster_id != 0 or cell->state.kind != Kind::tree) {
            // already labelled, nothing to do. Return current state
            return cell->state;
        }
        // else: need to label this cell
 
        // Increment the cluster ID counter and label the given cell
        _cluster_id_cnt++;
        cell->state.cluster_id = _cluster_id_cnt;
 
        // Use existing cluster member container, clear it, add current cell
        auto& cluster = _cluster_members;
        cluster.clear();
        cluster.push_back(cell);
 
        // Perform the percolation
        for (unsigned int i = 0; i < cluster.size(); ++i) {
            // Iterate over all potential cluster members c, i.e. all
            // neighbors of cell cluster[i] that is already in the cluster
            for (const auto& nb : this->_cm.neighbors_of(cluster[i])) {
                // If it is a tree that is not yet in the cluster, add it.
                if (    nb->state.cluster_id == 0
                    and nb->state.kind == Kind::tree)
                {
                    nb->state.cluster_id = _cluster_id_cnt;
                    cluster.push_back(nb);
                    // This extends the outer for-loop...
                }
            }
        }
 
        return cell->state;
    };

_params

const Params Utopia::Models::ContDisease::ContDisease::_params

private

Model parameters.

_prob_distr

std::uniform_real_distribution<double> Utopia::Models::ContDisease::ContDisease::_prob_distr

private

The range [0, 1] distribution to use for probability checks.

_update

RuleFunc Utopia::Models::ContDisease::ContDisease::_update

protected

Define the update rule.

Update the given cell according to the following rules:

• Empty cells grow trees with probability p_growth.
• Tree cells in neighborhood of an infected cell do not get infected with the probability p_immunity.
• Infected cells die and become an empty cell.

                                               {
        // Get the current state of the cell and reset its cluster ID
        auto state = cell->state;
        state.cluster_id = 0;
 
        // Distinguish by current state
        if (state.kind == Kind::empty) {
            // With a probability of p_growth, set the cell's state to tree
            if (_prob_distr(*this->_rng) < _params.p_growth){
                state.kind = Kind::tree;
                return state;
            }
        }
        else if (state.kind == Kind::tree){
            // Increase the age of the tree
            ++state.age;
 
            // Tree can be infected by neighbor or by random-point-infection.
 
            // Determine whether there will be a point infection
            if (_prob_distr(*this->_rng) < _params.p_infect) {
                // Yes, point infection occurred.
                state.kind = Kind::infected;
                return state;
            }
            else {
                // Go through neighbor cells (according to Neighborhood type),
                // and check if they are infected (or an infection source).
                // If yes, infect cell with the probability 1-p_immunity.
                for (const auto& nb: this->_cm.neighbors_of(cell)) {
                    // Get the neighbor cell's state
                    auto nb_state = nb->state;
 
                    if (   nb_state.kind == Kind::infected
                        or nb_state.kind == Kind::source)
                    {
                        // With a certain probability, become infected
                        if (_prob_distr(*this->_rng) > _params.p_immunity) {
                            state.kind = Kind::infected;
                            return state;
                        }
                    }
                }
            }
        }
        else if (state.kind == Kind::infected) {
            // Decease -> become an empty cell
            state.kind = Kind::empty;
 
            // Reset the age of the cell to 0
            state.age = 0;
 
            return state;
        }
        // else: other cell states need no update
 
        // Return the (potentially changed) cell state for the next round
        return state;
    };

_write_only_densities

bool Utopia::Models::ContDisease::ContDisease::_write_only_densities

private

---

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

• src/utopia/models/ContDisease/ContDisease.hh