rgpycrumbs.eon.plt_neb

Plots Nudged Elastic Band (NEB) reaction paths and landscapes.

This script provides a command-line interface (CLI) to visualize data generated from NEB calculations. It can plot:

1. Energy/Eigenvalue Profiles: Shows the evolution of the energy or lowest eigenvalue along the reaction coordinate. It can overlay multiple paths (e.g., from different optimization steps) and use a physically-motivated Hermite spline interpolation using force data.

2. 2D Reaction Landscapes: Plots the path on a 2D coordinate system defined by the Root Mean Square Deviation (RMSD) from the reactant and product structures. This requires the ‘ira_mod’ library. It can also interpolate and display the 2D energy/eigenvalue surface.

The script can also render atomic structures from a .con file as insets on the plots for key points (reactant, saddle, product).

This script follows the guidelines laid out here: https://realpython.com/python-script-structure/

Attributes

ira_mod
log
RUHI_COLORS
MIN_PATH_LENGTH
BATLOW_THEME
RUHI_THEME
THEMES
DEFAULT_INPUT_PATTERN
DEFAULT_PATH_PATTERN
ROUNDING_DF
RBF_SMOOTHING
IRA_KMAX_DEFAULT

Classes

PlotTheme	Holds all aesthetic parameters for a matplotlib theme.
PlotType	Defines the overall plot type.
RCMode	Defines the reaction coordinate for profile plots.
PlotMode	Defines the primary data to be plotted (Y-axis or color).
SplineMethod	Defines the interpolation method for profile plots.
SmoothingParams	Parameters for Savitzky-Golay smoothing of force data.
InsetImagePos

Functions

build_cmap(hex_list, name)	Build and register a LinearSegmentedColormap from a list of hex colors.
setup_global_theme(theme)	Sets global plt.rcParams based on the theme before plot creation.
apply_plot_theme(ax, theme)	Applies theme properties specific to an axis instance.
load_paths(→ list[pathlib.Path])	Finds and sorts files matching a glob pattern.
calculate_rmsd_from_ref(→ numpy.ndarray)	Calculates the RMSD of each structure in a list relative to a reference.
calculate_landscape_coords(atoms_list, ira_instance, ...)	Calculates 2D landscape coordinates (RMSD-R, RMSD-P) for a path.
_load_or_compute_data(→ polars.DataFrame)	Retrieves data from a parquet cache or triggers a computation callback.
plot_single_inset(ax, atoms, x_coord, y_coord[, ...])	Renders a single ASE Atoms object and plots it as an inset.
plot_structure_insets(ax, atoms_list, x_coords, ...[, ...])	Plots insets for critical points (reactant, saddle, product) or all images.
plot_energy_path(ax, path_data, color, alpha, zorder)	Plots a single interpolated energy path and its data points.
plot_eigenvalue_path(ax, path_data, color, alpha, zorder)	Plots a single interpolated eigenvalue path and its data points.
plot_landscape_path(ax, rmsd_r, rmsd_p, z_data, cmap, ...)	Plots the 1D path on the 2D RMSD landscape, colored by z_data.
plot_interpolated_grid(ax, rmsd_r, rmsd_p, z_data, ...)	Generates and plots an interpolated 2D surface (contour plot) with splines.
plot_interpolated_rbf(ax, rmsd_r, rmsd_p, z_data, ...)	Generates and plots an interpolated 2D surface (contour plot).
setup_plot_aesthetics(ax, title, xlabel, ylabel)	Applies labels, limits, and other plot aesthetics.
main(input_dat_pattern, input_path_pattern, con_file, ...)	Main entry point for NEB plot script.
_setup_theme(theme, cmap_profile, cmap_landscape, ...)	Loads the selected theme and applies any user overrides.
_run_dependency_checks(plot_type, rc_mode, ...)	Validates dependencies and option combinations.
_determine_figsize(figsize, fig_height, aspect_ratio)	Determines the final figure size based on user inputs.
_load_structures(con_file, additional_con, plot_type, ...)	Loads atoms from .con files and calcs RMSD for additional structure.
_validate_data_atoms_match(z_data, atoms, dat_file_name)	Checks if data points count matches structure count, exits on mismatch.
_get_profile_labels(rc_mode, plot_mode, xlabel, ...)	Determines default labels for profile plots.
_aggregate_all_paths(all_dat_paths, all_con_paths, ...)	Loads and aggregates data from all .dat and .con files for 2D surface using
_plot_landscape(ax, atoms_list, input_dat_pattern, ...)	Handles all logic for drawing 2D landscape plots.
_plot_profile(ax, fig, input_dat_pattern, atoms_list, ...)	Handles all logic for drawing 1D profile plots.

