torchref.refinement.targets.geometry.non_bonded module

class torchref.refinement.targets.geometry.non_bonded.NonBondedTarget(model=None, mode='prolsq', sigma=0.3, r_exp=4.0, c_rep=None, buffer=0.0, rebuild_threshold=1.0, verbose=0, scale=10.0)

Bases: GeometryTarget

Non-bonded (van der Waals) restraint target using PROLSQ-style repulsion, parameterized as a generalized-Gaussian NLL on the overlap with scale \(\sigma\).

Per-pair NLL (mode='prolsq'):

\[\mathrm{NLL}(v) \;=\; \frac{v^{p}}{p\,\sigma^{p}} \;+\; \log\sigma \;+\; \tfrac{1}{2}\log(2\pi) \qquad v \;=\; \max\!\bigl(0,\, d_{\text{vdw}} + b - d\bigr)\]

where \(p = r_\text{exp}\) (default 4). The shape term \(v^p/(p\sigma^p)\) is algebraically identical to the classical PROLSQ energy \(c_{\text{rep}}\,v^p\) with \(c_{\text{rep}} = 1/(p\,\sigma^{p})\); exposing \(\sigma\) makes the physics legible (σ is an “effective tolerance” on the overlap) and puts the VDW loss on the same NLL footing as bond / angle / planarity.

Default sigma = 0.3 Å. A practical middle ground: stiff enough to reliably pull medium-large clashes (~0.4–0.5 Å) out of the refinement but loose enough that starting from a shaken or rough model doesn’t generate LBFGS-destabilising gradients. A 0.4 Å MolProbity clash sits at ~1.3σ and contributes ~0.8 NLL units; a 0.5 Å severe clash sits at ~1.7σ and contributes ~1.9 NLL units. The classical PROLSQ strength c_rep=16, r_exp=4 is equivalent to \(\sigma \approx 0.354\ \text{\AA}\), very close to this default. Set sigma explicitly for deliberate tightening (e.g. 0.13 Å → 3σ clash, ~20 NLL units) or loosening.

Alternative modes:

• 'prolsq': generalized-Gaussian NLL with exponent r_exp (default)

• 'gaussian': Gaussian NLL on the overlap using per-pair sigmas

• 'soft': soft repulsion with linear core outside threshold

When symmetry information is available (cell and spacegroup on the model), also handles contacts between ASU atoms and symmetry-related copies. Symmetry mate positions are recomputed on-the-fly from current ASU coordinates so that gradients flow to both atoms in each pair.

Reference: cctbx/geometry_restraints/nonbonded.h, PROLSQ documentation, MolProbity clash criterion (Davis et al., NAR 2007).

Parameters:

• model (Model, optional) – Reference to Model object.

• mode (str, optional) – Repulsion function type (‘prolsq’, ‘gaussian’, ‘soft’). Default is ‘prolsq’.

• sigma (float, optional) – Effective tolerance on the overlap in Angstroms. Default is 0.3.

• r_exp (float, optional) – Exponent of the repulsion term. Default is 4.0.

• c_rep (float, optional) – Back-door repulsion coefficient. If provided, overrides the sigma-derived value and the NLL becomes \(c_{\text{rep}} v^{r_\text{exp}} + \log\sigma + \tfrac{1}{2}\log(2\pi)\). Useful for reproducing legacy PROLSQ weights. Default is None (derive from sigma).

• buffer (float, optional) – Distance buffer in Angstroms added to VDW radii sum. Shifts the repulsion onset outward so atoms feel repulsion before they clash. Default is 0.0.

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

name: str = 'geometry/nonbonded'

__init__(model=None, mode='prolsq', sigma=0.3, r_exp=4.0, c_rep=None, buffer=0.0, rebuild_threshold=1.0, verbose=0, scale=10.0)

Initialize non-bonded target.

Parameters:

• model (Model, optional) – Reference to Model object.

• mode (str, optional) – Repulsion function type (‘prolsq’, ‘gaussian’, ‘soft’). Default is ‘prolsq’.

• sigma (float, optional) – Effective tolerance on the overlap (Å). Default 0.3. Only used when c_rep is None.

• r_exp (float, optional) – Repulsion exponent. Default is 4.0.

• c_rep (float or None, optional) – Legacy coefficient override. If None (default), derived from sigma as 1 / (r_exp * sigma ** r_exp).

• buffer (float, optional) – Distance buffer in Angstroms added to VDW radii sum. Default is 0.0.

• rebuild_threshold (float, optional) – Maximum ASU atom displacement in Angstroms since the last VDW pair-list build before maintenance() triggers a rebuild. Default is 1.0 Å — well inside the ~2.4 Å safety margin of the default 6.0 Å cutoff, so newly-formed contacts cannot slip through the list.

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

property c_rep: float

Get repulsion coefficient.

property sigma_vdw: float

Get the effective overlap tolerance sigma (Å).

property r_exp: float

Get repulsion exponent.

property buffer: float

Get distance buffer.

maintenance()

Rebuild the VDW pair list if any ASU atom drifted too far.

Fast path: one max().item() sync on the per-atom displacement norm between the current ASU coordinates and the snapshot taken at the last VDW build. If the max displacement stays within _rebuild_threshold we return immediately.

Slow path (only when triggered): delegate to restraints.rebuild_vdw_restraints which refreshes the pair list using the original build kwargs and updates the snapshot. See Target.maintenance() for the general contract.

Safety invariant: the default build cutoff (6.0 Å) leaves roughly cutoff - max_vdw_sum ≈ 2.4 Å of slack before a previously- non-contact atom pair could form a new clash. Setting rebuild_threshold < 2.4 / 2 = 1.2 Å guarantees that no such pair can slip through the list — that is, a rebuild fires before the slack is consumed.

forward()

Compute and return the loss. Override in subclasses.

get_violations(threshold=0.0)

Get information about VDW violations.

Parameters:

threshold (float, optional) – Only report violations greater than this (Å). Default is 0.0.

Returns:

Dictionary with ‘indices’, ‘violations’, ‘distances’, ‘min_distances’.

Return type:

dict

stats()

Get non-bonded restraint statistics.