Utopia Namespace Reference

Namespaces
namespace	_internal
namespace	_Metaprogramming_helpers
namespace	DataIO
namespace	Graph
namespace	GraphUtils
namespace	impl
namespace	Itertools
	Tools for iterating over collections.
namespace	Models
namespace	TestTools
namespace	Utils

Classes
class	Agent
	An agent is a slightly specialized state container. More...
class	Agent< Traits, Space, std::enable_if_t< Traits::mode !=Update::sync > >
	Agent specialization for asynchronous update. More...
class	Agent< Traits, Space, std::enable_if_t< Traits::mode==Update::sync > >
	Agent Specialisation for synchronous update. More...
class	AgentManager
	The agent manager manages the agents living in a model. More...
class	Cell
	A cell is a slightly specialized state container. More...
class	CellManager
	Manages a physical space, its grid discretization, and cells on that grid. More...
class	DefaultTag
class	EmptyTag
class	Entity
	An entity is a slightly specialized state container. More...
struct	EntityTraits
	The entity traits struct gathers types to be used for specializing an entity. More...
class	Exception
	The base exception class to derive Utopia-specific exceptions from. More...
class	GotSignal
	An exception for when the program should end due to handling of a signal. More...
class	GraphEntity
	A graph entity is a slightly specialized state container. More...
class	Grid
	The base class for all grid discretizations used by the CellManager. More...
class	HexagonalGrid
	A grid discretization using hexagonal cells. More...
struct	is_agent_manager
	Metafunction to determine whether a Manager is an AgentManager. More...
struct	is_cell_manager
	Metafunction to determine whether a Manager is a CellManager. More...
class	KeyError
	For access to a dict-like structure with a bad key. More...
class	Model
	Base class interface for Models using the CRT Pattern. More...
struct	ModelTypes
	Wrapper struct for defining model class data types. More...
struct	NoCustomLinks
	Default struct for EntityTraits; use this one if there are no custom links. More...
class	OutOfSpace
	An exception class for invalid positions in Utopia::Space. More...
class	ParallelExecution
	Static information on the status of parallel execution. More...
class	PseudoParent
	A class to use at the top level of the model hierarchy as a mock parent. More...
class	rule_invoke_result
	Helper class for checking rule signatures and return types. More...
struct	Space
	The Space bundles properties about the physical space a model resides in. More...
class	SquareGrid
	A grid discretization using square cells. More...
class	StateContainer
	Container for states. More...
class	StateContainer< StateType, Update::async >
	State Container specialization for async states. More...
class	StateContainer< StateType, Update::manual >
	A very simple, default constructible container with public members. More...
class	StateContainer< StateType, Update::sync >
	State Container specialization for sync states. More...
class	TriangularGrid
	A grid discretization using triangular cells. More...

Typedefs
template<typename StateType , Update update_mode, bool use_def_state_constr = false, typename AgentTags = EmptyTag, template< class > class CustomLinkContainers = NoCustomLinks>
using	AgentTraits = EntityTraits< StateType, update_mode, use_def_state_constr, AgentTags, CustomLinkContainers >
	AgentTraits are just another name for Utopia::EntityTraits.
template<typename State , typename Rule , typename... Args>
using	rule_invoke_result_t = typename rule_invoke_result< State, Rule, Args... >::type
	Helper definition to query the rule result type.
template<typename StateType , Update update_mode, bool use_def_state_constr = false, typename CellTags = EmptyTag, template< class > class CustomLinkContainers = NoCustomLinks>
using	CellTraits = EntityTraits< StateType, update_mode, use_def_state_constr, CellTags, CustomLinkContainers >
	CellTraits are just another name for Utopia::EntityTraits.
template<typename StateType , typename GraphEntityTags = EmptyTag, template< class > class CustomLinkContainers = NoCustomLinks>
using	GraphEntityTraits = EntityTraits< StateType, Update::manual, false, GraphEntityTags, CustomLinkContainers >
	GraphEntityTraits are mainly just another name for Utopia::EntityTraits.
template<class Grid >
using	NBFuncID = std::function< IndexContainer(const IndexType)>
	Type of the neighborhood calculating function.
using	DefaultSpace = Space< 2 >
	The default Space object to be used throughout Utopia.
using	DefaultRNG = std::mt19937
	Type of default random number generator.
template<typename EntityType >
using	EntityContainer = std::vector< std::shared_ptr< EntityType > >
	Type of the variably sized container for entities.
