Analysis of the attractor#

This module provides plotting functions to visualize the attractive set of a dynamical system.

utopya.plot_funcs.attractor.bifurcation_diagram(dm: utopya.datamanager.DataManager, *, hlpr: utopya.plotting.PlotHelper, mv_data: xarray.core.dataset.Dataset, dim: Optional[str] = None, dims: Optional[Tuple[str, str]] = None, analysis_steps: Sequence[Union[str, Tuple[str, str]]], custom_analysis_funcs: Optional[Dict[str, Callable]] = None, analysis_kwargs: Optional[dict] = None, visualization_kwargs: Optional[dict] = None, to_plot: Optional[dict] = None, **kwargs) None[source]
Plots a bifurcation diagram for one or two parameter dimensions

(arguments dim or dims).

Parameters
  • dm (DataManager) – The data manager from which to retrieve the data

  • hlpr (PlotHelper) – The PlotHelper that instantiates the figure and takes care of plot aesthetics (labels, title, …) and saving

  • mv_data (xr.Dataset) – The extracted multidimensional dataset

  • dim (str, optional) – The required parameter dimension of the 1d bifurcation diagram.

  • dims (str, optional) – The required parameter dimensions (x, y) of the 2d-bifurcation diagram.

  • analysis_steps (Sequence) –

    The analysis steps that are to be made until one is conclusive. Applied per universe.

    • If seq of str: The str will also be used as attractor key for

      plotting if the test is conclusive.

    • If seq of Tuple(str, str): The first str defines the attractor

      key for plotting, the second str is a key within custom_analysis_funcs.

    Default analysis_funcs are:

    • endpoint: utopya.dataprocessing.find_endpoint

    • fixpoint: utopya.dataprocessing.find_fixpoint

    • multistability: utdp.find_multistability

    • oscillation: utdp.find_oscillation

    • scatter: resolve_scatter

  • custom_analysis_funcs (dict) – A collection of custom analysis functions that will overwrite the default analysis funcs (recursive update).

  • analysis_kwargs (dict, optional) – The entries need to match the analysis_steps. The subentry (dict) is passed on to the analysis function.

  • visualization_kwargs (dict, optional) – The entries need to match the analysis_steps. The subentry (dict) is used to configure a rectangle to visualize the conclusive analysis step. Is passed to matplotlib.patches.rectangle. xy, width, height, and angle are ignored and set automatically. Required in 2d bifurcation diagram.

  • to_plot (dict, optional) –

    The configuration for the data to plot. The entries of this key need to match the data_vars selected in mv_data. It is used to visualize the state of the attractor additionally to the visualization kwargs. Only for 1d-bifurcation diagram. sub_keys:

    • label (str, optional): label in plot

    • plot_kwargs (dict, optional): passed to scatter for every

      universe

      • color (str, recommended): unique color for every

        data_variable accross universes

  • **kwargs

    Collection of optional dicts passed to different functions

    • plot_coords_kwargs (dict): Passed to ax.scatter to mark the

      universe’s center in the bifurcation diagram

    • rectangle_map_kwargs (dict): Passed to

      utopya.plot_funcs._utils.calc_pxmap_rectangles

    • legend_kwargs (dict): Passed to ax.legend


Bifurcation in one parameter dimension#

For a bifurcation diagram in a single parameter dimension, there is the attractor.bifurcation_diagram method. 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.

utopya.plot_funcs.attractor.bifurcation_diagram(dm: utopya.datamanager.DataManager, *, hlpr: utopya.plotting.PlotHelper, mv_data: xarray.core.dataset.Dataset, dim: Optional[str] = None, dims: Optional[Tuple[str, str]] = None, analysis_steps: Sequence[Union[str, Tuple[str, str]]], custom_analysis_funcs: Optional[Dict[str, Callable]] = None, analysis_kwargs: Optional[dict] = None, visualization_kwargs: Optional[dict] = None, to_plot: Optional[dict] = None, **kwargs) None[source]
Plots a bifurcation diagram for one or two parameter dimensions

(arguments dim or dims).

