Source code for nvalchemi.dynamics.mep._alignment

# 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.
"""Rigid-position alignment shared by reaction-path implementations."""

from __future__ import annotations

from typing import TYPE_CHECKING, NamedTuple

import torch
from torch import Tensor

from nvalchemi.dynamics.mep._geometry import minimum_image_displacement

if TYPE_CHECKING:
    from nvalchemi.dynamics.mep._geometry import PreparedMIC


[docs] class PositionAlignment(NamedTuple): """Result of aligning one or more sets of positions to references. Attributes ---------- positions : Tensor Aligned mobile positions. For non-periodic systems, these are obtained as ``mobile_positions @ rotation.T + translation``. For periodic systems, minimum-image positions are translated and ``rotation`` is simply identity. Shape ``(n_atoms, 3)``. rotation : Tensor Proper rotation applied to row-vector positions as ``positions @ rotation.T``, shape ``(3, 3)`` or ``(num_graphs, 3, 3)`` for a batch. The same transform can be applied to vector-valued state such as velocities. translation : Tensor Common translation applied after rotation, or after periodic images have been reconciled, shape ``(3,)`` or ``(num_graphs, 3)`` for a batch. """ positions: Tensor rotation: Tensor translation: Tensor
def _quaternion_rotation(covariance: Tensor) -> Tensor: """Return least-squares proper rotations using quaternion alignment [1]_. For each position cross-covariance, this constructs the symmetric ``4 x 4`` quaternion matrix, selects the eigenvector associated with its largest eigenvalue as the optimal quaternion, and converts that quaternion to a ``3 x 3`` rotation matrix. A zero covariance is assigned the identity rotation. The cross-covariance for each graph is ``sum_i (mobile_i - mobile_centroid) (reference_i - reference_centroid)^T``, where ``i`` indexes atoms and each parenthesized term is a three-dimensional vector. Parameters ---------- covariance : Tensor Position cross-covariance matrices with shape ``(..., 3, 3)``. References ---------- .. [1] M. Melander, K. Laasonen, and H. Jónsson, "Removing External Degrees of Freedom from Transition-State Search Methods Using Quaternions," *Journal of Chemical Theory and Computation*, 11(3), 1055-1062 (2015). https://doi.org/10.1021/ct501155k """ # Each component has shape ``covariance.shape[:-2]``, for example # ``(num_graphs,)`` for a batch of covariance matrices. r11, r12, r13 = covariance[..., 0, :].unbind(dim=-1) r21, r22, r23 = covariance[..., 1, :].unbind(dim=-1) r31, r32, r33 = covariance[..., 2, :].unbind(dim=-1) # Each inner stack has shape ``(..., 4)``; the outer stack is ``(..., 4, 4)``. quaternion_matrix = torch.stack( ( torch.stack((r11 + r22 + r33, r23 - r32, r31 - r13, r12 - r21), dim=-1), torch.stack((r23 - r32, r11 - r22 - r33, r12 + r21, r13 + r31), dim=-1), torch.stack((r31 - r13, r12 + r21, -r11 + r22 - r33, r23 + r32), dim=-1), torch.stack((r12 - r21, r13 + r31, r23 + r32, -r11 - r22 + r33), dim=-1), ), dim=-2, ) # torch.linalg.eigh synchronizes CUDA with the CPU. # This batched 4x4 solve therefore introduces a host synchronization # on each alignment call. quaternion = torch.linalg.eigh(quaternion_matrix).eigenvectors[..., :, -1] q0, q1, q2, q3 = quaternion.unbind(dim=-1) rotation = torch.stack( ( torch.stack( ( q0.square() + q1.square() - q2.square() - q3.square(), 2 * (q1 * q2 - q0 * q3), 2 * (q1 * q3 + q0 * q2), ), dim=-1, ), torch.stack( ( 2 * (q1 * q2 + q0 * q3), q0.square() - q1.square() + q2.square() - q3.square(), 2 * (q2 * q3 - q0 * q1), ), dim=-1, ), torch.stack( ( 2 * (q1 * q3 - q0 * q2), 2 * (q2 * q3 + q0 * q1), q0.square() - q1.square() - q2.square() + q3.square(), ), dim=-1, ), ), dim=-2, ) identity = torch.eye(3, dtype=covariance.dtype, device=covariance.device) return torch.where( (covariance.abs().amax(dim=(-2, -1)) == 0)[..., None, None], identity, rotation, ) def _validate_align_batch_positions_inputs( reference_positions: Tensor, mobile_positions: Tensor, batch_idx: Tensor, num_atoms_per_graph: Tensor, cell: Tensor | None, pbc: Tensor | None, ) -> None: """Validate structural inputs not guaranteed by the alignment calculation.""" # Validate the paired position tensors. if reference_positions.ndim != 2 or reference_positions.shape[-1] != 3: raise ValueError("reference_positions must have shape (total_atoms, 3)") if mobile_positions.shape != reference_positions.shape: raise ValueError( "mobile_positions must have the same shape as reference_positions" ) if reference_positions.shape[0] == 0: raise ValueError("position tensors must contain at least one atom") if ( not reference_positions.is_floating_point() or not mobile_positions.is_floating_point() ): raise TypeError("position tensors must use a floating-point dtype") if mobile_positions.dtype != reference_positions.dtype: raise ValueError("position tensors must use the same dtype") if mobile_positions.device != reference_positions.device: raise ValueError("position tensors must be on the same device") # Validate packed graph-batch metadata. integer_dtypes = { torch.uint8, torch.int8, torch.int16, torch.int32, torch.int64, } if batch_idx.ndim != 1 or batch_idx.shape[0] != reference_positions.shape[0]: raise ValueError("batch_idx must have shape (total_atoms,)") if batch_idx.dtype not in integer_dtypes: raise TypeError("batch_idx must use an integer dtype") if batch_idx.device != reference_positions.device: raise ValueError("batch_idx and positions must be on the same device") if num_atoms_per_graph.ndim != 1 or num_atoms_per_graph.shape[0] == 0: raise ValueError("num_atoms_per_graph must have shape (num_graphs,)") if num_atoms_per_graph.dtype not in integer_dtypes: raise TypeError("num_atoms_per_graph must use an integer dtype") if num_atoms_per_graph.device != reference_positions.device: raise ValueError("num_atoms_per_graph and positions must be on the same device") if torch.any(num_atoms_per_graph <= 0): raise ValueError("every graph must contain at least one atom") # Confirm atom memberships match the declared graph sizes. num_graphs = num_atoms_per_graph.shape[0] if torch.any(batch_idx < 0) or torch.any(batch_idx >= num_graphs): raise ValueError("batch_idx values must be in [0, num_graphs)") observed_counts = torch.bincount(batch_idx.to(torch.long), minlength=num_graphs) if not torch.equal(observed_counts, num_atoms_per_graph.to(torch.long)): raise ValueError("num_atoms_per_graph must agree with batch_idx") # Validate periodicity flags and cells used by periodic graphs. if pbc is not None: if pbc.shape != (num_graphs, 3): raise ValueError("pbc must have shape (num_graphs, 3)") if pbc.dtype != torch.bool: raise TypeError("pbc must use the bool dtype") if pbc.device != reference_positions.device: raise ValueError("pbc and positions must be on the same device") if cell is not None: if cell.shape != (num_graphs, 3, 3): raise ValueError("cell must have shape (num_graphs, 3, 3)") if cell.dtype != reference_positions.dtype: raise ValueError("cell and positions must use the same dtype") if cell.device != reference_positions.device: raise ValueError("cell and positions must be on the same device") if pbc is not None and torch.any(pbc) and cell is None: raise ValueError("A cell is required when any PBC axis is active")
[docs] def align_batch_positions( reference_positions: Tensor, mobile_positions: Tensor, batch_idx: Tensor, num_atoms_per_graph: Tensor, cell: Tensor | None = None, pbc: Tensor | None = None, fit_mask: Tensor | None = None, *, prepared_mic: PreparedMIC | None = None, skip_extra_checks: bool = False, ) -> PositionAlignment: """Align each mobile structure in a batch to its paired reference. Both position tensors contain one or more graphs in the same flattened node layout. ``batch_idx`` assigns each atom to a graph, and every mobile graph is aligned independently to the reference graph with the same index. Fully non-periodic graphs are independently centered and quaternion-rotated to minimize their unweighted, atom-wise Cartesian RMSD. An optional node mask can restrict the atoms used to fit each rigid transform, which is still applied to every atom. For graphs with any active periodic axis, rotation is disabled: per-atom displacements are mapped to their minimum images and the mean displacement of the selected atoms is removed. Neither ``reference_positions`` nor ``mobile_positions`` is modified. Parameters ---------- reference_positions : Tensor Flattened fixed target positions for all graphs, shape ``(total_atoms, 3)``. mobile_positions : Tensor Flattened positions to align using the same graph and atom ordering as ``reference_positions``, shape ``(total_atoms, 3)``. batch_idx : Tensor Integer graph membership for every atom, shaped ``(total_atoms,)``. num_atoms_per_graph : Tensor Number of atoms in each graph, shaped ``(num_graphs,)``. Every graph must contain at least one atom and the counts must agree with ``batch_idx``. cell : Tensor or None, optional Per-graph cell matrices shaped ``(num_graphs, 3, 3)``. Required for every graph with an active periodic axis. Selected periodic cell vectors must be linearly independent; unused rows may be singular. pbc : Tensor or None, optional Boolean periodicity flags shaped ``(num_graphs, 3)``. ``None`` means every graph is fully non-periodic. fit_mask : Tensor or None, optional Boolean node mask shaped ``(total_atoms,)``. Selected corresponding atom pairs determine the fitted transform for each graph, while that transform is applied to every atom. Every graph must select at least one atom. ``None`` selects every atom. prepared_mic : PreparedMIC or None, optional Reusable MIC data prepared for ``cell`` and ``pbc``. Supplying it avoids repeating cell-dependent lattice analysis. skip_extra_checks : bool, optional Skip structural checks for prevalidated batch inputs. The fitting mask is always validated. Default is false. Returns ------- PositionAlignment Aligned flat positions, per-graph rotations shaped ``(num_graphs, 3, 3)``, and per-graph translations shaped ``(num_graphs, 3)``. Periodic graphs have identity rotations. Raises ------ TypeError If positions are not floating point, graph metadata is not integer, or periodicity flags or ``fit_mask`` are not boolean. ValueError If shapes, graph membership, dtypes, devices, or periodic inputs are incompatible. """ if not skip_extra_checks: _validate_align_batch_positions_inputs( reference_positions, mobile_positions, batch_idx, num_atoms_per_graph, cell, pbc, ) num_graphs = num_atoms_per_graph.shape[0] graph_idx = batch_idx.to(torch.long) # Validate the optional fitting selection. if fit_mask is not None: if fit_mask.ndim != 1 or fit_mask.shape[0] != reference_positions.shape[0]: raise ValueError("fit_mask must have shape (total_atoms,)") if fit_mask.dtype != torch.bool: raise TypeError("fit_mask must use the bool dtype") if fit_mask.device != reference_positions.device: raise ValueError("fit_mask and positions must be on the same device") fit_counts = torch.zeros( num_graphs, dtype=torch.long, device=reference_positions.device ).index_add(0, graph_idx, fit_mask.to(torch.long)) if torch.any(fit_counts == 0): raise ValueError("fit_mask must select at least one atom in every graph") # Fit an independent rigid transform (translation and rotation) for each graph. if fit_mask is None: fit_weights = reference_positions.new_ones(reference_positions.shape[0]) fit_counts = num_atoms_per_graph.to(reference_positions.dtype).unsqueeze(-1) else: fit_weights = fit_mask.to(reference_positions.dtype) fit_counts = reference_positions.new_zeros((num_graphs, 1)).index_add( 0, graph_idx, fit_weights.unsqueeze(-1) ) # Both centroid tensors have shape ``(num_graphs, 3)``. reference_centroid = ( reference_positions.new_zeros((num_graphs, 3)).index_add( 0, graph_idx, reference_positions * fit_weights.unsqueeze(-1) ) / fit_counts ) mobile_centroid = ( mobile_positions.new_zeros((num_graphs, 3)).index_add( 0, graph_idx, mobile_positions * fit_weights.unsqueeze(-1) ) / fit_counts ) centered_reference = reference_positions - reference_centroid[graph_idx] centered_mobile = mobile_positions - mobile_centroid[graph_idx] # Per-atom outer products have shape ``(total_atoms, 3, 3)``. atom_covariance = ( centered_mobile.unsqueeze(-1) * centered_reference.unsqueeze(-2) * fit_weights[:, None, None] ) # Sum the contributions by graph to obtain shape ``(num_graphs, 3, 3)``. covariance = reference_positions.new_zeros((num_graphs, 3, 3)).index_add( 0, graph_idx, atom_covariance ) rotation = _quaternion_rotation(covariance) rotated_mobile_centroid = torch.bmm( rotation, mobile_centroid.unsqueeze(-1) ).squeeze(-1) translation = reference_centroid - rotated_mobile_centroid # Apply each graph’s fitted rotation and translation to all of its mobile atoms. aligned = ( torch.bmm(rotation[graph_idx], mobile_positions.unsqueeze(-1)).squeeze(-1) + translation[graph_idx] ) # Skip periodic image reconciliation when periodic inputs are absent. if cell is None or pbc is None: return PositionAlignment(aligned, rotation, translation) # Reconcile periodic images without rotating periodic graphs. periodic_graph = pbc.any(dim=-1) identity = torch.eye( 3, dtype=reference_positions.dtype, device=reference_positions.device ) displacement = minimum_image_displacement( mobile_positions - reference_positions, graph_idx, cell, pbc, prepared=prepared_mic, ) mean_displacement = ( reference_positions.new_zeros((num_graphs, 3)).index_add( 0, graph_idx, displacement * fit_weights.unsqueeze(-1) ) / fit_counts ) periodic_aligned = reference_positions + displacement - mean_displacement[graph_idx] aligned = torch.where( periodic_graph[graph_idx].unsqueeze(-1), periodic_aligned, aligned ) rotation = torch.where(periodic_graph[:, None, None], identity, rotation) translation = torch.where(periodic_graph[:, None], -mean_displacement, translation) return PositionAlignment(aligned, rotation, translation)
__all__ = ["PositionAlignment", "align_batch_positions"]