Plotting API Reference #

Module: `chemparseplot.plot.neb`#

Data Structures #

`InsetImagePos`#

Frozen dataclass for inset structure image placement with fields x, y, and rad.

Field	Type	Description
`x`	`float`	Data x coordinate
`y`	`float`	Data y coordinate
`rad`	`float`	Arrow curvature radius

`SmoothingParams`#

Dataclass for Savitzky-Golay smoothing of NEB force profiles.

Field	Type	Default	Description
`window_length`	`int`	`5`	Savitzky-Golay window length
`polyorder`	`int`	`2`	Polynomial order

1D Profile Functions #

`plot_energy_path(ax, rc, energy, f_para, color, alpha, zorder, method`”hermite”, smoothing=None)=#

Plots a 1D energy profile with optional Hermite spline interpolation.

Parameters #

Parameter	Type	Default	Description
`ax`	`matplotlib.axes.Axes`		Target axes
`rc`	`np.ndarray`		Reaction coordinate (RMSD or image index)
`energy`	`np.ndarray`		Energy values
`f_para`	`np.ndarray`		Parallel force component
`color`	`str`		Line and marker color
`alpha`	`float`		Opacity
`zorder`	`int`		Drawing order
`method`	`str`	`"hermite"`	Interpolation method: `"hermite"` or `"spline"`
`smoothing`	`SmoothingParams` or `None`	`None`	Savitzky-Golay parameters (defaults to `SmoothingParams()`)

Notes #

hermite: CubicHermiteSpline using Savitzky-Golay smoothed force derivatives. Produces physically meaningful interpolation when forces are available.
spline: Standard B-spline via splrep/splev (cubic, k=3). Does not use force information.
Normalizes reaction coordinate to [0, 1] before fitting, then maps back.
Falls back to raw line plot if spline fitting raises an exception.

`plot_eigenvalue_path(ax, rc, eigenvalue, color, alpha, zorder, grid_color`”white”)=#

Plots a 1D eigenvalue profile with cubic spline interpolation.

Parameters #

Parameter	Type	Default	Description
`ax`	`matplotlib.axes.Axes`		Target axes
`rc`	`np.ndarray`		Reaction coordinate
`eigenvalue`	`np.ndarray`		Eigenvalue array
`color`	`str`		Line and marker color
`alpha`	`float`		Opacity
`zorder`	`int`		Drawing order
`grid_color`	`str`	`"white"`	Color of the horizontal zero-line

Notes #

Adds a horizontal dashed line at eigenvalue = 0
Uses square markers ("s")

2D Landscape Functions #

`plot_landscape_surface(...)`#

Plots a 2D landscape surface using gradient-enhanced GP/RBF interpolation.

Signature (core args abbreviated)::

plot_landscape_surface(: ax, rmsd_r, rmsd_p, grad_r, grad_p, z_data, step_data=None, method=”grad_matern", rbf_smooth=None, cmap=”viridis”, show_pts=True, variance_threshold=0.05, project_path=True, extra_points=None, n_inducing=None, xlim=None, ylim=None, basis=None, auto_thin=False, max_surface_points=64, surface_fit=None,

)

Parameters #

Parameter	Type	Default	Description
`ax`	`matplotlib.axes.Axes`		Target axes
`rmsd_r`	`np.ndarray`		RMSD from reactant
`rmsd_p`	`np.ndarray`		RMSD from product
`grad_r`	`np.ndarray`		Synthetic gradient (R direction)
`grad_p`	`np.ndarray`		Synthetic gradient (P direction)
`z_data`	`np.ndarray`		Energy or eigenvalue
`step_data`	`np.ndarray` or `None`	`None`	Step indices per point
`method`	`str`	`"grad_matern"`	Surface model (see table below)
`rbf_smooth`	`float` or `None`	`None`	Length scale hint (auto-optimized)
`cmap`	`str`	`"viridis"`	Matplotlib colormap name
`show_pts`	`bool`	`True`	Scatter data points on surface
`variance_threshold`	`float`	`0.05`	Variance contour threshold (fraction of range)
`project_path`	`bool`	`True`	Project to reaction valley coordinates
`extra_points`	`np.ndarray` or `None`	`None`	Shape `(N, 2)` array of extra points for grid extent
`n_inducing`	`int` or `None`	`None`	Inducing points for Nystrom approximation
`auto_thin`	`bool`	`False`	Opt-in: subsample dense clouds for the fit only
`max_surface_points`	`int`	`64`	Cap when `auto_thin` is true
`surface_fit`	`SurfaceFitConfig` / mapping / `None`	`None`	TOML-friendly config; overrides the two keys above when set

