Source code for nvalchemi.dynamics.mep.hooks.neb_force

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""NEB force hook configuration."""

from __future__ import annotations

from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from enum import Enum
from typing import Literal

import torch
from torch import Tensor

from nvalchemi.dynamics.base import DynamicsStage
from nvalchemi.dynamics.mep._geometry import PreparedMIC, prepare_batch_mic
from nvalchemi.dynamics.mep.hooks.path_energy_stats import PathEnergyStatsHook
from nvalchemi.dynamics.mep.neb_configs import (
    ConstantSpringConfig,
    NEBMethod,
    SpringConfig,
    SpringContext,
    TorchNEBMethod,
)
from nvalchemi.dynamics.mep.neb_ops.modes import ENDPOINT, REGULAR_NEB
from nvalchemi.dynamics.mep.neb_ops.torch_ops import neb_forces
from nvalchemi.dynamics.mep.validate import validate_paths
from nvalchemi.hooks import DynamicsContext


@dataclass
class _NEBWorkspace:
    """Persistent buffers resolved for a NEB batch containing multiple
    paths.

    Attributes
    ----------
    image_ptr : Tensor
        Int32 atom offsets delimiting packed images, shape ``(num_images + 1,)``.
        Copied from the batch so the kernel receives its required index dtype.
    path_ptr : Tensor
        Int32 image offsets delimiting packed paths, shape ``(num_paths + 1,)``.
        Copied from the group layout for the kernel's required index dtype.
    image_path_idx : Tensor
        Int32 path index for each packed image, shape ``(num_images,)``.
        Copied from the group layout for the kernel's required index dtype and
        stable workspace ownership.
    link_source_image_idx : Tensor
        Image index owning each forward link, shape
        ``(num_images - num_paths,)``. The final image in every path is omitted.
    spring_constants : Tensor
        Per-link spring constants, shape ``(num_images - num_paths,)``.
    fixed_node_mask : Tensor
        Boolean mask of atoms that must not be updated, shape
        ``(num_atoms,)``.
    cell : Tensor
        Representative cell per path, shape ``(num_paths, 3, 3)``.
    pbc : Tensor
        Periodic-boundary flags per path, shape ``(num_paths, 3)``.
    mic : PreparedMIC
        Reduced-lattice MIC buffers prepared once during admission.
    effective_forces : Tensor
        Per-atom output force buffer, shape ``(num_atoms, 3)``.
    link_lengths : Tensor
        Per-link distance buffer, shape ``(num_images - num_paths,)``.
    vector_scratch : Tensor or None
        Per-atom vector scratch for stored-tangent methods; otherwise ``None``.
    """

    image_ptr: Tensor
    path_ptr: Tensor
    image_path_idx: Tensor
    link_source_image_idx: Tensor

    spring_constants: Tensor
    fixed_node_mask: Tensor
    cell: Tensor
    pbc: Tensor
    mic: PreparedMIC
    effective_forces: Tensor
    link_lengths: Tensor
    vector_scratch: Tensor | None


[docs] class NEBForceHook: """Configure optimizer-facing forces for nudged elastic band dynamics. The hook prepares structural state at :attr:`DynamicsStage.ON_ADMISSION` and publishes the combined endpoint and user-fixed node mask for a :class:`~nvalchemi.dynamics.hooks.FreezeAtomsHook`. At :attr:`DynamicsStage.AFTER_COMPUTE`, it refreshes the spring constants and then replaces physical forces with the selected NEB force formulation. Energy extrema and image force modes come from hooks registered before this hook. Parameters ---------- energy_stats_hook : PathEnergyStatsHook Shared path-energy statistics hook registered before this hook. spring : float or SpringConfig, optional Positive constant spring value or a policy that resolves one spring constant for every adjacent image pair. Default is ``0.1``. method : str, NEBMethod, or TorchNEBMethod, optional Built-in method name, custom Warp equations, or a Torch method that computes NEB effective forces for the batch of paths. Default is ``"improved_tangent"``. endpoint_mode : {"fixed", "relaxed"}, optional Whether path endpoint images remain fixed or use their physical forces. Default is ``"fixed"``. fixed_atom_indices : mapping of int to sequence of int, optional Image-local atom indices that must remain fixed in every image of each keyed path. Keys are zero-based path indices; omitted paths have no additional fixed atoms. All three Cartesian components of every selected atom are fixed. Atoms in fixed endpoint images are added automatically. Attributes ---------- stage : DynamicsStage Primary hook stage, :attr:`DynamicsStage.AFTER_COMPUTE`. The hook also runs at :attr:`DynamicsStage.ON_ADMISSION` for batch preparation. frequency : int Always ``1``. NEB forces must be refreshed after every model-force evaluation. Notes ----- Component-level constraints, such as fixing only one Cartesian axis, are not supported. Examples -------- Use the improved-tangent method with a constant spring:: energy_stats = PathEnergyStatsHook() hook = NEBForceHook( energy_stats_hook=energy_stats, spring=0.1, method="improved_tangent", fixed_atom_indices={0: [0, 2], 1: [1]}, ) Pass a custom equation configuration directly:: method = NEBMethod( tangent_weights_fn=my_tangent_weights, effective_force_fn=my_effective_force, climbing_force_fn=my_climbing_force, ) hook = NEBForceHook(energy_stats_hook=energy_stats, method=method) Pass a Torch callable accepting ``(batch, *, ...)`` in the same way:: hook = NEBForceHook(energy_stats_hook=energy_stats, method=my_torch_method) """ stage = DynamicsStage.AFTER_COMPUTE frequency = 1 def __init__( self, *, energy_stats_hook: PathEnergyStatsHook, spring: float | SpringConfig = 0.1, method: str | NEBMethod | TorchNEBMethod = "improved_tangent", endpoint_mode: Literal["fixed", "relaxed"] = "fixed", fixed_atom_indices: Mapping[int, Sequence[int]] | None = None, ) -> None: """Initialize the NEB force hook. Raises ------ TypeError If an argument has an unsupported type. ValueError If the spring, spring refresh stage, method name, or endpoint mode is invalid. """ if not isinstance(energy_stats_hook, PathEnergyStatsHook): raise TypeError("energy_stats_hook must be a PathEnergyStatsHook") # Normalize numeric springs into the common policy interface and reject # refresh stages that this multi-stage hook cannot handle. if isinstance(spring, (int, float)): spring = ConstantSpringConfig(spring) elif not isinstance(spring, SpringConfig): raise TypeError( "spring must be a number or implement SpringConfig.resolve; " f"got {type(spring).__name__}" ) if not isinstance(spring.refresh, DynamicsStage): raise TypeError("SpringConfig.refresh must be a DynamicsStage") if spring.refresh not in { DynamicsStage.ON_ADMISSION, DynamicsStage.AFTER_COMPUTE, }: raise ValueError( "SpringConfig.refresh must be DynamicsStage.ON_ADMISSION or " "DynamicsStage.AFTER_COMPUTE" ) if isinstance(method, str): if method != "improved_tangent": raise ValueError(f"Unknown NEB method: {method!r}") method = NEBMethod() elif not isinstance(method, (NEBMethod, TorchNEBMethod)): raise TypeError( "method must be 'improved_tangent', an NEBMethod, or a " f"TorchNEBMethod; got {type(method).__name__}" ) method_key = method.to_key() if isinstance(method, NEBMethod) else None # Validate endpoint behavior and image-local atom constraints together. if endpoint_mode not in {"fixed", "relaxed"}: raise ValueError("endpoint_mode must be 'fixed' or 'relaxed'") if fixed_atom_indices is not None: if not isinstance(fixed_atom_indices, Mapping): raise TypeError( "fixed_atom_indices must map path indices to atom-index sequences" ) try: fixed_atom_indices = { path_index: tuple(atom_indices) for path_index, atom_indices in fixed_atom_indices.items() } except TypeError as error: raise TypeError( "fixed_atom_indices values must be sequences of integers" ) from error if any( isinstance(path_index, bool) or not isinstance(path_index, int) for path_index in fixed_atom_indices ): raise TypeError("fixed_atom_indices keys must be integer path indices") if any( isinstance(atom_index, bool) or not isinstance(atom_index, int) for atom_indices in fixed_atom_indices.values() for atom_index in atom_indices ): raise TypeError("fixed_atom_indices values must contain only integers") self.energy_stats_hook = energy_stats_hook self.spring = spring self.method = method self.method_key = method_key self.endpoint_mode = endpoint_mode self.fixed_atom_indices = fixed_atom_indices self._workspace: _NEBWorkspace | None = None
[docs] def on_register(self, workflow: object) -> None: """Require group-aware dynamics for NEB force construction. Parameters ---------- workflow : object Workflow on which this hook is being registered. Raises ------ ValueError If the workflow does not enable group-aware dynamics. """ if not getattr(workflow, "by_group", False): raise ValueError( f"{type(self).__name__} requires dynamics configured with by_group=True" )
def _runs_on_stage(self, stage: Enum) -> bool: """Return whether the hook participates in a dynamics stage. Parameters ---------- stage : Enum Stage currently being dispatched by the hook registry. Returns ------- bool Whether to run structural preparation or force construction. """ return stage in { DynamicsStage.ON_ADMISSION, DynamicsStage.AFTER_COMPUTE, } @torch.compiler.disable def _prepare_batch(self, ctx: DynamicsContext) -> None: """Validate and initialize private state for a new batch structure. This helper is reached only through the ``ON_ADMISSION`` branch of :meth:`__call__` and is typically called once for a batch. Parameters ---------- ctx : DynamicsContext Context containing the newly admitted grouped path batch. Raises ------ ValueError If the batch has no valid group layout, or if the paths, fixed atom indices, cells, or PBC flags are incompatible with NEB evaluation. """ batch = ctx.batch validate_paths(batch) layout = batch.group_layout dtype = batch.positions.dtype device = batch.device # Each path's first and last images use endpoint force handling. last_rank: Tensor = layout.num_graphs_per_group[layout.group_idx] - 1 is_terminal = layout.graph_rank == last_rank is_endpoint = (layout.graph_rank == 0) | is_terminal force_mode = torch.full_like( layout.group_idx, REGULAR_NEB, dtype=torch.int32, ) force_mode[is_endpoint] = ENDPOINT # Identify fixed atoms including those in fixed endpoints. fixed_atoms = torch.zeros( batch.num_nodes, dtype=torch.bool, device=device, ) if self.fixed_atom_indices is not None: num_nodes_per_image = batch.num_nodes_per_graph for path_index, atom_indices in self.fixed_atom_indices.items(): if path_index < 0 or path_index >= layout.num_groups: raise ValueError( "fixed_atom_indices keys must reference existing paths; " f"got {path_index}" ) path_start = layout.group_ptr[path_index].item() path_end = layout.group_ptr[path_index + 1].item() image_starts = batch.batch_ptr[path_start:path_end].long() for atom_index in atom_indices: if atom_index < 0 or torch.any( num_nodes_per_image[path_start:path_end] <= atom_index ): raise ValueError( f"fixed_atom_indices[{path_index}] must contain valid " f"image-local atom indices; got {atom_index}" ) fixed_atoms[image_starts + atom_index] = True if self.endpoint_mode == "fixed": fixed_atoms[is_endpoint[batch.batch_idx.long()]] = True # `validate_paths` guarantees cell and PBC consistency within each path, # so the kernels only need the first image's geometry. Missing cells use # dense identity matrices rather than zero-stride expanded views. cells = batch.cell if "cell" in batch else None pbcs = batch.pbc if "pbc" in batch else None # Graph indices selecting the first image of each path. first_image_idx = layout.group_ptr[:-1] if cells is None: path_cell = ( torch.eye(3, dtype=dtype, device=device) .unsqueeze(0) .repeat(layout.num_groups, 1, 1) ) else: path_cell = cells[first_image_idx].to(dtype=dtype).contiguous() if pbcs is None: path_pbc = torch.zeros( layout.num_groups, 3, dtype=torch.bool, device=device ) else: path_pbc = pbcs[first_image_idx].bool().contiguous() n_links = batch.num_graphs - layout.num_groups spring_constants = torch.empty(n_links, dtype=dtype, device=device) # Normalize kernel index buffers to int32. int32_max = torch.iinfo(torch.int32).max if batch.num_graphs > int32_max or batch.num_nodes > int32_max: raise ValueError("Path kernel layout exceeds int32 index capacity") image_ptr = batch.batch_ptr.to(torch.int32).contiguous() path_ptr = layout.group_ptr.to(torch.int32).contiguous() image_path_idx = layout.group_idx.to(torch.int32).contiguous() link_source_image_idx = torch.where(~is_terminal)[0].contiguous() # Include fields shared with other hooks on `Batch`. def set_batch_field(key: str, value: Tensor, level: str) -> None: if key in batch: target = getattr(batch, key) if ( target.shape == value.shape and target.dtype == value.dtype and target.device == value.device ): target.copy_(value) return values = ( list(value.unbind()) if level == "system" else list(value.split(batch.num_nodes_list)) ) batch.add_key(key, values, level=level, overwrite=key in batch) set_batch_field("force_mode", force_mode, "system") set_batch_field( "physical_forces", torch.zeros_like(batch.positions), "node", ) set_batch_field("neb_fixed_node_mask", fixed_atoms, "node") set_batch_field( "forward_link_length", torch.zeros(batch.num_graphs, dtype=dtype, device=device), "system", ) # Keep kernel-only masks and buffers private on workspace. prepared_mic = prepare_batch_mic(batch, path_cell, path_pbc) self._workspace = _NEBWorkspace( spring_constants=spring_constants, fixed_node_mask=batch.neb_fixed_node_mask, cell=path_cell, pbc=path_pbc, mic=prepared_mic, effective_forces=torch.empty_like(batch.positions), link_lengths=torch.empty(n_links, dtype=dtype, device=device), vector_scratch=( torch.empty_like(batch.positions) if self.method_key is not None and self.method_key.startswith("stored_tangent|") else None ), image_ptr=image_ptr, path_ptr=path_ptr, image_path_idx=image_path_idx, link_source_image_idx=link_source_image_idx, ) self._refresh_spring_constants(ctx, DynamicsStage.ON_ADMISSION) def __call__(self, ctx: DynamicsContext, stage: DynamicsStage) -> None: """Prepare NEB state or construct NEB forces. Parameters ---------- ctx : DynamicsContext Context containing the current grouped path batch. stage : DynamicsStage Current dynamics stage. Preparation occurs at ``ON_ADMISSION`` and force construction occurs at ``AFTER_COMPUTE``. Raises ------ RuntimeError If the force phase runs before the batch has been prepared. """ if stage == DynamicsStage.ON_ADMISSION: self._prepare_batch(ctx) return if stage != DynamicsStage.AFTER_COMPUTE: return batch = ctx.batch workspace = self._workspace active_nodes = ( torch.ones_like(workspace.fixed_node_mask) if ctx.active_graph_mask is None else ctx.active_graph_mask[batch.batch_idx.long()] ) active_fixed_nodes = active_nodes & workspace.fixed_node_mask stats = self.energy_stats_hook.get_stats(ctx) # Copy to `batch.physical_forces` before computation torch.where( active_nodes.unsqueeze(-1), batch.forces, batch.physical_forces, out=batch.physical_forces, ) batch.physical_forces.masked_fill_(active_fixed_nodes.unsqueeze(-1), 0) self._refresh_spring_constants(ctx, DynamicsStage.AFTER_COMPUTE) if self.method_key is None: # Compute neb forces with pure Torch effective_forces, link_lengths = self.method( batch, spring_constants=workspace.spring_constants, path_energy_ref=stats.endpoint_reference_energy, path_energy_max=stats.highest_interior_energy, mic=workspace.mic, ) if ( effective_forces.shape != workspace.effective_forces.shape or link_lengths.shape != workspace.link_lengths.shape ): raise ValueError( "TorchNEBMethod must return forces shaped like positions " "and one length per forward link" ) workspace.effective_forces.copy_(effective_forces) workspace.link_lengths.copy_(link_lengths) else: # Compute neb forces with Warp neb_forces( positions=batch.positions.contiguous(), physical_forces=batch.physical_forces.contiguous(), image_energies=batch.energy.reshape(-1).contiguous(), image_ptr=workspace.image_ptr, path_ptr=workspace.path_ptr, image_path_idx=workspace.image_path_idx, spring_constants=workspace.spring_constants, image_force_mode=batch.force_mode, path_energy_ref=stats.endpoint_reference_energy.contiguous(), path_energy_max=stats.highest_interior_energy.contiguous(), mic_mode=workspace.mic.mode, periodic_basis=workspace.mic.periodic_basis, cartesian_to_fractional=workspace.mic.cartesian_to_fractional, mic_candidate_count=workspace.mic.candidate_count, candidate_shifts=workspace.mic.candidate_shifts, method=self.method_key, vector_scratch=workspace.vector_scratch, effective_forces=workspace.effective_forces, link_lengths=workspace.link_lengths, ) workspace.effective_forces.masked_fill_(active_fixed_nodes.unsqueeze(-1), 0) # Expand packed link lengths into the per-image field. Terminal entries # are initialized to zero on admission and are not modified here. batch.forward_link_length.index_copy_( 0, workspace.link_source_image_idx, workspace.link_lengths, ) # Publish only the rows owned by this hook dispatch. Model evaluation # preserves inactive rows, so other sub-stages and graduated paths retain # their previously published effective forces. torch.where( active_nodes.unsqueeze(-1), workspace.effective_forces, batch.forces, out=batch.forces, ) # Newly entered paths skip both optimizer updates while these NEB forces # are primed. Reset their carried velocity before the first real update. velocities = getattr(batch, "velocities", None) reprime_pending = getattr(batch, "reprime_pending", None) if velocities is not None and reprime_pending is not None: pending_graphs = reprime_pending.view(-1)[: batch.num_graphs] pending_nodes = active_nodes & pending_graphs[batch.batch_idx.long()] velocities.masked_fill_(pending_nodes.unsqueeze(-1), 0) def _spring_context( self, ctx: DynamicsContext, stage: DynamicsStage, ) -> SpringContext: """Build a read-only spring-policy view of the current NEB state. The view exposes the fields a spring policy reads and omits workspace buffers it does not need. """ workspace = self._workspace batch = ctx.batch model_outputs_available = stage == DynamicsStage.AFTER_COMPUTE return SpringContext( energies=(batch.energy.squeeze(-1) if model_outputs_available else None), positions=batch.positions, physical_forces=( batch.physical_forces if model_outputs_available else None ), image_ptr=workspace.image_ptr, layout=batch.group_layout, cell=workspace.cell, pbc=workspace.pbc, step_count=ctx.step_count, ) def _refresh_spring_constants( self, ctx: DynamicsContext, stage: DynamicsStage, ) -> None: """Resolve spring constants when requested by the configured policy.""" workspace = self._workspace if self.spring.refresh is not stage: return resolved = self.spring.resolve(self._spring_context(ctx, stage)) if not isinstance(resolved, Tensor): raise TypeError("SpringConfig.resolve must return a Tensor") if resolved.shape != workspace.spring_constants.shape: raise ValueError( "SpringConfig.resolve must return shape " f"{tuple(workspace.spring_constants.shape)}" ) workspace.spring_constants.copy_(resolved)