ccu.fancyplots.plotting

Functions for plotting free energy diagrams.

The main function is ccu.fancyplots.plotting.generate_figure().

Examples

>>> from ccu.fancyplots.data import DEFAULT_PARAMETERS
>>> from ccu.fancyplots.data import FEDData
>>> from ccu.fancyplots import generate_figure
>>> energy_data = [[0.0, 1.5, 0.5]]
>>> data = FEDData(
...     energy_data=energy_data,
...     mechanism=["*", "*H", "H2"],
...     legend_labels=["Cu(111)"],
... )
>>> generate_figure(data, DEFAULT_PARAMETERS, visual=True)
(<Axes: ...>, None, <Figure ...>)
class ccu.fancyplots.plotting.SymHandler(marker_pad=0.3, numpoints=None, **kwargs)[source]

Bases: HandlerLine2D

Parameters:

  • marker_pad (float) – Padding between points in legend entry.

  • numpoints (int) – Number of points to show in legend entry.

  • **kwargs – Keyword arguments forwarded to .HandlerBase.

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)[source]

Return the legend artists generated.

Parameters:

  • legend (~matplotlib.legend.Legend) – The legend for which these legend artists are being created.

  • orig_handle (~matplotlib.artist.Artist or similar) – The object for which these legend artists are being created.

  • xdescent, ydescent, width, height (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.

  • fontsize (int) – The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.

  • trans (~matplotlib.transforms.Transform) – The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.

ccu.fancyplots.plotting.add_annotations(engine: Axes | ModuleType, annotations: list[Annotation], fontsize: float, font: str) → None[source]

Add the annotations to the free energy diagram.

Parameters:

  • engine – The engine with which to create the legend. Can either be an Axes object or matplotlib.pyplot.

  • annotations – The annotations to add.

  • fontsize – The font size to use for the annotations.

  • font – The matplotlib font family to use to write the annotations.

ccu.fancyplots.plotting.bracket_ts_step(ts_step_index: int, energies: list[float | None]) → tuple[int, int][source]

Determine the indices of the nearest mechanism steps to a TS.

Parameters:

  • ts_step_index – The index of the transition state step.

  • energies – A list of free energies. The ith entry in energies corresponds to the ith step in pathway.

Raises:

RuntimeError – Unable to bracket the transition step. Either there is no elementary reaction step defined prior to the reaction step or there is no elementary reaction step defined after the reaction step.

Returns:

A 2-tuple (index_before, index_after) indicating the indices of the nearest, defined reaction steps before and after the transition state, respectively.

ccu.fancyplots.plotting.create_axes(parameters: FormattingParameters, *, visual: bool = True) → tuple[Axes, Figure][source]

Create the primary axes for plotting free energy diagrams.

Parameters:

  • parameters – The formatting parameters to use to plot the diagram

  • visual – Whether or not the image is being displayed. Determines the interface to matplotlib that is used. Defaults to True.

Returns:

A 2-tuple (ax, fig) whose first and second elements are the primary axes and figure used to plot the diagram, respectively.

ccu.fancyplots.plotting.create_legend(engine: Axes | ModuleType, lines: list[Artist | None], legend_entries: list[str | None], fontsize: float, loc: str) → None[source]

Create the legend for the free energy diagram.

Parameters:

  • engine – The engine with which to create the legend. Can either be an Axes object or matplotlib.pyplot.

  • lines – The Artist objects for which legend entries will be made.

  • legend_entries – A list of legend entries.

  • fontsize – The fontsize for the legend.

  • loc – The legend location. See the documentation for Legend for valid values.

ccu.fancyplots.plotting.create_ts_curve(ts_step_index: int, energies: list[float | None], step_count: int) → tuple[list[float], list[float]][source]

Create the plotting data for a transition state curve.

Parameters:

  • ts_step_index – The index of the transition state step.

  • energies – A list of free energies. The ith entry in energies corresponds to the ith step in pathway.

  • step_count – A weighted index for mechanism steps. Elementary steps increment the index by 2 while steps corresponding to transition states increment the index by 1.

Returns:

A 2-tuple (xx, yy) whose first and second elements are the x and y values to be plotted on the free energy diagram.

ccu.fancyplots.plotting.format_primary_axes(ax: Axes, parameters: FormattingParameters, count: int, *, visual: bool = True) → None[source]

Format the primary axis.

Parameters:

  • ax – The primary matplotlib.axes.Axes.

  • parameters – The ccu.fancyplots.data.FormattingParameters to use for the axes.

  • count – A weighted index for mechanism steps. Elementary steps increment the index by 2 while steps corresponding to transition states increment the index by 1.

  • visual – Whether or not the image is being displayed. Determines the interface to matplotlib used. Defaults to True.

ccu.fancyplots.plotting.format_secondary_axes(ax: Axes, parameters: FormattingParameters) → None[source]

Format the secondary axis.

Parameters:
ccu.fancyplots.plotting.generate_figure(diagram_data: FEDData, parameters: FormattingParameters | None = None, annotations: list[Annotation] | list[tuple[str, float, str, float, float]] | None = None, *, visual: bool = True) → tuple[Axes, Axes | None, Figure][source]

Generate the free energy diagram figure.

Parameters:

  • diagram_data – The data for the free energy diagram.

  • parameters – The formatting parameters to use to create the free energy diagram. Defaults to :data:`ccu.fancyplots.data.DEFAULT_PARAMETERS.

  • annotations – Annotations for the free energy data. Defaults to an empty list.

  • visual – Whether or not to display the image. If False, the figure will be saved to file instead of displayed. Defaults to True.

Returns:

A 3-tuple (ax1,``ax2``, figure). ax1 is the primary axes containing the free energy diagram. ax2 is the secondary axes; it is None unless the “tick_double” parameter is True in parameters. figure is the matplotlib.figure.Figure containing all plot elements.

ccu.fancyplots.plotting.interpolate(x0: tuple[float, float, float], y0: tuple[float, float, float]) → tuple[list[float], list[float]][source]

Interpolate between three points with a sinusoidal function.

Parameters:

  • x0 – The x-coordinates of the start, mid-, and end points.

  • y0 – The y-coordinates of the start, mid-, and end points.

Returns:

The x- and y-coordinates of the interpolation.

ccu.fancyplots.plotting.plot_energy_data(ax: Axes, data: FEDData, parameters: FormattingParameters) → tuple[int, list[Artist | None]][source]

Plot the free energy diagrams of all pathways.

Parameters:

  • ax – The matplotlib.axes.Axes on which to plot the Gibbs plot.

  • data – The free energy data to plot.

  • parameters – The formatting parameters to use to plot the free energy diagram.

Returns:

A 2-tuple (step_count, lines) where step_count is a weighted index for mechanism steps. Elementary steps increment the index by 2 while steps corresponding to transition states increment the index by 1. lines is a list of matplotlib.artist.Artist objects, each corresponding to a data point in the data series.

ccu.fancyplots.plotting.plot_fed(ax: Axes, energies: list[float | None], mechanism: list[str], color: str, zorder: int, linewidth: float) → tuple[int, Artist | None][source]

Plot the free energy diagram of a pathway.

Parameters:

  • ax – The matplotlib.axes.Axes on which to plot the free energy diagram.

  • energies – A list of free energies. The ith entry in energies corresponds to the ith step in pathway.

  • mechanism – A list of strings corresponding to the steps of a reaction mechanism.

  • color – A string corresponding to a matplotlib colour.

  • zorder – The zorder for the lines for the pathway. A lower zorder indicates that the line will be drawn first.

  • linewidth – The width of the line to use to plot the free energy diagram.

Returns:

A 2-tuple (step_count, line) where step_count is a weighted index for mechanism steps. Elementary steps increment the index by 2 while steps corresponding to transition states increment the index by 1. line is a representative matplotlib.artist.Artist object for the data series.

ccu.fancyplots.plotting.save_fed_plot(savename: str, dpi: int) → None[source]

Save the free energy diagram.

Parameters:

  • savename – The filename to use when saving the file

  • dpi – The resolution in dots-per-inch.