Reaction Paths and NEB#

  • User guide: Reaction Paths and NEB — task-oriented walkthrough covering the high-level NEB strategy and the low-level FusedStage + hooks recipe.

The nvalchemi.dynamics.mep package provides tools for calculating minimum energy paths, including path construction, nudged elastic band (NEB) optimization, and hooks for monitoring and controlling the calculation.

Strategy#

NEB

Run regular or climbing-image nudged elastic band optimization.

ClimbingImageConfig

Configure climbing-image NEB activation.

Path construction#

interpolate_paths

Interpolate paired endpoint batches into grouped reaction paths.

IDPPModel

Evaluate the image-dependent pair potential for reaction-path images.

prepare_idpp_targets

Build full pairwise IDPP target distances for a batch of reaction paths.

validate_paths

Read-only validation of grouped image paths for path-related calculations.

Position alignment#

align_batch_positions

Align each mobile structure in a batch to its paired reference.

class nvalchemi.dynamics.mep.PositionAlignment(positions, rotation, translation)[source]#

Result of aligning one or more sets of positions to references.

Parameters:
positions#

Aligned mobile positions. For non-periodic systems, these are obtained as mobile_positions @ rotation.T + translation. For periodic systems, minimum-image positions are translated and rotation is simply identity. Shape (n_atoms, 3).

Type:

Tensor

rotation#

Proper rotation applied to row-vector positions as positions @ rotation.T, shape (3, 3) or (num_graphs, 3, 3) for a batch. The same transform can be applied to vector-valued state such as velocities.

Type:

Tensor

translation#

Common translation applied after rotation, or after periodic images have been reconciled, shape (3,) or (num_graphs, 3) for a batch.

Type:

Tensor

Spring and method configuration#

NEBMethod

Configure the device equations used to construct NEB forces.

TorchNEBMethod

Compute effective forces for a batch of paths using Torch operations.

SpringConfig

Resolve spring constants for the links in one or more NEB paths.

ConstantSpringConfig

Use one constant spring value for every adjacent image pair.

SpringContext

Read-only inputs available to spring-constant policies.

Hooks#

PathEnergyStatsHook

Compute reusable energy statistics for each path after model evaluation.

PathEnergyStats

Preallocated energy statistics for a grouped path batch.

PathDiagnosticsHook

Compute and cache one diagnostics record per reaction path.

PathDiagnostics

Preallocated diagnostics for a grouped reaction-path batch.

NEBForceHook

Configure optimizer-facing forces for nudged elastic band dynamics.

ClimbingImageSelectionHook

Select the highest-energy interior image in each NEB path.

Fixing atoms during NEB (endpoint_mode="fixed" or fixed_atom_indices) is enforced by the general-purpose FreezeAtomsHook, documented in Dynamics Hooks — Stages & Usage.