torchref.refinement.targets.geometry package

class torchref.refinement.targets.geometry.GeometryTarget(model=None, verbose=0, **kwargs)[source]

Bases: ModelTarget

Base class for geometry restraint targets.

Geometry targets access the model’s restraints property (built lazily) to compute losses for bonds, angles, torsions, planes, etc.

Parameters:

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

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

  • target_value (float, optional) – Target value for this loss. Default is -1.0.

  • sigma (float, optional) – Sigma parameter for weighting. Default is 0.5.

__init__(model=None, verbose=0, **kwargs)[source]

Initialize model target.

Parameters:

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

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

stats()[source]

Get statistics for this restraint type.

Returns dict with StatEntry values. Filter with filter_stats() at display time.

Returns:

Statistics dict with StatEntry values containing verbosity levels.

Return type:

dict

class torchref.refinement.targets.geometry.BondTarget(model=None, verbose=0)[source]

Bases: GeometryTarget

Bond length restraint target (Gaussian NLL).

NLL = 0.5 * ((d - d₀) / σ)² + log(σ) + 0.5 * log(2π)

name: str = 'geometry/bond'
__init__(model=None, verbose=0)[source]

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()[source]

Compute and return the loss. Override in subclasses.

stats()[source]

Get bond restraint statistics.

class torchref.refinement.targets.geometry.AngleTarget(model=None, verbose=0)[source]

Bases: GeometryTarget

Angle restraint target (Gaussian NLL).

NLL = 0.5 * ((θ - θ₀) / σ)² + log(σ) + 0.5 * log(2π)

name: str = 'geometry/angle'
__init__(model=None, verbose=0)[source]

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()[source]

Compute and return the loss. Override in subclasses.

stats()[source]

Get angle restraint statistics.

class torchref.refinement.targets.geometry.TorsionTarget(model=None, verbose=0, w_cis_proline=0.05, w_cis_general=0.0005)[source]

Bases: GeometryTarget

Torsion angle restraint target.

Handles all torsion restraints in one target:

  • Intra-residue & disulfide torsions: unimodal von Mises NLL with periodicity handling.

  • Omega (peptide bond) torsions: cis/trans von Mises mixture, so both cis and trans conformations are stable wells and the X-ray data decides which one to adopt.

Parameters:

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

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

  • w_cis_proline (float, optional) – Prior weight for cis conformation at pre-proline peptide bonds. Default 0.05 (~5% of X-Pro bonds are cis in the PDB).

  • w_cis_general (float, optional) – Prior weight for cis conformation at non-proline peptide bonds. Default 0.0005 (~0.05% of non-Pro bonds are cis in the PDB).

name: str = 'geometry/torsion'
__init__(model=None, verbose=0, w_cis_proline=0.05, w_cis_general=0.0005)[source]

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()[source]

Compute and return the loss. Override in subclasses.

stats()[source]

Get torsion angle statistics.

class torchref.refinement.targets.geometry.PlanarityTarget(model=None, verbose=0)[source]

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)[source]

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()[source]

Compute and return the loss. Override in subclasses.

stats()[source]

Get planarity restraint statistics.

class torchref.refinement.targets.geometry.ChiralTarget(model=None, verbose=0)[source]

Bases: GeometryTarget

Chiral volume restraint target.

Restrains the signed volume of tetrahedral chiral centers to maintain correct stereochemistry (R vs S configuration, L vs D amino acids).

The chiral volume is computed as:

V = v1 · (v2 × v3)

where vi = position of neighbor i - position of center.

For standard protein Cα atoms with ordering (N, C, CB): - L-amino acids: positive volume (~+2.5 ų) - D-amino acids: negative volume (~-2.5 ų)

The loss function penalizes deviations from the ideal signed volume:

NLL = 0.5 * ((V - V_ideal) / σ)² + log(σ) + 0.5 * log(2π)

For achiral centers (volume_sign=’both’), we restrain the absolute volume.

name: str = 'geometry/chiral'
__init__(model=None, verbose=0)[source]

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()[source]

Compute and return the loss. Override in subclasses.

get_violations(threshold=0.5)[source]

Get information about chiral volume violations.

Parameters:

threshold (float, optional) – Report deviations larger than this (ų). Default is 0.5.

Returns:

Dictionary with ‘indices’, ‘volumes’, ‘ideal_volumes’, ‘deviations’.

Return type:

dict

stats()[source]

Get chiral volume statistics.

class torchref.refinement.targets.geometry.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)[source]

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)[source]

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()[source]

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()[source]

Compute and return the loss. Override in subclasses.

get_violations(threshold=0.0)[source]

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()[source]

Get non-bonded restraint statistics.

class torchref.refinement.targets.geometry.NonBondedHTarget(model=None, mode='prolsq', sigma=0.3, r_exp=4.0, c_rep=None, buffer=0.0, rebuild_threshold=1.0, verbose=0)[source]

Bases: NonBondedTarget

Non-bonded target with transient riding hydrogen VDW contacts.

Drop-in replacement for NonBondedTarget. The heavy-heavy VDW loss is computed by the parent class; this subclass adds an H-VDW term from precomputed candidate H-heavy pairs.

Candidate pairs are derived at build time from the heavy-heavy VDW pair list. At forward time, only H placement + vectorized distance computation is needed — no spatial hashing.

Uses the same generalized-Gaussian NLL as the parent class; see NonBondedTarget for the sigma calibration.

Parameters:

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

  • mode (str, optional) – Repulsion function type. Default 'prolsq'.

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

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

  • c_rep (float or None, optional) – Legacy coefficient override; derived from sigma when None.

  • buffer (float, optional) – Distance buffer (Å). Default 0.0.

  • verbose (int, optional) – Verbosity level. Default 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)[source]

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.

forward()[source]

Compute and return the loss. Override in subclasses.

get_violations(threshold=0.0)[source]

Get violations including H-involving contacts.

stats()[source]

Get statistics including H-VDW contacts.

class torchref.refinement.targets.geometry.RamachandranTarget(model=None, verbose=0)[source]

Bases: GeometryTarget

Ramachandran restraint via pre-computed NLL surfaces.

Uses 6 residue-type-dependent NLL surfaces (general, glycine, cis-proline, trans-proline, pre-proline, ile/val) at 1-degree resolution. The loss is computed by bilinear interpolation of the NLL surface at the current (phi, psi) angles.

The surfaces store NLL = -log P(phi, psi | residue_type), so favored regions have low values and outlier regions have high values — consistent with all other geometry targets.

name: str = 'geometry/ramachandran'
__init__(model=None, verbose=0)[source]

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()[source]

Compute and return the loss. Override in subclasses.

stats()[source]

Get Ramachandran restraint statistics.

Submodules