Merge branch 'integrate-updated-hexgrid' into 'master'

endif()

# -- utopya

set(UTOPYA_REQUIRED_VERSION 1.1.1)

set(UTOPYA_REQUIRED_VERSION 1.1.3)

if(NOT UTOPYA_FROM_PYPI)

    set(UTOPYA_FROM_PYPI On)

# Evaluation for hexgrid plot

---

_utopia_colors: &utopia_colors

  dark_blue:          &darkblue           '#003366'

  medium_blue:        &mediumblue         '#0099CC'

  light_blue:         &lightblue          '#99CCFF'

  dark_green:         &darkgreen          '#006666'

  medium_green:       &mediumgreen        '#339999'

  light_green:        &lightgreen         '#AFD8BC'

  yellow:             &yellow             '#FFCC66'

  red:                &red                '#CC3333'

  cream_white:        &creamwhite         '#F6F6F6'

  white:              &white              '#fff'

  black:              &black              '#000000'

  gray:               &gray               '#F7F9FF'

  dark_gray:          &darkgray           '#666666'

_default_style: &default_style

  style:

    text.usetex: True

    mathtext.fontset: stix

    font.family: serif

.flush_kind_cmap:

  to_plot:

    kind:

      limits: ~

      cmap: ~

# -----------------------------------------------------------------------------

kind_snapshot:

  based_on:

    - ca/state

    - .plot.ca.snapshot

    - .flush_kind_cmap

  # Choose a frame that is more interesting

  frames_isel: 11

  # Do not add a time stamp

  suptitle_fstr: ~

  to_plot:

    kind:

      vmin: 0

      vmax: 3

      # Use a custom cmap; these colors must be globally defined somewhere

      cmap:

        empty: *white

        susceptible: *lightgreen

        infected: *red

        recovered: *darkgreen

# Runs SEIRD with a hexagonal grid

---

parameter_space:

  num_steps: 365

  SEIRD:

    cell_manager:

      grid:

        structure: hexagonal

        resolution: 32

      neighborhood:

        mode: hexagonal

.flush_cmap:

  cmap: ~

# -----------------------------------------------------------------------------

# Failing plots for usage/eval/dag/debug.rst

        - .sel: [!dag_prev , {kind: SuSCePTIble}]

### END --- debug_DAG_bad_args

.flush_select:

  select: ~

debug_DAG_locate_with_vis:

  based_on:

    - .debug_DAG

    - phase_diagram/SI

    - .flush_select

### START --- debug_DAG_locate_with_vis

  select:

# -----------------------------------------------------------------------------

# Demonstrates a basic line plot

density_basic:

      transform:

        - .sel: [!dag_prev , { kind: [infected] }]

# Demonstrates a basic line plot with style adjustments

### Start --- line_plot

line_plot:

      title: Density of infected agents

### End --- line_plot

# Demonstrates a stacked line plot

stacked_kinds:

  based_on:

    set_title:

      title: Density of agent kinds

# Demonstrates an animated cellular automaton

### Start --- .plot.ca.

animated_ca:

  to_plot:

    kind:

      limits: [0, 3]

      # Use a custom cmap; these colors must be globally defined somewhere

      # Will automatically be mapped to values [0, 1, 2, 3]

      cmap:

        empty: *white

        susceptible: *lightgreen

    font.size: 10

### End --- .plot.ca.

# Demonstrates a simple 2D scatter plot

scatter_2d_simple:

  based_on:

    set_title:

      title: ~

# Demonstrates a 2D scatterplot with an additional variable plotted on the 'hue'

# Demonstrates a 2D scatterplot with an additional variable plotted on 'hue'

### Start --- scatter_2d

scatter_2d:

  based_on:

  color: ~

# Demonstrates a 3D scatter plot with hue

### Start --- scatter_3d

scatter_3d:

      0.8: *lightblue

      1: *darkblue

# Demonstrates some PlotHelper features

helper_demo:

  based_on:

        major:

          locs: [0, 0.1, 0.2, 0.3, 0.4]

          labels: ['No', more, trouble, with, tick labels]

ca/state:

  based_on:

    - .creator.universe

    - .plot.ca

  enabled: false

  select:

    kind: kind

  to_plot:

    kind:

      title: State

      limits: [0, 7]

  suptitle_fstr: False

---------------------------

Which ways are there to initialize cells and agents?

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are three different ways to initialize cells and agents in your ``CellManager`` or ``AgentManager``. The examples below are for the ``CellManager`` but apply analogously to the ``AgentManager``.

Constructing an initial state from configuration (recommended)

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Constructing an initial state from configuration *(recommended)*

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

For this (recommended) way, the constructor of the state type accepts a ``Utopia::Config&`` node, from which all the information needed for that state can be extracted:

.. code-block:: c++

      a_bool: true

  # Other model configuration parameters ...

.. note::

  As the ``CellManager`` is not finished with construction at this point, it is

Constructing an initial state from the default constructor

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

As default constructors can sometimes lead to undefined behaviour, they need to be explicitly allowed. This happens via the ``Utopia::CellTraits`` struct.

