nvalchemi.enhanced_sampling.pair_displacement#

nvalchemi.enhanced_sampling.pair_displacement(batch, atom_indices)[source]#

Differentiable pair distance(s) as a collective variable.

Parameters:
  • batch (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 (Tensor) –

    • 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:

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.

Return type:

Tensor

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.