template<typename CellType >
using	CellContainer = EntityContainer< CellType >
	Type of the variably sized container for cells.
template<typename AgentType >
using	AgentContainer = EntityContainer< AgentType >
	Type of the variably sized container for agents.
using	DimType = unsigned short
	Type for dimensions, i.e. very small unsigned integers.
using	DistType = unsigned int
	Type for distancens, i.e. intermediately long unsigned integers.
using	IndexType = std::size_t
	Type for indices, i.e. values used for container indexing, agent IDs, ...
using	IndexContainer = std::vector< IndexType >
	Type for container of indices.
template<DimType dim>
using	MultiIndexType = arma::Col< IndexType >::fixed< dim >
	Type for index type vectors that are associated with a physical space.
template<DimType dim>
using	SpaceVecType = arma::Col< double >::fixed< dim >
	Type for vector-like data that is associated with a physical space.
using	Config = DataIO::Config
	Type of a variadic dictionary-like data structure used throughout Utopia.

Enumerations
enum class	Shuffle { Shuffle::on , Shuffle::off }
	Switch for enabling/disabling shuffling the cells for asynchronous updates. More...
enum class	IterateOver {   IterateOver::vertices , IterateOver::edges , IterateOver::neighbors , IterateOver::inv_neighbors ,   IterateOver::in_edges , IterateOver::out_edges }
	Over which graph entity to iterate. More...
enum class	GridStructure { GridStructure::square , GridStructure::triangular , GridStructure::hexagonal }
	Available grid implementations. More...
enum class	NBMode { NBMode::empty = 0 , NBMode::vonNeumann = 1 , NBMode::Moore = 2 , NBMode::hexagonal = 3 }
	Possible neighborhood types; availability depends on choice of grid. More...
enum class	WriteMode { WriteMode::basic , WriteMode::managed , WriteMode::manual , WriteMode::off }
	How to write data in the models. More...
enum	ExecPolicy { seq , unseq , par , par_unseq }
	Runtime execution policies. More...
enum class	SelectionMode {   SelectionMode::condition = 0 , SelectionMode::sample = 1 , SelectionMode::probability = 2 , SelectionMode::clustered_simple = 20 ,   SelectionMode::position = 100 , SelectionMode::boundary = 101 , SelectionMode::lanes = 102 }
	Possible selection modes; availability depends on choice of manager. More...
enum class	Update { Update::manual , Update::sync , Update::async }
	Update modes when applying rules. More...

Functions
template<typename State , typename Rule , typename... Args>
constexpr bool	is_void_rule ()
	Helper function to check if the rule returns void
template<class Tuple , std::size_t... I>
constexpr decltype(auto)	make_tuple_from_tuple_impl (Tuple &&t, std::index_sequence< I... >)
	Helper function to create a tuple from a tuple using an index sequence.
template<class Tuple >
constexpr decltype(auto)	make_tuple_from_tuple (Tuple &&t)
	Helper function to create a tuple from a tuple.
template<Update mode, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::sync, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0>
void	apply_rule (Rule &&rule, const ContTarget &cont_target, ContArgs &&... cont_args)
	Sequential overload.
template<Update mode, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::sync, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0>
void	apply_rule (const Utopia::ExecPolicy policy, Rule &&rule, const ContTarget &cont_target, ContArgs &&... cont_args)
	Apply a rule synchronously to manually updated states.
template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::off, int > = 0>
void	apply_rule (Rule &&rule, const ContTarget &cont_target, ContArgs &&... cont_args)
	Sequential case overload.
template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::off, int > = 0>
void	apply_rule (const Utopia::ExecPolicy policy, Rule &&rule, const ContTarget &cont_target, ContArgs &&... cont_args)
	Apply a rule asynchronously to manually updated states.
template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class RNG , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::on, int > = 0>
void	apply_rule (Rule &&rule, const ContTarget &cont_target, RNG &&rng, ContArgs &&... cont_args)
	Sequential case overload.
template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class RNG , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::on, int > = 0>
void	apply_rule (const Utopia::ExecPolicy policy, Rule &&rule, const ContTarget &cont_target, RNG &&rng, ContArgs &&... cont_args)
	Apply a rule asynchronously and shuffled to manually updated states.
template<class Rule , class Container , bool sync = impl::entity_t<Container>::is_sync()>
std::enable_if_t< sync, void >	apply_rule (const Rule &rule, const Container &container)
	Apply a rule synchronously on the state of all entities of a container.
