eOn NEB API Reference

Module: chemparseplot.parse.eon.neb

load_structures_and_calculate_additional_rmsd(con_file, additional_con, ira_kmax, sp_file=None)

Loads the main NEB trajectory and calculates RMSD for additional comparison structures.

Parameters

Parameter	Type	Default	Description
con_file	Path		Path to main trajectory CON file
additional_con	list[tuple[Path, str]]		List of (path, label) pairs for extra structures
ira_kmax	float		kmax factor for IRA alignment
sp_file	Path or None	None	Path to explicit saddle point CON file

Returns

NebOverlayBundle with fields:

Field	Type	Description
atoms_list	list[Atoms]	ASE Atoms from main trajectory
additional_structures	list[NebOverlayStructure]	Typed overlay records with atoms, r, p, and label
saddle_point	NebOverlayStructure or None	Explicit saddle-point overlay record

Notes

• Uses IRA (Iterative Rotations and Assignments) for RMSD

• Raises ImportError if ira_mod is not available, because landscape coordinates without IRA are chemically misleading for permutationally symmetric systems

• RMSD computed relative to first frame (reactant) and last frame (product)

• Empty labels default to the file stem

Overlay Record

NebOverlayStructure is a frozen typed record with four fields:

• atoms: ASE structure to render

• r: RMSD to the reactant

• p: RMSD to the product

• label: legend / annotation label

aggregate_neb_landscape_data(all_dat_paths, all_con_paths, y_data_column, ira_instance, *, cache_file=None, force_recompute=False, ira_kmax=1.8, augment_dat=None, augment_con=None, ref_atoms=None, prod_atoms=None)

Aggregates data from multiple NEB optimization steps for 2D landscape visualization.

Parameters

Parameter	Type	Default	Description
all_dat_paths	list[Path]		Sorted list of DAT file paths
all_con_paths	list[Path]		Sorted list of CON file paths (must match DAT order)
y_data_column	int		Column index in DAT file for energy/eigenvalue
ira_instance	object or None		IRA instance. Landscape coordinate generation requires a real IRA backend.
cache_file	Path or None	None	Parquet file for caching results
force_recompute	bool	False	Bypass cache and recompute
ira_kmax	float	1.8	Factor on the IRA basis cutoff
augment_dat	str or None	None	Glob pattern for augmentation DAT files
augment_con	str or None	None	Glob pattern for augmentation CON files
ref_atoms	Atoms or None	None	Reference reactant for augmentation projection
prod_atoms	Atoms or None	None	Reference product for augmentation projection

Returns

pl.DataFrame with columns [r, p, grad_r, grad_p, z, step]

Raises

Exception	Condition
RuntimeError	No data could be aggregated from any step

Notes

• DAT files contain columns: image index, energy, eigenvalue, parallel force, perpendicular force

• Column index 1 selects energy, column index 2 selects eigenvalue

• Cache validation checks for p and grad_r columns (rejects outdated caches)

• Augmentation paths receive step-1= to distinguish from primary data

• Mismatched DAT/CON counts are truncated to the shorter list with a warning

load_augmenting_neb_data(dat_pattern, con_pattern, ref_atoms, prod_atoms, y_data_column, ira_kmax)

Loads external NEB paths to augment the landscape surface fit.

Parameters

Parameter	Type	Default	Description
dat_pattern	str		Glob pattern for DAT files
con_pattern	str		Glob pattern for CON files
ref_atoms	Atoms		Reactant atoms for RMSD reference
prod_atoms	Atoms		Product atoms for RMSD reference
y_data_column	int		Column index for energy in DAT files
ira_kmax	float		kmax factor for IRA

Returns

pl.DataFrame – Same schema as aggregate_neb_landscape_data(), or empty DataFrame if no files match.

Notes

• Forces RMSD projection onto the main path’s reactant/product coordinate frame

• All augmented data gets step-1=

compute_profile_rmsd(atoms_list, *, cache_file, force_recompute, ira_kmax)

Computes RMSD from reactant for a 1D energy profile.

Parameters

Parameter	Type	Default	Description
atoms_list	list[Atoms]		NEB trajectory as ASE Atoms
cache_file	Path or None		Parquet cache path
force_recompute	bool		Bypass cache
ira_kmax	float		kmax factor for IRA

Returns

pl.DataFrame with column [r] (RMSD from first frame)

Notes

• Cache validation rejects DataFrames that contain a p column (landscape data)

• Cache validation checks row count matches len(atoms_list)

estimate_rbf_smoothing(df)

