Utopia::Models::SimpleFlocking::SimpleFlocking Class Reference

The SimpleFlocking Model. More...

#include <SimpleFlocking.hh>

Inheritance diagram for Utopia::Models::SimpleFlocking::SimpleFlocking:

Collaboration diagram for Utopia::Models::SimpleFlocking::SimpleFlocking:

Public Types
using	Base = Model< SimpleFlocking, ModelTypes >
	The type of the Model base class of this derived class.
using	AgentManager = Utopia::AgentManager< AgentTraits, SimpleFlocking >
	The type of the agent manager.
using	Agent = AgentManager::Agent
	Agent type.
using	AgentPtr = std::shared_ptr< Agent >
	Pointer to agent.
using	Rule = typename AgentManager::RuleFunc
	Type of the update rules for agents.
using	VoidRule = typename AgentManager::VoidRuleFunc
	Type of the update rules for agents where no state is to be returned.
using	SpaceVec = typename AgentManager::SpaceVec
	Type of spatial vectors within the domain.
using	DataSet = typename Base::DataSet
	Data type for a dataset.
Public Types inherited from Utopia::Model< SimpleFlocking, ModelTypes >
using	Config = typename ModelTypes::Config
	Data type that holds the configuration.
using	DataManager = DataIO::Default::DefaultDataManager< SimpleFlocking >
	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 >
	SimpleFlocking (const std::string &name, ParentModel &parent_model, const DataIO::Config &custom_cfg={})
	Construct the SimpleFlocking model instance.
void	perform_step ()
	Iterate a single step: adjust agent orientation, then move all agents.
void	monitor ()
	Monitor the model state.
void	write_data ()
	Write data.
std::size_t	num_agents () const
	The number of agents in the system (typically constant)
void	set_agent_speed (const double new_speed)
	Sets the speed value of all agents.
double	norm_group_velocity () const
	The normalized absolute group velocity.
template<class Adapter , class ValueType = std::invoke_result_t<Adapter, const AgentPtr&>>
std::vector< ValueType >	get_from_agents (const Adapter &adapter) const
	Aggregate agent properties into a container.
Public Member Functions inherited from Utopia::Model< SimpleFlocking, ModelTypes >
	Model (const std::string &name, const ParentModel &parent_model, const Config &custom_cfg={}, std::tuple< WriterArgs... > w_args={}, const DataIO::Default::DefaultDecidermap< SimpleFlocking > &w_deciders=DataIO::Default::default_deciders< SimpleFlocking >, const DataIO::Default::DefaultTriggermap< SimpleFlocking > &w_triggers=DataIO::Default::default_triggers< SimpleFlocking >)
	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.

Public Attributes
const Rule	_adjust_orientation
	Rule that sets agent orientation to the mean orientation (in a radius)
const VoidRule	_move
	Rule that applies the current displacement vector to the agent position.

Private Attributes
AgentManager	_am
	The agent manager.
double	_speed
	The global speed value, used as the uniform speed of all agents.
double	_interaction_radius
	The radius within which agents interact with each other.
double	_noise_level
	The amplitude of the noise applied to the orientation update.
std::uniform_real_distribution< double >	_noise_distr
	The distribution used for determining the orientation noise.
bool	_store_agent_data
	Whether to store agent-specific data.
std::shared_ptr< DataSet >	_dset_agent_x
std::shared_ptr< DataSet >	_dset_agent_y
std::shared_ptr< DataSet >	_dset_agent_orientation
std::shared_ptr< DataSet >	_dset_orientation_circmean
std::shared_ptr< DataSet >	_dset_orientation_circstd
std::shared_ptr< DataSet >	_dset_norm_group_velocity

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

Detailed Description

The SimpleFlocking Model.

An agent-based model of spatial collective dynamics, akin to those observed in bird flocks or fish schools.

These dynamics arise as a result of agents adjusting their orientation according to that of nearby agents.

Member Typedef Documentation

Agent

using Utopia::Models::SimpleFlocking::SimpleFlocking::Agent = AgentManager::Agent

Agent type.

AgentManager

using Utopia::Models::SimpleFlocking::SimpleFlocking::AgentManager = Utopia::AgentManager<AgentTraits, SimpleFlocking>

The type of the agent manager.

AgentPtr

using Utopia::Models::SimpleFlocking::SimpleFlocking::AgentPtr = std::shared_ptr<Agent>

Pointer to agent.

Base

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

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

DataSet

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

Data type for a dataset.

Rule

using Utopia::Models::SimpleFlocking::SimpleFlocking::Rule = typename AgentManager::RuleFunc

Type of the update rules for agents.

SpaceVec

using Utopia::Models::SimpleFlocking::SimpleFlocking::SpaceVec = typename AgentManager::SpaceVec

Type of spatial vectors within the domain.