template<bool shuffle = true, class Rule , class Container , bool sync = impl::entity_t<Container>::is_sync()>
std::enable_if_t< not sync &&not shuffle, void >	apply_rule (const Rule &rule, const Container &container)
	Apply a rule on asynchronous states without prior shuffling.
template<bool shuffle = true, class Rule , class Container , class RNG , bool sync = impl::entity_t<Container>::is_sync()>
std::enable_if_t< not sync &&shuffle, void >	apply_rule (const Rule &rule, const Container &container, RNG &&rng)
	Apply a rule on asynchronous states with prior shuffling.
template<class exc_t >
int	handle_exception (exc_t &exc)
	A helper function to handle a Utopia-specific exception.
template<IterateOver iterate_over, Update mode, typename Graph , typename Rule , typename std::enable_if_t< mode==Update::sync, int > = 0>
void	apply_rule (Rule &&rule, Graph &&g)
	Synchronously apply a rule to graph entities.
template<IterateOver iterate_over, Update mode, Shuffle shuffle, typename Graph , typename Rule , typename std::enable_if_t< mode==Update::async, int > = 0>
void	apply_rule (Rule &&rule, Graph &&g)
	Asynchronously apply a rule to graph entities, without shuffling.
template<IterateOver iterate_over, Update mode, Shuffle shuffle = Shuffle::on, typename Graph , typename Rule , typename RNG , typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< shuffle==Shuffle::on, int > = 0>
void	apply_rule (Rule &&rule, Graph &&g, RNG &&rng)
	Asynchronously, in shuffled order, apply a rule to graph entities.
template<IterateOver iterate_over, Update mode, typename Graph , typename Rule , typename VertexDesc = typename boost::graph_traits< std::remove_reference_t<Graph>>::vertex_descriptor, typename std::enable_if_t< mode==Update::sync, int > = 0>
void	apply_rule (Rule &&rule, const VertexDesc ref_vertex, Graph &&g)
	Synchronously apply a rule to graph entities.
template<IterateOver iterate_over, Update mode, Shuffle shuffle = Shuffle::on, typename Graph , typename Rule , typename VertexDesc = typename boost::graph_traits< std::remove_reference_t<Graph>>::vertex_descriptor, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< shuffle==Shuffle::off, int > = 0>
void	apply_rule (Rule &&rule, const VertexDesc ref_vertex, Graph &&g)
	Asynchronously apply a rule to graph entities, without shuffling.
template<IterateOver iterate_over, Update mode, Shuffle shuffle = Shuffle::on, typename Graph , typename Rule , typename RNG , typename VertexDesc = typename boost::graph_traits< std::remove_reference_t<Graph>>::vertex_descriptor>
void	apply_rule (Rule &&rule, const VertexDesc ref_vertex, Graph &&g, RNG &&rng)
	Asynchronously, in shuffled order, apply a rule to graph entities.
template<IterateOver iterate_over, typename Graph >
decltype(auto)	range (const Graph &g)
	Get the iterator range over selected graph entities.
template<IterateOver iterate_over, typename Graph , typename EntityDesc >
decltype(auto)	range (EntityDesc e, const Graph &g)
	Get the iterator range over selected graph entities.
std::string	grid_structure_to_string (const GridStructure &structure)
	Given an GridStructure enum value, return the corresponding string key.
std::string	nb_mode_to_string (const NBMode &nb_mode)
	Given an NBMode enum value, return the corresponding string key.
std::shared_ptr< spdlog::logger >	init_logger (const std::string name, const spdlog::level::level_enum level, const bool throw_on_exist=true)
	Initialize a logger with a certain name and log level.
void	setup_loggers (const spdlog::level::level_enum level_core=spdlog::level::warn, const spdlog::level::level_enum level_data_io=spdlog::level::warn, const spdlog::level::level_enum level_data_mngr=spdlog::level::warn, const std::string &log_pattern="")
	Set up and register the global loggers and set the global log pattern.
template<class Func , class... Args>
auto	exec_parallel (MAYBE_UNUSED const Utopia::ExecPolicy policy, Func &&f, Args &&... args)
	Call a function with an STL execution policy and arguments.
std::string	selection_mode_to_string (const SelectionMode &mode)
	Given a SelectionMode enum value, return the corresponding string key.