Module Contents

rgpycrumbs.eon.plt_neb.ira_mod

rgpycrumbs.eon.plt_neb.log

rgpycrumbs.eon.plt_neb.RUHI_COLORS

rgpycrumbs.eon.plt_neb.MIN_PATH_LENGTH = 1e-06

rgpycrumbs.eon.plt_neb.build_cmap(hex_list, name)

Build and register a LinearSegmentedColormap from a list of hex colors.

class rgpycrumbs.eon.plt_neb.PlotTheme

Holds all aesthetic parameters for a matplotlib theme.

name: str

font_family: str

font_size: int

facecolor: str

textcolor: str

edgecolor: str

gridcolor: str

cmap_profile: str

cmap_landscape: str

highlight_color: str

rgpycrumbs.eon.plt_neb.BATLOW_THEME

rgpycrumbs.eon.plt_neb.RUHI_THEME

rgpycrumbs.eon.plt_neb.THEMES

class rgpycrumbs.eon.plt_neb.PlotType(*args, **kwds)

Bases: enum.Enum

Defines the overall plot type.

PROFILE = 'profile'

LANDSCAPE = 'landscape'

class rgpycrumbs.eon.plt_neb.RCMode(*args, **kwds)

Bases: enum.Enum

Defines the reaction coordinate for profile plots.

PATH = 'path'

RMSD = 'rmsd'

INDEX = 'index'

class rgpycrumbs.eon.plt_neb.PlotMode(*args, **kwds)

Bases: enum.Enum

Defines the primary data to be plotted (Y-axis or color).

ENERGY = 'energy'

EIGENVALUE = 'eigenvalue'

class rgpycrumbs.eon.plt_neb.SplineMethod(*args, **kwds)

Bases: enum.Enum

Defines the interpolation method for profile plots.

HERMITE = 'hermite'

SPLINE = 'spline'

rgpycrumbs.eon.plt_neb.DEFAULT_INPUT_PATTERN = 'neb_*.dat'

rgpycrumbs.eon.plt_neb.DEFAULT_PATH_PATTERN = 'neb_path_*.con'

rgpycrumbs.eon.plt_neb.ROUNDING_DF = 3

rgpycrumbs.eon.plt_neb.RBF_SMOOTHING = 0.01

rgpycrumbs.eon.plt_neb.IRA_KMAX_DEFAULT = 1.8

class rgpycrumbs.eon.plt_neb.SmoothingParams

Parameters for Savitzky-Golay smoothing of force data.

window_length: int = 5

polyorder: int = 2

class rgpycrumbs.eon.plt_neb.InsetImagePos

Bases: tuple

x

y

rad

rgpycrumbs.eon.plt_neb.setup_global_theme(theme: PlotTheme)

Sets global plt.rcParams based on the theme before plot creation.

rgpycrumbs.eon.plt_neb.apply_plot_theme(ax: matplotlib.pyplot.Axes, theme: PlotTheme)

Applies theme properties specific to an axis instance.

rgpycrumbs.eon.plt_neb.load_paths(file_pattern: str) → list[pathlib.Path]

Finds and sorts files matching a glob pattern.

rgpycrumbs.eon.plt_neb.calculate_rmsd_from_ref(atoms_list: list, ira_instance, ref_atom: ase.Atoms, ira_kmax: float) → numpy.ndarray

Calculates the RMSD of each structure in a list relative to a reference.

