Utopia::Models::ForestFire::ForestFire Class Reference

The ForestFire model. More...

#include <ForestFire.hh>

Inheritance diagram for Utopia::Models::ForestFire::ForestFire:

Collaboration diagram for Utopia::Models::ForestFire::ForestFire:

Public Types
using	Base = Model< ForestFire, ModelTypes >
	The base model type.
using	DataSet = typename Base::DataSet
	Data type for a dataset.
using	CellManager = Utopia::CellManager< CellTraits, ForestFire >
	The type of the cell manager.
using	Cell = typename CellManager::Cell
	The type of a cell.
using	RuleFunc = typename CellManager::RuleFunc
	Rule function type, extracted from CellManager.
Public Types inherited from Utopia::Model< ForestFire, ModelTypes >
using	Config = typename ModelTypes::Config
	Data type that holds the configuration.
using	DataManager = DataIO::Default::DefaultDataManager< ForestFire >
	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 >
	ForestFire (const std::string &name, ParentModel &parent_model, const DataIO::Config &custom_cfg={})
	Construct the ForestFire model.
void	perform_step ()
	Perform step.
void	monitor ()
	Provide monitoring information to the frontend: tree_density
void	write_data ()
	Write data.
Public Member Functions inherited from Utopia::Model< ForestFire, ModelTypes >
	Model (const std::string &name, const ParentModel &parent_model, const Config &custom_cfg={}, std::tuple< WriterArgs... > w_args={}, const DataIO::Default::DefaultDecidermap< ForestFire > &w_deciders=DataIO::Default::default_deciders< ForestFire >, const DataIO::Default::DefaultTriggermap< ForestFire > &w_triggers=DataIO::Default::default_triggers< ForestFire >)
	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.

Private Member Functions
double	calculate_tree_density () const
	Calculate and return the density of tree cells.
unsigned int	identify_clusters ()
	Identifies clusters in the cells and labels them with corresponding IDs.

Private Attributes
CellManager	_cm
	The cell manager for the forest fire model.
const Param	_param
	Model parameters.
std::uniform_real_distribution< double >	_prob_distr
	A [0,1]-range uniform distribution used for evaluating probabilities.
unsigned int	_cluster_id_cnt
	The incremental cluster tag caching variable.
std::vector< std::shared_ptr< CellManager::Cell > >	_cluster_members
	A temporary container for use in cluster identification.
const bool	_write_only_tree_density
	Whether to only write the tree density.
const std::shared_ptr< DataSet >	_dset_kind
	The dataset that stores the kind for each cell, e.g. Kind::tree.
const std::shared_ptr< DataSet >	_dset_age
	2D dataset (tree age and time) of cells
const std::shared_ptr< DataSet >	_dset_cluster_id
	The dataset that stores the cluster id.
const std::shared_ptr< DataSet >	_dset_tree_density
	The dataset that stores the mean density.
RuleFunc	_update
	Update rule, called every step.
RuleFunc	_burn_cluster
	Rule to burn a cluster of trees around the given cell.
RuleFunc	_identify_cluster
	Get the identity of each cluster of trees.

Additional Inherited Members
Protected Member Functions inherited from Utopia::Model< ForestFire, 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.
ForestFire &	impl ()
	cast to the derived class
const ForestFire &	impl () const
	const cast to the derived interface
Protected Attributes inherited from Utopia::Model< ForestFire, 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< ForestFire, ModelTypes >
static constexpr WriteMode	_write_mode
	Which data-writing mode the base model should use.

Detailed Description

The ForestFire model.

The ForestFire model simulates the development of a forest under influence of fires. Trees grow randomly and lightning strikes lead to a whole cluster instantaneously burning down. This is the so-called two state model.

Member Typedef Documentation

Base

using Utopia::Models::ForestFire::ForestFire::Base = Model<ForestFire, ModelTypes>

The base model type.

Cell

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

The type of a cell.

CellManager

using Utopia::Models::ForestFire::ForestFire::CellManager = Utopia::CellManager<CellTraits, ForestFire>

The type of the cell manager.

DataSet

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

Data type for a dataset.

RuleFunc

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

Rule function type, extracted from CellManager.

Constructor & Destructor Documentation

ForestFire()

template<class ParentModel >

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

inline

