Bifurcation diagrams

Summary

This documents the utopya.eval.plots.attractor plot module.

Hint

This plot is powerful but equally specialised, and was originally designed for a Vegetation model (not included in Utopia). Making this plot more general and integrating it into the wider pool of base plots is WIP.

Bifurcation in one parameter dimension

For a bifurcation diagram in a single parameter dimension, there is the bifurcation_diagram() function. It takes a Sequence of analysis steps of type Tuple(str, str): attractor_key, function name or str: key from default analysis steps. The function performs an analysis of the data returning Tuple(bool, xr.DataArray): conclusive analysis, result. The attractor_key maps this to the plotting of the attractor and resolves how to visualize this dataset.

See utopya.eval.plots.attractor.bifurcation_diagram().

The default analysis steps are listed here:

# A test configuration for the bifurcation diagram
---
# The configuration specific to the SavannaHomogeneous model
bifurcation_diagram: &bifurcation_diagram
  select:
    # the data fields to plot
    fields:
      density_G:
        path: data/SavannaHomogeneous/density_G
      density_T:
        path: data/SavannaHomogeneous/density_T
      density_F:
        path: data/SavannaHomogeneous/density_F

  enabled: false

  # the bifurcation parameter
  dim: alpha

  # recommended to label and colorize the fields
  to_plot:
    density_G:
      label: grass
      plot_kwargs:
        color: green
        s: 10
    density_T:
      label: trees
      plot_kwargs:
        color: chocolate
        s: 6
    density_F:
      label: trees
      plot_kwargs:
        color: Black
        s: 6

# Plot the endpoint for every universe
bifurcation_endpoint:
  based_on: .attractor.bifurcation_diagram_1d
  <<: *bifurcation_diagram

  enabled: true

  # pass a Tuple(str, str): key, function name in utopya.dataprocessing.py
  analysis_steps: [[endpoint, find_endpoint]]

  visualization_kwargs:
    endpoint:
      color: green
      alpha: 0.3

# Plot the fixpoint(s) for every universe if available, else the endpoint.
# This is done for all universes at the bifurcation parameters coordinate
# duplicate fixpoints (e.g. from different initialisations) are removed.
bifurcation_fixpoint:
  based_on: .attractor.bifurcation_diagram_1d
  <<: *bifurcation_diagram

  enabled: true

  # pass a Sequence of str: keys in default_analysis_steps
  # iterate until the first conclusive step
  analysis_steps: [fixpoint, endpoint]
  analysis_kwargs:
    fixpoint:
      spin_up_time: 25000

  visualization_kwargs:
    endpoint:
      color: green
      alpha: 0.3
    fixpoint:
      color: yellow
      alpha: 0.3

# Plot the fixpoint - use the to_plot feature
bifurcation_fixpoint_to_plot:
  based_on: .attractor.bifurcation_diagram_1d
  <<: *bifurcation_diagram

  enabled: true

  # pass a Sequence of str: keys in default_analysis_steps
  # iterate until the first conclusive step
  analysis_steps: [fixpoint, endpoint]
  analysis_kwargs:
    fixpoint:
      spin_up_time: 25000

  visualization_kwargs:
    endpoint:
      color: green
      alpha: 0.3
    fixpoint:
      to_plot:
        density_G:
          label: fixpoint grass
          color: green
          alpha: 0.3
        density_T:
          label: fixpoint savanna
          color: chocolate
          alpha: 0.3
        density_F:
          label: fixpoint forest
          color: black
          alpha: 0.3

# Scatter the datapoints for every universe
bifurcation_scatter:
  based_on: .attractor.bifurcation_diagram_1d
  <<: *bifurcation_diagram

  enabled: true

  analysis_steps: [scatter]
  analysis_kwargs:
    scatter:
      spin_up_time: 25000

  # recommended to label and colorize the fields
  to_plot:
    density_G:
      label: grass
      plot_kwargs:
        # it is possible to chose a colormap to shift color with time
        cmap: Greens
        s: 10
    density_T:
      label: trees
      plot_kwargs:
        color: chocolate
        s: 6
    density_F:
      label: trees
      plot_kwargs:
        color: Black
        s: 6

# Plot oscillation and fixpoint for every universe
bifurcation_oscillation:
  based_on: .attractor.bifurcation_diagram_1d
  <<: *bifurcation_diagram

  enabled: true

  # Check for oscillation, then for fixpoint.
  # If both not conclusive nothing is plotted.
  analysis_steps: [oscillation, fixpoint]
  analysis_kwargs:
    oscillation:
      height: 0.    # this
      prominence: 0.05
    fixpoint:
      spin_up_time: 25000

  visualization_kwargs:
    fixpoint:
      color: yellow
      alpha: 0.3
    oscillation:
      color: red
      alpha: 0.3

Bifurcation in two parameter dimensions

For a bifurcation diagram in two parameter dimensions, there is the utopya.eval.plots.attractor.bifurcation_diagram() method. As the 1d equivalent it takes a Sequence of analysis steps of type Tuple(str, str): attractor_key, function name or str: key from default analysis steps. The function performs an analysis of the data returning Tuple(bool, xr.DataArray): conclusive analysis, result. The attractor_key maps this to the plotting of the attractor and resolves how to visualize this dataset. Other than in 1d the attractor itself cannot be visualized by its state, hence the previously optional visualisation_kwargs become obligatory and are passed to matplotlib.patches.Rectangle with auto detected or passed width and height.

Note

The visualisation_kwarg to fixpoint can have a to_plot entry that defines kwargs proper to every used data field. In that case the field with the heighest fixpoint value defines the coloring.