Source code for nvalchemi.dynamics.mep.idpp

# 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.
"""Image-dependent pair-potential inputs and model."""

from __future__ import annotations

from typing import Any

import torch
from torch import Tensor, nn

from nvalchemi._typing import ModelOutputs
from nvalchemi.data import AtomicData, Batch
from nvalchemi.data.level_storage import SegmentedLevelStorage
from nvalchemi.dynamics.mep._geometry import (
    PreparedMIC,
    minimum_image_displacement,
    prepare_batch_mic,
)
from nvalchemi.dynamics.mep.validate import validate_paths
from nvalchemi.models.base import BaseModelMixin, ModelConfig

_TARGET_DISTANCE_KEY = "idpp_target_distances"


def _pair_displacements(
    positions: Tensor,
    pair_indices: Tensor,
    pair_path: Tensor,
    prepared_mic: PreparedMIC,
) -> Tensor:
    """Return pair displacements with batched minimum-image wrapping.

    Parameters
    ----------
    positions : Tensor
        Cartesian atom positions with shape ``(N, 3)``.
    pair_indices : Tensor
        Global atom indices for each pair with shape ``(E, 2)``. Each row
        contains the source and destination indices ``(i, j)``.
    pair_path : Tensor
        Path index for each pair with shape ``(E,)``.
    prepared_mic : PreparedMIC
        Reusable path-level cell-dependent geometry.

    Returns
    -------
    Tensor
        Minimum-image Cartesian displacements from atom ``i`` to atom ``j`` with
        shape ``(E, 3)``.
    """
    displacements = positions[pair_indices[:, 1]] - positions[pair_indices[:, 0]]
    return minimum_image_displacement(displacements, pair_path, prepared=prepared_mic)


