`chemparseplot.plot.neb`#

Module Contents#

Classes#

`InsetImagePos`	Position specification for an inset structure image.
`SmoothingParams`	Parameters for Savitzky-Golay smoothing of NEB force profiles.
`_OrcaNebPlotPayload`	Normalized ORCA NEB plotting payload.
`SurfaceFitConfig`	Declarative surface-fit knobs (TOML-friendly mapping).

Functions#

`_crop_transparent_rgba`	Crop transparent or matte-colored margins from an RGBA image.
`_resize_rgba_image`	Resize an RGBA image to the requested pixel size.
`_alpha_blit_rgba`	Composite an RGBA image onto a canvas at top-left pixel coordinates.
`render_structure_to_image`	Renders an ASE Atoms object to a numpy RGBA image array.
`_import_xyzrender`	Import xyzrender via ensure_import (AUTO_DEPS) or a normal import.
`_check_xyzrender`	Verify xyzrender is importable (package or ensure_import cache).
`_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 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.
`surface_fit_indices`	Return indices for evenly spaced surface-fit observations.
`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_phase_points_overlay`	Overlay a second phase of sampled points on top of the NEB landscape.
`plot_neb_evolution`	Show NEB band evolution across optimization iterations.
`convert_neb_values`	Convert NEB values for the active plotted quantity.
`default_neb_ylabel`	Return the canonical label for NEB energy-like axes.
`landscape_projection_basis`	Reuse the full-dataset basis whenever projected overlays need one.
`landscape_half_span`	Symmetric \|d\| half-span for a projected (s, d) landscape.
`mark_saddle_point`	Draw a high-contrast saddle marker (gold star) on a profile or landscape.
`save_plot`	Save plots, cropping unused figure canvas (including strip layouts).
`profile_structure_indices`	Select profile structures to render as a strip payload.
`profile_strip_payload`	Build an ordered strip payload for profile plots.
`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.
`_normalize_orca_neb_plot_payload`	Normalize ORCA NEB inputs for plotting entrypoints.
`_orca_saddle_index`	Return the internal saddle index for a NEB profile, if any.
`_annotate_orca_barrier`	Annotate the forward barrier on an ORCA NEB profile plot.
`_plot_orca_profile_keypoints`	Plot reactant/product/saddle markers for ORCA NEB profile-like plots.
`_save_orca_figure`	Save an ORCA plotting figure with the standard settings.

Data#

`log`
`MIN_PATH_LENGTH`
`STRIP_IMAGE_ZOOM_SCALE`
`INSET_IMAGE_ZOOM_SCALE`

API#

chemparseplot.plot.neb.log#: ‘getLogger(…)’

class chemparseplot.plot.neb.InsetImagePos#

Position specification for an inset structure image.

Added in version 0.1.0.

x: float#: None

y: float#: None

rad: float#: None

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

class chemparseplot.plot.neb._OrcaNebPlotPayload#

Normalized ORCA NEB plotting payload.

energies: numpy.ndarray#: None

n_images: int#: None

barrier_forward: float | None#: None

rmsd_r: numpy.ndarray | None#: None

rmsd_p: numpy.ndarray | None#: None

grad_r: numpy.ndarray | None#: None

grad_p: numpy.ndarray | None#: None

chemparseplot.plot.neb.MIN_PATH_LENGTH#: 1e-06

chemparseplot.plot.neb.STRIP_IMAGE_ZOOM_SCALE#: 0.18

chemparseplot.plot.neb.INSET_IMAGE_ZOOM_SCALE#: 0.45

chemparseplot.plot.neb._crop_transparent_rgba(img_data: numpy.ndarray, alpha_threshold: float = 0.02, matte_threshold: float = 0.04) → numpy.ndarray#: Crop transparent or matte-colored margins from an RGBA image.

chemparseplot.plot.neb._resize_rgba_image(img_data: numpy.ndarray, target_h: int, target_w: int) → numpy.ndarray#: Resize an RGBA image to the requested pixel size.

