Utopia::Models::SimpleEG::SimpleEG Class Reference

Simple model of evolutionary games on grids. More...

#include <SimpleEG.hh>

Inheritance diagram for Utopia::Models::SimpleEG::SimpleEG:

Collaboration diagram for Utopia::Models::SimpleEG::SimpleEG:

Public Types
using	Base = Model< SimpleEG, ModelTypes >
	The base model.
using	Config = typename Base::Config
	Data type that holds the configuration.
using	DataSet = typename Base::DataSet
	Data type for a dataset.
using	CellManager = Utopia::CellManager< CellTraits, SimpleEG >
	Type of the CellManager to use.
using	RuleFunc = typename CellManager::RuleFunc
	Extract the type of the rule function from the CellManager.
using	RNG = typename Base::RNG
	Data type of the shared RNG.
using	IAMatrixType = typename std::array< std::array< double, 2 >, 2 >
	Type of the interaction matrix.
Public Types inherited from Utopia::Model< SimpleEG, ModelTypes >
using	Config = typename ModelTypes::Config
	Data type that holds the configuration.
using	DataManager = DataIO::Default::DefaultDataManager< SimpleEG >
	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 >
	SimpleEG (const std::string &name, ParentModel &parent_model, const DataIO::Config &custom_cfg={})
	Construct the SimpleEG model.
void	perform_step ()
	Iterate a single step.
void	monitor ()
	Monitor model information.
void	write_data ()
	Write data: the strategy and payoff of each cell.
Public Member Functions inherited from Utopia::Model< SimpleEG, ModelTypes >
	Model (const std::string &name, const ParentModel &parent_model, const Config &custom_cfg={}, std::tuple< WriterArgs... > w_args={}, const DataIO::Default::DefaultDecidermap< SimpleEG > &w_deciders=DataIO::Default::default_deciders< SimpleEG >, const DataIO::Default::DefaultTriggermap< SimpleEG > &w_triggers=DataIO::Default::default_triggers< SimpleEG >)
	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
void	initialize_cells ()
	Initialize the cells according to initial_state config parameter.
IAMatrixType	extract_ia_matrix () const
	Extract the interaction matrix from the config file.

Private Attributes
CellManager	_cm
	The cell manager.
const IAMatrixType	_ia_matrix
	The interaction matrix (extracted during initialization)
CellContainer< typename CellManager::Cell >	_fittest_cells_in_nbhood
	A container to temporarily accumulate the fittest neighbor cells in.
std::uniform_real_distribution< double >	_prob_distr
	Uniform real distribution in [0., 1.) used for evaluating probabilities.
std::shared_ptr< DataSet >	_dset_strategy
	Stores cell strategies over time.
std::shared_ptr< DataSet >	_dset_payoff
	Stores cell payoffs over time.
RuleFunc	_interaction
	The interaction between players.
RuleFunc	_update
	The update rule.

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

Detailed Description

Simple model of evolutionary games on grids.

In this model, cells have an internal strategy, which determines their success in the interactions with their neighboring cells. The success is given by an interaction matrix. In one interaction step, every cell interacts with all its neighboring cells (interaction lambda function). Afterwards, all cells are updated synchronously (update lambda function). From a cells perspective, the mechanism is as follows: Look around in you neighborhood for the cell, which had the highest payoff from the interactions. Change your state to this fittest neighboring cell's state. If multiple cells within a neighborhood have the same payoff choose randomly between their strategies.

Member Typedef Documentation

Base

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

The base model.

CellManager

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

Type of the CellManager to use.

Config

using Utopia::Models::SimpleEG::SimpleEG::Config = typename Base::Config

Data type that holds the configuration.

DataSet

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

Data type for a dataset.

IAMatrixType

using Utopia::Models::SimpleEG::SimpleEG::IAMatrixType = typename std::array<std::array<double, 2>, 2>

Type of the interaction matrix.

RNG

using Utopia::Models::SimpleEG::SimpleEG::RNG = typename Base::RNG

Data type of the shared RNG.

RuleFunc

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

Extract the type of the rule function from the CellManager.

This is a function that receives a reference to a cell and returns the new cell state. For more details, check out Utopia::CellManager

Note

Whether the cell state gets applied directly or requires a synchronous update depends on the update mode specified in the cell traits.

Constructor & Destructor Documentation

SimpleEG()

template<class ParentModel >

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

inline

Construct the SimpleEG 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),
 
        // Now initialize the cell manager
        _cm(*this),
 
        // Initialize model parameters
        _ia_matrix(this->extract_ia_matrix()),
 
        // ... and helpers objects
        _fittest_cells_in_nbhood(),
        _prob_distr(0., 1.),
 
        // And open datasets for strategy and payoff
        _dset_strategy(this->create_cm_dset("strategy", _cm)),
        _dset_payoff(this->create_cm_dset("payoff", _cm))
    {
        // Initialize cells
        this->initialize_cells();
 
        // Write calculated _ia_matrix to _hdfgrp attribute
        this->_hdfgrp->add_attribute("ia_matrix", _ia_matrix);
    }

