Source code for nvalchemi.dynamics.mep.neb_configs

# 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.

"""Public configuration for NEB."""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Literal, Protocol, Self, runtime_checkable

import torch
import warp as wp
from torch import Tensor

from nvalchemi.data import Batch, GroupLayout
from nvalchemi.dynamics.base import DynamicsStage
from nvalchemi.dynamics.mep._geometry import PreparedMIC
from nvalchemi.dynamics.mep.neb_equations import (
    climbing_image_effective_force,
    improved_tangent_weights,
    neb_effective_force,
)
from nvalchemi.dynamics.mep.neb_ops.methods import (
    prepare_neb_method_key,
    resolve_neb_method,
)

__all__ = [
    "ConstantSpringConfig",
    "NEBMethod",
    "SpringConfig",
    "SpringContext",
    "TorchNEBMethod",
]


[docs] @dataclass(frozen=True, slots=True) class SpringContext: """Read-only inputs available to spring-constant policies. Tensor fields share storage with the active NEB state and must not be modified in-place by implementations. Parameters ---------- energies : Tensor or None Flattened physical image energies, shape ``(num_images,)``. ``None`` before the first model evaluation. positions : Tensor Packed atomic positions, shape ``(num_atoms, 3)``. physical_forces : Tensor or None Packed physical model forces, shape ``(num_atoms, 3)``. ``None`` before the first model evaluation. image_ptr : Tensor Atom offsets delimiting packed images, shape ``(num_images + 1,)``. layout : GroupLayout Mapping from packed images to NEB paths. cell : Tensor Representative cell for each path, shape ``(num_paths, 3, 3)``. pbc : Tensor Periodic-boundary flags for each path, shape ``(num_paths, 3)``. step_count : int Current dynamics step. """ energies: Tensor | None positions: Tensor physical_forces: Tensor | None image_ptr: Tensor layout: GroupLayout cell: Tensor pbc: Tensor step_count: int @property def num_links(self) -> int: """Return the number of adjacent image pairs across all paths.""" return self.layout.group_idx.numel() - self.layout.num_groups
[docs] @runtime_checkable class SpringConfig(Protocol): """Resolve spring constants for the links in one or more NEB paths.""" refresh: Literal[ DynamicsStage.ON_ADMISSION, DynamicsStage.AFTER_COMPUTE, ]
[docs] def resolve(self, context: SpringContext) -> Tensor: """Return one spring constant per adjacent image link. Parameters ---------- context : SpringContext Read-only current NEB state. Returns ------- Tensor Spring constants with shape ``(context.num_links,)`` on the same device as ``context.positions``. """
[docs] @dataclass(frozen=True, slots=True) class ConstantSpringConfig: """Use one constant spring value for every adjacent image pair. Parameters ---------- value : float Positive spring constant. """ value: float refresh: Literal[DynamicsStage.ON_ADMISSION] = field( default=DynamicsStage.ON_ADMISSION, init=False, ) def __post_init__(self) -> None: """Normalize and validate the constant spring value.""" if isinstance(self.value, bool) or not isinstance(self.value, (int, float)): raise TypeError( "ConstantSpringConfig.value must be a number; " f"got {type(self.value).__name__}" ) value = float(self.value) if not value > 0: raise ValueError("ConstantSpringConfig.value must be positive") object.__setattr__(self, "value", value)
[docs] def resolve(self, context: SpringContext) -> Tensor: """Return constant spring values for the current path layout.""" return torch.full( (context.num_links,), self.value, dtype=context.positions.dtype, device=context.positions.device, )
[docs] @runtime_checkable class TorchNEBMethod(Protocol): """Compute effective forces for a batch of paths using Torch operations.""" def __call__( self, batch: Batch, *, spring_constants: Tensor, path_energy_ref: Tensor, path_energy_max: Tensor, mic: PreparedMIC, ) -> tuple[Tensor, Tensor]: """Return effective forces and forward-link lengths. The batch provides packed positions, physical forces, energies, path layout, and image force modes. Handle regular, climbing, and endpoint images. Compute minimum-image link lengths with ``minimum_image_displacement(..., prepared=mic)``. The hook applies fixed-atom and active-path masks before publishing the returned forces. Parameters ---------- batch : Batch Current batch of paths. ``positions`` and ``physical_forces`` have shape ``(num_atoms, 3)``; ``energy`` and ``force_mode`` have one entry per image. Read inputs without modifying the batch. spring_constants : Tensor, shape (num_images - num_paths,) Per-link spring constants. path_energy_ref, path_energy_max : Tensor, shape (num_paths,) Endpoint reference and highest interior energy per path. mic : PreparedMIC Geometry for ``minimum_image_displacement(..., prepared=mic)``. Returns ------- tuple[Tensor, Tensor] Effective forces with shape ``(num_atoms, 3)`` and MIC-aware forward-link lengths with shape ``(num_images - num_paths,)``. """
[docs] @dataclass(frozen=True, slots=True) class NEBMethod: """Configure the device equations used to construct NEB forces. Equation functions must be importable module-level functions decorated with :func:`warp.func`. The hook prepares their kernel key during setup. Parameters ---------- tangent_weights_fn : wp.Function, optional Return the forward and backward weights used to construct the path tangent from adjacent image displacements. effective_force_fn : wp.Function, optional Construct the effective force for an active, non-climbing interior image using the stored-tangent or Gram-statistics signature. climbing_force_fn : wp.Function, optional Construct the effective force for a climbing image. Examples -------- Override only the tangent weighting while retaining regular NEB and climbing-image force laws:: import warp as wp from nvalchemi.dynamics.mep import NEBMethod @wp.func def central_tangent_weights( energy_prev: float, energy_curr: float, energy_next: float, ): return 1.0, 1.0 method = NEBMethod(tangent_weights_fn=central_tangent_weights) """ tangent_weights_fn: wp.Function = improved_tangent_weights effective_force_fn: wp.Function = neb_effective_force climbing_force_fn: wp.Function = climbing_image_effective_force def __post_init__(self) -> None: """Validate the setup-time method configuration.""" for field_name in ( "tangent_weights_fn", "effective_force_fn", "climbing_force_fn", ): value = getattr(self, field_name) if not isinstance(value, wp.Function): raise TypeError( f"{field_name} must be a function decorated with warp.func; " f"got {type(value).__name__}" )
[docs] def to_key(self) -> str: """Return the prepared kernel key containing importable equation paths. Returns ------- str Kernel kind and dotted paths for the three equation functions. """ return prepare_neb_method_key( self.tangent_weights_fn, self.effective_force_fn, self.climbing_force_fn, )
[docs] @classmethod def from_key(cls, key: str) -> Self: """Restore the equation functions from a prepared kernel key. Parameters ---------- key : str Key produced by :meth:`to_key`. Returns ------- NEBMethod Method using the imported equation functions. """ equations = resolve_neb_method(key) return cls( tangent_weights_fn=equations.tangent_fn, effective_force_fn=equations.force_fn, climbing_force_fn=equations.climbing_force_fn, )