`SurfaceFitConfig` (v1.9.10+)#

Prefer a small config object over growing kwargs. Key names match rgpycrumbs eOn plot TOML (auto_thin, max_surface_points):

from chemparseplot.plot.neb import SurfaceFitConfig, plot_landscape_surface

cfg = SurfaceFitConfig.from_mapping({"auto_thin": True, "max_surface_points": 64})
# or: SurfaceFitConfig(auto_thin=True, max_surface_points=64)

plot_landscape_surface(
    ax, rmsd_r, rmsd_p, grad_r, grad_p, z_data,
    method="grad_imq",
    surface_fit=cfg,
)

Defaults keep historical behaviour (~auto_thin=False=).

Interpolation Methods #

Method	Description
`"grad_matern"`	Gradient-enhanced Matern kernel (default)
`"grad_imq"`	Gradient-enhanced Inverse MultiQuadric
`"grad_imq_ny"`	Nystrom-approximated `grad_imq` (auto for large N)
`"rbf"`	Value-only RBF (no gradients)

Notes #

Hyperparameters (length scale, noise) optimized on the latest step’s data only
Variance contours drawn at 5%, variance_threshold, and 95% of the range
When Nystrom is active, non-inducing points are drawn with reduced opacity (alpha=0.15)
Reaction valley projection rotates (RMSD-R, RMSD-P) into (progress s, deviation d) along the R-to-P line
Surface models come from rgpycrumbs.surfaces
With auto_thin, the GP trains on a thinned set; scatter and viewport still use the full cloud
Dense force-eval movies can yield non-finite grad_imq grids without thinning; opt in explicitly

`plot_landscape_path_overlay(ax, r, p, z, cmap, z_label, project_path=True)`#

Overlays a colored NEB path line on the landscape surface.

Parameters #

Parameter	Type	Default	Description
`ax`	`matplotlib.axes.Axes`		Target axes
`r`	`np.ndarray`		RMSD from reactant (path images)
`p`	`np.ndarray`		RMSD from product (path images)
`z`	`np.ndarray`		Energy coloring values
`cmap`	`str`		Colormap name
`z_label`	`str`		Colorbar label
`project_path`	`bool`	`True`	Apply reaction valley projection

Returns #

matplotlib.colorbar.Colorbar – The created colorbar instance.

Notes #

Draws a LineCollection colored by the average energy of adjacent images
Scatter points with black edge at each image position
Creates and returns a colorbar

Structure Rendering Functions #

`render_structure_to_image(atoms, zoom, rotation)`#

Renders an ASE Atoms object to a numpy RGBA image array using ASE’s built-in PNG writer.

Parameters #

Parameter	Type	Description
`atoms`	`ase.Atoms`	Structure to render
`zoom`	`float`	Zoom level (used by callers for OffsetImage scaling)
`rotation`	`str`	ASE rotation string, e.g. `"0x,90y,0z"`

Returns #

np.ndarray – RGBA image array with shape (H, W, 4) and float dtype.

`plot_structure_strip(ax, atoms_list, labels=None, zoom=0.3, rotation`”0x,90y,0z”, theme_color=”black”, max_cols=6, renderer=”xyzrender”, label_ax=None)=#

Renders a horizontal gallery of atomic structures.

Parameters #

Parameter	Type	Default	Description
`ax`	`matplotlib.axes.Axes`		Target axes (turned off)
`atoms_list`	`list[Atoms]` or `list[StructurePlacement]`		Structures to render, or typed strip entries
`labels`	`list[str]` or `None`	`None`	Labels below each image; inferred from `StructurePlacement` entries when omitted
`zoom`	`float`	`0.3`	Image zoom level
`rotation`	`str`	`"0x,90y,0z"`	ASE rotation string
`theme_color`	`str`	`"black"`	Label text color
`max_cols`	`int`	`6`	Maximum columns before wrapping
`renderer`	`str`	`"xyzrender"`	Structure rendering backend
`label_ax`	`matplotlib.axes.Axes` or `None`	`None`	Optional caption-only axis aligned with the structure gallery