.. code-block:: c++

Explicit initial state

""""""""""""""""""""""

In this mode, all cells have an identical initial state, which is passed down from the ``CellManager``. Assuming you are setting up the manager as a member of ``MyFancyModel``, this would look something like this:

.. code-block:: c++

      {}

  };

.. _random_num_q:

Can I use a random number generator when constructing cells or agents?

.. _cell_manager_faq:

``CellManager`` FAQs

Neighborhood calculation

^^^^^^^^^^^^^^^^^^^^^^^^

Where and how are neighborhoods calculated?

"""""""""""""""""""""""""""""""""""""""""""

The neighborhood computation does not take place in the ``CellManager`` itself, but in the underlying ``Grid`` object and based on the cells' IDs.

The ``CellManager`` then retrieves the corresponding shared pointers from the IDs and makes them available via the ``neighbors_of`` method.

Are neighborhoods computed on the fly, or can I cache them?

"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Yes, the ``CellManager`` allows caching the neighborhood computation's result.

This feature can be controlled via the ``compute_and_store`` argument.

If enabled (which is the default), the neighborhood is computed once for each cell, stored, and retrieved upon calls to ``neighbors_of``.

For more information, see `the doxygen documentation <../../doxygen/html/class_utopia_1_1_cell_manager.html>`_.

Having this feature enabled gives a slight performance gain in most situations.

However, if memory is limited, it might make sense to disable it:

.. code-block:: yaml

    cell_manager:

      neighborhood:

        mode: Moore

        compute_and_store: false

.. note::

    In the ``Grid`` itself, the IDs of the cells in the neighborhood are always computed on the fly.

.. _cell_manager_grid_discretization:

Can I change the grid discretization? And when should I?

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Yes, the grid discretization can be changed.

Currently available are the ``square`` and ``hexagonal`` grid discretizations.

To change this, select the respective ``structure`` and ``neighborhood/mode`` in the ``cell_manager``'s configuration

To change this, select the respective ``structure`` and ``neighborhood/mode`` in the ``cell_manager``'s configuration:

.. code-block:: yaml

    cell_manager:

      grid:

        structure: square   # can be: square or hexagonal

      resolution: 42      # 42 cells per unit length (of space)

        resolution: 42      # cells per unit length (of space)

      neighborhood:

        mode: Moore         # can be: empty (0), vonNeumann (4), Moore (8) (with square structure)

.. note::

  The ``resolution`` of the ``hexagonal`` discretization is evaluated per unit area (of space), instead of unit length, as the extent of a hexagon is non-isotrop.

  I.e. with a resolution of 32 in 1x1 space, there will be 30 x 34 = 1020 cells.

    The ``resolution`` of the ``hexagonal`` discretization is evaluated per unit area (of space), instead of unit length, as the extent of a hexagon is non-isotropic.

    I.e. with a resolution of 32 in a space with extent ``(1.0, 1.0)``, there will be 30 x 34 = 1020 cells.

The grid discretization, together with the respectively available neighborhoods, should be changed when exploring the influence of geometry and cell-connectivity on cell-cell interactions.

In particular, the number of neighbors per cell can be varied between

In the ``Moore`` neighborhood they are too close with distance 1, where the true distance of the cell centers would be :math:`\sqrt{2}`.

In the ``hexagonal`` discretization all neighbors have the true unit distance, however this is only true for paths that are 60° (instead of 90°) apart.

For more details have a look at the `grid implementation <../../doxygen/html/class_utopia_1_1_grid.html>`_ and `these tutorial <https://www.redblobgames.com>`_.

Are neighborhoods computed on the fly, or can I cache them?

"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Yes, the ``CellManager`` allows caching the neighborhood computation's result.

This feature can be controlled via the ``compute_and_store`` argument.

If enabled (which is the default), the neighborhood is computed once for each cell, stored, and retrieved upon calls to ``neighbors_of``.

For more information, see `the doxygen documentation <../../doxygen/html/class_utopia_1_1_cell_manager.html>`_.

For more details (e.g. regarding coordinate mode, cell orientation etc.) have a look at the `grid implementation <../../doxygen/html/class_utopia_1_1_grid.html>`_ and `this excellent introduction to hexagonal grid representation <https://www.redblobgames.com/grids/hexagons/>`_.

Having this feature enabled gives a slight performance gain in most situations.

However, if memory is limited, it might make sense to disable it:

.. note::

.. code-block:: yaml

    For an example for comparing these, have a look at the :ref:`SEIRD model <model_SEIRD>` and its ``grid_structure_sweep`` config set.

    cell_manager:

      neighborhood:

        mode: Moore

        compute_and_store: false

.. hint::

.. note::

    In the ``Grid`` itself, the IDs of the cells in the neighborhood are always computed on the fly.

    The plot function specialized on cellular automata, ``.plot.ca``, can visualize hexagonal grids out-of-the-box.

    For more info, see :ref:`the corresponding page <plot_ca_hex>`.