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
Batchcontaining 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]— displacementr_j - r_iin the same length unit asbatch.positions(Å). Fully differentiable w.r.t.batch.positionsandbatch.cell.- Return type:
Tensor
- Raises:
ValueError – If
atom_indicesis 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.pbcis 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 whenevercellandpbcare both present. Compiled callers must therefore supply a non-degenerate cell (or omit it entirely,cell=None) for non-periodic graphs.