chemparseplot.plot.neb._alpha_blit_rgba(canvas: numpy.ndarray, img_data: numpy.ndarray, x0: int, y0: int) → None#: Composite an RGBA image onto a canvas at top-left pixel coordinates.

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._import_xyzrender()#

Import xyzrender via ensure_import (AUTO_DEPS) or a normal import.

Prefer the Python API over a PATH binary. Matches the suite lazy-dep model (rgpycrumbs ensure_import / RGPYCRUMBS_AUTO_DEPS).

chemparseplot.plot.neb._check_xyzrender()#

Verify xyzrender is importable (package or ensure_import cache).

Raises

RuntimeError If xyzrender cannot be imported, 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 Python API (xyzrender.render), staged through ensure_import when RGPYCRUMBS_AUTO_DEPS=1 — not a PATH binary.

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.

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=None, 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, max_display_height_px: float | None = None, width_fill_fraction=0.82, prefer_single_row: bool = True) → 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. "--", "-", ":"). prefer_single_row : bool If True (default), pack up to 16 structures in one row. If False, honour max_cols so e.g. 12 images with max_cols=6 become two rows of larger molecules.

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 spline interpolation.

Parameters

method : "hermite" — cubic Hermite using -f_para as dE/d(rc) (path-length coordinates only; meaningless when rc is image index). "spline" — cubic spline through the energy points. "none" — markers joined by straight segments only (no interpolant).

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.surface_fit_indices(n: int, max_points: int) → numpy.ndarray#

Return indices for evenly spaced surface-fit observations.

Always includes the first and last indices when n > 0. When n <= max_points, returns arange(n). Used by

Func:: plot_landscape_surface when auto_thin is enabled.

Added in version 1.9.9.

class chemparseplot.plot.neb.SurfaceFitConfig#

Declarative surface-fit knobs (TOML-friendly mapping).

Prefer this over growing positional/flag lists. Key names match rgpycrumbs eOn plot TOML ([shared] / [min] / [neb])::

auto_thin = false
max_surface_points = 64

Defaults keep historical behaviour (no thinning).

Added in version 1.9.10.

auto_thin: bool#: False

max_surface_points: int#: 64

classmethod from_mapping(data: collections.abc.Mapping[str, Any] | None) → chemparseplot.plot.neb.SurfaceFitConfig#: Build from a TOML table or plain dict (unknown keys ignored).

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, auto_thin: bool = False, max_surface_points: int = 64, surface_fit: chemparseplot.plot.neb.SurfaceFitConfig | collections.abc.Mapping[str, Any] | None = 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. auto_thin : bool, default False If True and the number of observations exceeds max_surface_points, subsample for the GP surface fit only (first/last + evenly spaced intermediates). Viewport and scatter points still use the full cloud. Off by default so callers must opt in (dense eOn min movies can otherwise yield non-finite grids). max_surface_points : int, default 64 Cap on fit observations when auto_thin is True. surface_fit : SurfaceFitConfig or mapping, optional TOML-friendly config object. When given, overrides auto_thin and max_surface_points (prefer this over ad-hoc kwargs).

Added in version 0.1.0.

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

Added in version 1.9.9: Added auto_thin and max_surface_points.

Added in version 1.9.10: Added surface_fit (:class:SurfaceFitConfig / mapping).

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_phase_points_overlay(ax, rmsd_r, rmsd_p, *, project_path=True, path_rmsd_r=None, path_rmsd_p=None, phase_color='#FF8F00', label=None) → None#

Overlay a second phase of sampled points on top of the NEB landscape.

This is intended for OCI-NEB / RONEB refinement trajectories, where the main NEB band points are already shown as dark background samples and the dimer/MMF phase needs a distinct inner marker to remain legible.

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.convert_neb_values(values, plot_mode: str, energy_unit: str)#: Convert NEB values for the active plotted quantity.

chemparseplot.plot.neb.default_neb_ylabel(plot_mode: str, energy_unit: str) → str#: Return the canonical label for NEB energy-like axes.

chemparseplot.plot.neb.landscape_projection_basis(global_basis, final_r, final_p)#: Reuse the full-dataset basis whenever projected overlays need one.

