The agent manager manages the agents living in a model. More...

#include <agent_manager.hh>

Public Types
using	Self = AgentManager< AgentTraits, Model >
	The type of this AgentManager.

using	Space = typename Model::Space
	The type of the space.

using	Agent = Utopia::Agent< AgentTraits, Space >
	The type of the managed agents.

using	Entity = Agent
	Alias for entity type; part of the shared interface of entity managers.

using	AgentState = typename AgentTraits::State
	The type of the agent state.

using	SpaceVec = SpaceVecType< dim >
	The type of the vectors that represent physical quantities.

using	MoveFunc = std::function< void(Agent &, const SpaceVec &)>
	The type of the move function type.

using	PosFunc = std::function< SpaceVec(const SpaceVec &)>
	The type of the function that prepares the position of a new agent.

using	RuleFunc = std::function< AgentState(const std::shared_ptr< Agent > &)>
	The type of a rule function acting on agents of this agent manager.

using	VoidRuleFunc = std::function< void(const std::shared_ptr< Agent > &)>
	The type of a void rule function acting on agents of this agent manager.

using	RNG = typename Model::RNG
	The random number generator type.

Public Member Functions
	AgentManager (const Model &model, const DataIO::Config &custom_cfg={})
	Construct an agent manager.

	AgentManager (const Model &model, const AgentState initial_state, const DataIO::Config &custom_cfg={})
	Construct an agent manager, using the same initial state for all agents.

const auto &	log () const

const DataIO::Config &	cfg () const
	Return the configuration used for building this AgentManager.

const std::shared_ptr< RNG > &	rng () const
	Return a reference to the shared random number generator.

const std::shared_ptr< Space > &	space () const
	Return pointer to the space, for convenience.

const AgentContainer< Agent > &	agents () const
	Return const reference to the managed agents.

const AgentContainer< Agent > &	entities () const
	Return const reference to the entities managed by this manager: agents.

IndexType	id_counter () const
	Return the ID counter.

void	move_to (const std::shared_ptr< Agent > &agent, const SpaceVec &pos) const
	Move an agent to a new position in the space.

void	move_to (Agent &agent, const SpaceVec &pos) const
	Move an agent to a new position in the space.

void	move_by (const std::shared_ptr< Agent > &agent, const SpaceVec &move_vec) const
	Move an agent relative to its current position.

void	move_by (Agent &agent, const SpaceVec &move_vec) const
	Move an agent relative to its current position.

const std::shared_ptr< Agent > &	add_agent (const AgentState &state, const SpaceVec &pos)
	Create an agent and associate it with this AgentManager.

const std::shared_ptr< Agent > &	add_agent (const SpaceVec &pos, const Config &custom_cfg={})
	add_agent overload for auto-constructed agent states

const std::shared_ptr< Agent > &	add_agent (const Config &custom_cfg={})
	add_agent overload for auto constructed states and random position

void	remove_agent (const std::shared_ptr< Agent > &agent)
	Removes the given agent from the agent manager.

template<typename UnaryPredicate >
void	erase_agent_if (UnaryPredicate &&condition)
	Remove agents if the given condition is met.

void	update_agents ()
	Update the agents.

template<SelectionMode mode, class... Args>
AgentContainer< Agent >	select_agents (Args &&... args)
	Select agents using the Utopia::select_entities interface.

AgentContainer< Agent >	select_agents (const Config &sel_cfg)
	Select entities according to parameters specified in a configuration.

SpaceVec	displacement (const std::shared_ptr< Agent > &a, const std::shared_ptr< Agent > &b) const
	Returns the (shortest) displacement vector between two agents.

template<class NormType = std::size_t>
double	distance (const std::shared_ptr< Agent > &a, const std::shared_ptr< Agent > &b, const NormType p=2) const
	Returns the (shortest) distance between two agents.

AgentContainer< Agent >	neighbors_of (const std::shared_ptr< Agent > &agent, const double radius) const
	Returns a container of all agents within a certain radius.

Static Public Attributes
static constexpr DimType	dim = Space::dim
	The dimensionality of the space.

Private Member Functions
SpaceVec	random_pos () const
	Returns a valid (uniformly) random position in space.