template<class Manager , class Container = EntityContainer<typename Manager::Entity>>
Container	select_entities (const Manager &mngr, const DataIO::Config &sel_cfg)
	Select entities according to parameters specified in a configuration.
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, class Condition = std::function<bool(const std::shared_ptr<typename Manager::Entity>&)>, typename std::enable_if_t< mode==SelectionMode::condition, int > = 0>
Container	select_entities (const Manager &mngr, const Condition &condition)
	Return a container with entities that match the given condition.
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::sample, int > = 0>
Container	select_entities (const Manager &mngr, const int num_entities)
	Select a sample of entities randomly.
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::probability, int > = 0>
Container	select_entities (const Manager &mngr, const double probability)
	Select entities with a certain probability.
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::position, int > = 0>
Container	select_entities (const Manager &mngr, const std::vector< typename Manager::SpaceVec > &positions)
	Selects cells at given positions in space.
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::boundary, int > = 0>
Container	select_entities (const Manager &mngr, const std::string &boundary)
	Selects cells on a boundary.
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::lanes, int > = 0>
Container	select_entities (const Manager &mngr, const unsigned int num_vertical, const unsigned int num_horizontal, const std::pair< double, double > permeability={0., 0.}, const std::pair< unsigned int, unsigned int > gate_width={0, 0})
	Selects horizontal or vertical lanes of cells.
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::clustered_simple, int > = 0>
Container	select_entities (const Manager &mngr, const double p_seed, const double p_attach, const unsigned int num_passes)
	Selects cells that are clustered using a simple clustering algorithm.
void	default_signal_handler (int signum)
	Default signal handler function, only setting the stop_now global flag.
template<typename Handler >
void	attach_signal_handler (int signum, Handler &&handler)
	Attaches a signal handler for the given signal via sigaction.
void	attach_signal_handler (int signum)
	Attaches the default signal handler for the given signal.
template<class Cont = std::vector<std::string>>
std::string	join (const Cont &cont, const std::string &delim=", ")
	Joins together the strings in a container.
template<class SeqCont = std::vector<std::string>>
SeqCont	split (const std::string &s, const std::string &delims=" ")
	Splits a string and returns a container of string segments.
template<typename ReturnType >
ReturnType	get_as (const std::string &key, const DataIO::Config &node)
	This function is a wrapper around the yaml-cpp YAML::Node::as function.
template<typename ReturnType >
ReturnType	get_as (const std::string &key, const DataIO::Config &node, ReturnType fallback)
	Like Utopia::get_as, but instead of KeyError, returns a fallback value.
template<DimType dim>
SpaceVecType< dim >	get_as_SpaceVec (const std::string &key, const DataIO::Config &node)
	Special case of Utopia::get_as to retrieve an entry as SpaceVec.
template<DimType dim>
MultiIndexType< dim >	get_as_MultiIndex (const std::string &key, const DataIO::Config &node)
	Special case of Utopia::get_as to retrieve an entry as MultiIndex.

Variables
const std::map< std::string, GridStructure >	grid_structure_map
	A map from strings to grid structure enum values.
const std::map< std::string, NBMode >	nb_mode_map
	A map from strings to neighborhood enum values.
const std::string	log_core = "core"
const std::string	log_data_io = "data_io"
const std::string	log_data_mngr = "data_mngr"
constexpr WriteMode	DefaultWriteMode = WriteMode::basic
	Alias for the default write mode.
const std::map< std::string, SelectionMode >	selection_mode_map
	A map from strings to Select enum values.
std::atomic< bool >	stop_now
	The flag indicating whether to stop whatever is being done right now.
std::atomic< int >	received_signum
	The received signal value.

Typedef Documentation

AgentContainer

template<typename AgentType >

using Utopia::AgentContainer = typedef EntityContainer<AgentType>

Type of the variably sized container for agents.

CellContainer

template<typename CellType >

using Utopia::CellContainer = typedef EntityContainer<CellType>

Type of the variably sized container for cells.

Config

using Utopia::Config = typedef DataIO::Config

Type of a variadic dictionary-like data structure used throughout Utopia.

DefaultRNG

using Utopia::DefaultRNG = typedef std::mt19937

Type of default random number generator.

DimType

using Utopia::DimType = typedef unsigned short

Type for dimensions, i.e. very small unsigned integers.

DistType

using Utopia::DistType = typedef unsigned int

Type for distancens, i.e. intermediately long unsigned integers.

EntityContainer

template<typename EntityType >

using Utopia::EntityContainer = typedef std::vector<std::shared_ptr<EntityType> >

Type of the variably sized container for entities.

IndexContainer