Construct the ForestFire 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
        _param(this->_cfg),
 
        // Initialize remaining members
        _prob_distr(0., 1.),
        _cluster_id_cnt(0),
        _cluster_members(),
        _write_only_tree_density(get_as<bool>("write_only_tree_density",
                                              this->_cfg)),
 
        // Create datasets using the helper functions for CellManager-data
        _dset_kind{this->create_cm_dset("kind", _cm)},
        _dset_age{this->create_cm_dset("age", _cm)},
        _dset_cluster_id{this->create_cm_dset("cluster_id", _cm)},
        _dset_tree_density{this->create_dset("tree_density", {})}
    {
        // Cells are already set up in the CellManager.
        // Take care of the heterogeneities now:
 
        // 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["ignite_permanently"]
            and get_as<bool>("enabled", _cfg["ignite_permanently"]))
        {
            this->_log->info("Setting cells to be permanently ignited ...");
            auto to_be_ignited = _cm.select_cells(_cfg["ignite_permanently"]);
 
            apply_rule<Update::async, Shuffle::off>(
                [](const auto& cell){
                    auto& state = cell->state;
                    state.kind = Kind::source;
                    return state;
                },
                to_be_ignited
            );
 
            this->_log->info("Set {} cells to be permanently ignited using "
                "selection mode '{}'.", to_be_ignited.size(),
                get_as<std::string>("mode", _cfg["ignite_permanently"]));
        }
 
        this->_log->debug("{} model fully set up.", this->_name);
    }

Member Function Documentation

calculate_tree_density()

double Utopia::Models::ForestFire::ForestFire::calculate_tree_density ( ) const

inlineprivate

Calculate and return the density of tree cells.

                                          {
        // NOTE If execution policies are implemented, this could be easily
        //      made parallel by replacing std::accumulate with std::reduce
        //      and adding std::execution::par from the header
        //      <execution> as first argument.
        return
            std::accumulate(_cm.cells().begin(), _cm.cells().end(),
                0,
                [&](std::size_t sum, const std::shared_ptr<Cell>& cell) {
                    return sum + (cell->state.kind == Kind::tree);
                }
            )
            / static_cast<double>(_cm.cells().size());
    }

identify_clusters()

unsigned int Utopia::Models::ForestFire::ForestFire::identify_clusters ( )

inlineprivate

Identifies clusters in the cells and labels them with corresponding IDs.

This function updates the cluster ID of each cell. This only applies to cells that are trees; all others keep ID 0.

Returns

Number of clusters identified

                                     {
        this->_log->debug("Identifying clusters...");
 
        // Reset counter for cluster IDs, then call the identification function
        _cluster_id_cnt = 0;
 
        apply_rule<Update::async, Shuffle::off>(
            _identify_cluster, _cm.cells()
        );
 
        this->_log->debug("Identified {} clusters.", _cluster_id_cnt);
 
        return _cluster_id_cnt;
    }

monitor()

void Utopia::Models::ForestFire::ForestFire::monitor ( )

inline

Provide monitoring information to the frontend: tree_density

                    {
        this->_monitor.set_entry("tree_density", calculate_tree_density());
    }

perform_step()

void Utopia::Models::ForestFire::ForestFire::perform_step ( )

inline

Perform step.

                         {
        // Apply update rule on all cells, asynchronously and shuffled
        apply_rule<Update::async, Shuffle::on>(
            _update, _cm.cells(), *this->_rng
        );
    }

write_data()

void Utopia::Models::ForestFire::ForestFire::write_data ( )

inline

Write data.

                       {
        // Calculate and write the tree density
        _dset_tree_density->write(calculate_tree_density());
 
        if (_write_only_tree_density) {
            // Done here.
            return;
        }
 
        // Store all cells' kind
        _dset_kind->write(_cm.cells().begin(), _cm.cells().end(),
            [](const auto& cell) {
                return static_cast<char>(cell->state.kind);
        });
 
        // ... and age
        _dset_age->write(_cm.cells().begin(), _cm.cells().end(),
            [](const auto& cell) {
                return cell->state.age;
        });
 
        // Identify the clusters (only needed when actually writing)
        identify_clusters();
        _dset_cluster_id->write(_cm.cells().begin(), _cm.cells().end(),
            [](const auto& cell) {
                return cell->state.cluster_id;
        });
    }

Member Data Documentation

_burn_cluster

RuleFunc Utopia::Models::ForestFire::ForestFire::_burn_cluster

private

Rule to burn a cluster of trees around the given cell.

Note

