Utopia  2
Framework for studying models of complex & adaptive systems.
Classes | Enumerations | Functions | Variables
Entity Selection

An interface to select a subset of entities from a manager. More...

Collaboration diagram for Entity Selection:

Classes

struct  Utopia::is_cell_manager< M >
 Metafunction to determine whether a Manager is a CellManager. More...
 
struct  Utopia::is_agent_manager< M >
 Metafunction to determine whether a Manager is an AgentManager. More...
 

Enumerations

enum class  Utopia::SelectionMode {
  Utopia::condition = 0 , Utopia::sample = 1 , Utopia::probability = 2 , Utopia::clustered_simple = 20 ,
  Utopia::position = 100 , Utopia::boundary = 101 , Utopia::lanes = 102
}
 Possible selection modes; availability depends on choice of manager. More...
 

Functions

std::string Utopia::selection_mode_to_string (const SelectionMode &mode)
 Given a SelectionMode enum value, return the corresponding string key. More...
 
template<class Manager , class Container = EntityContainer<typename Manager::Entity>>
Container Utopia::select_entities (const Manager &mngr, const DataIO::Config &sel_cfg)
 Select entities according to parameters specified in a configuration. More...
 
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 Utopia::select_entities (const Manager &mngr, const Condition &condition)
 Return a container with entities that match the given condition. More...
 
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::sample, int > = 0>
Container Utopia::select_entities (const Manager &mngr, const int num_entities)
 Select a sample of entities randomly. More...
 
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::probability, int > = 0>
Container Utopia::select_entities (const Manager &mngr, const double probability)
 Select entities with a certain probability. More...
 
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::position, int > = 0>
Container Utopia::select_entities (const Manager &mngr, const std::vector< typename Manager::SpaceVec > &positions)
 Selects cells at given positions in space. More...
 
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::boundary, int > = 0>
Container Utopia::select_entities (const Manager &mngr, const std::string &boundary)
 Selects cells on a boundary. More...
 
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::lanes, int > = 0>
Container Utopia::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. More...
 
template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::clustered_simple, int > = 0>
Container Utopia::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. More...
 

Variables

const std::map< std::string, SelectionModeUtopia::selection_mode_map
 A map from strings to Select enum values. More...
 

Detailed Description

An interface to select a subset of entities from a manager.

The Utopia constructs Utopia::Cell and Utopia::Agent both have a common parent type: Utopia::Entity. Additionally, there are corresponding manager types that provide an interface to work with these entities: Utopia::CellManager and Utopia::AgentManager.

Given this structure, Utopia is able to provide a common interface with which a subset of entities can be selected in a consistent and configurable fashion. This allows to re-use the selection algorithms and while also allowing specializations for certain entity types.

The interface requires managers of Utopia::Entity -derived types; let's call them EntityManagers for now. (Side note: The interface is currently only assumed; the CellManager and AgentManager are yet to be based on a common base class). These managers provide the embedding of a container of entities, which is required as soon as more complicated selections are to be performed, e.g. selecting cells that are distributed in a certain pattern in space.

For the mode of selection, the Utopia::SelectionMode is used. For each mode value, a Utopia::select_entities method is specialized. That method defines the parameters required for the selection. The whole interface is made accessible via configuration by the specialization that accepts a Utopia::DataIO::Config as argument. Furthermore, the entity managers can implement a method that makes use of the free functions defined here, for example Utopia::CellManager::select_entities .

This selection interface has a similar motivation as the Utopia::apply_rule interface; in fact, it cooperates nicely with that interface, as you can first select some entities and then apply an operation to them...

Enumeration Type Documentation

◆ SelectionMode

enum Utopia::SelectionMode
strong

Possible selection modes; availability depends on choice of manager.

For further details, consult the actual implementations.

Warning
Associated integer values may be subject to change.
Enumerator
condition 

Select if a condition is fulfilled.

sample 

Select a random sample of entities with a known sample size.

probability 

Select an entity with a given probability.

clustered_simple 

Select entity clusters using a simple neighborhood-based algorithm.

Uses the "simple" algorithm: From a given start population, iterate over neighbors and attach them with a certain probability.

Note
Currently only implemented for CellManager, but expandable to all managers that provide a neighborhood interface for the entities they manage.
position 

(For CellManager only) Selects cells at given positions in space

boundary 

(For CellManager only) Select the boundary cells of a grid

lanes 

(For CellManager only) Selects horizontal or vertical lanes of cells

Function Documentation

◆ select_entities() [1/8]

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 Utopia::select_entities ( const Manager &  mngr,
const Condition &  condition 
)

Return a container with entities that match the given condition.

Parameters
mngrThe manager to select the entities from
conditionA unary function working on a single entity and returning a boolean.

◆ select_entities() [2/8]

template<class Manager , class Container = EntityContainer<typename Manager::Entity>>
Container Utopia::select_entities ( const Manager &  mngr,
const DataIO::Config sel_cfg 
)

Select entities according to parameters specified in a configuration.

Via the mode key, one of the modes (see Utopia::SelectionMode) can be selected. Depending on that mode, the other parameters are extracted from the configuration.