Member Function Documentation

extract_ia_matrix()

IAMatrixType Utopia::Models::SimpleEG::SimpleEG::extract_ia_matrix ( ) const

inlineprivate

Extract the interaction matrix from the config file.

In the model config file there are three different ways to specify the interaction: 1) Explicitly setting the interaction matrix ia_matrix S0 S1 S0 [ia_00 ia_01] S1 [ia_10 ia_11]

2) Setting a benefit and cost pair bc_pair S0 S1 S0 [b-c -c] S1 [b 0]

3) Setting the benefit parameter b following the paper of Nowak&May1992 S0 S1 S0 [1 0] S1 [b(>1) 0]

If 1) is set, 2) and 3) will be ignored. The function returns the explicitly given ia_matrix. If 1) is not set, then the interaction matrix of 2) will be returned. If 1) and 2) are not set, the interaction matrix of 3) will be returned.

Returns

IAMatrixType The interaction matrix

                                           {
        // Return the ia_matrix if it is explicitly given in the config
        if (this->_cfg["ia_matrix"]) {
            return get_as<IAMatrixType>("ia_matrix", this->_cfg);
        }
        else if (this->_cfg["bc_pair"]) {
            // If ia_matrix is not provided in the config, get the ia_matrix
            // from the bc-pair
            const auto [b, c] = get_as<std::pair<double, double>>("bc_pair",
                                                                  this->_cfg);
            const double ia_00 = b - c;
            const double ia_01 = -c;
            const double ia_10 = b;
            const double ia_11 = 0.;
 
            const std::array<double,2> row0({{ia_00, ia_01}});
            const std::array<double,2> row1({{ia_10, ia_11}});
 
            return IAMatrixType({{row0, row1}});
        }
        else if (this->_cfg["b"]) {
            // If both previous cases are not provided, then return the
            // ia_matrix given by the parameter "b"
            const auto b = get_as<double>("b", this->_cfg);
 
            if (b <= 1.) {
                throw std::invalid_argument("Parameter `b` needs to be >1, "
                    "but was: " + std::to_string(b));
            }
 
            const double ia_00 = 1;
            const double ia_01 = 0;
            const double ia_10 = b;
            const double ia_11 = 0.;
 
            const std::array<double, 2> row0({{ia_00, ia_01}});
            const std::array<double, 2> row1({{ia_10, ia_11}});
 
            return IAMatrixType({{row0, row1}});;
        }
 
        // If we reach this point, not enough parameters were provided
        throw std::invalid_argument("No interaction matrix given! Check that "
                                    "at least one of the following config "
                                    "entries is available: `ia_matrix`, "
                                    "`bc_pair`, `b`");
    }

initialize_cells()

void Utopia::Models::SimpleEG::SimpleEG::initialize_cells ( )

inlineprivate

Initialize the cells according to initial_state config parameter.

