nvalchemi.enhanced_sampling.periodic_difference#

nvalchemi.enhanced_sampling.periodic_difference(values, centers, periods=None)[source]#

Return values - centers, wrapped into (-period/2, period/2].

A dihedral restrained at +3.0 rad must not see a configuration at -3.0 rad as 6.0 rad away; the true separation is 0.28 rad the other way round. Taking a raw difference makes the restraint pull the long way round the circle, which is both wrong and violently discontinuous at the branch cut.

Parameters:
  • values (Tensor) – Current CV values, shape [B, D].

  • centers (Tensor) – Reference values, shape [B, D] (or broadcastable to it).

  • periods (Tensor | None) – Period per CV component, shape [D]. A component whose period is 0 (or non-finite) is treated as non-periodic and its difference is returned unwrapped. None means every component is non-periodic.

Returns:

Wrapped difference, shape [B, D].

Return type:

Tensor

Notes

Differentiability

round has zero gradient almost everywhere, so the wrap contributes nothing to d(delta)/d(values) — the derivative is the same as for an unwrapped difference, which is what a harmonic restraint needs. The wrap is discontinuous exactly at delta = period/2, the antipode of the center; that is inherent to a periodic CV, not an artefact here.