VoidRule

using Utopia::Models::SimpleFlocking::SimpleFlocking::VoidRule = typename AgentManager::VoidRuleFunc

Type of the update rules for agents where no state is to be returned.

Constructor & Destructor Documentation

SimpleFlocking()

template<class ParentModel >

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

inline

Construct the SimpleFlocking model instance.

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

                                         {}
    )
    :
        Base(name, parent_model, custom_cfg)
 
    ,   _am(*this)
 
    ,   _speed(get_as<double>("speed", this->_cfg))
    ,   _interaction_radius(get_as<double>("interaction_radius", this->_cfg))
    ,   _noise_level(get_as<double>("noise_level", this->_cfg))
 
    ,   _noise_distr(-_noise_level/2., +_noise_level/2.)
 
    // .. Output-related ......................................................
    ,   _store_agent_data(get_as<bool>("store_agent_data", this->_cfg))
 
    ,   _dset_agent_x(this->create_am_dset("agent/x", _am))
    ,   _dset_agent_y(this->create_am_dset("agent/y", _am))
    ,   _dset_agent_orientation(this->create_am_dset("agent/orientation", _am))
 
    ,   _dset_orientation_circmean(
            this->create_dset("orientation_circmean", {})
        )
    ,   _dset_orientation_circstd(
            this->create_dset("orientation_circstd", {})
        )
    ,   _dset_norm_group_velocity(
            this->create_dset("norm_group_velocity", {})
        )
    {
        set_agent_speed(_speed);
 
        this->_log->info("{} all set up.", this->_name);
        this->_log->info("  Store agent data?  {}", _store_agent_data);
    }

Member Function Documentation

get_from_agents()

template<class Adapter , class ValueType = std::invoke_result_t<Adapter, const AgentPtr&>>

std::vector< ValueType > Utopia::Models::SimpleFlocking::SimpleFlocking::get_from_agents ( const Adapter &  adapter ) const

inline

Aggregate agent properties into a container.

                                                                        {
        std::vector<ValueType> cont;
        cont.reserve(num_agents());
 
        std::transform(
            this->_am.agents().begin(), this->_am.agents().end(),
            std::back_inserter(cont), adapter
        );
        return cont;
    }

monitor()

void Utopia::Models::SimpleFlocking::SimpleFlocking::monitor ( )

inline

Monitor the model state.

This monitor provides information about the current orientation's (circular) mean and standard deviation. In addition, the normalized group velocity is monitored, which represents the system's order parameter.

                    {
        const auto orientations = get_from_agents([](const auto& agent){
            return agent->state().get_orientation();
        });
 
        const auto [circ_mean, circ_std] = circular_mean_and_std(orientations);
        this->_monitor.set_entry("orientation_mean", circ_mean);
        this->_monitor.set_entry("orientation_std", circ_std);
        this->_monitor.set_entry("norm_group_velocity", norm_group_velocity());
    }

norm_group_velocity()

double Utopia::Models::SimpleFlocking::SimpleFlocking::norm_group_velocity ( ) const

inline

The normalized absolute group velocity.

Computed by dividing the absolute group velocity of all agents by the absolute speed. This represents the order parameter of the system.

Note

The computation assumes that all agents have the same speed (as indicated by the _speed member). If this is not the case, the result will be erroneous! For performance reasons, no check for uniform agent velocities is carried out.

                                        {
        const auto velocities = get_from_agents([](const auto& agent){
            return agent->state().get_displacement();
        });
        return absolute_group_velocity(velocities) / std::fabs(_speed);
    }

num_agents()

std::size_t Utopia::Models::SimpleFlocking::SimpleFlocking::num_agents ( ) const

inline

The number of agents in the system (typically constant)

                                  {
        return _am.agents().size();
    }

perform_step()

void Utopia::Models::SimpleFlocking::SimpleFlocking::perform_step ( )

inline

Iterate a single step: adjust agent orientation, then move all agents.

These rules are both applied synchronously to all agents.

                         {
        apply_rule(_adjust_orientation, _am.agents());
        apply_rule(_move, _am.agents());
    }

set_agent_speed()

void Utopia::Models::SimpleFlocking::SimpleFlocking::set_agent_speed ( const double  new_speed )

inline

Sets the speed value of all agents.

                                                  {
        this->_log->info("Setting all agent's speed to {} ...", new_speed);
        apply_rule(
            [speed=new_speed](const auto& agent){
                auto state = agent->state();
                state.set_speed(speed);
                return state;
            },
            this->_am.agents()
        );
    }

write_data()

void Utopia::Models::SimpleFlocking::SimpleFlocking::write_data ( )

inline

