ContDisease — Contagious Diseases#

This is a simple model of a contagious disease on a 2D grid.

Fundamentals#

We model a “forest” on a two-dimensional square grid of cells. Each cell can be in one of five different states: empty, tree, infected, source, or stone.

Implementation#

Update Rules#

In each time step, the cells update their respective states according to the following rules:

  1. An infected cell turns into an empty cell.

  2. An empty cell can become a tree cell with probability p_growth.

  3. A tree cell can become infected in the following ways:

    • from a neighboring infected cell with probability 1-p_immunity per neighbor,

    • via a random point infection with probability p_infect,

    • via a constantly infected cell, an infection source.

For the neighborhood, both the von Neumann neighborhood (5-neighborhood) and the Moore neighborhood (9-neighborhood) are supported (see model configuration).

Heterogeneities#

As in the Forest Fire model, there is the possibility to introduce heterogeneities into the grid, which are implemented as two additional possible cell states:

  • source: these are constant infection sources. They spread infection like normal infected trees, but don not revert back to the empty state. If activated, they are per default on the lower boundary of the grid, though this can be changed in the configuration.

  • stone: stones are cells that can not be infected nor turn into trees. They are used to represent barriers in the forest. If enabled, the default mode is clustered_simple, which leads to randomly distributed stones whose neighbours have a certain probability to also be a stone.

Both make use of the entity selection interface.

Infection Control#

Via the infection_control parameter in the model configuration, additional infections can be introduced at desired times. The infections are introduced before the update rule above is carried out.

Data Output#

The following data is stored alongside the simulation:

  • kind: the state of each cell. Possible values:

    • 0: empty

    • 1: tree

    • 2: infected

    • 3: source, is constantly ignited

    • 4: stone, does not take part in any interaction

  • age: the age of each tree, reset after lightning strikes

  • cluster_id: a number identifying to which cluster a cell belongs; 0 for non-tree cells

  • densities: the densities of each of the kind of cells over time; this is a labeled 2D array with the dimensions time and kind.

Default configuration parameters#

Below are the default configuration parameters for the ContDisease model.

# --- Space parameters --------------------------------------------------------
# The physical space this model is embedded in
space:
  periodic: false

# --- CellManager and cell initialization -------------------------------------
cell_manager:
  grid:
    structure: square
    resolution: 64      # in cells per unit length of physical space

  neighborhood:
    mode: vonNeumann

  # Cell initialization parameters
  cell_params:
    # Initial tree density, value in [0, 1]
    # With this probability, a cell is initialized as tree (instead of empty)
    p_tree: !is-probability 0

# --- Model Dynamics ----------------------------------------------------------
# Probability per site and time step to transition from state empty to tree
p_growth: !is-probability 7.5e-3

# Probability per site and time step for a tree cell to not become infected if
# an infected cell is in the neighborhood. This probability applies per event
# so it does _not_ mean that an immune cell is also immune in the next
# iteration step
p_immunity: !is-probability 0.

# Probability per site and time step for a random point infection of a tree
p_infect: !is-probability 0.
# NOTE This is affected by the infection control, see below.

# --- Infection Control -------------------------------------------------------
# Infection control to investigate the time-dependent influence of the 
# disease driving force. Note that infection control is applied at the
# beginning of an iteration step. It's effect is seen in the following
# time step
infection_control:
  enabled: !is-bool false

  # The number of additional infections to be placed on the grid
  num_additional_infections: !is-unsigned 10

  # Add the additional infections at the given times
  # Note the the !listgen tag creates a list from the parameters 
  # (start, stop, step_size)
  # To disable, pass an empty sequence.
  at_times: !listgen [0, 100, 20]

  # Change the probability of a random infection.
  # The expected value is a list of [iteration_step, new_value] pairs, e.g.
  #   - [10, .5]
  #   - [42, 0.]
  # ... will set p_infect from the default value to .5 at time 10 and set it
  # back to 0. at time 42.
  # To disable, pass an empty sequence.
  change_p_infect: []

# --- Heterogeneities ---------------------------------------------------------
# Some cells can be permanently infected 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: clustered_simple

  # Clustering parameters
  # Probability with which a cell is a cluster seed
  p_seed: !is-probability .02
  # Attachment probability (per neighbor) 
  p_attach: !is-probability .1
  num_passes: !is-unsigned 5  # How many attachment procedures to perform

# Set some cells to be permanently infected (invoked after stones are set)
infection_source:
  enabled: !is-bool true
  mode: boundary

  # Boundary selection parameters (requires space to be set to NON-periodic!)
  boundary: bottom

