tools_plotting — figures¶

Ready-made figures for the reaction and metadynamics workflows.

One call per thing worth looking at, each returning (fig, ax) so it can be dropped into a larger figure: plot_images() and show_atoms() draw structures, plot_neb() and plot_irc() draw an energy profile against path distance, plot_temperature() and plot_total_energy() follow an MD run frame by frame, and plot_plumed() and plot_plumed_multi() draw one-dimensional free-energy surfaces.

Saving here is save=True plus a filename stem, and always writes both PNG and PDF; reactiontools.tools_fes keys off filename alone instead.

The PLUMED wrappers are deliberately thin: they hand the work to reactiontools.tools_fes with the units fixed to the eV an ASE-driven run writes, plotted in meV. Go to that module directly for two-dimensional surfaces, other units, or anything else it does that is not wrapped here.

Styling comes from reactiontools.tools_style, so these figures and the free-energy ones come out looking alike.

plot_images(images: Atoms | Sequence[Atoms], view: str = 'tilted', rotation: str | None = None, n_cols: int = 4, titles: Sequence[str] | None = None, radii: float = 0.8, show_unit_cell: int = 2, fig_size: tuple[float, float] | None = None, save: bool = False, show: bool = True, filename: str = 'images') → tuple[Figure, ndarray][source]¶

Plot a series of structures as a grid of panels, one per image.

Each panel is titled with the index of the image, which makes it easy to pick frames out of a trajectory, a NEB band or a set of local minima.

Parameters:

images (ase.Atoms or sequence of ase.Atoms) – Structures to draw. A single Atoms object is accepted and drawn as a one-panel figure.
view (str, optional) – Camera angle: one of "top", "side", "front" or "tilted", or any ASE rotation string (e.g. "300x,0y,0z").
rotation (str, optional) – Explicit ASE rotation string. Overrides view when given.
n_cols (int, optional) – Number of panels per row. Clamped to the number of images.
titles (sequence of str, optional) – Per-panel titles. Defaults to the index of each image.
radii (float, optional) – Atomic radius scale passed to plot_atoms().
show_unit_cell (int, optional) – Unit-cell drawing mode passed to plot_atoms() (0 none, 1 behind, 2 in front).
fig_size (tuple, optional) – Size of the created figure. Defaults to 3 inches per panel.
save (bool, optional) – Save .png and .pdf outputs when True.
show (bool, optional) – Display the plot with plt.show() when True.
filename (str, optional) – Output filename stem for saved figures.

Returns:

tuple – (fig, axes) with axes as a flat array, one entry per panel.

Raises:

ValueError – If there are no images, or if titles has the wrong length.

show_atoms(atoms: Atoms | Sequence[Atoms], view: str = 'tilted', rotation: str | None = None, ax: Axes | None = None, save: bool = True, show: bool = True, filename: str = 'atoms') → tuple[Figure, Axes][source]¶

Draw one or more structures superimposed on a single axes.

Unlike plot_images(), which gives every structure its own panel, this overlays them all in one frame. That is the view for seeing how far a band has moved: pass the images of a NEB and the drawings stack up, so the atoms that shift stand out against the ones that do not.

Parameters:

atoms (ase.Atoms or sequence of ase.Atoms) – Structure, or structures, to draw.
view (str, optional) – Camera angle: one of "top", "side", "front" or "tilted", or any ASE rotation string (e.g. "300x,0y,0z").
rotation (str, optional) – Explicit ASE rotation string. Overrides view when given.
ax (matplotlib.axes.Axes, optional) – Axes to draw on. A new figure and axes are created if None.
save (bool, optional) – Save .png and .pdf outputs when True.
show (bool, optional) – Display the plot with plt.show() when True.
filename (str, optional) – Output filename stem for saved figures.

Returns:

tuple – (fig, ax) containing the matplotlib figure and axes.

plot_neb(images: Sequence[Atoms], calc: Any = None, fig: Figure | None = None, ax: Axes | None = None, save: bool = True, show: bool = True, smooth: bool = True, k: int = 2, fig_size: tuple[float, float] = (8, 3), filename: str = 'neb', label: str | None = None, annotate: bool = False) → tuple[Figure, Axes][source]¶

Plot a nudged elastic band energy profile.

Parameters:

images (sequence of ase.Atoms) – NEB images along the reaction path.
calc (ase.calculators.Calculator or None, optional) – Calculator used to evaluate any missing energies. Not needed for a band read back by optimise_neb, whose images already carry theirs.
fig (matplotlib.figure.Figure, optional) – Figure to draw on. A new figure is created if None.
ax (matplotlib.axes.Axes, optional) – Axes to draw on. A new axes is created if None.
save (bool, optional) – Save .png and .pdf outputs when True.
show (bool, optional) – Display the plot with plt.show() when True.
smooth (bool, optional) – Use spline interpolation for the path when True.
k (int, optional) – Spline order used when smooth is True.
fig_size (tuple, optional) – Size of the created figure.
filename (str, optional) – Output filename stem for saved figures.
label (str, optional) – Line label for the path curve.
annotate (bool, optional) – Write the forward barrier in the top-left corner of the axes, in the meV the y-axis is drawn in. Off by default so that existing figures do not change. The value matches barrier from summarise_neb(), converted to meV.

Returns:

tuple – (fig, ax) containing the matplotlib figure and axes.

