Source code for nvalchemi.enhanced_sampling.cv.pair_distance

# 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.
"""Differentiable pair-distance collective variable.

:func:`pair_distance` supports:

* Non-periodic systems (``batch.cell`` is ``None`` or ``batch.pbc`` is all
  ``False``).
* Periodic and mixed-periodic systems via the minimum-image convention (MIC)
  for **Minkowski-reduced** triclinic cells (see requirement below).

Scope: Minkowski-reduced MIC, not general triclinic MIC
--------------------------------------------------------
This is a **reduced-cell MIC implementation**.  It is *not* a general
triclinic MIC implementation.  The 27-image exhaustive search (offsets in
``{−1, 0, +1}³``) is correct only when the cell satisfies the Minkowski
reduction conditions.  For unreduced cells the minimum-image offset can
exceed ±1 in one or more fractional components, and the search silently
returns a longer-than-minimum image.

True general triclinic MIC (arbitrary unreduced cells, implemented via LLL
lattice reduction or an extended image search with a data-dependent radius)
is **not yet implemented** — its interaction with the strain-based virial
computation in :class:`ConservativeBias` adds non-trivial complexity.

Minkowski reduction condition
-----------------------------
For every pair of periodic lattice vectors ``(aᵢ, aⱼ)`` with ``i ≠ j``:

.. math::

    |\\mathbf{a}_i \\cdot \\mathbf{a}_j| \\le
    \\tfrac{1}{2}\\,\\min(|\\mathbf{a}_i|^2,\\,|\\mathbf{a}_j|^2)

When this fails, the search returns the wrong image.  Counter-example:
cell ``[[1,0,0],[10,0.1,0],[0,0,10]]``, fractional displacement
``[0,0.49,0]`` — the 27-image search returns ≈ 3.9 Å, but the true image
(offset ``[−5,0,0]``) is ≈ 0.11 Å.

:func:`pair_distance` checks this condition at call time **in eager mode
only** and raises ``ValueError`` for non-reduced cells.

.. warning::

    Under ``torch.compile`` the check is skipped (guarded by
    ``torch.compiler.is_compiling()``).  In compiled mode the caller is
    **solely responsible** for supplying Minkowski-reduced cells.  Passing
    an unreduced cell in compiled mode produces wrong distances with no
    error.  Pre-reduce cells with a Niggli or LLL algorithm (e.g.
    ``ASE: atoms.get_cell().niggli_reduce()``) before simulation.

Triclinic MIC algorithm
-----------------------
For a reduced cell with lattice matrix ``A`` (rows = lattice vectors,
ASE convention)::

    df          = (r_j − r_i) @ A⁻¹          # fractional displacement
    df_rounded  = df − round(df) × pbc_mask   # map to (−0.5, 0.5]
    candidates  = df_rounded + n,  n ∈ {−1,0,+1}³ × pbc_mask
    dr_mic      = argmin_n |candidates @ A|   # shortest image

torch.compile compatibility
---------------------------
Shape-based branches (periodicity, cell presence) resolve at trace time.
Gradient flow through ``pair_distance`` for use inside
:class:`ConservativeBias` is fully supported.  The Minkowski check and
bounds check are guarded by ``torch.compiler.is_compiling()`` and do not
appear in the compiled graph.
"""

from __future__ import annotations

from typing import TYPE_CHECKING

import torch
from torch import Tensor

if TYPE_CHECKING:
    from nvalchemi.data import Batch

__all__ = ["pair_displacement", "pair_distance"]