# --- Output Configuration ----------------------------------------------------
# Whether to only write out the densities; useful for runs on large grids
# where spatial information is not needed.
write_only_densities: !is-bool false

Available plots#

The following plot configurations are available for the ContDisease model:

Default Plot Configuration#

# --- Plot of all densities over time -----------------------------------------
densities:
  based_on: densities
  
# --- Create a phase plot of two densities ------------------------------------
phase_diagram:
  based_on: phase_diagram

  # Select from what densities to create the phase diagram
  x: tree
  y: infected

  helpers:
    set_labels:
      x: Tree Density [1/A]
      y: Infected Density [1/A]
    set_limits:
      x: [0, 0.7]
      y: [0, 0.01]

  # Parameters that are passed on to plot.scatter
  s: 10


# --- Snapshots and animations of the spatial grid ----------------------------
# NOTE These are both based on the snapshot base plots and add the remaining
#      parameters: For snapshots, the time index that is to be plotted; for
#      animations, the animation parameters (using multiple inheritance).

# ... The forest ..............................................................
forest_snapshot:
  based_on: forest_snapshot
  enabled: false
  time_idx: -1

forest:
  based_on: [forest_snapshot, .ca.state.anim_ffmpeg]

# ... The forest age ..........................................................
forest_age_snapshot:
  based_on: forest_age_snapshot
  enabled: false
  time_idx: -1

forest_age:
  based_on: [forest_age_snapshot, .ca.state.anim_ffmpeg]

# ... The clusters ............................................................
clusters_snapshot:
  based_on: clusters_snapshot
  enabled: false
  time_idx: -1

clusters:
  based_on: [clusters_snapshot, .ca.state.anim_ffmpeg]

# --- Miscellaneous -----------------------------------------------------------
# ... Combined plot of forest states and clusters .............................
forest_and_clusters:
  based_on: [forest_snapshot, clusters_snapshot, .ca.state.anim_ffmpeg]
  enabled: false

Base Plot Configuration#

# -- Any kind of phase plot ---------------------------------------------------
phase_diagram:
  based_on: .default_style_and_helpers

  creator: universe
  universes: all

  module: model_plots.ContDisease
  plot_func: phase_diagram

  cmap: viridis_r

  helpers:
    set_title:
      title: Phase Diagram


# -- Densities plot -----------------------------------------------------------
densities:
  based_on: .basic_uni.lineplots

  model_name: ContDisease

  to_plot:
    empty:
      path_to_data: densities
      transform_data:
        - sel: { kind: empty }
      label: empty
      color: &color_empty darkkhaki

    tree:
      path_to_data: densities
      transform_data:
        - sel: { kind: tree }
      label: tree
      color: &color_tree forestgreen

    infected:
      path_to_data: densities
      transform_data:
        - sel: { kind: infected }
      label: infected
      color: &color_infected firebrick

    source:
      path_to_data: densities
      transform_data:
        - sel: { kind: source }
      label: source
      color: &color_source orange

    stone:
      transform_data:
        - sel: { kind: stone }
      path_to_data: densities
      label: stone
      color: &color_stone slategray

  helpers:
    set_limits:
      x: [min, max]
      y: [0., 1.]
    set_labels:
      x: Time [Iteration Steps]
      y: Density [1/A]
    set_title:
      title: Densities
    set_legend:
      loc: best


# --- Grid Snapshots ----------------------------------------------------------
# NOTE These can also be used as basis for grid animations.
# ... The forest ..............................................................
forest_snapshot:
  based_on: .ca.state
  model_name: ContDisease
  
  to_plot:
    kind:
      title: Forest State
      limits: [0, 4]
      cmap:
        empty: *color_empty
        tree: *color_tree
        infected: *color_infected
        source: *color_source
        stone: *color_stone

# ... The forest age ..........................................................
forest_age_snapshot:
  based_on: .ca.state
  model_name: ContDisease

  to_plot:
    age:
      title: Forest Age
      cmap: YlGn

# ... The clusters ............................................................
clusters_snapshot:
  based_on: .ca.state
  model_name: ContDisease

  to_plot:
    cluster_id:
      title: Clusters
      limits: [0, 20]
      cmap: tab20
      no_cbar_markings: true

  transform_data:
    cluster_id:
      - where: ['!=', 0]       # 0 is masked: not part of a cluster
      - mod: 20                # ... to match the tab20 color map

For the utopya base plots, see Multiverse Base Configuration.

References#

Kurt Roth: Chaotic, Complex, and Evolving Environmental Systems. Unpublished lecture notes, University of Heidelberg, 2018.