plot_irc(images: Sequence[Atoms], calc: Any = None, fig: Figure | None = None, ax: Axes | None = None, save: bool = True, show: bool = True, smooth: bool = True, k: int = 2, fig_size: tuple[float, float] = (8, 3), filename: str = 'irc', color: str = 'black', label: str | None = None) → tuple[Figure, Axes][source]¶

Plot an intrinsic reaction coordinate energy profile.

The same profile as plot_neb(), with defaults suited to an IRC: a single black curve rather than one of a labelled set, since an IRC is normally shown on its own. Feed it the two halves from optimise_irc() joined by stitch_path().

Parameters:

images (sequence of ase.Atoms) – Images along the reaction path, ordered reactant to product.
calc (ase.calculators.Calculator or None, optional) – Calculator used to evaluate any missing energies. Not needed for images read back from a trajectory, which already carry theirs.
fig (matplotlib.figure.Figure, optional) – Figure to draw on. A new figure is created if None.
ax (matplotlib.axes.Axes, optional) – Axes to draw on. A new axes is created if None.
save (bool, optional) – Save .png and .pdf outputs when True.
show (bool, optional) – Display the plot with plt.show() when True.
smooth (bool, optional) – Use spline interpolation for the path when True.
k (int, optional) – Spline order used when smooth is True.
fig_size (tuple, optional) – Size of the created figure.
filename (str, optional) – Output filename stem for saved figures.
color (str, optional) – Colour of the curve and its markers.
label (str, optional) – Line label for the path curve.

Returns:

tuple – (fig, ax) containing the matplotlib figure and axes.

Plot temperature against frame number or time for one or more runs.

Parameters:

trajectories (str or path-like or sequence) – Trajectory file paths readable by ASE.
labels (sequence of str, optional) – Legend labels. Defaults to the filename for each trajectory.
timestep (float, optional) – Time spacing between frames. When given, the x-axis is in fs.
ax (matplotlib.axes.Axes, optional) – Axes to draw on. A new figure and axes are created if None.

Returns:

tuple – (fig, ax) containing the matplotlib figure and axes.

Plot total energy against frame number or time for one or more runs.

Parameters:

trajectories (str or path-like or sequence) – Trajectory file paths readable by ASE.
labels (sequence of str, optional) – Legend labels. Defaults to the filename for each trajectory.
timestep (float, optional) – Time spacing between frames. When given, the x-axis is in fs.
ax (matplotlib.axes.Axes, optional) – Axes to draw on. A new figure and axes are created if None.

Returns:

tuple – (fig, ax) containing the matplotlib figure and axes.

plot_plumed(file: str | Path = 'fes.dat', fig: Figure | None = None, ax: Axes | None = None, save: bool = True, show: bool = True, fig_size: tuple[float, float] = (8, 3), filename: str = 'fes', x_range: tuple[float, float] | None = None, x_label: str = 'CV') → tuple[Figure, Axes][source]¶

Plot a one-dimensional PLUMED free-energy surface.

Parameters:

file (str, optional) – Path to a PLUMED fes.dat-style file.
fig (matplotlib.figure.Figure, optional) – Figure to draw on. A new figure is created if None.
ax (matplotlib.axes.Axes, optional) – Axes to draw on. A new axes is created if None.
save (bool, optional) – Save .png and .pdf outputs when True.
show (bool, optional) – Display the plot with plt.show() when True.
fig_size (tuple, optional) – Size of the created figure.
filename (str, optional) – Output filename stem for saved figures.
x_range (tuple, optional) – Optional x-axis limits passed to Axes.set_xlim.
x_label (str, optional) – Optional x-axis label.

Returns:

tuple – (fig, ax) containing the matplotlib figure and axes.

plot_plumed_multi(files: str | Path | Sequence[str | Path], labels: Sequence[str] | None = None, fig: Figure | None = None, ax: Axes | None = None, save: bool = True, show: bool = True, fig_size: tuple[float, float] = (8, 3), filename: str = 'fes_multi', x_range: tuple[float, float] | None = None, x_label: str = 'CV', mintozero: bool = False, colors: Sequence[str] = ('#D4447E', '#2F3E56', '#5FABA2', '#E9A66C', '#7B6CA8', '#9AA5B1')) → tuple[Figure, Axes][source]¶

Plot the free-energy surfaces of several PLUMED runs on one axes.

Parameters:

files (str or path-like or sequence) – Paths to PLUMED fes.dat-style files, as written by plumed sum_hills. A directory is expanded to every fes.dat beneath it, matching the <run>/fes.dat layout of the metadynamics runs.
labels (sequence of str, optional) – Legend labels. Defaults to the file stems, or to the parent directory names when the runs share a filename.
fig (matplotlib.figure.Figure, optional) – Figure to draw on. A new figure is created if None.
ax (matplotlib.axes.Axes, optional) – Axes to draw on. A new axes is created if None.
save (bool, optional) – Save .png and .pdf outputs when True.
show (bool, optional) – Display the plot with plt.show() when True.
fig_size (tuple, optional) – Size of the created figure.
filename (str, optional) – Output filename stem for saved figures.
x_range (tuple, optional) – Optional x-axis limits passed to Axes.set_xlim.
x_label (str, optional) – Optional x-axis label.
mintozero (bool, optional) – Shift each curve so its minimum sits at zero. Use when the runs were summed without --mintozero, or to compare barrier heights directly.
colors (sequence, optional) – Colours cycled over the runs.

Returns:

tuple – (fig, ax) containing the matplotlib figure and axes.