src.canns.analyzer.plotting.energy

Energy landscape visualization utilities.

Functions

energy_landscape_1d_animation(data_sets[, ...])

Create an animation of an evolving 1D energy landscape.

energy_landscape_1d_static(data_sets[, config, title, ...])

Plot a 1D static energy landscape using Matplotlib.

energy_landscape_2d_animation(zs_data[, config, ...])

Create an animation of an evolving 2D landscape.

energy_landscape_2d_static(z_data[, config, title, ...])

Plot a static 2D landscape from a 2D array as a heatmap.

Module Contents

src.canns.analyzer.plotting.energy.energy_landscape_1d_animation(data_sets, time_steps_per_second=None, config=None, *, fps=30, title='Evolving 1D Energy Landscape', xlabel='Collective Variable / State', ylabel='Energy', figsize=(10, 6), grid=False, repeat=True, save_path=None, show=True, show_progress_bar=True, **kwargs)[source]

Create an animation of an evolving 1D energy landscape.

The docstring intentionally preserves the guidance from the previous implementation so existing callers can rely on the same parameter explanations.

Parameters:

  • data_sets (dict[str, tuple[numpy.ndarray, numpy.ndarray]]) – Dictionary whose keys are legend labels and values are (x_data, y_data) tuples where y_data is shaped as (time, state).

  • time_steps_per_second (int | None) – Number of simulation time steps per second of wall-clock time (e.g., 1/dt).

  • config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig with shared styling overrides.

  • fps (int) – Frames per second to render in the resulting animation.

  • title (str) – Title used when config is not provided.

  • xlabel (str) – X-axis label used when config is not provided.

  • ylabel (str) – Y-axis label used when config is not provided.

  • figsize (tuple[int, int]) – Figure size passed to Matplotlib when building the canvas.

  • grid (bool) – Whether to overlay a grid on the animation axes.

  • repeat (bool) – Whether the animation should loop once it finishes.

  • save_path (str | None) – Optional path to persist the animation (.gif / .mp4).

  • show (bool) – Whether to display the animation interactively.

  • show_progress_bar (bool) – Whether to show a tqdm progress bar when saving.

  • **kwargs (Any) – Further keyword arguments passed through to ax.plot.

Returns:

The constructed animation.

Return type:

matplotlib.animation.FuncAnimation

src.canns.analyzer.plotting.energy.energy_landscape_1d_static(data_sets, config=None, *, title='1D Energy Landscape', xlabel='Collective Variable / State', ylabel='Energy', show_legend=True, figsize=(10, 6), grid=False, save_path=None, show=True, **kwargs)[source]

Plot a 1D static energy landscape using Matplotlib.

This mirrors the long-form description from the pre-reorganisation module so existing documentation references stay accurate. The function accepts a dictionary of datasets, plotting each curve on the same set of axes while honouring the PlotConfig defaults callers relied on previously.

Parameters:

  • data_sets (dict[str, tuple[numpy.ndarray, numpy.ndarray]]) – Mapping of series labels to (x, y) tuples representing the energy curve to draw.

  • config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig carrying shared styling.

  • title (str) – Plot title when no config override is supplied.

  • xlabel (str) – X-axis label when no config override is supplied.

  • ylabel (str) – Y-axis label when no config override is supplied.

  • show_legend (bool) – Whether to display the legend for labelled curves.

  • figsize (tuple[int, int]) – Figure size forwarded to Matplotlib when creating the axes.

  • grid (bool) – Whether to enable a grid background.

  • save_path (str | None) – Optional path for persisting the plot to disk.

  • show (bool) – Whether to display the generated figure.

  • **kwargs (Any) – Additional keyword arguments forwarded to ax.plot.

Returns:

The created figure and axes handles.

Return type:

Tuple[plt.Figure, plt.Axes]

src.canns.analyzer.plotting.energy.energy_landscape_2d_animation(zs_data, config=None, *, time_steps_per_second=None, fps=30, title='Evolving 2D Landscape', xlabel='X-Index', ylabel='Y-Index', clabel='Value', figsize=(8, 7), grid=False, repeat=True, save_path=None, show=True, show_progress_bar=True, **kwargs)[source]

Create an animation of an evolving 2D landscape.

The long-form description mirrors the previous implementation to maintain backwards-compatible documentation for downstream users.

Parameters:

  • zs_data (numpy.ndarray) – Array of shape (timesteps, dim_y, dim_x) describing the landscape at each simulation step.

  • config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig carrying display preferences.

  • time_steps_per_second (int | None) – Number of simulation steps per second of simulated time; required unless encoded in config.

  • fps (int) – Frames per second in the generated animation.

  • title (str) – Title used when config is not provided.

  • xlabel (str) – X-axis label used when config is not provided.

  • ylabel (str) – Y-axis label used when config is not provided.

  • clabel (str) – Colorbar label used when config is not provided.

  • figsize (tuple[int, int]) – Figure size passed to Matplotlib.

  • grid (bool) – Whether to overlay a grid on the heatmap.

  • repeat (bool) – Whether the animation should loop.

  • save_path (str | None) – Optional output path (.gif / .mp4).

  • show (bool) – Whether to display the animation interactively.

  • show_progress_bar (bool) – Whether to render a tqdm progress bar during save.

  • **kwargs (Any) – Additional keyword arguments forwarded to ax.imshow.

Returns:

The constructed animation.

Return type:

matplotlib.animation.FuncAnimation

src.canns.analyzer.plotting.energy.energy_landscape_2d_static(z_data, config=None, *, title='2D Static Landscape', xlabel='X-Index', ylabel='Y-Index', clabel='Value', figsize=(8, 7), grid=False, save_path=None, show=True, **kwargs)[source]

Plot a static 2D landscape from a 2D array as a heatmap.

Parameters:

  • z_data (numpy.ndarray) – 2D array (dim_y, dim_x) representing the landscape.

  • config (src.canns.analyzer.plotting.config.PlotConfig | None) – Optional PlotConfig with pre-set styling.

  • title (str) – Plot title when config is not provided.

  • xlabel (str) – X-axis label when config is not provided.

  • ylabel (str) – Y-axis label when config is not provided.

  • clabel (str) – Colorbar label when config is not provided.

  • figsize (tuple[int, int]) – Figure size forwarded to Matplotlib when allocating the canvas.

  • grid (bool) – Whether to draw a grid overlay.

  • save_path (str | None) – Optional path that triggers saving the figure to disk.

  • show (bool) – Whether to display the figure interactively.

  • **kwargs (Any) – Additional keyword arguments passed through to ax.imshow.

Returns:

The Matplotlib figure and axes objects.

Return type:

Tuple[plt.Figure, plt.Axes]