chemparseplot.plot.neb

Module Contents

Classes

SmoothingParams

Parameters for Savitzky-Golay smoothing of NEB force profiles.

Functions

render_structure_to_image	Renders an ASE Atoms object to a numpy RGBA image array.
_check_xyzrender	Verify that the xyzrender binary is on PATH.
_apply_perspective_tilt	Apply a small off-axis rotation to reveal hidden atoms.
_parse_rotation_angles	Parse ASE-style rotation string into (rx, ry, rz) degrees.
_render_xyzrender	Render an ASE Atoms object to a numpy RGBA array via xyzrender.
_render_atoms	Dispatch rendering to the selected backend.
_render_solvis	Render an atomic structure via solvis (ball-and-stick with PyVista).
_render_ovito	Render via OVITO Python (high-quality off-screen rendering).
plot_structure_strip	Renders a horizontal gallery of atomic structures.
plot_structure_inset	Plots a single structure as an annotation inset.
plot_energy_path	Plots 1D energy profile with optional Hermite spline interpolation.
plot_eigenvalue_path	Plots 1D eigenvalue profile.
_augment_minima_points	Creates a ‘collar’ of synthetic points around the endpoints. This forces the RBF interpolator to curve upwards around these points, preventing artificial wells (overshooting) where the physics dictates a minimum.
_augment_with_gradients	Uses projected gradients to create helper points slightly offset from the path. This effectively tells the RBF interpolator the local slope.
plot_landscape_surface	Plot the 2D landscape surface using reaction valley projection.
plot_landscape_path_overlay	Overlay the colored path line on the landscape.
plot_mmf_peaks_overlay	Overlay MMF (mode-following) refinement peak positions on the landscape.
plot_neb_evolution	Show NEB band evolution across optimization iterations.
plot_orca_neb_profile	Plot ORCA NEB energy profile from OPI-parsed data.
plot_orca_neb_energy_profile	Plot ORCA NEB energy profile using existing eOn-style plotting.
plot_orca_neb_landscape	Plot ORCA NEB 2D landscape using existing eOn-style plotting.

Data

log
InsetImagePos	Position specification for an inset structure image (x, y, rad).
MIN_PATH_LENGTH

API

chemparseplot.plot.neb.log

‘getLogger(…)’

chemparseplot.plot.neb.InsetImagePos

‘namedtuple(…)’

Position specification for an inset structure image (x, y, rad).

Added in version 0.1.0.

class chemparseplot.plot.neb.SmoothingParams

Parameters for Savitzky-Golay smoothing of NEB force profiles.

Added in version 0.1.0.

window_length: int

5

polyorder: int

2

chemparseplot.plot.neb.MIN_PATH_LENGTH

1e-06

chemparseplot.plot.neb.render_structure_to_image(atoms, zoom, rotation)

Renders an ASE Atoms object to a numpy RGBA image array.

Parameters

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

Returns

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

Added in version 0.1.0.

chemparseplot.plot.neb._check_xyzrender()

Verify that the xyzrender binary is on PATH.

Raises

RuntimeError If xyzrender is not found, with install instructions.

chemparseplot.plot.neb._apply_perspective_tilt(atoms, tilt_deg=8.0)

Apply a small off-axis rotation to reveal hidden atoms.

Uses Rodrigues formula to rotate around an axis perpendicular to the viewing direction. This prevents atoms from occluding each other in orthographic projection without significantly distorting the view.

Parameters

atoms : ase.Atoms Structure to tilt (modified in place). tilt_deg : float Tilt angle in degrees. 5-10 is usually enough.

chemparseplot.plot.neb._parse_rotation_angles(rotation_str)

Parse ASE-style rotation string into (rx, ry, rz) degrees.

E.g. "0x,90y,0z" -> (0, 90, 0).

chemparseplot.plot.neb._render_xyzrender(atoms, rotation='auto', canvas_size=400, config='paton')

Render an ASE Atoms object to a numpy RGBA array via xyzrender.

Uses the specified config preset (default: paton for ball-and-stick). Other useful presets: bubble (space-filling, good for surfaces), flat, tube, wire, skeletal.

Parameters

atoms : ase.Atoms Structure to render. rotation : str "auto" (default) uses xyzrender’s auto-orientation. Any ASE-style string (e.g. "0x,90y,0z") disables auto-orient and pre-rotates the atoms. canvas_size : int Output image width/height in pixels (passed as -S).

Returns

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

chemparseplot.plot.neb._render_atoms(atoms, renderer, zoom, rotation, canvas_size=400, perspective_tilt=0.0, xyzrender_config='paton')

Dispatch rendering to the selected backend.

All backends return a numpy RGBA image array.

Parameters