Available keys for each mode:

  • sample mode: num_cells
  • probability mode: probability
  • positions mode: positions (a list of coordinate pairs)
  • boundary mode: boundary (a string, e.g. left, right, top, bottom)
  • lanes mode: num_horizontal, num_vertical, permeability (optional; can be given as scalar, pair, or mapping w/ keys horizontal and vertical), gate_width (optional, same as permeability)
  • clustered_simple mode: p_seed, p_attach, num_passes
Note
The Utopia::SelectionMode::condition is not available!
Parameters
mngrThe manager to select the entities from
sel_cfgThe configuration node containing the expected key-value pairs specifying the selection.

◆ select_entities() [3/8]

template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::clustered_simple, int > = 0>
Container Utopia::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.

This is done by first determining some "seed" cells and then attaching their neighbors to them with a certain probability.

Parameters
mngrThe manager to select the entities from. Needs to be a Utopia::CellManager for this function.
p_seedThe probability with which a cell becomes a seed for a cluster
p_attachThe probability with which a neighbor of a cluster cell is also added to the cluster
num_passesHow often to invoke the attachment iteration

\TODO Could generalize this to all kinds of entities that have neighbors.

◆ select_entities() [4/8]

template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::probability, int > = 0>
Container Utopia::select_entities ( const Manager &  mngr,
const double  probability 
)

Select entities with a certain probability.

Iterates over all entities and selects each entity with the given probability.

Note
The order of the entities in the returned container is the same as in the underlying container!
Parameters
mngrThe manager to select the entities from
probabilityThe probablity with which a single entity is selected

◆ select_entities() [5/8]

template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::sample, int > = 0>
Container Utopia::select_entities ( const Manager &  mngr,
const int  num_entities 
)

Select a sample of entities randomly.

Uses std::sample to select num_entities randomly.

Note
The order of the entities in the returned container is the same as in the underlying container!
Parameters
mngrThe manager to select the entities from
num_entitiesThe number of entities to sample from the given container. Need be a value in [0, container size]

◆ select_entities() [6/8]

template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::boundary, int > = 0>
Container Utopia::select_entities ( const Manager &  mngr,
const std::string &  boundary 
)

Selects cells on a boundary.

Invokes CellManager::boundary_cells

Parameters
mngrThe manager to select the entities from. Needs to be a Utopia::CellManager for this work.
boundaryWhich boundary to select.

◆ select_entities() [7/8]

template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::position, int > = 0>
Container Utopia::select_entities ( const Manager &  mngr,
const std::vector< typename Manager::SpaceVec > &  positions 
)

Selects cells at given positions in space.

Invokes CellManager::cell_at to populate a container of cells that are at the given absolute positions. Which cells are selected depends on the chosen discretization, see Utopia::Grid and the derived classes.

Parameters
mngrThe manager to select the entities from. Needs to be a Utopia::CellManager for this work.
positionsAbsolute positions; the cells under these positions are then selected.

◆ select_entities() [8/8]

template<SelectionMode mode, class Manager , class Container = EntityContainer<typename Manager::Entity>, typename std::enable_if_t< mode==SelectionMode::lanes, int > = 0>
Container Utopia::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.

The lanes are spaced such that the domain is divided into N equally large parts for periodic space and N+1 parts for non-periodic space in each dimension.

For example:

  • In non-periodic space, two vertical lanes will be set at 1/3 and 2/3 relative position of the space, thus dividing the domain into three parts in x-direction
  • In periodic space, one needs to take the wraparound into account. Two vertical lanes would then be set at the lower-value boundary and at the center of the grid and would divide the domain into two parts! For three lanes, they would be at 0/3, 1/3, and 2/3 of the relative space extent along the x-dimension.

Calculation occurs by first determining the relative position along the corresponding dimension at which a lane is to occur. From that, the multi- multi-index is computed, and then all cells that match the desired multi index component are selected to become part of the lane. This is done on the grid level, i.e.: on the level of multi indices. As all grid discretizations can operate on multi-indices, this approach is valid among all types of grid discretizations.

Parameters
mngrThe manager to select the entities from. Needs to be a Utopia::CellManager .
num_verticalNumber of vertical lanes
num_horizontalNumber of horizontal lanes
permeabilityThe permeability of the horizontal and vertical lanes, respectively. The probability that a cell is spared out. Optional.
gate_widthThe width of gates in the horizontal and vertical lanes, respectively. Given in number of cells per compartment, i.e. between two lanes. Optional.

◆ selection_mode_to_string()

std::string Utopia::selection_mode_to_string ( const SelectionMode mode)

Given a SelectionMode enum value, return the corresponding string key.

This iterates over the selection_mode_map and returns the first key that matches the given enum value.

Variable Documentation

◆ selection_mode_map

const std::map<std::string, SelectionMode> Utopia::selection_mode_map
Initial value:
{
{"condition", SelectionMode::condition},
{"sample", SelectionMode::sample},
{"probability", SelectionMode::probability},
{"position", SelectionMode::position},
{"boundary", SelectionMode::boundary},
{"lanes", SelectionMode::lanes},
{"clustered_simple", SelectionMode::clustered_simple}
}

A map from strings to Select enum values.