Parameters
  • dm (DataManager) – The data manager from which to retrieve the data

  • hlpr (PlotHelper) – The PlotHelper that instantiates the figure and takes care of plot aesthetics (labels, title, …) and saving

  • mv_data (xr.Dataset) – The extracted multidimensional dataset

  • dim (str, optional) – The required parameter dimension of the 1d bifurcation diagram.

  • dims (str, optional) – The required parameter dimensions (x, y) of the 2d-bifurcation diagram.

  • analysis_steps (Sequence) –

    The analysis steps that are to be made until one is conclusive. Applied per universe.

    • If seq of str: The str will also be used as attractor key for

      plotting if the test is conclusive.

    • If seq of Tuple(str, str): The first str defines the attractor

      key for plotting, the second str is a key within custom_analysis_funcs.

    Default analysis_funcs are:

    • endpoint: utopya.dataprocessing.find_endpoint

    • fixpoint: utopya.dataprocessing.find_fixpoint

    • multistability: utdp.find_multistability

    • oscillation: utdp.find_oscillation

    • scatter: resolve_scatter

  • custom_analysis_funcs (dict) – A collection of custom analysis functions that will overwrite the default analysis funcs (recursive update).

  • analysis_kwargs (dict, optional) – The entries need to match the analysis_steps. The subentry (dict) is passed on to the analysis function.

  • visualization_kwargs (dict, optional) – The entries need to match the analysis_steps. The subentry (dict) is used to configure a rectangle to visualize the conclusive analysis step. Is passed to matplotlib.patches.rectangle. xy, width, height, and angle are ignored and set automatically. Required in 2d bifurcation diagram.

  • to_plot (dict, optional) –

    The configuration for the data to plot. The entries of this key need to match the data_vars selected in mv_data. It is used to visualize the state of the attractor additionally to the visualization kwargs. Only for 1d-bifurcation diagram. sub_keys:

    • label (str, optional): label in plot

    • plot_kwargs (dict, optional): passed to scatter for every

      universe

      • color (str, recommended): unique color for every

        data_variable accross universes

  • **kwargs

    Collection of optional dicts passed to different functions

    • plot_coords_kwargs (dict): Passed to ax.scatter to mark the

      universe’s center in the bifurcation diagram

    • rectangle_map_kwargs (dict): Passed to

      utopya.plot_funcs._utils.calc_pxmap_rectangles

    • legend_kwargs (dict): Passed to ax.legend

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 attractor.bifurcation_diagram_2d 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.

utopya.plot_funcs.attractor.bifurcation_diagram(dm: utopya.datamanager.DataManager, *, hlpr: utopya.plotting.PlotHelper, mv_data: xarray.core.dataset.Dataset, dim: Optional[str] = None, dims: Optional[Tuple[str, str]] = None, analysis_steps: Sequence[Union[str, Tuple[str, str]]], custom_analysis_funcs: Optional[Dict[str, Callable]] = None, analysis_kwargs: Optional[dict] = None, visualization_kwargs: Optional[dict] = None, to_plot: Optional[dict] = None, **kwargs) None[source]
Plots a bifurcation diagram for one or two parameter dimensions

(arguments dim or dims).

Parameters
  • dm (DataManager) – The data manager from which to retrieve the data

  • hlpr (PlotHelper) – The PlotHelper that instantiates the figure and takes care of plot aesthetics (labels, title, …) and saving

  • mv_data (xr.Dataset) – The extracted multidimensional dataset

  • dim (str, optional) – The required parameter dimension of the 1d bifurcation diagram.

  • dims (str, optional) – The required parameter dimensions (x, y) of the 2d-bifurcation diagram.

  • analysis_steps (Sequence) –

    The analysis steps that are to be made until one is conclusive. Applied per universe.

    • If seq of str: The str will also be used as attractor key for

      plotting if the test is conclusive.

    • If seq of Tuple(str, str): The first str defines the attractor

      key for plotting, the second str is a key within custom_analysis_funcs.

    Default analysis_funcs are:

    • endpoint: utopya.dataprocessing.find_endpoint

    • fixpoint: utopya.dataprocessing.find_fixpoint

    • multistability: utdp.find_multistability

    • oscillation: utdp.find_oscillation

    • scatter: resolve_scatter

  • custom_analysis_funcs (dict) – A collection of custom analysis functions that will overwrite the default analysis funcs (recursive update).

  • analysis_kwargs (dict, optional) – The entries need to match the analysis_steps. The subentry (dict) is passed on to the analysis function.

  • visualization_kwargs (dict, optional) – The entries need to match the analysis_steps. The subentry (dict) is used to configure a rectangle to visualize the conclusive analysis step. Is passed to matplotlib.patches.rectangle. xy, width, height, and angle are ignored and set automatically. Required in 2d bifurcation diagram.

  • to_plot (dict, optional) –

    The configuration for the data to plot. The entries of this key need to match the data_vars selected in mv_data. It is used to visualize the state of the attractor additionally to the visualization kwargs. Only for 1d-bifurcation diagram. sub_keys:

    • label (str, optional): label in plot

    • plot_kwargs (dict, optional): passed to scatter for every

      universe

      • color (str, recommended): unique color for every

        data_variable accross universes

  • **kwargs

    Collection of optional dicts passed to different functions

    • plot_coords_kwargs (dict): Passed to ax.scatter to mark the

      universe’s center in the bifurcation diagram

    • rectangle_map_kwargs (dict): Passed to

      utopya.plot_funcs._utils.calc_pxmap_rectangles

    • legend_kwargs (dict): Passed to ax.legend