Write data.

                       {
        using WriteT = float;
        const auto& agents = _am.agents();
 
        // -- Global observables
        const auto orientations = get_from_agents([](const auto& agent){
            return agent->state().get_orientation();
        });
 
        const auto [circ_mean, circ_std] = circular_mean_and_std(orientations);
        _dset_orientation_circmean->write(circ_mean);
        _dset_orientation_circstd->write(circ_std);
 
        _dset_norm_group_velocity->write(norm_group_velocity());
 
        // -- Agent-specific data
        // ... only stored optionally
        if (not _store_agent_data) return;
 
        _dset_agent_x->write(
            agents.begin(), agents.end(),
            [](const auto& agent) {
                return static_cast<WriteT>(agent->position()[0]);
        });
 
        _dset_agent_y->write(
            agents.begin(), agents.end(),
            [](const auto& agent) {
                return static_cast<WriteT>(agent->position()[1]);
        });
 
        _dset_agent_orientation->write(
            orientations.begin(), orientations.end(),
            [](const auto& orientation) {
                return static_cast<WriteT>(orientation);
        });
    }

Member Data Documentation

_adjust_orientation

const Rule Utopia::Models::SimpleFlocking::SimpleFlocking::_adjust_orientation

Rule that sets agent orientation to the mean orientation (in a radius)

The orientation of the current agent is included into the calculation of the mean orientation.

Currently uses a

                                                              {
        auto state = agent->state();
 
        // Find all agents within the interaction radius and compute their
        // average orientation, including (!) the current agent.
        // To find an average orientation, we need to separate the x- and y-
        // components and later combine them back into an angle.
        auto agg_sin = std::sin(agent->state().get_orientation());
        auto agg_cos = std::cos(agent->state().get_orientation());
 
        // NOTE The AgentManager::neighbors_of method finds neighbors with
        //      linear complexity in agent number, leading to an overall
        //      quadratic complexity in agent number for this search.
        //      This can be mitigated (on the level of the AgentManager!) by
        //      using a spatially restricted search or a lookup grid.
        for (const auto& nb :
             this->_am.neighbors_of(agent, this->_interaction_radius))
        {
            agg_sin += std::sin(nb->state().get_orientation());
            agg_cos += std::cos(nb->state().get_orientation());
        }
 
        // Can now set the orientation, including noise
        // NOTE Could divide by number of involved agents here, but that is
        //      unnecessary because it cancels out through division anyway.
        state.set_orientation(
            std::atan2(agg_sin, agg_cos) +
            (this->_noise_level > 0. ? _noise_distr(*this->_rng) : 0.)
        );
 
        return state;
    };

_am

AgentManager Utopia::Models::SimpleFlocking::SimpleFlocking::_am

private

The agent manager.

_dset_agent_orientation

std::shared_ptr<DataSet> Utopia::Models::SimpleFlocking::SimpleFlocking::_dset_agent_orientation

private

_dset_agent_x

std::shared_ptr<DataSet> Utopia::Models::SimpleFlocking::SimpleFlocking::_dset_agent_x

private

_dset_agent_y

std::shared_ptr<DataSet> Utopia::Models::SimpleFlocking::SimpleFlocking::_dset_agent_y

private

_dset_norm_group_velocity

std::shared_ptr<DataSet> Utopia::Models::SimpleFlocking::SimpleFlocking::_dset_norm_group_velocity

private

_dset_orientation_circmean

std::shared_ptr<DataSet> Utopia::Models::SimpleFlocking::SimpleFlocking::_dset_orientation_circmean

private

_dset_orientation_circstd

std::shared_ptr<DataSet> Utopia::Models::SimpleFlocking::SimpleFlocking::_dset_orientation_circstd

private

_interaction_radius

double Utopia::Models::SimpleFlocking::SimpleFlocking::_interaction_radius

private

The radius within which agents interact with each other.

_move

const VoidRule Utopia::Models::SimpleFlocking::SimpleFlocking::_move

Initial value:

= [this](const auto& agent){
        this->_am.move_by(agent, agent->state().get_displacement());
    }

Rule that applies the current displacement vector to the agent position.

                                                    {
        this->_am.move_by(agent, agent->state().get_displacement());
    };

_noise_distr

std::uniform_real_distribution<double> Utopia::Models::SimpleFlocking::SimpleFlocking::_noise_distr

private

The distribution used for determining the orientation noise.

_noise_level

double Utopia::Models::SimpleFlocking::SimpleFlocking::_noise_level

private

The amplitude of the noise applied to the orientation update.

_speed

double Utopia::Models::SimpleFlocking::SimpleFlocking::_speed

private

The global speed value, used as the uniform speed of all agents.

_store_agent_data

bool Utopia::Models::SimpleFlocking::SimpleFlocking::_store_agent_data

private

Whether to store agent-specific data.

---

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

• src/utopia/models/SimpleFlocking/SimpleFlocking.hh