Source code for nvalchemi.dynamics.mep.validate
# 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.
"""Validation helpers for reaction-path batches."""
from __future__ import annotations
from typing import TYPE_CHECKING
import torch
if TYPE_CHECKING:
from nvalchemi.data import Batch
# Cells may acquire small floating-point differences through dtype conversion or
# serialization. These tolerances accept numerical noise without treating a
# physically different lattice as the same path cell.
_CELL_RTOL = 1e-5
_CELL_ATOL = 1e-6
[docs]
def validate_paths(batch: Batch) -> None:
"""Read-only validation of grouped image paths for path-related calculations.
Each group in the batch is interpreted as one path. A valid path contains
at least three images, with the same number and ordering of atoms in every
image. Periodic images must also have consistent cells and periodic-boundary
settings within each path. A missing ``pbc`` field means that every image is
nonperiodic. This function never adds fields to or otherwise mutates the
batch.
Parameters
----------
batch : Batch
Grouped batch whose graphs are the images along one or more paths.
Raises
------
ValueError
If the batch has no group layout, paths, or atomic numbers; a path has
fewer than three images; or the images in a path do not have matching
atoms, cells, or periodic-boundary settings.
"""
if "atomic_numbers" not in batch:
raise ValueError("Reaction paths require atomic_numbers")
layout = batch.group_layout
if layout.num_groups == 0:
raise ValueError("A reaction-path batch requires at least one path")
if torch.any(layout.num_graphs_per_group < 3):
raise ValueError("Every reaction path must contain at least three images")
cells = batch.cell if "cell" in batch else None
pbcs = batch.pbc if "pbc" in batch else None
if cells is not None and cells.shape != (batch.num_graphs, 3, 3):
raise ValueError(
f"cell must have shape ({batch.num_graphs}, 3, 3), got {tuple(cells.shape)}"
)
if pbcs is not None and pbcs.shape != (batch.num_graphs, 3):
raise ValueError(
f"pbc must have shape ({batch.num_graphs}, 3), got {tuple(pbcs.shape)}"
)
if cells is None and pbcs is not None and torch.any(pbcs):
raise ValueError("Periodic paths require a cell")
# Generate `first_image` with shape (num_graphs,)
first_image = layout.group_ptr[layout.group_idx]
counts = batch.num_nodes_per_graph
if not torch.all(counts == counts[first_image]):
raise ValueError("All images in a reaction path must have the same atom count")
if pbcs is not None and not torch.all(pbcs == pbcs[first_image]):
raise ValueError(
"All images in a reaction path must have identical PBC settings"
)
if cells is not None and not torch.all(
torch.isclose(
cells,
cells[first_image],
rtol=_CELL_RTOL,
atol=_CELL_ATOL,
)
):
raise ValueError("All images in a reaction path must have the same cell")
node_image = batch.batch_idx.long()
node_rank = (
torch.arange(batch.num_nodes, device=batch.device)
- batch.batch_ptr[node_image].long()
)
first_node = batch.batch_ptr[layout.group_ptr[layout.node_to_group]].long()
reference_node = first_node + node_rank
if not torch.equal(batch.atomic_numbers, batch.atomic_numbers[reference_node]):
raise ValueError(
"All images in a reaction path must have identical atomic numbers"
)