The cell initialization for most cases is done directly at cell construction. However, some initialization options depend on the position of the cell on the grid. Only these cases are dealt with in this initialization function.

                            {
        static_assert(Base::Space::dim == 2, "Only 2D space is supported.");
 
        // Extract the mode that determines the initial strategy
        auto initial_state = get_as<std::string>("initial_state", this->_cfg);
 
        this->_log->info("Initializing cells in '{}' mode ...", initial_state);
 
        // Distinguish according to the mode, which strategy to choose
        if (initial_state == "random") {
            // Get the threshold probability value
            const auto s1_prob = get_as<double>("s1_prob", this->_cfg);
 
            // Define the update rule
            auto set_random_strategy = [this, &s1_prob](const auto cell) {
                auto state = cell->state();
 
                // Draw a random number and compare it to the threshold
                if (this->_prob_distr(*this->_rng) < s1_prob) {
                    state.strategy = Strategy::S1;
                }
                else {
                    state.strategy = Strategy::S0;
                }
 
                return state;
            };
 
            // Apply the rule to all cells
            apply_rule(set_random_strategy, _cm.cells());
        }
 
        else if (initial_state == "fraction") {
            // Get the value for the fraction of cells to have strategy 1
            const auto s1_fraction = get_as<double>("s1_fraction", this->_cfg);
 
            if (s1_fraction > 1. or s1_fraction < 0.) {
                throw std::invalid_argument("Need `s1_fraction` in [0, 1], "
                    "but got value: " + std::to_string(s1_fraction));
            }
 
            // Calculate the number of cells that should have that strategy
            const auto num_cells = _cm.cells().size();
            const std::size_t num_s1 = s1_fraction * num_cells;
            // NOTE this is a flooring calculation!
 
            this->_log->debug("Cells with strategy 1:  {} of {}",
                              num_s1, num_cells);
 
            // TODO Optionally, can add some logic here to make more clever
            //      assignments, i.e. starting out with all S1 if the number
            //      to set is higher than half ...
 
            // Need a counter of cells that were set to S1
            std::size_t num_set = 0;
 
            // Get a copy of the cells container... and shuffle them.
            auto random_cells = _cm.cells();
            std::shuffle(random_cells.begin(), random_cells.end(),
                         *this->_rng);
 
            // Make num_s1 cells use strategy 1
            for (const auto& cell : random_cells) {
                // If the desired number of cells using strategy 1 is not yet reached change another cell's strategy
                if (num_set < num_s1) {
                    // Check if it already has strategy 1.
                    if (cell->state().strategy == Strategy::S1) {
                        // Already has strategy 1, don't set it again
                        continue;
                    }
                    // else: has strategy 0 -> set to S1 and increment counter
                    cell->state_new().strategy = Strategy::S1;
                    cell->update();
 
                    num_set++;
                }
                // Break, if fraction of strategy 1 is reached
                else break;
            }
        }
 
        else if (initial_state == "single_s0" or initial_state == "single_s1"){
            // Get the grid shape and perform checks on it
            const auto& grid_shape = _cm.grid()->shape();
 
            // Need to throw an error for non-odd-valued grid shape
            if (grid_shape[0] % 2 == 0 or grid_shape[1] % 2 == 0) {
                throw std::invalid_argument("In mode '" + initial_state + "', "
                    "odd grid extensions are required to calculate the "
                    "central cell! Either adapt your grid resolution or the "
                    "space's extent in order to have a different shape. "
                    );
            }
            // FIXME This and the below is rather fragile and should be
            //       improved. Better approach: calculate the central point
            //       (here!) and find the cell beneath that point, setting it
            //       to single_strategy. Then use rule application to set
            //       default_strategy.
 
            // Determine which strategy is the common default strategy
            // and which one is the single strategy in the center of the grid
            Strategy default_strategy, single_strategy;
            if (initial_state == "single_s0") {
                default_strategy = Strategy::S1;
                single_strategy = Strategy::S0;
            }
            else {
                default_strategy = Strategy::S0;
                single_strategy = Strategy::S1;
            }
 
            // Define the rule function
            auto set_initial_strategy = [&](const auto& cell) {
                // Get the state of this cell
                auto state = cell->state();
 
                // Get the multi index to find out if this cell is central
                const auto midx = _cm.midx_of(cell);
 
                if (    midx[0] == grid_shape[0] / 2
                    and midx[1] == grid_shape[1] / 2) {
                    // The cell _is_ in the center of the grid
                    state.strategy = single_strategy;
                }
                else {
                    // The cell _is not_ in the center of the grid
                    state.strategy = default_strategy;
                }
 
                return state;
            };
 
            // Apply the rule
            apply_rule(set_initial_strategy, _cm.cells());
        }
        else {
            throw std::invalid_argument("Invalid value '" + initial_state
                + "' for parameter `initial_state`! Allowed values: random, "
                "fraction, single_s0, single_s1.");
        }
 
        // Done.
        this->_log->info("Initialized all {} cells.", _cm.cells().size());
    }

monitor()

void Utopia::Models::SimpleEG::SimpleEG::monitor ( )

inline

Monitor model information.

                    {
 
    }

perform_step()

void Utopia::Models::SimpleEG::SimpleEG::perform_step ( )

inline

Iterate a single step.

In the config, the following interaction matrix is stored: S0 S1 S0 ( _ia_matrix[0][0] _ia_matrix[0][1] ) S1 ( _ia_matrix[1][0] _ia_matrix[1][1] )

The interaction payoff is given from the perspective of the left-column- strategy. E.g. if S0 interacts with S1, S0 receives the payoff given by _ia_matrix[0][1] whereas S1 receives the payoff given by _ia_matrix[1][0].

                         {
        // Apply the rules to all cells
        apply_rule(_interaction, _cm.cells());
        apply_rule(_update, _cm.cells());
    }

write_data()

void Utopia::Models::SimpleEG::SimpleEG::write_data ( )

inline

Write data: the strategy and payoff of each cell.

                       {
        // strategy
        _dset_strategy->write(_cm.cells().begin(), _cm.cells().end(),
            [](const auto& cell) {
                return static_cast<unsigned short int>(cell->state().strategy);
            }
        );
 
        // payoffs
        _dset_payoff->write(_cm.cells().begin(), _cm.cells().end(),
            [](const auto& cell) {
                return cell->state().payoff;
            }
        );
    }