Config	setup_cfg (const Model &model, const Config &custom_cfg)
	Set up the agent manager configuration member.

SpaceVec	initial_agent_pos ()
	Setup helper used to determine a single agent's initial position.

void	setup_agents (const AgentState &initial_state)
	Set up the manager's agent container with initial states.

void	setup_agents ()
	Set up agents container via config or default constructor.

MoveFunc	setup_move_to_func () const
	Depending on periodicity, return the function to move agents in space.

PosFunc	setup_prepare_pos_func () const

Private Attributes
IndexType	_id_counter
	Counts the number of agents created with this manager, used for new IDs.

const std::shared_ptr< spdlog::logger >	_log
	The logger (same as the model this manager resides in)

const DataIO::Config	_cfg
	Agent manager configuration node.

const std::shared_ptr< RNG >	_rng
	The model's random number generator.

const std::shared_ptr< Space >	_space
	The physical space the agents are to reside in.

AgentContainer< Agent >	_agents
	Storage container for agents.

MoveFunc	_move_to_func
	Function that will be used for moving agents, called by move_* methods.

PosFunc	_prepare_pos
	Function that will be used to prepare positions for adding an agent.

Detailed Description

template<class AgentTraits, class Model>
class Utopia::AgentManager< AgentTraits, Model >

The agent manager manages the agents living in a model.

The agent manager holds a container with all agents that live in a model space. It provides dynamic functions such as to move models within a space and ensures that the agents move correctly and are never allowed to leave the allowed space. Further, all agents get an ID that is unique among all existing agents (also with respect to multiple agent managers).

Template Parameters

AgentTraits	Specialized Utopia::AgentTraits describing the kind of agents this manager should manage
Model	The model this AgentManager resides in

Member Typedef Documentation

◆ Agent

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::Agent = Utopia::Agent<AgentTraits, Space>

The type of the managed agents.

◆ AgentState

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::AgentState = typename AgentTraits::State

The type of the agent state.

◆ Entity

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::Entity = Agent

Alias for entity type; part of the shared interface of entity managers.

◆ MoveFunc

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::MoveFunc = std::function<void(Agent&, const SpaceVec&)>

The type of the move function type.

◆ PosFunc

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::PosFunc = std::function<SpaceVec(const SpaceVec&)>

The type of the function that prepares the position of a new agent.

◆ RNG

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::RNG = typename Model::RNG

The random number generator type.

◆ RuleFunc

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::RuleFunc = std::function<AgentState(const std::shared_ptr<Agent>&)>

The type of a rule function acting on agents of this agent manager.

This is a convenience type def that models can use to easily have this type available.

◆ Self

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::Self = AgentManager<AgentTraits, Model>

The type of this AgentManager.

◆ Space

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::Space = typename Model::Space

The type of the space.

◆ SpaceVec

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::SpaceVec = SpaceVecType<dim>

The type of the vectors that represent physical quantities.

◆ VoidRuleFunc

template<class AgentTraits , class Model >

using Utopia::AgentManager< AgentTraits, Model >::VoidRuleFunc = std::function<void(const std::shared_ptr<Agent>&)>

The type of a void rule function acting on agents of this agent manager.

This is a convenience type def that models can use to easily have this type available. Unlike RuleFunc, this

Constructor & Destructor Documentation

◆ AgentManager() [1/2]

template<class AgentTraits , class Model >

Utopia::AgentManager< AgentTraits, Model >::AgentManager	(	const Model &	model,
		const DataIO::Config &	custom_cfg = `{}`
	)

inline

Construct an agent manager.

With the model available, the AgentManager can extract the required information from the model without the need to pass it explicitly. Furthermore, this constructor differs to the one with the initial_state and num_agents parameters such that the way the initial state of the agents is determined can be controlled via the configuration.

Parameters

model	The model this AgentManager belongs to
custom_cfg	A custom config node to use to use for grid and agent setup. If not given, the model's configuration is used to extract the required entries.

                                                  {})
    :
        _id_counter(0),
        _log(model.get_logger()),
        _cfg(setup_cfg(model, custom_cfg)),
        _rng(model.get_rng()),
        _space(model.get_space()),
        _agents(),
        _move_to_func(setup_move_to_func()),
        _prepare_pos(setup_prepare_pos_func())
    {
        setup_agents();
        _log->info("AgentManager is all set up.");
    }

