nvalchemi-mep

nvalchemi Minimum-Energy Paths (MEP)

Overview

nvalchemi.dynamics.mep provides tools for computing minimum-energy paths between reactant and product structures. A path is an ordered band of structures called images. Many paths are optimized together in one Batch: every image is one graph, and the images of a path share a group_layout group. NEB is currently the only path-optimization method.

Details (force equations, method signatures, a full manual-hooks example) live in docs/userguide/dynamics_mep.md. The end-to-end workflow (IDPP, climbing-image NEB with AIMNet2-rxn, diagnostics CSV) is examples/advanced/11_batched_neb.py. Upstream skills: nvalchemi-data-structures (Batch, group_layout), nvalchemi-dynamics-api (FIRE2, FusedStage), and nvalchemi-dynamics-hooks (hook stages and ordering).

from nvalchemi.dynamics.mep import (
    NEB,
    ClimbingImageConfig,
    IDPPModel,
    interpolate_paths,
    prepare_idpp_targets,
    validate_paths,
)

Build the initial paths

Endpoints are two Batches: graph i of initial and graph i of final define path i. Atoms must match by index (same atomic numbers, same order).

import torch

from nvalchemi.data import Batch

initial = Batch.from_data_list(reactants, device=device)
final = Batch.from_data_list(products, device=device)

paths = interpolate_paths(
    initial,
    final,
    num_images=10,  # total images per path, endpoints included; or one per path
    remove_translation_and_rotation=True,  # optional rigid alignment first
    fit_mask=initial.atomic_numbers > 1,  # optional: fit on heavy atoms only
)
validate_paths(paths)  # >= 3 images per path, matching atoms/cell/pbc

interpolate_paths drops fields that no longer apply (forces, energy, velocities, stress, embeddings, ...). Reinitialize them before any optimizer run, as the example's initialize_dynamics_fields does:

def initialize_dynamics_fields(batch: Batch) -> None:
    batch.energy = torch.zeros(
        batch.num_graphs, 1, dtype=batch.positions.dtype, device=batch.device
    )
    batch.forces = torch.zeros_like(batch.positions)
    batch.velocities = torch.zeros_like(batch.positions)