Utopia provides a config-accessible interface to select a subset of entities from a manager, e.g. cells from a
CellManager. This page aims to answer some basic questions regarding that interface. For a full documentation, you should consult the About the C++ Documentation, e.g. by starting from the module on entity selection.
select_entities accessible via the configuration?#
Whenever a model documentation states that it uses the
select_entities interface, it means that a configuration node is passed down into that function. You can thus make changes to the configuration file and thereby change which entities are selected.
For example, ForestFire Model uses this interface to configure heterogeneities:
# Some cells can be permanently ignited or turned into stones. # Both these features are using the `select_entities` interface; consult the # documentation regarding information on available selection modes. # Turn some cells into stones: these do not take part in any of the processes stones: enabled: !is-bool false mode: !param name: selection mode for stones default: clustered_simple is_any_of: &selection_modes - sample - probability - position - boundary - lanes - clustered_simple # Clustering parameters p_seed: !is-probability .02 # Probability for a cell being a cluster seed p_attach: !is-probability .1 # Attachment probability (per neighbor) num_passes: !is-unsigned 5 # How many attachment procedures to perform # Depending on mode, can pass additional parameters here. # Set some cells on fire permanently (invoked after stones are set) ignite_permanently: enabled: !is-bool false mode: !param name: selection mode for permanently ignited cells default: boundary is_any_of: *selection_modes # Boundary selection parameters (requires space to be set to NON-periodic!) boundary: !param default: bottom is_any_of: [bottom, top, left, right, all]
mode is crucial. Only those parameters that are relevant for the chosen mode are used; the others may be present, but will be ignored.
enabled key is not a part of the
select_entities interface, but is implemented by the calling structure.
Which selection modes are available?#
The following is an excerpt from the C++ documentation. For information on parameters corresponding to each mode, take a look there.
enum class Utopia::SelectionMode#
Possible selection modes; availability depends on choice of manager.
For further details, consult the actual implementations.
Associated integer values may be subject to change.
Select if a condition is fulfilled.
Select a random sample of entities with a known sample size.
Select an entity with a given probability.
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.
Currently only implemented for CellManager, but expandable to all managers that provide a neighborhood interface for the entities they manage.
(For CellManager only) Selects cells at given positions in space
(For CellManager only) Select the boundary cells of a grid
(For CellManager only) Selects horizontal or vertical lanes of cells
- enumerator condition#
Selecting from the
Why can’t I select boundary cells?#
Probably because you have configured a periodic space and for periodic space it does not really make sense to be able to configure a boundary. You should also see a warning in your logs that states this.
space configuration such that it reads
space: periodic: false