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. More...

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

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

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

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

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

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

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

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

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

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

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

	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. More...

const auto &	log () const

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

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

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

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

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

IndexType	id_counter () const
	Return the ID counter. More...

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

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

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

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

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

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

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

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

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

void	update_agents ()
	Update the agents. More...

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

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

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

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. More...

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

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

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

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

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

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

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

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

PosFunc	setup_prepare_pos_func () const

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

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

const DataIO::Config	_cfg
	Agent manager configuration node. More...

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

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

AgentContainer< Agent >	_agents
	Storage container for agents. More...

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

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

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.

◆ 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.

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

◆ 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.

◆ 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.

◆ agents()

template<class AgentTraits , class Model >

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

inline

Return const reference to the managed 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.

◆ 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.

◆ 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.

◆ 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.

◆ 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.

◆ id_counter()

template<class AgentTraits , class Model >

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

inline

Return the 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.

◆ log()

template<class AgentTraits , class Model >

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

inline

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

◆ 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_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() [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() [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.

◆ 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

◆ random_pos()

template<class AgentTraits , class Model >

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

inlineprivate

Returns a valid (uniformly) random position in space.

◆ 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.

◆ 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.

◆ 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

◆ 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.

◆ 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.

◆ 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

◆ 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

◆ 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.

◆ 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.

◆ 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.

◆ 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.

Member Data Documentation

◆ _agents

template<class AgentTraits , class Model >

AgentContainer<Agent> Utopia::AgentManager< AgentTraits, Model >::_agents

private

Storage container for agents.

◆ _cfg

template<class AgentTraits , class Model >

const DataIO::Config Utopia::AgentManager< AgentTraits, Model >::_cfg

private

Agent manager configuration node.

◆ _id_counter

template<class AgentTraits , class Model >

IndexType Utopia::AgentManager< AgentTraits, Model >::_id_counter

private

Counts the number of agents created with this manager, used for new IDs.

◆ _log

template<class AgentTraits , class Model >

const std::shared_ptr<spdlog::logger> Utopia::AgentManager< AgentTraits, Model >::_log

private

The logger (same as the model this manager resides in)

◆ _move_to_func

template<class AgentTraits , class Model >

MoveFunc Utopia::AgentManager< AgentTraits, Model >::_move_to_func

private

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

◆ _prepare_pos

template<class AgentTraits , class Model >

PosFunc Utopia::AgentManager< AgentTraits, Model >::_prepare_pos

private

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

◆ _rng

template<class AgentTraits , class Model >

const std::shared_ptr<RNG> Utopia::AgentManager< AgentTraits, Model >::_rng

private

The model's random number generator.

◆ _space

template<class AgentTraits , class Model >

const std::shared_ptr<Space> Utopia::AgentManager< AgentTraits, Model >::_space

private

The physical space the agents are to reside in.

◆ dim

template<class AgentTraits , class Model >

constexpr DimType Utopia::AgentManager< AgentTraits, Model >::dim = Space::dim

staticconstexpr

The dimensionality of the space.

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

include/utopia/core/agent_manager.hh

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

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

Member Typedef Documentation

◆ Agent

◆ AgentState

◆ Entity

◆ MoveFunc

◆ PosFunc

◆ RNG

◆ RuleFunc

◆ Self

◆ Space

◆ SpaceVec

◆ VoidRuleFunc

Constructor & Destructor Documentation

◆ AgentManager() [1/2]

◆ AgentManager() [2/2]

Member Function Documentation

◆ add_agent() [1/3]

◆ add_agent() [2/3]

◆ add_agent() [3/3]

◆ agents()

◆ cfg()

◆ displacement()

◆ distance()

◆ entities()

◆ erase_agent_if()

◆ id_counter()

◆ initial_agent_pos()

◆ log()

◆ move_by() [1/2]

◆ move_by() [2/2]

◆ move_to() [1/2]

◆ move_to() [2/2]

◆ neighbors_of()

◆ random_pos()

◆ remove_agent()

◆ rng()

◆ select_agents() [1/2]

◆ select_agents() [2/2]

◆ setup_agents() [1/2]

◆ setup_agents() [2/2]

◆ setup_cfg()

◆ setup_move_to_func()

◆ setup_prepare_pos_func()

◆ space()

◆ update_agents()

Member Data Documentation

◆ _agents

◆ _cfg

◆ _id_counter

◆ _log

◆ _move_to_func

◆ _prepare_pos

◆ _rng

◆ _space

◆ dim

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