Estimates a smoothing parameter for RBF surface interpolation.

Parameters

Parameter	Type	Description
df	pl.DataFrame	Landscape DataFrame with r, p, step columns

Returns

float – Median Euclidean distance between sequential images within each step. Returns 0.0 if the median is None or zero.

load_or_compute_data(cache_file, *, force_recompute, validation_check, computation_callback, context_name)

Generic caching helper. Loads from parquet or computes via callback.

Parameters

Parameter	Type	Description
cache_file	Path or None	Parquet path (None disables caching)
force_recompute	bool	Skip cache and compute
validation_check	Callable[[pl.DataFrame], None]	Raises on invalid cache
computation_callback	Callable[[], pl.DataFrame]	Called when cache misses
context_name	str	Label for log messages

Returns

pl.DataFrame

DataFrame Schema

All landscape DataFrames follow this schema:

Column	Polars Type	Unit	Description
r	Float64	Angstrom	RMSD from reactant reference
p	Float64	Angstrom	RMSD from product reference
grad_r	Float64	(projected)	Synthetic gradient in R direction
grad_p	Float64	(projected)	Synthetic gradient in P direction
z	Float64	eV or unitless	Energy or eigenvalue
step	Int64		Optimization step index (-1 = augmented)

Module: chemparseplot.parse.eon.dimer_trajectory

Parses dimer/saddle search trajectory output from eOn (write_movies=true).

DimerTrajectoryData

Dataclass containing the full trajectory:

Field	Type	Description
atoms_list	list[Atoms]	Per-iteration structures from movie file
dat_df	pl.DataFrame	Metrics reconstructed from per-frame CON metadata when available, otherwise from climb.dat (iteration, stepsize, deltae, convergence, eigenvalue, torque, angle, rotations)
initial_atoms	Atoms	Starting structure (reactant.con or pos.con)
saddle_atoms	Atoms or None	Saddle point (saddle.con)
mode_vector	np.ndarray or None	Eigenvector (mode.dat)

load_dimer_trajectory(job_dir) -> DimerTrajectoryData

Loads the complete trajectory from an eOn saddle search job directory. Expects a climb movie file; the parser prefers per-frame CON metadata and falls back to climb.dat only when the embedded metadata is incomplete.

parse_climb_dat(path) -> pl.DataFrame

Reads the climb.dat TSV file into a DataFrame. This is a compatibility utility; metadata-native callers should prefer load_dimer_trajectory(...).

parse_climb_con(path) -> list[Atoms]

Reads the concatenated climb movie file via ASE. This is a lower-level compatibility helper; metadata-native callers should prefer load_dimer_trajectory(...).

Module: chemparseplot.parse.eon.min_trajectory

Parses minimization trajectory output from eOn (write_movies=true).

MinTrajectoryData

Dataclass containing the full trajectory:

Field	Type	Description
atoms_list	list[Atoms]	Per-iteration structures from movie file
dat_df	pl.DataFrame	Metrics reconstructed from per-frame CON metadata when available, otherwise from minimization.dat (or <prefix>.dat) with columns iteration, stepsize, convergence, energy
initial_atoms	Atoms	Starting structure (first frame)
final_atoms	Atoms	Final minimized structure (prefers <prefix>.con, then legacy min.con, otherwise last movie frame)

load_min_trajectory(job_dir, prefix”minimization”) -> MinTrajectoryData=

Loads the complete trajectory from an eOn minimization job directory. The movie file is required; the parser prefers per-frame CON metadata and falls back to the sidecar .dat table only when the embedded metadata is incomplete.

parse_min_dat(path) -> pl.DataFrame

Reads the minimization TSV data file. This remains available as a compatibility utility; metadata-native callers should prefer load_min_trajectory(...).

Module: chemparseplot.parse.neb_utils (updated)

calculate_landscape_coords(atoms_list, ira_instance, ira_kmax, ref_a=None, ref_b=None)

Calculates RMSD-A and RMSD-B coordinates for landscape plots.

Notes

• This function now requires a non-None IRA instance

• If ira_instance is missing it raises ImportError instead of silently falling back to order-dependent alignment

• ref_a and ref_b allow single-ended methods to reuse the same coordinate machinery with explicit endpoint references

Now accepts explicit ref_a and ref_b reference structures. Defaults to first/last atoms for backward compatibility. For single-ended methods, pass the initial and final structures explicitly.

See Also

• How-to: Parse eOn NEB Calculations

• Plotting API Reference

• NEB Parsing Design