Uses the Iterative Reordering and Alignment (IRA) algorithm to find the optimal alignment and permutation before calculating RMSD.

Parameters:

• atoms_list (list) – A list of ASE Atoms objects.

• ira_instance (ira_mod.IRA) – An instantiated IRA object.

• ref_atom (ase.Atoms) – The reference Atoms object to align against.

• ira_kmax (float) – kmax factor for IRA.

Returns:

An array of RMSD values, one for each structure in atoms_list.

Return type:

np.ndarray

rgpycrumbs.eon.plt_neb.calculate_landscape_coords(atoms_list: list, ira_instance: ira_mod, ira_kmax: float)

Calculates 2D landscape coordinates (RMSD-R, RMSD-P) for a path.

Parameters:

• atoms_list (list) – List of ASE Atoms objects representing the path.

• ira_instance (ira_mod.IRA) – An instantiated IRA object.

• ira_kmax (float) – kmax factor for IRA.

Returns:

A tuple of (rmsd_r, rmsd_p) arrays relative to reactant and product.

Return type:

tuple[np.ndarray, np.ndarray]

rgpycrumbs.eon.plt_neb._load_or_compute_data(cache_file: pathlib.Path | None, force_recompute: bool, validation_check: collections.abc.Callable[[polars.DataFrame], None], computation_callback: collections.abc.Callable[[], polars.DataFrame], context_name: str) → polars.DataFrame

Retrieves data from a parquet cache or triggers a computation callback.

Parameters:

• cache_file (Path | None) – The path to the cache file.

• force_recompute (bool) – If True, skips loading and forces computation.

• validation_check (Callable) – A function that receives the loaded DataFrame and raises ValueError if the schema appears incorrect (e.g., missing columns).

• computation_callback (Callable) – A function that performs the heavy calculation and returns a DataFrame if the cache remains unavailable or invalid.

• context_name (str) – Label for logging (e.g., “Profile” or “Landscape”).

Returns:

The requested data.

Return type:

pl.DataFrame

rgpycrumbs.eon.plt_neb.plot_single_inset(ax, atoms, x_coord, y_coord, xybox=(15.0, 60.0), rad=0.0, zoom=0.4, ase_rotation='0x, 90y, 0z', arrow_head_length=0.4, arrow_head_width=0.4, arrow_tail_width=0.1)

Renders a single ASE Atoms object and plots it as an inset.

Parameters:

• ax (matplotlib.axes.Axes) – The axis to plot on.

• atoms (ase.Atoms) – The atomic structure to render.

• x_coord (float) – The x-data coordinate to anchor the arrow to.

• y_coord (float) – The y-data coordinate to anchor the arrow to.

• xybox (tuple, optional) – The (x, y) offset in points for placing the image box.

• rad (float, optional) – The connection style ‘rad’ parameter for the arrow.

• zoom (float) – Scale the inset image.

• ase_rotation (str) – ASE rotation string for structure insets.

• arrow_head_length (float) – Arrow head length for insets.

• arrow_head_width (float) – Arrow head width for insets.

• arrow_tail_width (float) – Arrow tail width for insets.

rgpycrumbs.eon.plt_neb.plot_structure_insets(ax, atoms_list, x_coords, y_coords, saddle_data, images_to_plot, plot_mode, draw_reactant: InsetImagePos | None = None, draw_saddle: InsetImagePos | None = None, draw_product: InsetImagePos | None = None, zoom_ratio: float = 0.4, ase_rotation: str = '0x, 90y, 0z', arrow_head_length: float = 0.4, arrow_head_width: float = 0.4, arrow_tail_width: float = 0.1)

Plots insets for critical points (reactant, saddle, product) or all images.

Parameters:

• ax (matplotlib.axes.Axes) – The axis to plot on.

• atoms_list (list) – List of all ASE Atoms objects for the path.

• x_coords (np.ndarray) – Array of x-coordinates (RC or RMSD-R) for each image.

• y_coords (np.ndarray) – Array of y-coordinates (Energy, Eigenvalue, or RMSD-P) for each image.

