torchref.refinement.targets.geometry.planarity module

class torchref.refinement.targets.geometry.planarity.PlanarityTarget(model=None, verbose=0)

Bases: GeometryTarget

Planarity restraint target (Gaussian NLL).

For each planar group (e.g., aromatic rings, peptide planes), computes the distance of each atom from the best-fit plane.

The best-fit plane normal is found by eigendecomposition of the 3x3 covariance matrix of centered coordinates (eigh). The normal is detached from the computational graph so that gradients flow only through the deviation projection, not through the eigendecomposition. This is standard practice in crystallographic refinement (SHELXL, Phenix, Refmac) and is more numerically robust than differentiating through SVD — in particular it avoids NaN gradients when atoms are exactly coplanar.

Plane groups with <= 3 atoms are skipped since 3 coplanar points have zero deviation by construction and contribute no gradient signal.

NLL = 0.5 * (d_i / σ_i)² + log(σ_i) + 0.5 * log(2π)

where d_i is the distance of atom i from the best-fit plane.

name: str = 'geometry/planarity'

__init__(model=None, verbose=0)

Initialize model target.

Parameters:

• model (Model, optional) – Reference to the Model object (optional for empty init).

• verbose (int, optional) – Verbosity level. Default is 0.

forward()

Compute and return the loss. Override in subclasses.

stats()

Get planarity restraint statistics.