plt-neb

Visualizing NEB Paths and Landscapes

This tool generates both 1D NEB profiles and 2D NEB landscapes from eOn calculations. It supports energy or curvature plots, structure strips, OCI/MMF refinement-sample overlays, and evolution overlays from saved optimization history.

Method

The default grad_matern surface method uses gradient-enhanced interpolation on 2D RMSD projections. This approach is described in:

• R. Goswami, “Two-dimensional RMSD projections for reaction path visualization and validation,” MethodsX, p. 103851, Mar. 2026, doi: 10.1016/j.mex.2026.103851.

The method projects high-dimensional structures onto 2D RMSD coordinates (reactant distance r vs product distance p), then fits a smooth surface using energy values and their gradients for enhanced accuracy.

Usage

To plot an energy profile:

rgpycrumbs eon plt-neb --plot-type profile -o neb_profile.pdf

To plot a 2D landscape:

rgpycrumbs eon plt-neb --plot-type landscape -o neb_landscape.pdf

To show the plot interactively without saving:

python -m rgpycrumbs.cli eon plt-neb --plot-type profile

Library API

from rgpycrumbs.eon import plot_neb, plot

# Job files / patterns (same as CLI)
plot_neb(
    plot_type="landscape",
    con_file="neb.con",
    surface_type="grad_imq",
    plot_structures="crit_points",
    output_file="neb_2d.pdf",
    config="plot.toml",  # optional TOML
)

# Live pyeonclient NEB after compute()
plot(neb, plot_type="profile", output_file="1d.pdf")

# Stamped ConFrame list (e.g. neb.path_frames())
plot(frames, kind="neb", plot_type="profile", output_file="1d.pdf")

Library calls enable RGPYCRUMBS_AUTO_DEPS automatically so jax (for grad_imq surfaces) and xyzrender (structure strips) resolve through ensure_import without declaring them in the host environment.

Prefer TOML for suite options

Use --config plot.toml for shared style, strip rendering, and surface-fit settings (auto_thin, max_surface_points). Those surface-fit knobs are TOML-only (default auto_thin = false). See eOn plot TOML config.

rgpycrumbs eon plt-neb --config plot.toml

Key Options

Option	Default	Description
--config	(none)	TOML plot config ([shared] / [neb])
--plot-type	profile	profile, landscape, or evolution
--surface-type	grad_matern	Surface fitting method for landscapes
--plot-mode	energy	Plot energy or curvature
--energy-unit	eV	Presentation unit: eV, kcal/mol, kJ/mol
--plot-structures	none	Structure strip: none, all, crit_points
--strip-renderer	xyzrender	Renderer backend for structure strips
--xyzrender-config	paton	xyzrender preset for strip rendering
--rotation	auto	Shared viewing rotation control
--perspective-tilt	0.0	Small off-axis tilt to reveal occluded atoms
--ira-kmax	14.0	IRA kmax for RMSD calculation
--mmf-peaks	Off	Overlay OCI-NEB/RONEB refinement samples
--show-evolution	Off	Fade earlier optimization bands behind final path

Dense-fit keys (auto_thin, max_surface_points) are not CLI flags; set them in the TOML file only.

Troubleshooting

“No .dat files found” error

Problem: The script reports no input files matching the pattern.

Solution:

1. Verify the input pattern matches your files:

   ls neb_*.dat
   

2. Use the --input-dat-pattern flag to specify a custom pattern:

   python -m rgpycrumbs.cli eon plt-neb --input-dat-pattern "path/to/neb_*.dat"
   

“Index out of range” error

Problem: The --start or --end indices are outside the available data range.

Solution:

1. Check available iterations:

   ls -1 neb_*.dat | wc -l
   

2. Adjust indices to be within range (0 to N-1 where N is the number of files)

Plot appears empty

Problem: The plot window opens but shows no data.

Solution:

1. Verify the .dat files contain valid energy data (column 2)

2. Check that the energy values are not all identical

3. Try with a smaller range first: --start 0 --end 5

Force-corrected interpolation fails

Problem: Hermite spline interpolation produces warnings or errors.

Solution:

1. Ensure you have at least 3 data points

2. Check that force data (column 4 in .dat) is present

3. The script falls back to raw lines if spline fails - this is expected behavior

“Surface prediction produced no finite values for contourf”

Problem: Gradient surface fit (often grad_imq) returns a non-finite grid on a dense observation cloud (many NEB or min force evaluations).

Solution: In plot TOML set auto_thin = true (and optionally max_surface_points = 64) under [shared] or [neb], then re-run with --config. Default remains off so behaviour is opt-in. See eOn plot TOML config.

OCI-NEB/RONEB Options

MMF Peak Overlay

When eOn produces peak{NN}_pos.con files (from OCI-NEB mode-following), overlay them on the landscape:

rgpycrumbs eon plt-neb --plot-type landscape --mmf-peaks

Peaks are auto-detected in the current directory. Use --peak-dir to specify an explicit path:

rgpycrumbs eon plt-neb --plot-type landscape --mmf-peaks --peak-dir path/to/peaks/

If the same directory also contains a metadata-rich climb / climb.con movie from the MMF refinement, the sampled dimer phase is overlaid too, with distinct inner markers on top of the shared dark point cloud.

Band Evolution

Show how the NEB band evolves across optimization iterations (requires write_movies=true data):

rgpycrumbs eon plt-neb --plot-type landscape --show-evolution

Older bands appear with lower opacity; the final band is most visible.

Structure Rendering

Rendering Backends

Four backends available via --strip-renderer:

Backend	Install	Style
xyzrender (default)	pip install xyzrender	Ball-and-stick, paton preset
ase	Built-in	Space-filling spheres
solvis	pip install solvis-tools	PyVista ball-and-stick, transparent bg
ovito	pip install ovito	OVITO off-screen

Viewing Angle

--rotation auto (default) lets xyzrender auto-orient each structure. Use an ASE-style string such as --rotation "0x,90y,0z" to force the same manual orientation across all backends.

Perspective Tilt

--perspective-tilt 8 applies a small Rodrigues off-axis rotation (8 degrees) to reveal atoms hidden by orthographic projection overlap. Useful for ring structures where H atoms hide behind carbons.

Profile Structure Strips

Profile plots also support structure strips. With --plot-structures crit_points the reactant, saddle, and product images are rendered below the profile instead of being inset on top of the curve:

rgpycrumbs eon plt-neb \
  --plot-type profile \
  --plot-structures crit_points \
  --strip-renderer xyzrender \
  --energy-unit kJ/mol \
  -o neb_profile_strip.pdf

See Also

• Plotting saddle search trajectories for dimer/single-ended visualization

• Plotting minimization trajectories for minimization visualization

API Reference

For developer details and source code see rgpycrumbs.eon.plt_neb.