chemparseplot.plot.neb.landscape_half_span(x_limits, final_r, final_p, additional_atoms_data, global_basis, *, path_pad: float = 1.15, min_half: float = 0.02, equal_metric: bool = True)#

Symmetric |d| half-span for a projected (s, d) landscape.

With equal_metric=True (default), the half-span is at least half the s window so that Δs = Δd and set_aspect('equal') yields a square panel where 1 Å of progress matches 1 Å of orthogonal deviation (same RMSD metric). Path/overlay markers still expand the span when they exceed that.

chemparseplot.plot.neb.mark_saddle_point(ax, x, y, *, label: str = 'SP', font_size: float = 12.0, vline: bool = False, annotate: bool = True)#: Draw a high-contrast saddle marker (gold star) on a profile or landscape.

chemparseplot.plot.neb.save_plot(output_file, dpi, *, has_strip)#: Save plots, cropping unused figure canvas (including strip layouts).

chemparseplot.plot.neb.profile_structure_indices(atoms_list, y_values, plot_structures, plot_mode)#: Select profile structures to render as a strip payload.

chemparseplot.plot.neb.profile_strip_payload(atoms_list, x_values, y_values, plot_structures, plot_mode)#: Build an ordered strip payload for profile plots.

chemparseplot.plot.neb.plot_orca_neb_profile(neb_data: collections.abc.Mapping[str, Any] | chemparseplot.parse.types.OrcaNebResult, output: pathlib.Path, *, width: float = 7.0, height: float = 5.0, dpi: int = 200, energy_unit: str = 'eV') → None#

Plot ORCA NEB energy profile from OPI-parsed data.

Parameters

neb_data Mapping-like ORCA NEB result from parse_orca_neb() 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: collections.abc.Mapping[str, Any] | chemparseplot.parse.types.OrcaNebResult, output: pathlib.Path, *, width: float = 5.37, height: float = 5.37, dpi: int = 200, method: str = 'hermite', smoothing: Any = None, energy_unit: str = 'eV') → 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 Mapping-like ORCA NEB result from parse_orca_neb() 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: collections.abc.Mapping[str, Any] | chemparseplot.parse.types.OrcaNebResult, output: pathlib.Path, *, width: float = 5.37, height: float = 5.37, dpi: int = 200, method: str = 'grad_matern', project_path: bool = True, energy_unit: str = 'eV') → 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 Mapping-like ORCA NEB result from parse_orca_neb() 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”)

chemparseplot.plot.neb._normalize_orca_neb_plot_payload(neb_data: collections.abc.Mapping[str, Any] | chemparseplot.parse.types.OrcaNebResult, energy_unit: str) → chemparseplot.plot.neb._OrcaNebPlotPayload#: Normalize ORCA NEB inputs for plotting entrypoints.

chemparseplot.plot.neb._orca_saddle_index(energies: numpy.ndarray) → int | None#: Return the internal saddle index for a NEB profile, if any.

chemparseplot.plot.neb._annotate_orca_barrier(ax, *, x: float, y: float, barrier_forward: float | None, energy_unit: str, dx: float, dy: float, use_math_text: bool = False, zorder: int | None = None) → None#: Annotate the forward barrier on an ORCA NEB profile plot.

chemparseplot.plot.neb._plot_orca_profile_keypoints(ax, *, x_values: numpy.ndarray, energies: numpy.ndarray, payload: chemparseplot.plot.neb._OrcaNebPlotPayload, energy_unit: str, reactant_markersize: float, product_markersize: float, saddle_markersize: float, barrier_dx: float, barrier_dy: float, use_math_text: bool = False, zorder: int | None = None, barrier_zorder: int | None = None) → int | None#: Plot reactant/product/saddle markers for ORCA NEB profile-like plots.

chemparseplot.plot.neb._save_orca_figure(fig, output: pathlib.Path, *, dpi: int) → None#: Save an ORCA plotting figure with the standard settings.

chemparseplot.plot.neb#

Module Contents#

Classes#

Functions#

Data#

API#

`chemparseplot.plot.neb`#