Entity Selection

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.

---

Configuration Access

When is 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]

There, the mode is crucial. Only those parameters that are relevant for the chosen mode are used; the others may be present, but will be ignored.

Note

The enabled key is not a part of the select_entities interface, but is implemented by the calling structure.

Which selection modes are available?

Selection modes are defined in the Utopia::SelectionMode enum.

The following is an excerpt from the C++ documentation, showing available selection modes. For information on parameters corresponding to each mode, take a look there or at the documentation of the respective implementations.

group SelectionModes

Enums

enum class SelectionMode

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.

Values:

enumerator condition

Select if a condition is fulfilled.

enumerator sample

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

enumerator probability

Select an entity with a given probability.

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

enumerator position

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

enumerator boundary

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

enumerator lanes

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

Functions

std::string 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.

Variables

const std::map<std::string, SelectionMode> selection_mode_map{{"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.

Selecting from the CellManager

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.

Change your space configuration such that it reads

space:
  periodic: false