Member Data Documentation

_cm

CellManager Utopia::Models::SimpleEG::SimpleEG::_cm

private

The cell manager.

_dset_payoff

std::shared_ptr<DataSet> Utopia::Models::SimpleEG::SimpleEG::_dset_payoff

private

Stores cell payoffs over time.

_dset_strategy

std::shared_ptr<DataSet> Utopia::Models::SimpleEG::SimpleEG::_dset_strategy

private

Stores cell strategies over time.

_fittest_cells_in_nbhood

CellContainer<typename CellManager::Cell> Utopia::Models::SimpleEG::SimpleEG::_fittest_cells_in_nbhood

private

A container to temporarily accumulate the fittest neighbor cells in.

_ia_matrix

const IAMatrixType Utopia::Models::SimpleEG::SimpleEG::_ia_matrix

private

The interaction matrix (extracted during initialization)

_interaction

RuleFunc Utopia::Models::SimpleEG::SimpleEG::_interaction

private

The interaction between players.

This rule calculates the payoff for a given cell, depending on the interaction matrix and the payoffs of the neighbors.

                                                    {
        // Get the state of the current cell and its strategy
        auto state = cell->state();
 
        // First, reset payoff to zero
        state.payoff = 0.;
 
        // Go through neighboring cells, look at their strategies and add
        // the corresponding payoff only to the current cell's payoff.
        // NOTE: Careful! Adding the corresponding payoff to the neighboring
        //       cell would lead to payoffs being added multiple times!
        for (const auto& nb : this->_cm.neighbors_of(cell)) {
            const auto nb_strategy = nb->state().strategy;
 
            // Calculate the payoff depending on this cell's and the other
            // cell's state
            if (state.strategy == S0 and nb_strategy == S0) {
                state.payoff += _ia_matrix[0][0];
            }
            else if (state.strategy == S0 and nb_strategy == S1) {
                state.payoff += _ia_matrix[0][1];
            }
            else if (state.strategy == S1 and nb_strategy == S0) {
                state.payoff += _ia_matrix[1][0];
            }
            else if (state.strategy == S1 and nb_strategy == S1) {
                state.payoff += _ia_matrix[1][1];
            }
        }
 
        // Return the updated state of this cell
        return state;
    };

_prob_distr

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

private

Uniform real distribution in [0., 1.) used for evaluating probabilities.

_update

RuleFunc Utopia::Models::SimpleEG::SimpleEG::_update

private

The update rule.

Update procedure is as follows:

• Loop through the neighbors and store all neighbors with the highest payoff.
• Use the member _fittest_cells_in_nbhood for this, such that the vector does not need to be recreated for each cell.

Note

In most cases the vector will contain only one cell. However, there are parameter regimes where multiple cells can have the same payoff; this approach copes with spatial artifacts regardless of the parameter regime.

                                               {
        // Get the state of the cell
        auto state = cell->state();
 
        // Set highest payoff in the neighborhood to the cell's payoff
        double highest_payoff = state.payoff;
        _fittest_cells_in_nbhood.clear();
        _fittest_cells_in_nbhood.push_back(cell);
 
        // Iterate over neighbors of this cell:
        for (const auto& nb : this->_cm.neighbors_of(cell)){
            if (nb->state().payoff > highest_payoff) {
                // Found a new highest payoff
                highest_payoff = nb->state().payoff;
                _fittest_cells_in_nbhood.clear();
                _fittest_cells_in_nbhood.push_back(nb);
            }
            else if (nb->state().payoff == highest_payoff) {
                // Have a payoff equal to that of another cell
                _fittest_cells_in_nbhood.push_back(nb);
            }
            // else: payoff was below highest payoff
        }
 
        // Now, update the strategy according to the fittest neighbor
        if (_fittest_cells_in_nbhood.size() == 1) {
            // Only one fittest neighbor. -> The state of the current cell
            // is updated with that of the fittest neighbor.
            state.strategy = _fittest_cells_in_nbhood[0]->state().strategy;
        }
        else if (_fittest_cells_in_nbhood.size() > 1) {
            // There are multiple nbs with the same (highest) payoff.
            // -> Choose randomly one of them to pass on its strategy
            std::uniform_int_distribution<> dist(0, _fittest_cells_in_nbhood.size()-1);
            state.strategy = _fittest_cells_in_nbhood[dist(*this->_rng)]->state().strategy;
        }
        else {
            // There is no fittest neighbor. This case should never occur!
            throw std::runtime_error("There was no fittest neighbor in the "
                                     "cell update. Should not have occurred!");
        }
 
        return state;
    };

---

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

• src/utopia/models/SimpleEG/SimpleEG.hh