◆ AgentManager() [2/2]

template<class AgentTraits , class Model >

Utopia::AgentManager< AgentTraits, Model >::AgentManager	(	const Model &	model,
		const AgentState	initial_state,
		const DataIO::Config &	custom_cfg = `{}`
	)

inline

Construct an agent manager, using the same initial state for all agents.

Parameters

model	The model this AgentManager belongs to
initial_state	The initial state of all agents
custom_cfg	A custom config node to use to use for grid and agent setup. If not given, the model's configuration is used to extract the required entries.

                                                  {})
    :
        _id_counter(0),
        _log(model.get_logger()),
        _cfg(setup_cfg(model, custom_cfg)),
        _rng(model.get_rng()),
        _space(model.get_space()),
        _agents(),
        _move_to_func(setup_move_to_func()),
        _prepare_pos(setup_prepare_pos_func())
    {
        setup_agents(initial_state);
        _log->info("AgentManager is all set up.");
    }

Member Function Documentation

◆ add_agent() [1/3]

template<class AgentTraits , class Model >

const std::shared_ptr< Agent > & Utopia::AgentManager< AgentTraits, Model >::add_agent	(	const AgentState &	state,
		const SpaceVec &	pos
	)

inline

Create an agent and associate it with this AgentManager.

Adds an agent with the specified state to the managed container of agents. It is checked whether the given position is valid; if space is periodic, any position outside the space is mapped back into the space.

Parameters

state	The state of the agent that is to be added
pos	The position of the agent that is to be added

    {
        _log->trace("Creating agent with ID {:d} ...", _id_counter);
        _agents.emplace_back(
            std::make_shared<Agent>(_id_counter, state, _prepare_pos(pos))
        );
        ++_id_counter;
 
        return _agents.back();
    }

◆ add_agent() [2/3]

template<class AgentTraits , class Model >

const std::shared_ptr< Agent > & Utopia::AgentManager< AgentTraits, Model >::add_agent ( const Config & custom_cfg = {} )

inline

add_agent overload for auto constructed states and random position

Add an agent with a random position and an auto-constructed AgentState depending on the setup: Either default constructed if the flag was set in the AgentTraits or config-constructed with or without use of the RNG.

                                                                      {}) {
        return add_agent(random_pos(), custom_cfg);
    }

◆ add_agent() [3/3]

template<class AgentTraits , class Model >

const std::shared_ptr< Agent > & Utopia::AgentManager< AgentTraits, Model >::add_agent	(	const SpaceVec &	pos,
		const Config &	custom_cfg = `{}`
	)

inline

add_agent overload for auto-constructed agent states

Adds an agent with a specified position and an auto-constructed AgentState depending on the setup, either default-constructed if the flag was set in the AgentTraits or config-constructed with or without use of the RNG.

Parameters

pos	The position of the newly created agent
custom_cfg	A custom configuration. If not given, will use the configuration given at initialization.

                                                                        {})
    {
        // Check if flag for default constructor was set
        if constexpr (AgentTraits::use_default_state_constructor) {
            if (custom_cfg.size()) {
                throw std::runtime_error("custom_cfg was passed but "
                    "AgentTraits specified use of default constructor!");
            }
 
            return add_agent(AgentState(), pos);
        }
        else {
            // Determine whether to use the given custom configuration or the
            // one  passed at construction of AgentManager
            DataIO::Config cfg;
 
            if (custom_cfg.size()) {
                cfg = custom_cfg;
            }
            else {
                cfg = _cfg["agent_params"];
            }
 
            // Distinguish the two config-constructible states
            if constexpr (std::is_constructible<AgentState,
                                                const DataIO::Config&,
                                                const std::shared_ptr<RNG>&
                                                >())
            {
                return add_agent(AgentState(cfg, _rng), pos);
            }
            else {
                // Should be config-constructible
                return add_agent(AgentState(cfg), pos);
            }
        }
 
    }

◆ agents()

template<class AgentTraits , class Model >

const AgentContainer< Agent > & Utopia::AgentManager< AgentTraits, Model >::agents ( ) const

inline

Return const reference to the managed agents.

                                                 {
        return _agents;
    }