rotation : str ASE-style rotation string (e.g. "0x,90y,0z"). Applied uniformly across all backends. perspective_tilt : float Small off-axis tilt in degrees to reveal occluded atoms. 0 disables. 5-10 is usually enough. xyzrender_config : str xyzrender preset name (paton, bubble, flat, tube, wire, skeletal).

chemparseplot.plot.neb._render_solvis(atoms, rotation='0x,90y,0z', canvas_size=400)

Render an atomic structure via solvis (ball-and-stick with PyVista).

Requires the solvis-tools package (pip install solvis-tools).

Parameters

atoms : ase.Atoms Atomic structure to render. rotation : str, optional Rotation string in the format "RXx,RYy,RZz" (degrees). Default is "0x,90y,0z". canvas_size : int, optional Width and height of the rendered image in pixels. Default is 400.

Returns

numpy.ndarray RGBA image array.

chemparseplot.plot.neb._render_ovito(atoms, rotation='0x,90y,0z', canvas_size=400)

Render via OVITO Python (high-quality off-screen rendering).

Requires: pip install ovito

Returns

numpy.ndarray RGBA image array.

chemparseplot.plot.neb.plot_structure_strip(ax, atoms_list, labels, zoom=0.3, rotation='0x,90y,0z', theme_color='black', max_cols=6, renderer='xyzrender', col_spacing=1.5, show_dividers=False, xyzrender_config='paton', divider_color='gray', divider_style='--', perspective_tilt=0.0) → Any

Renders a horizontal gallery of atomic structures.

Parameters

renderer : str Rendering backend: "ase", "xyzrender", "solvis", or "ovito". col_spacing : float Horizontal spacing between structure images in data units. show_dividers : bool Draw vertical divider lines between structures. divider_color : str Color for divider lines. divider_style : str Linestyle for divider lines (e.g. "--", "-", ":").

Added in version 0.1.0.

Changed in version 1.2.0: Added the renderer parameter.

Changed in version 1.5.0: Added col_spacing, show_dividers, divider_color, divider_style parameters. Added "solvis" and "ovito" renderer backends.

chemparseplot.plot.neb.plot_structure_inset(ax, atoms, x, y, xybox, rad, zoom=0.4, rotation='0x,90y,0z', arrow_props=None, renderer='xyzrender', perspective_tilt=0.0, xyzrender_config='paton') → Any

Plots a single structure as an annotation inset.

Parameters

renderer : str Rendering backend: "ase" (default) or "xyzrender".

Added in version 0.1.0.

Changed in version 1.2.0: Added the renderer parameter.

chemparseplot.plot.neb.plot_energy_path(ax, rc, energy, f_para, color, alpha, zorder, method='hermite', smoothing=None, label=None) → Any

Plots 1D energy profile with optional Hermite spline interpolation.

Added in version 0.1.0.

chemparseplot.plot.neb.plot_eigenvalue_path(ax, rc, eigenvalue, color, alpha, zorder, grid_color='white')

Plots 1D eigenvalue profile.

Added in version 0.1.0.

chemparseplot.plot.neb._augment_minima_points(rmsd_r, rmsd_p, z_data, radius=0.01, d_e=0.02, num_pts=12)

Creates a ‘collar’ of synthetic points around the endpoints. This forces the RBF interpolator to curve upwards around these points, preventing artificial wells (overshooting) where the physics dictates a minimum.

chemparseplot.plot.neb._augment_with_gradients(r, p, z, gr, gp, epsilon=0.05)

Uses projected gradients to create helper points slightly offset from the path. This effectively tells the RBF interpolator the local slope.

Creates 4 helper points for every real point: (r +/- eps, p) and (r, p +/- eps)

chemparseplot.plot.neb.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) → Any

Plot the 2D landscape surface using reaction valley projection.

If project_path evaluates to True, the plot maps into reaction valley coordinates (Progress \(s\) vs Orthogonal Distance \(d\)).

Implements 2D reaction valley projection method from cite:[goswami2026valley]. The method rotates the RMSD plane into reaction progress and orthogonal deviation coordinates.

Parameters

basis : ProjectionBasis or None Pre-computed projection basis. When provided, this basis is used instead of computing one from rmsd_r/rmsd_p. Pass this when the surface data is a subset (e.g. last step only) but the basis should come from the full path.

Added in version 0.1.0.

Changed in version 1.1.0: Added the project_path parameter for reaction-valley coordinate projection.

chemparseplot.plot.neb.plot_landscape_path_overlay(ax, r, p, z, cmap, z_label, project_path=True, all_r=None, all_p=None, all_z=None, basis=None) → Any

Overlay the colored path line on the landscape.

Mapped to the chosen coordinate basis. When all_r/all_p/all_z arrays are provided (all NEB iterations), a triangulated filled contour is drawn as the background so the landscape is never empty.

