# 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.
"""Construction and interpolation of reaction paths."""
from __future__ import annotations
from collections.abc import Sequence
import torch
from torch import Tensor
from nvalchemi.data import Batch
from nvalchemi.dynamics.mep._alignment import align_batch_positions
from nvalchemi.dynamics.mep._geometry import (
PreparedMIC,
minimum_image_displacement,
prepare_mic,
)
_CELL_RTOL = 1e-5
_CELL_ATOL = 1e-6
_PATH_INPUT_FIELDS = frozenset(
{
"positions",
"atomic_numbers",
"atomic_masses",
"atom_categories",
"cell",
"pbc",
"charges",
"charge",
"node_attrs",
"node_alpha_spins",
"node_beta_spins",
"spin",
"graph_alpha_spins",
}
)
def _normalize_num_images(num_images: int | Sequence[int], num_paths: int) -> list[int]:
"""Return one total image count, including endpoints, for every path."""
if isinstance(num_images, bool):
raise TypeError("num_images must be an integer or a sequence of integers")
if isinstance(num_images, int):
counts = [num_images] * num_paths
elif isinstance(num_images, Sequence) and not isinstance(num_images, (str, bytes)):
counts = list(num_images)
if len(counts) != num_paths:
raise ValueError(
"num_images must contain one value per path; "
f"expected {num_paths}, got {len(counts)}"
)
else:
raise TypeError("num_images must be an integer or a sequence of integers")
if any(isinstance(count, bool) or not isinstance(count, int) for count in counts):
raise TypeError("Every num_images value must be an integer")
if any(count < 3 for count in counts):
raise ValueError("Every num_images value must be at least three")
return counts
def _validate_endpoint_geometry(
initial: Batch, final: Batch
) -> tuple[Tensor | None, Tensor, PreparedMIC | None]:
"""Validate and prepare cells and PBC shared by all endpoint pairs."""
initial_has_cell = "cell" in initial
final_has_cell = "cell" in final
if initial_has_cell != final_has_cell:
raise ValueError(
"Paired endpoints must either both define a cell or neither do"
)
initial_has_pbc = "pbc" in initial
final_has_pbc = "pbc" in final
if initial_has_pbc != final_has_pbc:
raise ValueError("Paired endpoints must either both define PBC or neither do")
num_paths = initial.num_graphs
cell = initial.cell if initial_has_cell else None
final_cell = final.cell if final_has_cell else None
pbc = (
initial.pbc
if initial_has_pbc
else torch.zeros((num_paths, 3), dtype=torch.bool, device=initial.device)
)
final_pbc = final.pbc if final_has_pbc else pbc
if cell is not None and cell.shape != (num_paths, 3, 3):
raise ValueError(f"cell must have shape ({num_paths}, 3, 3)")
if final_cell is not None and final_cell.shape != (num_paths, 3, 3):
raise ValueError(f"cell must have shape ({num_paths}, 3, 3)")
if pbc.shape != (num_paths, 3) or final_pbc.shape != (num_paths, 3):
raise ValueError(f"pbc must have shape ({num_paths}, 3)")
if pbc.dtype != torch.bool or final_pbc.dtype != torch.bool:
raise TypeError("pbc must use the bool dtype")
if not torch.equal(pbc, final_pbc):
raise ValueError("Paired endpoints must have identical PBC settings")
if (
cell is not None
and final_cell is not None
and not torch.allclose(cell, final_cell, rtol=_CELL_RTOL, atol=_CELL_ATOL)
):
raise ValueError("Paired endpoints must have the same cell")
if cell is None:
if torch.any(pbc):
raise ValueError("Periodic endpoints must define a cell")
prepared_mic = None
else:
prepared_mic = prepare_mic(cell, pbc)
return cell, pbc, prepared_mic
[docs]
def interpolate_paths(
initial: Batch,
final: Batch,
num_images: int | Sequence[int],
remove_translation_and_rotation: bool = False,
fit_mask: Tensor | None = None,
) -> Batch:
"""Interpolate paired endpoint batches into grouped reaction paths.
Graph ``i`` in ``initial`` is paired with graph ``i`` in ``final`` and
becomes one path. Atomic correspondence is index-based: paired graphs must
contain identical atomic numbers in identical order. Periodic endpoint
displacements use the minimum-image convention.
Parameters
----------
initial, final : Batch
Batches containing corresponding initial and final structures.
num_images : int or sequence of int
Total number of images per path, including both endpoints. An integer
applies the same count to every path. A sequence supplies one count per
paired endpoint graph. Every count must be at least three.
remove_translation_and_rotation : bool, optional
Align each final structure to its paired initial structure before
interpolation. For non-periodic systems, both rigid translation and
rotation are removed. For periodic systems, rotation is disabled and
minimum-image translation is removed. Default is ``False``.
fit_mask : Tensor or None, optional
Boolean node mask with shape ``(initial.num_nodes,)``. Selected atom
pairs determine each path's alignment. Each path must select at least
one atom. Requires ``remove_translation_and_rotation=True``. ``None``
uses all atom pairs for fitting.
Returns
-------
Batch
Images ordered path-by-path with a populated group layout.
Raises
------
TypeError
If ``num_images`` is not an integer or integer sequence, or if
``fit_mask`` is not boolean.
ValueError
If the endpoint batches or interpolation options are incompatible.
Notes
-----
Only positions, atomic numbers/masses/categories, cell/PBC, charges,
spin fields, and node attributes are copied from each initial graph.
Neighbor data, model outputs, dynamical state, and other custom fields
are discarded. Reattach any custom model inputs to the resulting path
before evaluation.
Unless alignment is requested, endpoint coordinates are retained exactly,
even when periodic interior images follow an unwrapped minimum-image path.
With alignment, terminal images use the aligned final coordinates. The
input endpoint batches are never modified.
"""
if initial.num_graphs == 0 or final.num_graphs == 0:
raise ValueError("Endpoint batches must contain at least one graph")
if initial.num_graphs != final.num_graphs:
raise ValueError("Endpoint batches must contain the same number of graphs")
if initial.device != final.device:
raise ValueError("Endpoint batches must be on the same device")
image_counts = _normalize_num_images(num_images, initial.num_graphs)
if initial.positions.dtype != final.positions.dtype:
raise ValueError("Paired endpoints must use the same position dtype")
if not torch.equal(initial.num_nodes_per_graph, final.num_nodes_per_graph):
raise ValueError("Paired endpoints must contain the same number of atoms")
if not torch.equal(initial.atomic_numbers, final.atomic_numbers):
raise ValueError(
"Paired endpoints must have identical atomic numbers in the same order"
)
if fit_mask is not None and not remove_translation_and_rotation:
raise ValueError("fit_mask requires remove_translation_and_rotation=True")
cell, pbc, prepared_mic = _validate_endpoint_geometry(initial, final)
final_positions = final.positions
if remove_translation_and_rotation:
final_positions = align_batch_positions(
initial.positions,
final_positions,
initial.batch_idx,
initial.num_nodes_per_graph,
cell,
pbc,
fit_mask=fit_mask,
prepared_mic=prepared_mic,
skip_extra_checks=True,
).positions
endpoint_displacement = minimum_image_displacement(
final_positions - initial.positions,
initial.batch_idx,
cell,
pbc,
prepared=prepared_mic,
)
interpolation_target = initial.positions + endpoint_displacement
# Materialize every ragged path directly from segmented batch tensors.
image_counts_tensor = torch.tensor(
image_counts,
dtype=torch.long,
device=initial.device,
)
path_indices = torch.arange(
initial.num_graphs, dtype=torch.long, device=initial.device
)
image_to_path = torch.repeat_interleave(path_indices, image_counts_tensor)
image_starts = torch.cumsum(image_counts_tensor, dim=0) - image_counts_tensor
image_rank = (
torch.arange(image_to_path.numel(), device=initial.device)
- image_starts[image_to_path]
)
fractions = image_rank.to(initial.positions.dtype) / (
image_counts_tensor[image_to_path] - 1
).to(initial.positions.dtype)
discarded = {field for field, _ in initial if field not in _PATH_INPUT_FIELDS}
result = initial.index_select(image_to_path, drop=discarded)
# Dropping edge tensors alone retains their storage cardinality.
result._storage.groups.pop("edges", None)
output_graph = result.batch_idx.to(torch.long)
source_graph = image_to_path[output_graph]
output_node = torch.arange(
result.num_nodes, device=result.device
) - result.batch_ptr[output_graph].to(torch.long)
source_node = initial.batch_ptr[source_graph].to(torch.long) + output_node
start_positions = result.positions
target_positions = interpolation_target[source_node]
interpolated = start_positions + fractions[output_graph, None] * (
target_positions - start_positions
)
node_rank = image_rank[output_graph]
positions = torch.where((node_rank == 0)[:, None], start_positions, interpolated)
terminal = node_rank == image_counts_tensor[source_graph] - 1
positions = torch.where(terminal[:, None], final_positions[source_node], positions)
result.positions = positions
result.set_group_layout(image_to_path)
return result
__all__ = ["interpolate_paths"]