◆ cfg()

template<class AgentTraits , class Model >

const DataIO::Config & Utopia::AgentManager< AgentTraits, Model >::cfg ( ) const

inline

Return the configuration used for building this AgentManager.

                                     {
        return _cfg;
    }

◆ displacement()

template<class AgentTraits , class Model >

SpaceVec Utopia::AgentManager< AgentTraits, Model >::displacement	(	const std::shared_ptr< Agent > &	a,
		const std::shared_ptr< Agent > &	b
	)		const

inline

Returns the (shortest) displacement vector between two agents.

The returned vector points from agent a to agent b.

In periodic space, this will also check across boundaries to return the shortest vector.

    {
        return this->_space->displacement(a->position(), b->position());
    }

◆ distance()

template<class AgentTraits , class Model >

template<class NormType = std::size_t>

double Utopia::AgentManager< AgentTraits, Model >::distance	(	const std::shared_ptr< Agent > &	a,
		const std::shared_ptr< Agent > &	b,
		const NormType	p = `2`
	)		const

inline

Returns the (shortest) distance between two agents.

By default, uses the 2-norm.

    {
        return this->_space->distance(a->position(), b->position(), p);
    }

◆ entities()

template<class AgentTraits , class Model >

const AgentContainer< Agent > & Utopia::AgentManager< AgentTraits, Model >::entities ( ) const

inline

Return const reference to the entities managed by this manager: agents.

                                                   {
        return agents();
    }

◆ erase_agent_if()

template<class AgentTraits , class Model >

template<typename UnaryPredicate >

void Utopia::AgentManager< AgentTraits, Model >::erase_agent_if ( UnaryPredicate && condition )

inline

Remove agents if the given condition is met.

Uses the erase-remove idiom

Template Parameters

UnaryPredicate type of the UnaryPredicate

Parameters

condition The condition under which the agent is to be removed. This should be a callable that takes the agent shared pointer as argument and returns bool.

                                                     {
        _agents.erase(
            std::remove_if(_agents.begin(), _agents.end(), condition),
            _agents.cend()
        );
    }

◆ id_counter()

template<class AgentTraits , class Model >

IndexType Utopia::AgentManager< AgentTraits, Model >::id_counter ( ) const

inline

Return the ID counter.

                                  {
        return _id_counter;
    }

◆ initial_agent_pos()

template<class AgentTraits , class Model >

SpaceVec Utopia::AgentManager< AgentTraits, Model >::initial_agent_pos ( )

inlineprivate

Setup helper used to determine a single agent's initial position.

                                 {
        // By default, use a random initial position
        std::string initial_pos_mode = "random";
 
        // If given, extract the initial_position mode from the configuration
        if (_cfg["initial_position"]) {
            initial_pos_mode = get_as<std::string>("initial_position", _cfg);
        }
 
        // Return the agent position depending on the mode
        if (initial_pos_mode == "random") {
            return random_pos();
        }
        else {
            throw std::invalid_argument("AgentManager got an invalid "
                "configuration entry for 'initial_position': '"
                + initial_pos_mode + "'. Valid options are: 'random'");
        }
    }

◆ log()

template<class AgentTraits , class Model >

const auto & Utopia::AgentManager< AgentTraits, Model >::log ( ) const

inline

– Getters ---------------------------------------------------------— Return the logger of this AgentManager

                             {
        return _log;
    }

◆ move_by() [1/2]

template<class AgentTraits , class Model >

void Utopia::AgentManager< AgentTraits, Model >::move_by	(	Agent &	agent,
		const SpaceVec &	move_vec
	)		const

inline

Move an agent relative to its current position.

    {
        _move_to_func(agent, agent.position() + move_vec);
    }

◆ move_by() [2/2]

template<class AgentTraits , class Model >

void Utopia::AgentManager< AgentTraits, Model >::move_by	(	const std::shared_ptr< Agent > &	agent,
		const SpaceVec &	move_vec
	)		const

inline

Move an agent relative to its current position.

    {
        _move_to_func(*agent, agent->position() + move_vec);
    }

◆ move_to() [1/2]

template<class AgentTraits , class Model >

void Utopia::AgentManager< AgentTraits, Model >::move_to	(	Agent &	agent,
		const SpaceVec &	pos
	)		const