Notes #

Adaptive font size: shrinks for more than 4 items
Multi-row layout with max_cols wrapping
xyzrender renderer requires pip install 'xyzrender>=0.1.3'
StructurePlacement lets callers pass a typed strip payload instead of parallel atoms_list / labels lists
Supplying label_ax keeps captions out of the structure-image axis and uses matching normalized row and column positions

`plot_structure_inset(ax, atoms, x, y, xybox, rad, zoom=0.4, rotation`”0x,90y,0z”, arrow_props=None, renderer=”ase”)=#

Plots a single structure as an annotation inset with an arrow.

Parameters #

Parameter	Type	Default	Description
`ax`	`matplotlib.axes.Axes`		Target axes
`atoms`	`ase.Atoms`		Structure to render
`x`	`float`		Data x coordinate for arrow target
`y`	`float`		Data y coordinate for arrow target
`xybox`	`tuple`		Offset in points for image placement
`rad`	`float`		Arrow curvature (`arc3,rad`…=)
`zoom`	`float`	`0.4`	Image zoom level
`rotation`	`str`	`"0x,90y,0z"`	ASE rotation string
`arrow_props`	`dict` or `None`	`None`	Override default arrow properties
`renderer`	`str`	`"ase"`	`"ase"` or `"xyzrender"`

Notes #

Default arrow style: Fancy with head_length=0.4, head_width=0.4, tail_width=0.1
Image zorder set to 80 (above most plot elements)

OCI-NEB/RONEB Functions #

`plot_mmf_peaks_overlay(ax, peak_rmsd_r, peak_rmsd_p, peak_energies, project_path=True)`#

Overlays MMF (mode-following) refinement peak positions on the landscape. Used for OCI-NEB/RONEB to show where dimer refinement was applied.

Parameters #

Parameter	Type	Default	Description
`ax`	`matplotlib.axes.Axes`		Target axes (same as landscape)
`peak_rmsd_r`	`np.ndarray`		RMSD-R coordinates of peak structures
`peak_rmsd_p`	`np.ndarray`		RMSD-P coordinates of peak structures
`peak_energies`	`np.ndarray`		Energy at each peak
`project_path`	`bool`	`True`	Apply reaction valley projection

Notes #

Draws a dark outer halo marker below each peak and an energy-colored core on top
Colors peak cores by energy using coolwarm colormap

`plot_neb_evolution(ax, step_rmsd_r_list, step_rmsd_p_list, project_path=True, cmap`”Blues”)=#

Shows NEB band evolution across optimization iterations with fading older bands.

Parameters #

Parameter	Type	Default	Description
`ax`	`matplotlib.axes.Axes`		Target axes
`step_rmsd_r_list`	`list[np.ndarray]`		RMSD-R arrays per NEB iteration
`step_rmsd_p_list`	`list[np.ndarray]`		RMSD-P arrays per NEB iteration
`project_path`	`bool`	`True`	Apply reaction valley projection
`cmap`	`str`	`"Blues"`	Colormap for band fading

High-Level ORCA Functions #

`plot_orca_neb_profile(neb_data, output, *, width=7.0, height=5.0, dpi=200)`#

Simple ORCA NEB energy profile. Plots image index vs energy with labeled reactant, product, and saddle.

Parameters #

Parameter	Type	Default	Description
`neb_data`	`OrcaNebResult` / `Mapping`		Typed result from `parse_orca_neb()`
`output`	`Path`		Output file path
`width`	`float`	`7.0`	Figure width (inches)
`height`	`float`	`5.0`	Figure height (inches)
`dpi`	`int`	`200`	Output resolution

`plot_orca_neb_energy_profile(neb_data, output, *, width=5.37, height=5.37, dpi=200, method`”hermite”, smoothing=None)=#

Publication ORCA NEB energy profile using the eOn-style plot_energy_path() function.

Parameters #

Parameter	Type	Default	Description
`neb_data`	`OrcaNebResult` / `Mapping`		Typed result from `parse_orca_neb()`
`output`	`Path`		Output file path
`width`	`float`	`5.37`	Figure width (inches)
`height`	`float`	`5.37`	Figure height (inches)
`dpi`	`int`	`200`	Output resolution
`method`	`str`	`"hermite"`	Interpolation method
`smoothing`	`Any`	`None`	Smoothing parameters