This function is never actually called via apply_rule, but only from the update method. It relies on an asynchronous cell update.

                                                      {
        // A tree cell should burn, i.e.: transition to empty.
        if (cell->state.kind == Kind::tree) {
            cell->state.kind = Kind::empty;
        }
        // The only other possibility would be a fire source: remains alight!
 
        // Use existing cluster member container, clear it, add current cell
        auto& cluster = _cluster_members;
        cluster.clear();
        cluster.push_back(cell);
 
        // Recursively go over all cluster members
        for (unsigned int i = 0; i < cluster.size(); ++i) {
            const auto& cluster_member = cluster[i];
 
            // Iterate over all potential cluster members
            for (const auto& c : this->_cm.neighbors_of(cluster_member)) {
                // If it is a tree, it will burn ...
                if (c->state.kind == Kind::tree) {
                    // ... unless there is p_immunity > 0 ...
                    if (this->_param.p_immunity > 0.) {
                        // ... where there is a chance not to burn:
                        if (  this->_prob_distr(*this->_rng)
                            < _param.p_immunity) {
                            continue;
                        }
                    }
 
                    // Bad luck. Burn.
                    c->state.kind = Kind::empty;
                    c->state.age = 0;
                    cluster.push_back(c);
                    // This extends the outer for-loop
                }
            }
        }
 
        // Return the current cell's adjusted state.
        return cell->state;
    };

_cluster_id_cnt

unsigned int Utopia::Models::ForestFire::ForestFire::_cluster_id_cnt

private

The incremental cluster tag caching variable.

_cluster_members

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

private

A temporary container for use in cluster identification.

_cm

CellManager Utopia::Models::ForestFire::ForestFire::_cm

private

The cell manager for the forest fire model.

_dset_age

const std::shared_ptr<DataSet> Utopia::Models::ForestFire::ForestFire::_dset_age

private

2D dataset (tree age and time) of cells

_dset_cluster_id

const std::shared_ptr<DataSet> Utopia::Models::ForestFire::ForestFire::_dset_cluster_id

private

The dataset that stores the cluster id.

_dset_kind

const std::shared_ptr<DataSet> Utopia::Models::ForestFire::ForestFire::_dset_kind

private

The dataset that stores the kind for each cell, e.g. Kind::tree.

_dset_tree_density

const std::shared_ptr<DataSet> Utopia::Models::ForestFire::ForestFire::_dset_tree_density

private

The dataset that stores the mean density.

_identify_cluster

RuleFunc Utopia::Models::ForestFire::ForestFire::_identify_cluster

private

Get the identity of each cluster of trees.

                                                         {
        // Only need to continue if a tree and not already labelled
        if (   cell->state.cluster_id != 0
            or cell->state.kind != Kind::tree)
        {
            return cell->state;
        }
        // else: is an unlabelled tree; need to label it.
 
        // 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& c : this->_cm.neighbors_of(cluster[i])) {
                // If it is a tree that is not yet in the cluster, add it.
                if (    c->state.cluster_id == 0
                    and c->state.kind == Kind::tree)
                {
                    c->state.cluster_id = _cluster_id_cnt;
                    cluster.push_back(c);
                    // This extends the outer for-loop...
                }
            }
        }
 
        return cell->state;
    };

_param

const Param Utopia::Models::ForestFire::ForestFire::_param

private

Model parameters.

_prob_distr

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

private

A [0,1]-range uniform distribution used for evaluating probabilities.

_update

RuleFunc Utopia::Models::ForestFire::ForestFire::_update

private

Update rule, called every step.

The possible transitions are the following:

- empty -> tree (with p_growth)
- tree -> burning (with p_lightning)

A burning tree directly invokes the burning of the whole cluster of connected trees ("two-state FFM"). After that, all burned cells are in the empty state again.

Additionally, some trees are constantly ignited and will always lead to the burning of the adjacent cluster. Other cells ("stones") do not take part in interactions at all.

Note

This rule relies on an asynchronous cell update.

                                               {
        // Get the current state of the cell and reset the cluster tag
        auto& state = cell->state;
        state.cluster_id = 0;
 
        // Empty cells can grow a tree
        if (state.kind == Kind::empty) {
            if (this->_prob_distr(*this->_rng) < _param.p_growth) {
                state.kind = Kind::tree;
            }
        }
 
        // Trees can be hit by lightning or continue living
        else if (state.kind == Kind::tree) {
            // Can be hit by lightning
            if (this->_prob_distr(*this->_rng) < _param.p_lightning) {
                state = _burn_cluster(cell);
            }
            else {
                // Lives. Increase its age
                state.age++;
            }
        }
 
        // Permanently ignited cells always burn the cluster
        else if (state.kind == Kind::source) {
            state = _burn_cluster(cell);
        }
 
        // Stones don't do anything
        else if (state.kind == Kind::stone) {
            // Not doing anything, like the good stone I am ...
        }
 
        else {
            // Should never occur!
            throw std::invalid_argument("Invalid cell state!");
        }
 
        return state;
    };

_write_only_tree_density

const bool Utopia::Models::ForestFire::ForestFire::_write_only_tree_density

private

Whether to only write the tree density.

---

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

• src/utopia/models/ForestFire/ForestFire.hh