inline

Move an agent to a new position in the space.

    {
        _move_to_func(agent, pos);
    }

◆ move_to() [2/2]

template<class AgentTraits , class Model >

void Utopia::AgentManager< AgentTraits, Model >::move_to	(	const std::shared_ptr< Agent > &	agent,
		const SpaceVec &	pos
	)		const

inline

Move an agent to a new position in the space.

    {
        _move_to_func(*agent, pos);
    }

◆ neighbors_of()

template<class AgentTraits , class Model >

AgentContainer< Agent > Utopia::AgentManager< AgentTraits, Model >::neighbors_of	(	const std::shared_ptr< Agent > &	agent,
		const double	radius
	)		const

inline

Returns a container of all agents within a certain radius.

This does not include the agent itself

Warning: Neighbors are found simply by iterating over all available agents, thus scaling linearly with the number of agents for each lookup (or: quadratically if using this on all agents).

Todo:: This should be parallelized or a lookup-grid should be used to constrain the number of possible neighbors to a smaller number

Parameters

agent	The agent whose neighborhood is to be constructed
radius	The radius within which agents other than `agent` are considered to be part of the neighborhood

    {
        AgentContainer<Agent> nbs{};
        for (const auto& a : agents()) {
            if (distance(a, agent) <= radius and a != agent) {
                nbs.push_back(a);
            }
        }
        return nbs;
    }

◆ random_pos()

template<class AgentTraits , class Model >

SpaceVec Utopia::AgentManager< AgentTraits, Model >::random_pos ( ) const

inlineprivate

Returns a valid (uniformly) random position in space.

                                {
        // Create a space vector with random relative positions [0, 1), and
        // calculate the absolute position by multiplying element-wise with the
        // extent of the space
        std::uniform_real_distribution<double> dist(0., 1.);
        return (  this->_space->extent
                % SpaceVec().imbue([this,&dist](){return dist(*this->_rng);}));
    }

◆ remove_agent()

template<class AgentTraits , class Model >

void Utopia::AgentManager< AgentTraits, Model >::remove_agent ( const std::shared_ptr< Agent > & agent )

inline

Removes the given agent from the agent manager.

                                                          {
        // Find the position in the agents container that belongs to the agent
        const auto it = std::find(_agents.cbegin(), _agents.cend(), agent);
 
        if (it == _agents.cend()) {
            throw std::invalid_argument("The given agent is not handled by "
                                        "this manager!");
        };
 
        _log->trace("Removing agent with ID {:d} ...", agent->id());
        _agents.erase(it);
    }

◆ rng()

template<class AgentTraits , class Model >

const std::shared_ptr< RNG > & Utopia::AgentManager< AgentTraits, Model >::rng ( ) const

inline

Return a reference to the shared random number generator.

                                           {
        return _rng;
    }

◆ select_agents() [1/2]

template<class AgentTraits , class Model >

template<SelectionMode mode, class... Args>

AgentContainer< Agent > Utopia::AgentManager< AgentTraits, Model >::select_agents ( Args &&... args )

inline

Select agents using the Utopia::select_entities interface.

Returns a container of agents that were selected according to a certain selection mode. This is done via the Utopia::select_entities interface.

Template Parameters

mode	The selection mode

\args args Forwarded to Utopia::select_entities

                                                        {
        return select_entities<mode>(*this, std::forward<Args>(args)...);
    }

◆ select_agents() [2/2]

template<class AgentTraits , class Model >

AgentContainer< Agent > Utopia::AgentManager< AgentTraits, Model >::select_agents ( const Config & sel_cfg )

inline

Select entities according to parameters specified in a configuration.

Via the mode key, one of the selection modes can be chosen; for available oens, see Utopia::SelectionMode.

Depending on that mode, the other parameters are extracted from the configuration. See Utopia::select_entities for more info.

Parameters

sel_cfg The configuration node containing the expected key-value pairs specifying the selection.

                                                               {
        return select_entities(*this, sel_cfg);
    }

◆ setup_agents() [1/2]

template<class AgentTraits , class Model >

void Utopia::AgentManager< AgentTraits, Model >::setup_agents ( )

inlineprivate

