Reaction Paths and NEB#
The nvalchemi.dynamics.mep subpackage provides tools for computing
minimum-energy paths (MEPs), and therefore transition-state estimates, between
reactant and product structures.
Each path is represented as an ordered band of structures called images, and
many paths can be optimized together: every image is one graph in a Batch,
and the images of a path share a group_layout group.
The subpackage currently provides batched nudged elastic band (NEB) methods. There are two ways to run NEB:
The
NEBstrategy: a declarative, serializable wrapper that builds a correctly-ordered engine for you. Use this for standard regular or climbing-image NEB runs.An optimizer (or
FusedStage) with the NEB hooks attached directly: for full control over hook ordering, custom convergence criteria, or non-standard staging.
Building the initial path#
Whether you use the high-level NEB strategy or the low-level FusedStage
approach, the input is the same: a Batch of images with group_layout
set, one group per path, at least three images each, matching atoms/cell
across images (see validate_paths()). You
can build this batch yourself, or use the two basic interpolation utilities
below to go from just reactant/product endpoints:
import torch
from nvalchemi.dynamics.mep import (
IDPPModel,
NEB,
interpolate_paths,
prepare_idpp_targets,
)
paths = interpolate_paths(initial, final, num_images=7) # linear interpolation
# optionally remove rigid endpoint displacement before interpolation
paths = interpolate_paths(
initial,
final,
num_images=7,
remove_translation_and_rotation=True,
fit_mask=initial.atomic_numbers > 1, # fit on corresponding heavy atoms
)
paths.velocities = torch.zeros_like(paths.positions) # dropped by interpolation
# optional: refine with IDPP before switching to the real model
idpp_paths = paths.clone()
prepare_idpp_targets(idpp_paths)
idpp_paths = NEB(model=IDPPModel(), fmax=0.1, n_steps=200).run(idpp_paths)
paths.positions.copy_(idpp_paths.positions)
IDPP runs on a separate clone. Copy only its relaxed positions back so model NEB starts without IDPP status, neighbor data, or optimizer state.
interpolate_paths linearly interpolates positions between index-matched
endpoint graphs, retaining only structural/model-input fields. Neighbor data,
outputs, stage counters, and custom fields are dropped, so reattach velocities
and any custom model inputs before optimizing. Set
remove_translation_and_rotation=True to align each final structure to its
paired initial structure first. For periodic paths, this reconciles
minimum-image positions and removes translation without rotating the cell. An
optional Boolean fit_mask, following the flattened node layout of initial,
restricts the corresponding atom pairs used to fit each transform without
restricting which atoms are transformed. Every path must select at least one
atom; for example, initial.atomic_numbers > 1 fits molecular paths using only
heavy atoms.
For alignment without interpolation, call
align_batch_positions() directly on two
Batches with matching atom order (optionally passing fit_mask):
from nvalchemi.dynamics.mep import align_batch_positions
alignment = align_batch_positions(
initial.positions,
final.positions,
initial.batch_idx,
initial.num_nodes_per_graph,
)
aligned_final = alignment.positions
The returned PositionAlignment also holds
the rotation and translation for each graph. Pass cell and pbc for periodic
graphs; the function then uses minimum-image positions and translation without
rotating the cell.
For alignment at each NEB step, implement a custom hook using
align_batch_positions().
prepare_idpp_targets() +
IDPPModel relax the path against target
pairwise distances (IDPP,
Smidstrup et al. 2014) to avoid poor
linear-interpolation guesses where atoms pass through each other.
IDPPModel is just a BaseModelMixin like any other, so running it through
NEB (as above) is the normal way to do this refinement. It is a regular
NEB optimization whose “physical” model happens to be the analytic IDPP
potential instead of your real MLIP. See
examples/advanced/11_batched_neb.py for the full IDPP-then-MLIP workflow.
The high-level NEB strategy#
from nvalchemi.dynamics.mep import NEB, ClimbingImageConfig
neb = NEB(
model=model,
spring=0.1, # constant spring force (eV/Å); or a SpringConfig
method="improved_tangent", # tangent + spring-force formulation
climbing=ClimbingImageConfig(mode="after_regular", regular_fmax=0.1),
fmax=0.05, # force convergence threshold
n_steps=500,
diagnostics_log_path="neb_diagnostics.csv", # per-path fmax/barrier/length CSV
)
relaxed_paths = neb.run(paths)
Key fields:
Field |
Default |
Description |
|---|---|---|
|
|
Constant spring force, or a custom |
|
|
Named method, custom Warp |
|
|
|
|
|
|
|
|
Arguments forwarded to each optimizer stage; unspecified parameters use NEB-tuned defaults for |
|
|
Force threshold for the final (or only) stage |
|
|
Limit on the total number of optimization steps; |
|
|
Custom |
|
|
Custom |
|
|
|
|
|
Per-path, image-local atom indices held fixed in every image |
|
|
CSV path for per-path |
|
|
Step frequency for computing and logging diagnostics |
|
|
Override |
|
|
Compile the fused NEB step with |
|
|
Keyword arguments forwarded to |
optimizer is fixed after construction. To select a different optimizer class,
construct a new NEB strategy. optimizer_kwargs remains an editable dictionary.
optimizer_kwargs is forwarded to every internal optimizer stage, for
settings such as dt or maxstep. NEB sets model, hooks, by_group,
convergence_hook, and n_steps itself for each stage, so passing any of
them in optimizer_kwargs raises ValueError. Use the corresponding NEB
fields instead. NEB rejects a non-None engine or nonempty engine_kwargs.
Configure its optimizer stages through optimizer and optimizer_kwargs.
optimizer accepts an optimizer class derived from
BaseDynamics that supports fixed-cell,
group-aware updates through FusedStage.
Each path is one update unit, and pre_update / post_update consume the
projected NEB forces in batch.forces. Regular and climbing stages use
separate optimizer instances and history.
FIRE2 is the default. Its NEB-tuned parameters are applied to
optimizer_kwargs during validation, with explicit values taking precedence.
Other optimizer classes use their own defaults.
Inspect neb.optimizer_kwargs to see the arguments forwarded to the optimizer.
NEBForceHook always publishes neb_fixed_node_mask, a Boolean node mask
marking fixed endpoints and any fixed_atom_indices. It zeroes the physical
and effective forces at those nodes. When endpoint_mode="fixed" or a nonempty
fixed_atom_indices mapping is provided, NEB also appends a
FreezeAtomsHook to clear velocities and
restore positions across optimizer stages.
ClimbingImageConfig.mode="after_regular" runs regular NEB to
regular_fmax (or fmax if unset) before promoting the highest-energy
interior image to a climbing image and continuing to fmax;
mode="immediate" climbs from the first step.
selection="fixed" locks in the initial climbing image;
selection="dynamic" reselects it every evaluation.
max_regular_steps and max_climbing_steps optionally limit each path’s steps
in the respective stage. A path advances when its stage limit is reached even
if it has not met the force threshold. max_regular_steps is only valid with
mode="after_regular".
neb.run(paths) builds a fresh engine via neb.build_engine() and calls
engine.run(paths). NEB is a Pydantic model, so it also serializes with
to_spec_dict() / from_spec_dict() alongside other
DynamicsStrategy subclasses used for
training and fine-tuning specs.
NEB appends build_hooks() after its neighbor and path hooks. Subclasses can override
build_hooks() to customize these additional hooks without replacing NEB’s
engine construction.
NEB methods#
method="improved_tangent" (the default and only named method)
implements the Henkelman–Jónsson improved tangent
(J. Chem. Phys. 113, 9978 (2000)).
It corresponds to the default NEBMethod() without overrides.
For an interior image with neighbor energies \(E^-, E, E^+\) and
displacement vectors \(\mathbf{d}^\pm\) to the adjacent images:
Tangent: \(\vec{\tau} = w^+\mathbf{d}^+ + w^-\mathbf{d}^-\) (then normalized), where the weights \(w^\pm\) favor the higher-energy neighbor on monotonic sections of the path and blend both links at an extremum.
Effective (regular) force:
\[ \mathbf{F}^{\mathrm{NEB}} = \mathbf{F} - (\mathbf{F}\cdot\hat{\tau})\hat{\tau} {}+ F^{\mathrm{s},\parallel}\hat{\tau} \]That is the physical force projected perpendicular to the tangent, plus the parallel spring contribution
\[ F^{\mathrm{s},\parallel} = k^+\lVert\mathbf{d}^+\rVert - k^-\lVert\mathbf{d}^-\rVert. \]Climbing-image force:
\[ \mathbf{F}^{\mathrm{climb}} = \mathbf{F} - 2(\mathbf{F}\cdot\hat{\tau})\hat{\tau} \]The spring force is dropped and the parallel physical-force component is reversed, driving the image uphill along the path toward the saddle point.
To use a different formulation, pass a custom
NEBMethod to method. It bundles three
warp.func-decorated device functions, any of which can be overridden
independently (unset ones fall back to the improved-tangent equations above):
Field |
Inputs available |
Returns |
|---|---|---|
|
|
|
|
One of the two ordered signatures below |
effective force vector for a regular (non-climbing) interior image |
|
|
effective force vector for the climbing image |
The effective_force_fn parameter names and order must match one of these
signatures exactly; they select the corresponding Warp kernel:
Stored tangent:
(physical_force, tangent, force_dot_tangent, k_plus, k_minus,
norm_d_plus, norm_d_minus, energy_prev, energy_curr, energy_next,
path_energy_ref, path_energy_max)
Gram statistics:
(physical_force, tangent, d_plus, d_minus, force_dot_tangent,
dplus_dot_tangent, dminus_dot_tangent, norm_d_plus, norm_d_minus,
dplus_dot_dminus, force_dot_dplus, force_dot_dminus, force_squared_norm,
k_plus, k_minus, energy_prev, energy_curr, energy_next,
path_energy_ref, path_energy_max)
physical_force, tangent, d_plus, and d_minus are vectors for the
current atom. The dot products and link norms are scalars reduced over the
current image; k_plus and k_minus are the adjacent link spring constants.
energy_prev, energy_curr, and energy_next are image energies, while
path_energy_ref and path_energy_max are path-wide energy statistics.
import warp as wp
from nvalchemi.dynamics.mep import NEB, NEBMethod
@wp.func
def central_tangent_weights(energy_prev: float, energy_curr: float, energy_next: float):
return 1.0, 1.0 # plain central-difference tangent instead of improved-tangent weighting
neb = NEB(model=model, method=NEBMethod(tangent_weights_fn=central_tangent_weights), fmax=0.05)
Use the Gram-statistics signature when the force needs more than the tangent
projection, for example the link vectors d_plus and d_minus and their dot
products. The doubly nudged elastic band (DNEB,
Trygubenko & Wales 2004) uses them to add
a perpendicular spring correction. examples/advanced/11_batched_neb.py uses
the improved-tangent method by default; set method = "dneb" there to run the
dneb_effective_force equation from _dneb_method.py.
Custom NEBMethod objects round-trip through to_spec_dict() and
from_spec_dict(). The spec stores a stable method key with the kernel kind and
dotted import paths for all three Warp equations. Restoring the spec imports
those equations and rebuilds the NEBMethod; each equation must therefore be
defined at module level in an importable module. The same key selects the kernel
for compilation and CUDA graph capture.
If you prefer to implement an NEB method entirely in PyTorch, pass a callable
matching TorchNEBMethod as method. It
receives the current batch, link spring constants, path energy statistics, and
prepared minimum-image geometry. It returns effective forces for every atom
and one minimum-image length per forward image link. Importable classes whose
constructor arguments are stored as attributes also round-trip through
to_spec_dict() and from_spec_dict(). Other callables, such as lambdas or
locally defined functions, still work with NEB.run(), but to_spec_dict()
raises ValueError for them.
from nvalchemi.dynamics.mep import NEB
from nvalchemi.dynamics.mep._geometry import minimum_image_displacement
class MyTorchNEBMethod:
def __init__(self, scale: float = 1.0) -> None:
self.scale = scale # stored as an attribute, so the spec round-trips
def __call__(self, batch, *, spring_constants, path_energy_ref, path_energy_max, mic):
forces = batch.physical_forces.clone() # don't modify the batch in place
# ... apply your equations to regular, climbing, and endpoint images,
# using batch.positions, batch.energy, and batch.force_mode
# use minimum_image_displacement(..., prepared=mic) for link vectors
link_lengths = ... # one minimum-image length per forward link
return forces, link_lengths
neb = NEB(model=model, method=MyTorchNEBMethod(scale=0.5), fmax=0.05)
spring follows the same pattern: pass a plain float for a constant spring
constant, or a custom SpringConfig
(resolve(context) returning one spring constant per link) for e.g.
energy-dependent springs. Custom spring policies round-trip through
NEB.to_spec_dict() when their class is importable and their constructor
arguments are stored as attributes (or they provide a checkpoint_spec()
constructor spec). Other custom spring policies can be used at runtime.
Numeric springs and ConstantSpringConfig
retain their existing spec representation.
Building NEB manually with hooks#
NEB is a factory around a fixed hook order. Assembling it by hand gives you
control over convergence criteria, staging, or optimizer choice beyond what
the strategy exposes. For regular (non-climbing) NEB there is only one stage,
so any BaseDynamics subclass that
accepts by_group=True and a hooks list is enough on its own; no
FusedStage wrapper is required. FusedStage is
only needed once you have more than one stage, e.g. climbing-image NEB (see
below). The example uses FIRE2.
from nvalchemi.dynamics import ConvergenceHook, DynamicsStage
from nvalchemi.dynamics.hooks import FreezeAtomsHook, LoggingHook
from nvalchemi.dynamics.optimizers.fire2 import FIRE2
from nvalchemi.dynamics.mep.hooks import (
ClimbingImageSelectionHook,
NEBForceHook,
PathDiagnosticsHook,
PathEnergyStatsHook,
)
energy_stats = PathEnergyStatsHook()
force_hook = NEBForceHook(
energy_stats_hook=energy_stats,
spring=0.1,
method="improved_tangent",
endpoint_mode="fixed",
)
freeze = FreezeAtomsHook(mask_key="neb_fixed_node_mask")
diagnostics = PathDiagnosticsHook(energy_stats_hook=energy_stats)
logger = LoggingHook(
stage=DynamicsStage.AFTER_STEP,
backend="csv",
log_path="neb_diagnostics.csv",
by_group=True,
custom_scalars={
"fmax": lambda _ctx: diagnostics.get_diagnostics().fmax,
"energy_barrier": lambda _ctx: diagnostics.get_diagnostics().energy_barrier,
"path_length": lambda _ctx: diagnostics.get_diagnostics().path_length,
},
)
optimizer = FIRE2(
model=model,
dt=0.01,
n_steps=500,
by_group=True,
convergence_hook=ConvergenceHook.from_fmax(threshold=0.05, by_group=True),
hooks=[
*model.make_neighbor_hooks(),
energy_stats,
force_hook,
freeze,
diagnostics,
logger,
],
)
relaxed_paths = optimizer.run(paths)
ClimbingImageSelectionHook, NEBForceHook, and PathDiagnosticsHook must
receive the same PathEnergyStatsHook instance registered in the hooks list.
That hook refreshes its statistics first at AFTER_COMPUTE, before any of the
three consumers reads them. NEB.build_engine() wires this shared instance and
order automatically.
The NEB path hooks, in the order they must be registered:
PathEnergyStatsHook: always first. Computes per-path endpoint reference energy and the highest-energy interior image; the selection, force, and diagnostics hooks read its results viaget_stats().ClimbingImageSelectionHook(optional): flips the selected image’sforce_modeto climbing beforeNEBForceHookruns. Needed only for climbing-image NEB.NEBForceHook: the core hook. It computes the local tangent and replacesbatch.forceswith the spring + perpendicular-physical-force NEB update, saving the raw model force tobatch.physical_forces. Whenendpoint_mode="fixed"orfixed_atom_indicesis set, it populatesneb_fixed_node_mask(present on every batch) with the constrained atoms and zeroes their forces. The mask alone does not keep their positions fixed during optimizer updates.FreezeAtomsHook(optional, needed whenever step 3 produces a fixed-atom mask): a general-purpose, non-NEB-specific hook (nvalchemi.dynamics.hooks) that zeroes forces and velocities and restores positions for masked atoms across every integrator stage. Passmask_key="neb_fixed_node_mask"to use the mask fromNEBForceHookinstead of the defaultatom_categories-based freezing.PathDiagnosticsHook(optional): exposes per-pathfmax,energy_barrier,highest_interior_image_idx, andpath_lengthviaget_diagnostics(). Accepts afrequencyto throttle recomputation on long runs.LoggingHook(optional, pairs with step 5): readsdiagnostics.get_diagnostics()throughcustom_scalarscallbacks and writes per-path rows to CSV. This is howNEBwiresdiagnostics_log_path: both this hook andPathDiagnosticsHookshould share the samefrequency/diagnostics_frequencyso the CSV rows line up with the diagnostics they log.
The manual single-stage example logs at AFTER_STEP. The NEB strategy
logs at ON_GRADUATE so scheduled rows see status after stage-budget
transitions. Both retain the configured frequency. Finishing between logging
intervals does not produce an extra row.
All of these hooks require the enclosing workflow to be constructed with
by_group=True (each group_layout group is one path) and raise
ValueError at registration otherwise. Convergence uses the standard
ConvergenceHook, evaluated per path with
by_group=True; there is no NEB-specific convergence criterion.
Because you assemble the hooks list yourself, you are not limited to the
built-in hooks above: any of them can be replaced with a custom
implementation (e.g. a different PathDiagnosticsHook-like hook that logs
extra scalars, or your own freezing hook instead of FreezeAtomsHook), and
you can insert additional hooks anywhere in the stack, as long as you
preserve the dependency order (PathEnergyStatsHook before anything that
calls get_stats(), NEBForceHook before anything that reads
neb_fixed_node_mask or the NEB force decomposition). See the
Hooks guide for the hook protocol used to write one.
Climbing-image NEB needs two stages (regular, then climbing) and is
therefore built on FusedStage, not a single optimizer. Rather than
duplicating that construction here, read NEB.build_engine() in
nvalchemi/dynamics/mep/neb.py. It is the reference
implementation for a two-substage, status-gated FusedStage with
ClimbingImageSelectionHook(status_code=...) scoped to the climbing stage.
With mode="after_regular" it creates the climbing optimizer with
reprime_on_entry=True, so a path entering
the climbing stage skips one optimizer update while the shared model evaluation
and the climbing sub-stage’s AFTER_COMPUTE hooks refresh its forces. If you
build the engine yourself, register the path hooks on the FusedStage and
scope stage-specific ones with status_code, as NEB.build_engine() does. At
AFTER_COMPUTE, sub-stage hooks run before fused-stage hooks, so a sub-stage
hook would read stale PathEnergyStatsHook results.
Periodic paths#
Interpolation, IDPP, and NEB automatically apply the minimum-image convention
(MIC): each displacement uses the nearest periodic copy of an atom. This works
with orthogonal or skewed cells and with periodicity in only some directions.
Each pbc entry enables the corresponding row of cell (a lattice vector),
which need not align with the Cartesian x, y, or z axis. The enabled cell
vectors must be linearly independent. Nonperiodic paths are left unchanged.
Wrapped endpoints do not record whether a path is intended to cross one or more whole cells. For such winding paths, provide appropriately unwrapped images.
See also#
Example:
examples/advanced/11_batched_neb.pyruns a full climbing-image NEB workflow (IDPP initialization, AIMNet2-rxn, diagnostics CSV, and a comparison against DFT reference paths) on eight batched reactions.Optimization: Optimization and Integrators covers the
FIRE2optimizer driving each NEB image.Hooks: The Hooks guide covers the hook protocol and
ConvergenceHook.Overview: The Dynamics overview describes the shared execution loop and
FusedStagecomposition.