using Utopia::IndexContainer = typedef std::vector<IndexType>

Type for container of indices.

IndexType

using Utopia::IndexType = typedef std::size_t

Type for indices, i.e. values used for container indexing, agent IDs, ...

MultiIndexType

template<DimType dim>

using Utopia::MultiIndexType = typedef arma::Col<IndexType>::fixed<dim>

Type for index type vectors that are associated with a physical space.

Uses a fixed-size Armadillo column vector of IndexType

Note

This vector is not to be interpreted as a "container"

Template Parameters

dim	The dimensionality (or: rank) of the vector

SpaceVecType

template<DimType dim>

using Utopia::SpaceVecType = typedef arma::Col<double>::fixed<dim>

Type for vector-like data that is associated with a physical space.

Uses a fixed-size Armadillo column vector of doubles

Template Parameters

dim	The dimensionality (or: rank) of the vector

Function Documentation

attach_signal_handler() [1/2]

void Utopia::attach_signal_handler

(

int

signum

)

Attaches the default signal handler for the given signal.

                                       {
    attach_signal_handler(signum, default_signal_handler);
}

attach_signal_handler() [2/2]

template<typename Handler >

void Utopia::attach_signal_handler	(	int	signum,
		Handler &&	handler
	)

Attaches a signal handler for the given signal via sigaction.

This function constructs a sigaction struct for the given handler and attaches it to the specified signal number.

Parameters

signum	The signal number to attach a custom handler to
handler	Pointer to the function that should be invoked when the specified signal is received.

                                                          {
    // Initialize the signal flag to make sure it is false
    stop_now.store(false);
 
    // Also initialize the global variable storing the received signal
    received_signum.store(0);
 
    // Use POSIX-style sigaction definition rather than deprecated signal
    struct sigaction sa;
    sa.sa_handler = handler;
    sa.sa_flags = 0;
 
    // Add only the given signal to the set of actions
    // See sigaddset documentation: https://linux.die.net/man/3/sigfillset
    sigaddset(&sa.sa_mask, signum);
 
    sigaction(signum, &sa, NULL);
}

default_signal_handler()

void Utopia::default_signal_handler

(

int

signum

)

Default signal handler function, only setting the stop_now global flag.

                                        {
    stop_now.store(true);
    received_signum.store(signum);
}

handle_exception()

template<class exc_t >

int Utopia::handle_exception

(

exc_t &

exc

)

A helper function to handle a Utopia-specific exception.

Parameters

exc	The exception to handle

Returns

int The exit code from the exception

                                 {
    std::cerr << exc.what() << std::endl;
    return exc.exit_code;
}

join()

template<class Cont = std::vector<std::string>>

std::string Utopia::join	(	const Cont &	cont,
		const std::string &	delim = ", "
	)

Joins together the strings in a container.

Wraps boost::algorithm::join

                                                                 {
    if (cont.empty()) {
        return "";
    }
    return boost::algorithm::join(cont, delim);
}

split()

template<class SeqCont = std::vector<std::string>>

SeqCont Utopia::split	(	const std::string &	s,
		const std::string &	delims = " "
	)

Splits a string and returns a container of string segments.

Wraps boost::algorithm::split. This function aims to cover typical use cases for string splitting, not the task of string splitting in general.

Template Parameters

SeqCont

The container type to use; note that the element type of that container always be std::string

Parameters

s	The string to split according to delims
delims	The delimiters (plural!) to split by. Will be passed to boost::is_any_of.

Note

The boost::is_any_of classifier being used here means that any character in delims is used as a delimiter, even if they are on their own. Additionally, the boost::algorithm::token_compress_on qualifier is used, meaning that adjacent tokens are compressed and do not lead to an empty segment entry. However, note that a delimiter like -> will match -> but also >- ->- ->>- and other combinations!

                                                                  {
    auto segments = SeqCont{};
 
    if (s.empty()) {
        return segments;
    }
 
    boost::split(segments, s, boost::is_any_of(delims),
                 boost::algorithm::token_compress_on);
    return segments;
}

Variable Documentation

received_signum

std::atomic<int> Utopia::received_signum

The received signal value.

stop_now

std::atomic<bool> Utopia::stop_now

The flag indicating whether to stop whatever is being done right now.

This needs to be an atomic flag in order to be thread-safe. While the check of this flag is about three times slower than checking a boolean's value (quick-bench.com/IRtD4sQfp_xUwGPa2YrATD4vEyA), this difference is minute to other computations done between two checks.