• saddle_data (np.ndarray) – Data used to find the saddle point. For energy mode, this is the energy array. For eigenvalue mode, this is the eigenvalue array.

• images_to_plot (str) – Which images to plot: “all” or “crit_points”.

• plot_mode (str) – “energy” or “eigenvalue”, used to determine saddle point logic.

• draw_reactant (InsetImagePos) – Positioning info for the reactant inset.

• draw_saddle (InsetImagePos) – Positioning info for the saddle inset.

• draw_product (InsetImagePos) – Positioning info for the product inset.

• zoom_ratio (float) – Scale the inset image.

• ase_rotation (str) – ASE rotation string for structure insets.

• arrow_head_length (float) – Arrow head length for insets.

• arrow_head_width (float) – Arrow head width for insets.

• arrow_tail_width (float) – Arrow tail width for insets.

rgpycrumbs.eon.plt_neb.plot_energy_path(ax, path_data, color, alpha, zorder, method='hermite', smoothing=SmoothingParams())

Plots a single interpolated energy path and its data points.

Supports two interpolation methods:

• ‘hermite’: Cubic Hermite spline. Uses energy values and their derivatives (taken from the parallel force f_para). This is often a more physically accurate interpolation for NEB paths.

• ‘spline’: Standard cubic spline. Ignores derivative information.

Parameters:

• ax (matplotlib.axes.Axes) – The axis to plot on.

• path_data (np.ndarray) – 2D array of data (from neb_*.dat), transposed. Expected: path_data[1] = rc, path_data[2] = energy, path_data[3] = f_para

• color (str or tuple) – Color for the plot.

• alpha (float) – Transparency for the plot.

• zorder (int) – Plotting layer order.

• method (str, optional) – Interpolation method: “hermite” or “spline”.

• smoothing (SmoothingParams, optional) – Parameters for Savitzky-Golay filter if using Hermite spline.

rgpycrumbs.eon.plt_neb.plot_eigenvalue_path(ax, path_data, color, alpha, zorder, grid_color='white')

Plots a single interpolated eigenvalue path and its data points.

Parameters:

• ax (matplotlib.axes.Axes) – The matplotlib axes object on which to plot.

• path_data (np.ndarray) – 2D array of data (from neb_*.dat), transposed. Expected: path_data[1] = rc, path_data[4] = eigenvalue

• color (str or tuple) – Color specification for the plot line and markers.

• alpha (float) – Transparency level for the plot line and markers.

• zorder (int) – Drawing order for the plot elements.

• grid_color (str, optional) – Color for the horizontal zero line.

rgpycrumbs.eon.plt_neb.plot_landscape_path(ax, rmsd_r, rmsd_p, z_data, cmap, z_label)

Plots the 1D path on the 2D RMSD landscape, colored by z_data. …

rgpycrumbs.eon.plt_neb.plot_interpolated_grid(ax, rmsd_r, rmsd_p, z_data, show_pts, cmap, scatter_r=None, scatter_p=None)

Generates and plots an interpolated 2D surface (contour plot) with splines.

This may have artifacts where samples are not present, debug with show_pts or use with “last”.

Parameters:

• ax (matplotlib.axes.Axes) – The axis to plot on.

• rmsd_r (np.ndarray) – RMSD from reactant (x-axis).

• rmsd_p (np.ndarray) – RMSD from product (y-axis).

• z_data (np.ndarray) – Data for coloring the path (z-axis).

• show_pts (bool) – Whether to show scatter points.

• cmap (str) – Name of the colormap to use.

• scatter_r (np.ndarray, optional) – Optional separate x-coords for scatter points.

• scatter_p (np.ndarray, optional) – Optional separate y-coords for scatter points.

rgpycrumbs.eon.plt_neb.plot_interpolated_rbf(ax, rmsd_r, rmsd_p, z_data, show_pts, rbf_smoothing, cmap, scatter_r=None, scatter_p=None)

Generates and plots an interpolated 2D surface (contour plot).

Parameters:

• ax (matplotlib.axes.Axes) – The axis to plot on.