Notes #

Uses RMSD as reaction coordinate if available, image index otherwise
Applies the ruhi theme
Labels reactant, product, and saddle points

`plot_orca_neb_landscape(neb_data, output, *, width=5.37, height=5.37, dpi=200, method`”grad_matern", project_path=True)=#

Publication ORCA NEB 2D landscape using plot_landscape_surface() and plot_landscape_path_overlay().

Parameters #

Parameter	Type	Default	Description
`neb_data`	`OrcaNebResult` / `Mapping`		Typed result from `parse_orca_neb()`
`output`	`Path`		Output file path
`width`	`float`	`5.37`	Figure width (inches)
`height`	`float`	`5.37`	Figure height (inches)
`dpi`	`int`	`200`	Output resolution
`method`	`str`	`"grad_matern"`	Surface interpolation method
`project_path`	`bool`	`True`	Project to reaction valley coordinates

Raises #

Exception	Condition
`ValueError`	`rmsd_r` or `rmsd_p` not available in `neb_data`

Module: `chemparseplot.plot.theme`#

`PlotTheme`#

Frozen dataclass holding all aesthetic parameters.

Field	Type	Description
`name`	`str`	Theme identifier
`font_family`	`str`	Font family name
`font_size`	`int`	Base font size
`facecolor`	`str`	Figure/axes background
`textcolor`	`str`	Text and label color
`edgecolor`	`str`	Axes edge color
`gridcolor`	`str`	Grid line color
`cmap_profile`	`str`	Default colormap for profiles
`cmap_landscape`	`str`	Default colormap for landscapes
`highlight_color`	`str`	Accent color

Built-in Themes #

Name	Font	Colormap	Notes
`"ruhi"`	Atkinson Hyperlegible	`ruhi_diverging`	Default theme
`"cmc.batlow"`	Atkinson Hyperlegible	`cmc.batlow`	Crameri scientific colormap

`get_theme(name, **overrides)`#

Retrieves a theme by name, applying optional field overrides.

`setup_global_theme(theme)`#

Sets plt.rcParams from the theme (font, colors, sizes).

`setup_publication_theme(theme)`#

Extends setup_global_theme() with publication defaults: spine removal, line widths, DPI 300, tight bbox.

`apply_axis_theme(ax, theme)`#

Applies theme properties to a specific axes instance (facecolor, spine colors, tick colors).

`build_cmap(hex_list, name)`#

Builds and registers a LinearSegmentedColormap from hex color strings.

Module: `chemparseplot.plot.optimization`#

Functions for single-ended method (dimer, minimization) visualization.

`plot_optimization_landscape(ax, rmsd_a, rmsd_b, grad_a, grad_b, z_data, *, label_mode`”optimization”, project_path=True, method=”grad_matern", cmap=”viridis”, z_label=”Energy (eV)”, **surface_kwargs)=#

Wraps plot_landscape_surface() and plot_landscape_path_overlay() with semantically correct axis labels for single-ended methods.

Parameters #

Parameter	Type	Default	Description
`label_mode`	`str`	`"optimization"`	`"optimization"` or `"reaction"` for axis labels

All other parameters (including auto_thin, max_surface_points, surface_fit) are passed through to plot_landscape_surface().

`render_single_ended_landscape(...)`#

Full single-ended pipeline (min/saddle CLIs). Accepts the same surface-fit knobs (auto_thin default false, max_surface_points 64, surface_fit). See plot_landscape_surface above.

`plot_optimization_profile(ax, iterations, energies, *, eigenvalues=None, ax_eigen=None, color`”#004D40”, eigen_color=”#FF655D”)=#

Plots energy (and optionally eigenvalue) vs iteration.

`plot_convergence_panel(ax_force, ax_step, dat_df, *, force_col`”convergence”, step_col=”step_size", iter_col=”iteration”, color=”#004D40”)=#

Plots convergence metrics (force norm and step size) from a trajectory DataFrame.

Field	Type	Description
`a_start`, `b_start`	`float`	RMSD origin (first point)
`u_a`, `u_b`	`float`	Unit vector along path direction
`v_a`, `v_b`	`float`	Unit vector perpendicular to path
`path_norm`	`float`	Path length in RMSD space