[docs] def prepare_idpp_targets(paths: Batch) -> Batch: """Build full pairwise IDPP target distances for a batch of reaction paths. IDPP (image dependent pair potential) initialization needs a target interatomic distance for every atom pair in every image. This function replaces whatever edge/neighbor list ``paths`` currently has with a complete upper-triangle pair list per image, and assigns each pair a target distance linearly interpolated between that pair's distance in the path's first image and its distance in the path's last image. ``paths`` is a :class:`Batch` of one or more reaction paths, where each path is a group of images (``group_layout``) and each image is one graph in that group. All images within a path must share the same atoms and ordering (enforced by :func:`validate_paths`) so that pair ``(i, j)`` refers to the same atoms across every image of the path. Parameters ---------- paths : Batch Grouped reaction paths, where each group is a path and each graph within a group is one image along that path, with corresponding atoms in every image. Returns ------- Batch ``paths``, mutated in place: its edge storage now holds the full pair ``neighbor_list`` and the interpolated ``idpp_target_distances`` for every image. """ validate_paths(paths) layout = paths.group_layout first_image_idx = layout.group_ptr[:-1] if "cell" in paths: path_cell = paths.cell[first_image_idx].to(paths.positions.dtype).contiguous() else: path_cell = ( torch.eye(3, dtype=paths.positions.dtype, device=paths.device) .unsqueeze(0) .repeat(layout.num_groups, 1, 1) ) if "pbc" in paths: path_pbc = paths.pbc[first_image_idx].contiguous() else: path_pbc = torch.zeros( layout.num_groups, 3, dtype=torch.bool, device=paths.device ) # Prepare MIC using the cell and PBC settings from the first image of each path. prepare_batch_mic(paths, path_cell, path_pbc) node_ptr = paths.batch_ptr.long() # [B + 1] node_image = paths.batch_idx.long() # [N] num_atoms = paths.num_nodes_per_graph.long() # [B] nodes = torch.arange(paths.num_nodes, device=paths.device) # [N] node_rank = nodes - node_ptr[node_image] # [N] # Enumerate each image's complete upper-triangle pair list. # For one three-atom image with global nodes [0, 1, 2]: # repeats = [2, 1, 0] -> pair_i = [0, 0, 1] # pair_offset = [0, 1, 0] -> pair_j = [1, 2, 2] # pair_indices = [[0, 1], [0, 2], [1, 2]] # Later images produce the same local pairs shifted to their global node indices. repeats = num_atoms[node_image] - node_rank - 1 # [N] pair_i = torch.repeat_interleave(nodes, repeats) # [E] pair_i_starts = repeats.cumsum(0) - repeats # [N] pair_offset = torch.arange(pair_i.numel(), device=paths.device) - ( torch.repeat_interleave(pair_i_starts, repeats) ) # [E] pair_j = pair_i + pair_offset + 1 # [E] pair_indices = torch.stack((pair_i, pair_j), dim=-1) # [E, 2] # Prepare quantities needed to locate each pair's path and image, and each path's # last-image rank - used below to select the two endpoint images pair_counts = num_atoms * (num_atoms - 1) // 2 # [B] pair_ptr = torch.cat((pair_counts.new_zeros(1), pair_counts.cumsum(0))) # [B + 1] pair_image = node_image[pair_i] # [E] pair_rank = ( torch.arange(pair_i.numel(), device=paths.device) - pair_ptr[pair_image] ) # [E] pair_path = layout.group_idx[pair_image] # [E] image_rank = layout.graph_rank[pair_image] # [E] last_image_rank = layout.num_graphs_per_group[pair_path] - 1 # [E] # Measure pair distances in the initial and final path images. # E_init = E_final = number of edges in the initial or the final image. initial_pair_mask = image_rank == 0 # [E] initial_endpoint_pairs = pair_indices[initial_pair_mask] # [E_init, 2] initial_endpoint_displacements = _pair_displacements( paths.positions, initial_endpoint_pairs, pair_path[initial_pair_mask], paths._mic_data, ) # [E_init, 3] initial_endpoint_distances = torch.linalg.vector_norm( initial_endpoint_displacements, dim=-1 ) # [E_init] final_pair_mask = image_rank == last_image_rank # [E] final_endpoint_pairs = pair_indices[final_pair_mask] # [E_final, 2] final_endpoint_displacements = _pair_displacements( paths.positions, final_endpoint_pairs, pair_path[final_pair_mask], paths._mic_data, ) # [E_final, 3] final_endpoint_distances = torch.linalg.vector_norm( final_endpoint_displacements, dim=-1 ) # [E_final] # Map each per-image atom pair to the corresponding atom pair at both endpoints. pairs_per_path = pair_counts[layout.group_ptr[:-1]] # [P] path_pair_ptr = torch.cat( (pairs_per_path.new_zeros(1), pairs_per_path.cumsum(0)) ) # [P + 1] pair_endpoint_index = path_pair_ptr[pair_path] + pair_rank # [E] initial_distances = initial_endpoint_distances[pair_endpoint_index] # [E] final_distances = final_endpoint_distances[pair_endpoint_index] # [E] # Linearly interpolate each target according to the image's position in its path. fractions = image_rank.to(paths.positions.dtype) / last_image_rank.to( paths.positions.dtype ) target_distances = torch.lerp(initial_distances, final_distances, fractions) segment_lengths = pair_counts.to(torch.int32) paths._storage.groups["edges"] = SegmentedLevelStorage( data={ "neighbor_list": pair_indices.to(torch.int32), _TARGET_DISTANCE_KEY: target_distances, }, device=paths.device, segment_lengths=segment_lengths, validate=False, ) if paths.keys is not None: paths.keys["edge"] = {"neighbor_list", _TARGET_DISTANCE_KEY} # Full pair edges do not use a neighbor-list cutoff. if hasattr(paths, "_neighbor_list_cutoff"): object.__delattr__(paths, "_neighbor_list_cutoff") return paths
[docs] class IDPPModel(nn.Module, BaseModelMixin): r"""Evaluate the image-dependent pair potential for reaction-path images. Linear Cartesian interpolation can place atoms unnaturally close together or produce uneven changes in interatomic distances. IDPP provides a better initial guess for reaction-path calculations, such as NEB, by relaxing the interior images toward smoothly varying pair distances before evaluating them with a physical potential [1]_. For image fraction :math:`s \in [0, 1]`, the target distance for atoms :math:`i` and :math:`j` is interpolated between the endpoint distances: .. math:: d_{ij}^{\mathrm{target}}(s) = (1-s)d_{ij}^{(0)} + s d_{ij}^{(1)}. The artificial IDPP energy for an image is .. math:: E_{\mathrm{IDPP}} = \sum_{i<j} \frac{\left(d_{ij} - d_{ij}^{\mathrm{target}}\right)^2}{d_{ij}^4}, which weights close atom pairs more strongly. Forces are the negative coordinate gradient, :math:`\mathbf{F}_i = -\partial E_{\mathrm{IDPP}} / \partial \mathbf{r}_i`. Call :func:`prepare_idpp_targets` on each grouped path batch before evaluation. Pair displacements use minimum-image wrapping for periodic images. IDPP energies are optimization objectives, not physical potential energies. References ---------- .. [1] S. Smidstrup, A. Pedersen, K. Stokbro, and H. Jónsson, "Improved initial guess for minimum energy path calculations," *The Journal of Chemical Physics*, 140, 214106 (2014). `doi:10.1063/1.4878664 <https://doi.org/10.1063/1.4878664>`_. """ def __init__(self) -> None: super().__init__() self.model_config = ModelConfig( outputs=frozenset({"energy", "forces"}), autograd_outputs=frozenset(), autograd_inputs=frozenset({"positions"}), required_inputs=frozenset({"neighbor_list", _TARGET_DISTANCE_KEY}), optional_inputs=frozenset({"cell", "pbc"}), supports_pbc=True, needs_pbc=False, neighbor_config=None, ) @property def embedding_shapes(self) -> dict[str, tuple[int, ...]]: """Return no embedding shapes because IDPP has no learned features.""" return {}
[docs] def compute_embeddings( self, data: AtomicData | Batch, **kwargs: Any ) -> AtomicData | Batch: """Raise because the analytic IDPP model has no embeddings.""" raise NotImplementedError("IDPPModel does not provide embeddings")
[docs] def direct_derivative_keys(self) -> set[str]: """Return outputs computed analytically by the IDPP model. Returns ------- set[str] The analytic force output. """ return {"forces"}
[docs] def forward(self, data: Batch, **kwargs: Any) -> ModelOutputs: """Compute active IDPP outputs for every image. Parameters ---------- data : Batch Complete grouped paths prepared by :func:`prepare_idpp_targets`. Returns ------- ModelOutputs Active per-image energies and per-atom forces. Raises ------ TypeError If ``data`` is not a :class:`Batch`. KeyError If ``data`` has not been prepared with IDPP target distances. RuntimeError If any distinct atom pair is coincident within machine precision. """ if _TARGET_DISTANCE_KEY not in data: raise KeyError("IDPPModel requires paths prepared by prepare_idpp_targets") inputs = self.adapt_input(data, **kwargs) pair_indices = inputs["neighbor_list"].long() target_distances = inputs[_TARGET_DISTANCE_KEY] positions = inputs["positions"] num_graphs = data.num_graphs pair_batch = data.batch_idx.index_select(0, pair_indices[:, 0]).long() cell = inputs.get("cell") pbc = inputs.get("pbc") prepared_mic = getattr(data, "_mic_data", None) if cell is not None and pbc is not None and prepared_mic is None: raise RuntimeError( "Periodic IDPP data requires explicit MIC preparation; " "call prepare_idpp_targets after moving the batch" ) if prepared_mic is not None: if prepared_mic.periodic_basis.device != positions.device: raise RuntimeError("Prepared MIC data is on the wrong device") if prepared_mic.periodic_basis.dtype != positions.dtype: raise RuntimeError("Prepared MIC data has the wrong dtype") with torch.no_grad(): if prepared_mic is None: displacements = ( positions[pair_indices[:, 1]] - positions[pair_indices[:, 0]] ) else: pair_path = data.group_layout.group_idx[pair_batch] displacements = _pair_displacements( positions, pair_indices, pair_path, prepared_mic, ) distances = torch.linalg.vector_norm(displacements, dim=-1) minimum_distance = torch.finfo(positions.dtype).eps # This guards against overlaps introduced unexpectedly during optimization # without synchronizing every evaluation. torch._assert_async( torch.all(distances > minimum_distance), "IDPP cannot evaluate coincident atom pairs; perturb overlapping " "atoms before optimization", ) safe_distances = distances.clamp_min(minimum_distance) distance_errors = distances - target_distances inverse_distances = safe_distances.reciprocal() model_output: dict[str, Tensor] = {} if "energy" in self.model_config.active_outputs: pair_energies = distance_errors.square() * inverse_distances.pow(4) accumulation_dtype = ( torch.float64 if pair_energies.dtype == torch.float32 else pair_energies.dtype ) energy = torch.zeros( num_graphs, dtype=accumulation_dtype, device=positions.device, ) energy.scatter_add_(0, pair_batch, pair_energies.to(accumulation_dtype)) model_output["energy"] = energy.to(positions.dtype).unsqueeze(-1) if "forces" in self.model_config.active_outputs: pair_force_scale = ( 2 * distance_errors * (2 * target_distances - distances) * inverse_distances.pow(6) ) pair_forces = pair_force_scale.unsqueeze(-1) * displacements forces = torch.zeros_like(positions) forces.index_add_(0, pair_indices[:, 0], pair_forces) forces.index_add_(0, pair_indices[:, 1], -pair_forces) model_output["forces"] = forces return self.adapt_output(model_output, data)
__all__ = ["IDPPModel", "prepare_idpp_targets"]