Set up agents container via config or default constructor.

If no explicit initial state is given, this setup function is called. There are three modes: If the Utopia::AgentTraits are set such that the default constructor of the agent state is to be used, that constructor is required and is called for each agent.

Otherwise, the AgentState needs to be constructible via a const DataIO::Config& argument, which gets passed the config entry agent_params from the AgentManager's configuration.

If a constructor with the signature (const DataIO::Config&, const std::shared_ptr<RNG>&) is supported, that constructor is called instead.

Note: If the constructor for the agent state has an RNG available it is called anew for each agent; otherwise, an initial state is constructed once and used for all agents.

                        {
        // Distinguish depending on constructor.
        // Is the default constructor to be used?
        if constexpr (AgentTraits::use_default_state_constructor) {
            static_assert(std::is_default_constructible<AgentState>(),
                "AgentTraits were configured to use the default constructor "
                "to create agent states, but the AgentState is not "
                "default-constructible! Either implement such a constructor, "
                "unset the flag in the AgentTraits, or pass an explicit "
                "initial agent state to the AgentManager.");
 
            _log->info("Setting up agents using default constructor ...");
 
            // Create the initial state (same for all agents)
            setup_agents(AgentState());
        }
 
        // Is there a constructor available that allows passing the RNG?
        else if constexpr (std::is_constructible<AgentState,
                                                 const DataIO::Config&,
                                                 const std::shared_ptr<RNG>&
                                                 >())
        {
            _log->info("Setting up agents using config constructor (with RNG) "
                       "...");
 
            // Extract the configuration parameter
            if (not _cfg["agent_params"]) {
                throw std::invalid_argument("AgentManager is missing the "
                    "configuration entry 'agent_params' to set up the agents' "
                    "initial states!");
            }
            const auto agent_params = _cfg["agent_params"];
 
            if (not _cfg["initial_num_agents"]){
                throw std::invalid_argument("AgentManager is missing the "
                    "configuration entry 'initial_num_agents' to set up the "
                    "agents!"
                    );
            }
            const auto initial_num_agents =
                get_as<IndexType>("initial_num_agents", _cfg);
 
            // Populate the container, creating the agent state anew each time
            for (IndexType i=0; i<initial_num_agents; i++) {
                add_agent(AgentState(agent_params, _rng),
                          initial_agent_pos());
            }
 
            // Done. Shrink it.
            _agents.shrink_to_fit();
            _log->info("Populated agent container with {:d} agents.",
                       _agents.size());
        }
 
        // As default, require a Config constructor
        else {
            static_assert(std::is_constructible<AgentState,
                                                const DataIO::Config&>(),
                "AgentManager::AgentState needs to be constructible using "
                "const DataIO::Config& as only argument. Either implement "
                "such a constructor, pass an explicit initial agent state to "
                "the AgentManager, or set the AgentTraits such that a default "
                "constructor is to be used.");
 
            _log->info("Setting up agents using config constructor ...");
 
            // Extract the configuration parameter
            if (not _cfg["agent_params"]) {
                throw std::invalid_argument("AgentManager is missing the "
                    "configuration entry 'agent_params' to set up the agents' "
                    "initial states!");
            }
 
            // Create the initial state (same for all agents)
            return setup_agents(AgentState(_cfg["agent_params"]));
        }
        // This point is never reached.
    }

◆ setup_agents() [2/2]

template<class AgentTraits , class Model >

void Utopia::AgentManager< AgentTraits, Model >::setup_agents ( const AgentState & initial_state )

inlineprivate

Set up the manager's agent container with initial states.

Creates a container with agents that get an initial state and are set up with a random position.

Parameters

initial_state	The initial state of the agents
num_agents	The number of agents

                                                       {
        // Extract parameters from the configuration
        if (not _cfg["initial_num_agents"]) {
            throw std::invalid_argument("AgentManager is missing the "
                "configuration entry 'initial_num_agents' that specifies the "
                "number of agents to set up!");
        }
        const auto num_agents = get_as<IndexType>("initial_num_agents", _cfg);
 
        // Construct all the agents with incremented IDs, the initial state
        // and a random position
        for (IndexType i=0; i<num_agents; ++i){
            add_agent(initial_state, initial_agent_pos());
        }
 
        // Done. Shrink it.
        _agents.shrink_to_fit();
        _log->info("Populated agent container with {:d} agents.",
                   _agents.size());
    }