• rmsd_r (np.ndarray) – RMSD from reactant (x-axis).

• rmsd_p (np.ndarray) – RMSD from product (y-axis).

• z_data (np.ndarray) – Data for coloring the path (z-axis).

• show_pts (bool) – Whether to show scatter points.

• rbf_smoothing (float) – Smoothing parameter for RBF interpolation.

• cmap (str) – Name of the colormap to use.

• scatter_r (np.ndarray, optional) – Optional separate x-coords for scatter points.

• scatter_p (np.ndarray, optional) – Optional separate y-coords for scatter points.

rgpycrumbs.eon.plt_neb.setup_plot_aesthetics(ax, title, xlabel, ylabel)

Applies labels, limits, and other plot aesthetics.

rgpycrumbs.eon.plt_neb.main(input_dat_pattern, input_path_pattern, con_file, additional_con, plot_type, landscape_mode, landscape_path, rc_mode, plot_structures, rbf_smoothing, rounding, show_pts, plot_mode, surface_type, output_file, start, end, normalize_rc, title, xlabel, ylabel, highlight_last, theme, cmap_profile, cmap_landscape, facecolor, fontsize_base, figsize, fig_height, aspect_ratio, dpi, zoom_ratio, ase_rotation, arrow_head_length, arrow_head_width, arrow_tail_width, spline_method, savgol_window, savgol_order, draw_reactant, draw_saddle, draw_product, cache_file, force_recompute, ira_kmax)

Main entry point for NEB plot script.

rgpycrumbs.eon.plt_neb._setup_theme(theme, cmap_profile, cmap_landscape, fontsize_base, facecolor)

Loads the selected theme and applies any user overrides.

rgpycrumbs.eon.plt_neb._run_dependency_checks(plot_type, rc_mode, additional_con, plot_structures, con_file)

Validates dependencies and option combinations.

rgpycrumbs.eon.plt_neb._determine_figsize(figsize, fig_height, aspect_ratio)

Determines the final figure size based on user inputs.

rgpycrumbs.eon.plt_neb._load_structures(con_file, additional_con, plot_type, rc_mode)

Loads atoms from .con files and calcs RMSD for additional structure.

rgpycrumbs.eon.plt_neb._validate_data_atoms_match(z_data, atoms, dat_file_name)

Checks if data points count matches structure count, exits on mismatch.

rgpycrumbs.eon.plt_neb._get_profile_labels(rc_mode, plot_mode, xlabel, ylabel, atoms_list)

Determines default labels for profile plots.

rgpycrumbs.eon.plt_neb._aggregate_all_paths(all_dat_paths, all_con_paths, y_data_column, ira_instance, cache_file: pathlib.Path | None = None, force_recompute: bool = False, ira_kmax: float = IRA_KMAX_DEFAULT)

Loads and aggregates data from all .dat and .con files for 2D surface using Polars and averaging points within each bin. Optionally, a cache file is used.

Returns:

df_raw

where df_raw is a Polars DataFrame with columns: [r, p, z, step]

rgpycrumbs.eon.plt_neb._plot_landscape(ax, atoms_list, input_dat_pattern, input_path_pattern, con_file, additional_atoms_data, landscape_path, landscape_mode, plot_mode, surface_type, plot_structures, show_pts, rbf_smoothing, rounding, selected_theme, cache_file, force_recompute, ira_kmax, draw_reactant, draw_saddle, draw_product, zoom_ratio, ase_rotation, arrow_head_length, arrow_head_width, arrow_tail_width)

Handles all logic for drawing 2D landscape plots.

rgpycrumbs.eon.plt_neb._plot_profile(ax, fig, input_dat_pattern, atoms_list, additional_atoms_data, rc_mode, plot_mode, plot_structures, start, end, normalize_rc, highlight_last, selected_theme, spline_method, savgol_window, savgol_order, draw_reactant, draw_saddle, draw_product, zoom_ratio, ase_rotation, arrow_head_length, arrow_head_width, arrow_tail_width, cache_file=None, force_recompute=False)

Handles all logic for drawing 1D profile plots.