[docs] def pair_displacement(batch: Batch, atom_indices: Tensor) -> Tensor: """Differentiable pair distance(s) as a collective variable. Parameters ---------- batch: Current ``Batch`` containing atomic positions and (optionally) cell and PBC flags. When a periodic cell is present it must be **Minkowski-reduced** — see module docstring for details. atom_indices: * Shape ``[2]`` — selects the same atom pair ``(i, j)`` in every graph of the batch. * Shape ``[B, 2]`` — selects a different pair per graph. Indices are **local to each graph** (0-based within the graph, not global row indices in the batched position tensor). May live on any device; it is moved to the batch's device, so a CV closure built before the batch reaches the GPU still works. Returns ------- Tensor Shape ``[B, 3]`` — displacement ``r_j - r_i`` in the same length unit as ``batch.positions`` (Å). Fully differentiable w.r.t. ``batch.positions`` and ``batch.cell``. Raises ------ ValueError If ``atom_indices`` is not shape ``[2]`` or ``[B, 2]``, or is not an integer dtype (eager mode only). IndexError If any local atom index is negative or >= the graph's atom count (eager mode only). ValueError If any periodic cell is not Minkowski-reduced (eager mode only). This check is **skipped under** ``torch.compile``; see module docstring for the compiled-mode caller responsibility. Notes ----- Non-periodic graphs with an explicit cell In **eager mode**, MIC is skipped entirely when ``batch.pbc`` is all-False, so a degenerate cell (e.g. zeros) is safe. In **compiled mode**, ``bool(pbc.any())`` cannot be evaluated without a graph break, so MIC is entered whenever ``cell`` and ``pbc`` are both present. Compiled callers must therefore supply a non-degenerate cell (or omit it entirely, ``cell=None``) for non-periodic graphs. """ positions = batch.positions # [N_total, 3] batch_ptr = batch.batch_ptr # [B+1] B = batch.num_graphs # --- Eager-only shape / dtype check on atom_indices ------------------ # Must come BEFORE the dim()==1 broadcast so wrong shapes are caught, # not silently coerced. E.g. [1] would expand to [[0,0]] (self-pair) # and [B,3] would silently drop the third column. if not torch.compiler.is_compiling(): _validate_atom_indices(atom_indices, B) # --- Follow the batch's device --------------------------------------- # atom_indices names atoms; it is configuration, not data, so it is # normally built once — before the batch is moved to GPU — and closed over # by a CV lambda. Combining it with batch_ptr would then raise a bare # "expected all tensors to be on the same device" naming neither the CV # nor the fix. A no-op when it is already on the right device, and the # same treatment ConservativeBias gives its buffers. atom_indices = atom_indices.to(device=positions.device) # --- Resolve atom_indices to global row indices ----------------------- if atom_indices.dim() == 1: atom_indices = atom_indices.unsqueeze(0).expand(B, 2) # [B, 2] # --- Eager-only bounds validation ------------------------------------ if not torch.compiler.is_compiling(): # Bounds check: catch silent cross-graph wrapping before any indexing. atoms_per_graph = batch_ptr[1:] - batch_ptr[:-1] # [B] for col, label in ((0, "atom_indices[…, 0]"), (1, "atom_indices[…, 1]")): idx = atom_indices[:, col] neg = idx < 0 if neg.any(): bad = neg.nonzero(as_tuple=False).squeeze(-1).tolist() raise IndexError( f"pair_distance: {label} has negative values for graph(s) " f"{bad}: {idx[neg].tolist()}" ) oob = idx >= atoms_per_graph if oob.any(): bad = oob.nonzero(as_tuple=False).squeeze(-1).tolist() raise IndexError( f"pair_distance: {label} is out of range for graph(s) " f"{bad} — index {idx[oob].tolist()} >= " f"graph size {atoms_per_graph[oob].tolist()}" ) offsets = batch_ptr[:-1] # [B] global_i = offsets + atom_indices[:, 0] # [B] global_j = offsets + atom_indices[:, 1] # [B] pos_i = positions[global_i] # [B, 3] pos_j = positions[global_j] # [B, 3] dr = pos_j - pos_i # [B, 3], raw Cartesian displacement # --- Apply MIC for periodic systems ---------------------------------- has_cell = getattr(batch, "cell", None) is not None and batch.cell is not None has_pbc = getattr(batch, "pbc", None) is not None and batch.pbc is not None # In eager mode, also require at least one True pbc flag before calling # _apply_mic. Without this guard, a batch with cell=<degenerate> and # pbc=all-False would reach torch.linalg.inv and raise LinAlgError. # # In compiled mode, bool(pbc.any()) would force a data-dependent Python # branch that breaks fullgraph=True. We skip the guard there and rely # on pbc_mask (all-zeros for all-False pbc) to make the MIC computation # a mathematical identity for non-periodic graphs. Compiled callers # must therefore supply a non-degenerate cell (or cell=None) for # non-periodic graphs; a degenerate cell still causes LinAlgError. any_periodic = ( has_cell and has_pbc and (torch.compiler.is_compiling() or bool(batch.pbc.any())) ) if any_periodic: if not torch.compiler.is_compiling(): _check_minkowski_reduced(batch.cell, batch.pbc) dr = _apply_mic(dr, batch.cell, batch.pbc) return dr # [B, 3]
[docs] def pair_distance(batch: Batch, atom_indices: Tensor) -> Tensor: """Return the displacement between two atoms per graph, shape ``[B, 3]``. The vector ``r_j - r_i``, minimum-image corrected when the batch is periodic. :func:`pair_distance` is its norm; the vector form is what a method needs when it works with the CV *gradient* rather than the value — adaptive biasing force projects atomic forces onto it. The norm of :func:`pair_displacement`, which carries the validation, device handling, and minimum-image convention documented there. Parameters ---------- batch: Current ``Batch``; see :func:`pair_displacement`. atom_indices: Atom pair, shape ``[2]`` or ``[B, 2]``; see :func:`pair_displacement`. Returns ------- Tensor Pair distances in angstrom, shape ``[B, 1]``, differentiable with respect to ``batch.positions`` and ``batch.cell``. Raises ------ IndexError If an atom index is out of range for its graph. ValueError If *atom_indices* has the wrong shape or dtype, or if a periodic cell is not Minkowski-reduced (eager mode only). Examples -------- >>> import torch >>> from nvalchemi.enhanced_sampling import pair_distance >>> from nvalchemi.data import AtomicData, Batch >>> data = AtomicData( ... positions=torch.tensor([[0.0, 0.0, 0.0], [3.0, 4.0, 0.0]]), ... atomic_numbers=torch.ones(2, dtype=torch.long), ... ) >>> pair_distance(Batch.from_data_list([data]), torch.tensor([0, 1])) tensor([[5.]]) """ dr = pair_displacement(batch, atom_indices) return torch.linalg.vector_norm(dr, dim=-1, keepdim=True) # [B, 1]
# --------------------------------------------------------------------------- # atom_indices validation # --------------------------------------------------------------------------- _INTEGER_DTYPES = frozenset( { torch.int8, torch.int16, torch.int32, torch.int64, torch.uint8, } ) def _validate_atom_indices(atom_indices: Tensor, B: int) -> None: """Raise ``ValueError`` for malformed ``atom_indices`` (eager mode only). Accepted shapes --------------- * ``[2]`` — shared pair; broadcast to every graph. * ``[B, 2]`` — one pair per graph. Rejected (with clear error messages) ------------------------------------- * Wrong number of dimensions (not 1-D or 2-D). * 1-D tensor whose length is not exactly 2. A length-1 tensor such as ``torch.tensor([0])`` would otherwise silently expand to ``[[0, 0]]`` (a self-distance), not raise. * 2-D tensor whose second dimension is not exactly 2. A ``[B, 3]`` tensor would otherwise silently drop the third column. * 2-D tensor whose first dimension does not match the batch size ``B``. * Non-integer dtype. Float indices would silently be used as memory offsets after casting by the indexing operation. Parameters ---------- atom_indices: The tensor to validate. B: Number of graphs in the current batch. """ # dtype check if atom_indices.dtype not in _INTEGER_DTYPES: raise ValueError( f"pair_distance: atom_indices must have an integer dtype, " f"got {atom_indices.dtype}. Use e.g. torch.tensor([i, j]) " f"(default int64) or pass dtype=torch.long explicitly." ) ndim = atom_indices.dim() shape = tuple(atom_indices.shape) if ndim == 1: if shape[0] != 2: raise ValueError( f"pair_distance: 1-D atom_indices must have exactly 2 elements " f"(shape [2] for a shared pair), got shape {shape}. " f"A length-1 tensor would silently produce a self-distance." ) elif ndim == 2: if shape[1] != 2: raise ValueError( f"pair_distance: 2-D atom_indices must have shape [B, 2], " f"got {shape}. The second dimension must be exactly 2 " f"(atom i and atom j); extra columns are not allowed." ) if shape[0] != B: raise ValueError( f"pair_distance: 2-D atom_indices has shape {shape} but the " f"batch has B={B} graphs. The first dimension must equal B." ) else: raise ValueError( f"pair_distance: atom_indices must be 1-D (shape [2]) or " f"2-D (shape [B, 2]), got {ndim}-D tensor with shape {shape}." ) # --------------------------------------------------------------------------- # Minkowski-reduction check # --------------------------------------------------------------------------- def _check_minkowski_reduced(cell: Tensor, pbc: Tensor) -> None: """Raise ``ValueError`` if any periodic cell pair violates the Minkowski condition. This check is an **eager-mode guard only**. It is never called under ``torch.compile`` (guarded by ``torch.compiler.is_compiling()`` in the caller). Compiled callers are responsible for supplying reduced cells; no error is raised if a non-reduced cell is used in compiled mode. The 27-image MIC search returns the true minimum-image vector only for Minkowski-reduced cells. For every pair of periodic lattice vectors ``(aᵢ, aⱼ)`` with ``i ≠ j``: .. math:: |\\mathbf{a}_i \\cdot \\mathbf{a}_j| \\le \\tfrac{1}{2}\\,\\min(|\\mathbf{a}_i|^2,\\,|\\mathbf{a}_j|^2) When this fails, the minimum-image offset can exceed ±1 in some fractional component and the search silently returns the wrong image. Parameters ---------- cell: Lattice matrices, shape ``[B, 3, 3]`` or ``[B, 1, 3, 3]``. pbc: Periodicity flags, shape ``[B, 3]`` or ``[B, 1, 3]``. """ if cell.dim() == 4: cell = cell.squeeze(1) if pbc.dim() == 3: pbc = pbc.squeeze(1) for i in range(3): for j in range(i + 1, 3): # Only enforce for pairs of dimensions that are BOTH periodic. both_periodic = pbc[:, i] & pbc[:, j] # [B] bool if not both_periodic.any(): continue ai = cell[:, i, :] # [B, 3] aj = cell[:, j, :] # [B, 3] dot_abs = (ai * aj).sum(-1).abs() # [B] norm_sq_i = (ai * ai).sum(-1) # [B] norm_sq_j = (aj * aj).sum(-1) # [B] threshold = 0.5 * torch.minimum(norm_sq_i, norm_sq_j) # [B] violated = both_periodic & (dot_abs > threshold) if violated.any(): bad = violated.nonzero(as_tuple=False).squeeze(-1).tolist() raise ValueError( f"pair_distance: the cell for graph(s) {bad} is not " f"Minkowski-reduced: lattice vectors a[{i}] and a[{j}] satisfy " f"|a[{i}]·a[{j}]| > 0.5·min(|a[{i}]|², |a[{j}]|²). " f"The 27-image MIC search is only guaranteed correct for " f"Minkowski-reduced cells. Pre-reduce the cell using a Niggli " f"or LLL algorithm (e.g. ASE niggli_reduce) before simulation." ) # --------------------------------------------------------------------------- # MIC implementation # --------------------------------------------------------------------------- def _apply_mic(dr: Tensor, cell: Tensor, pbc: Tensor) -> Tensor: """Apply the minimum-image convention via an exhaustive 27-image search. Parameters ---------- dr: Cartesian displacement vectors, shape ``[B, 3]``. cell: Lattice matrices, shape ``[B, 3, 3]`` or ``[B, 1, 3, 3]``. Rows are lattice vectors (ASE convention). pbc: Periodicity flags per dimension, shape ``[B, 3]`` or ``[B, 1, 3]``. Returns ------- Tensor MIC-corrected displacement vectors, shape ``[B, 3]``. Notes ----- The cell must be Minkowski-reduced; see :func:`_check_minkowski_reduced`. That check is performed in :func:`pair_distance` before this function is called, so it is not repeated here. """ if cell.dim() == 4: cell = cell.squeeze(1) if pbc.dim() == 3: pbc = pbc.squeeze(1) pbc_mask = pbc.to(dtype=cell.dtype) # [B, 3] # Fractional displacement cell_inv = torch.linalg.inv(cell) # [B, 3, 3] df = torch.bmm(dr.unsqueeze(1), cell_inv).squeeze(1) # [B, 3] # Initial half-cell rounding (periodic dims only) df_rounded = df - torch.round(df) * pbc_mask # [B, 3] # Exhaustive 27-image search over offsets in {-1, 0, +1}³ coords = torch.tensor([-1.0, 0.0, 1.0], device=dr.device, dtype=dr.dtype) gi, gj, gk = torch.meshgrid(coords, coords, coords, indexing="ij") all_offsets = torch.stack( [gi.flatten(), gj.flatten(), gk.flatten()], dim=-1 ) # [27, 3] offsets_masked = all_offsets[None] * pbc_mask[:, None, :] # [B, 27, 3] df_cands = df_rounded[:, None, :] + offsets_masked # [B, 27, 3] dr_cands = torch.einsum("bki,bij->bkj", df_cands, cell) # [B, 27, 3] dist_sq = (dr_cands * dr_cands).sum(dim=-1) # [B, 27] best = dist_sq.argmin(dim=-1)[:, None, None].expand(-1, 1, 3) # [B, 1, 3] return dr_cands.gather(1, best).squeeze(1) # [B, 3]