◆ setup_cfg()

template<class AgentTraits , class Model >

Config Utopia::AgentManager< AgentTraits, Model >::setup_cfg	(	const Model &	model,
		const Config &	custom_cfg
	)

inlineprivate

Set up the agent manager configuration member.

Determines whether to use a custom configuration or the one provided by the model this AgentManager belongs to

                                                                   {
        Config cfg;
 
        if (custom_cfg.size() > 0) {
            _log->debug("Using custom config for agent manager setup ...");
            cfg = custom_cfg;
        }
        else {
            _log->debug("Using '{}' model's configuration for agent manager "
                        "setup ... ", model.get_name());
 
            if (not model.get_cfg()["agent_manager"]) {
                throw std::invalid_argument("Missing config entry "
                    "'agent_manager' in model configuration! Either specify "
                    "that key or pass a custom configuration node to the "
                    "AgentManager constructor.");
            }
            cfg = model.get_cfg()["agent_manager"];
        }
        return cfg;
    }

◆ setup_move_to_func()

template<class AgentTraits , class Model >

MoveFunc Utopia::AgentManager< AgentTraits, Model >::setup_move_to_func ( ) const

inlineprivate

Depending on periodicity, return the function to move agents in space.

The function that is used to move an agent to a new position in space depends on whether the space is periodic or not. In the case of a periodic space the position is automatically mapped into space again across the borders. For a nonperiodic space a position outside of the borders will throw an error.

                                        {
        // Need to distinguish by periodicity of the space the agents live in
        if (_space->periodic) {
            // Can simply use the space's mapping function
            return [this](Agent& agent, const SpaceVec& pos){
                agent.set_pos(this->_space->map_into_space(pos));
            };
        }
        else {
            // For nonperiodic space, need to make sure the position is valid
            return [this](Agent& agent, const SpaceVec& pos){
                if (not this->_space->contains(pos)) {
                    throw OutOfSpace(pos, this->_space,
                                     "Could not move agent!");
                }
 
                // Set the new agent position
                agent.set_pos(pos);
            };
        }
    }

◆ setup_prepare_pos_func()

template<class AgentTraits , class Model >

PosFunc Utopia::AgentManager< AgentTraits, Model >::setup_prepare_pos_func ( ) const

inlineprivate

Depending on periodicity, return the function to prepare positions of agents before they are added The function that is used to prepare a position before an agent is added (if passed explicitly) depends on whether the space is periodic or not. In the case of a periodic space the position is automatically mapped into space again across the borders. For a nonperiodic space a position outside of the borders will throw an error.

                                           {
        // If periodic, map the position back into space
        if (_space->periodic) {
            return
                [this](const SpaceVec& pos){
                    return this->_space->map_into_space(pos);
                };
        }
        // If non-periodic, check wether the position is valid
        else {
            return
                [this](const SpaceVec& pos) {
                    if (not _space->contains(pos)) {
                        throw OutOfSpace(pos, _space,
                                         "Given position is out of space!");
                    }
                    return pos;
                };
        }
    }

◆ space()

template<class AgentTraits , class Model >

const std::shared_ptr< Space > & Utopia::AgentManager< AgentTraits, Model >::space ( ) const

inline

Return pointer to the space, for convenience.

                                               {
        return _space;
    }

◆ update_agents()

template<class AgentTraits , class Model >

void Utopia::AgentManager< AgentTraits, Model >::update_agents ( )

inline

Update the agents.

This method is used in the case of synchronous update. It updates the state and position from the agent's state and position cache variables.

Note: In the case of asynchronous agent update this function will throw an error during compilation. There is no need to update these agent traits because there is no cached trait.

                         {
        // Assert that the agents update synchronously
        static_assert(AgentTraits::mode == Update::sync,
            "The update_agents method only makes sense to call when agents "
            "are set to be updated synchronously, which is not the case! "
            "Either adapt the AgentTraits to that update mode or remove the "
            "call to the update_agents method.");
 
        // Go through all agents and update them
        for (const auto& agent : _agents){
            agent->update();
        }
    }