Added in version 0.1.0.

Changed in version 1.1.0: Added the project_path parameter for reaction-valley coordinate projection.

Changed in version 1.6.0: Added all_r, all_p, all_z for triangulated background contours.

chemparseplot.plot.neb.plot_mmf_peaks_overlay(ax, peak_rmsd_r, peak_rmsd_p, peak_energies, project_path=True, path_rmsd_r=None, path_rmsd_p=None) → None

Overlay MMF (mode-following) refinement peak positions on the landscape.

Used for OCI-NEB/RONEB visualization to show where dimer refinement was applied along the band.

Parameters

ax Matplotlib axes (same as the landscape plot). peak_rmsd_r, peak_rmsd_p RMSD coordinates of MMF peak structures. peak_energies Energy values at the peak positions. project_path Whether to project into (s, d) coordinates. path_rmsd_r, path_rmsd_p RMSD arrays of the main NEB path, used to define the projection basis. Required when project_path=True. If None, falls back to computing basis from the peaks themselves (less accurate).

Added in version 1.5.0.

chemparseplot.plot.neb.plot_neb_evolution(ax, step_rmsd_r_list: list[numpy.ndarray], step_rmsd_p_list: list[numpy.ndarray], project_path=True, cmap='Blues') → None

Show NEB band evolution across optimization iterations.

Older bands are drawn with lower opacity; the final band is most visible. All bands are projected using the final band’s basis so they share one consistent coordinate frame.

Parameters

ax Matplotlib axes. step_rmsd_r_list List of RMSD-R arrays, one per NEB iteration. step_rmsd_p_list List of RMSD-P arrays, one per NEB iteration. project_path Whether to project into (s, d) coordinates. cmap Colormap for fading bands (older = lighter).

Added in version 1.5.0.

chemparseplot.plot.neb.plot_orca_neb_profile(neb_data: dict[str, Any], output: pathlib.Path, *, width: float = 7.0, height: float = 5.0, dpi: int = 200) → None

Plot ORCA NEB energy profile from OPI-parsed data.

Parameters

neb_data Dictionary from parse_orca_neb() containing: - energies: list of energies in eV - n_images: number of images - barrier_forward, barrier_reverse: barrier heights output Output file path width, height Figure dimensions in inches dpi Output resolution

Example

from chemparseplot.parse.orca.neb import parse_orca_neb from chemparseplot.plot.neb import plot_orca_neb_profile data = parse_orca_neb(“job”, Path(“calc”)) plot_orca_neb_profile(data, “neb_profile.pdf”)

chemparseplot.plot.neb.plot_orca_neb_energy_profile(neb_data: dict[str, Any], output: pathlib.Path, *, width: float = 5.37, height: float = 5.37, dpi: int = 200, method: str = 'hermite', smoothing: Any = None) → None

Plot ORCA NEB energy profile using existing eOn-style plotting.

Creates publication-quality energy profile similar to eOn NEB plots. Uses the same plotting functions as eOn NEB for consistency.

Parameters

neb_data Dictionary from parse_orca_neb() containing: - energies: array of energies in eV - rmsd_r, rmsd_p: RMSD coordinates (optional) - grad_r, grad_p: gradients (optional) - n_images: number of images output Output file path width, height Figure dimensions in inches dpi Output resolution method Interpolation method: ‘hermite’ or ‘spline’ smoothing Smoothing parameters

Example

from chemparseplot.parse.orca.neb import parse_orca_neb from chemparseplot.plot.neb import plot_orca_neb_energy_profile data = parse_orca_neb(“job”, Path(“calc”)) plot_orca_neb_energy_profile(data, “orca_neb_profile.pdf”)

chemparseplot.plot.neb.plot_orca_neb_landscape(neb_data: dict[str, Any], output: pathlib.Path, *, width: float = 5.37, height: float = 5.37, dpi: int = 200, method: str = 'grad_matern', project_path: bool = True) → None

Plot ORCA NEB 2D landscape using existing eOn-style plotting.

Creates publication-quality landscape plot similar to eOn NEB plots. Uses the same plotting functions as eOn NEB for consistency.

Parameters

neb_data Dictionary from parse_orca_neb() containing: - energies: array of energies in eV - rmsd_r, rmsd_p: RMSD coordinates - grad_r, grad_p: gradients - n_images: number of images output Output file path width, height Figure dimensions in inches dpi Output resolution method Surface interpolation method project_path Whether to project into reaction valley coordinates

Example

from chemparseplot.parse.orca.neb import parse_orca_neb from chemparseplot.plot.neb import plot_orca_neb_landscape data = parse_orca_neb(“job”, Path(“calc”)) plot_orca_neb_landscape(data, “orca_neb_landscape.pdf”)