torchref.refinement.targets.adp package

class torchref.refinement.targets.adp.ADPTarget(model=None, verbose=0, **kwargs)

Bases: ModelTarget

Base class for ADP restraint targets.

ADP targets access the model’s ADP values and restraints for similarity, rigid bond, and other ADP-related restraints.

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 1.0.

__init__(model=None, verbose=0, **kwargs)

Initialize model target.

Parameters:

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

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

class torchref.refinement.targets.adp.ADPSimilarityTarget(model=None, simu_sigma=2.0, verbose=0)

Bases: ADPTarget

ADP Similarity restraint (SIMU in Phenix/SHELX).

Restrains B-factors of bonded atoms to be similar. NLL = 0.5 * ((B_i - B_j) / σ)² + log(σ) + 0.5 * log(2π)

Tunable parameters (as buffers): - _simu_sigma: float, sigma for B-factor differences (default 2.0 Ų)

name: str = 'adp/simu'

__init__(model=None, simu_sigma=2.0, 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.

property simu_sigma: float

Get SIMU sigma value.

forward()

Compute and return the loss. Override in subclasses.

stats()

Get SIMU restraint statistics.

class torchref.refinement.targets.adp.RigidBondTarget(model=None, sigma=0.004, use_aniso=True, verbose=0)

Bases: ADPTarget

Rigid Bond restraint (DELU in SHELX, Hirshfeld test).

Based on Hirshfeld’s rigid bond test (Acta Cryst. A32, 239, 1976).

For a truly rigid bond, the mean-square displacement amplitudes (MSDA) of the two bonded atoms along the bond direction should be equal. This is because in a rigid bond, the atoms move together.

For anisotropic ADPs (U tensors):

z_12 = l_12^T U_1 l_12 / |l_12|²  (MSDA of atom 1 along bond)
z_21 = l_21^T U_2 l_21 / |l_21|²  (MSDA of atom 2 along bond)
Δz = z_12 - z_21 should be ~0

For isotropic B-factors, the difference in B_iso is used as a proxy:

ΔB = B_1 - B_2

This differs from SIMU (ADPSimilarityTarget) which restrains the full ADP tensors to be similar. Rigid bond only restrains the component along the bond direction.

Energy: E = w * Δz² NLL: NLL = 0.5 * (Δz / σ)² + log(σ) + 0.5 * log(2π)

References

• Hirshfeld, F.L. (1976). Acta Cryst. A32, 239.

• cctbx/adp_restraints/rigid_bond.h

Parameters:

• model (Model) – Reference to Model object.

• sigma (float, optional) – Target standard deviation for Δz. Default is 0.004 Ų. Hirshfeld found typical values of 0.001 Ų for good structures.

• use_aniso (bool, optional) – If True and model has anisotropic ADPs, use proper tensor calculation. Default is True.

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

name: str = 'adp/delu'

__init__(model=None, sigma=0.004, use_aniso=True, 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 rigid bond restraint.

For isotropic refinement, uses B-factor differences along bonds. For anisotropic refinement, computes proper MSDA differences.

get_delta_z_stats()

Get statistics of Δz values for analysis.

Returns:

Dictionary with mean, std, max, min of |Δz| values and Z-scores.

Return type:

dict

stats()

Get rigid bond restraint statistics.

Returns statistics including Δz values along bonds.

class torchref.refinement.targets.adp.ADPEntropyTarget(model=None, verbose=0)

Bases: ADPTarget

ADP Entropy regularization target.

Uses the model’s existing adp_kl_divergence_loss or similar.

name: str = 'adp/KL'

__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 KL divergence statistics.

class torchref.refinement.targets.adp.ADPLocalityTarget(model=None, k_neighbors=50, correlation_length=5.0, scale=5.0, exclude_bonded=True, verbose=0)

Bases: ADPTarget

Proximity-based ADP restraint using K nearest neighbors.

Uses a spatial cell-list (O(N) memory, O(N·k) time) instead of a full N×N distance matrix, so it scales to arbitrarily large structures without memory issues.

Parameters:

• model (Model) – Reference to Model object.

• k_neighbors (int, optional) – Number of nearest neighbors to consider. Default is 50.

• correlation_length (float, optional) – Distance scale for weight decay in Angstrom. Default is 5.0.

• scale (float, optional) – Scaling factor for loss magnitude. Default is 5.0.

• exclude_bonded (bool, optional) – Exclude directly bonded atoms. Default is True.

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

name: str = 'adp/locality'

__init__(model=None, k_neighbors=50, correlation_length=5.0, scale=5.0, exclude_bonded=True, 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.

property k_neighbors: int

property correlation_length: float

property scale: float

forward(recompute_neighbors=False)

Compute weighted MSE on log(B) differences with inverse-distance weights.

loss = scale * mean_ij [w_ij * (log(B_i) - log(B_j))^2] where w_ij = 1 / (d_ij + eps)

stats()

Get locality restraint statistics.

class torchref.refinement.targets.adp.ScalerURegularizationTarget(scaler, n_reflections, verbose=0)

Bases: Target

Pin the isotropic component of the scaler’s anisotropic U to zero.

F_scaled = scale · exp(-2π²·sᵀUs) · F_calc couples U into the same Debye-Waller slot as the atomic B-factors. The anisotropic deviatoric part of U encodes real directional attenuation in the data and should stay free. The isotropic part — the trace U11 + U22 + U33 — is a straight trade with a uniform atomic B shift and must be anchored so the atoms absorb the B-factor roll-off, not the scaler.

Penalty (tr U)² · N_ref / 6 — squared trace, scaled by the order of magnitude of the xray gradient on U. The / 6 matches the per-component gradient scaling the user originally requested.

name: str = 'adp/scaler_U'

__init__(scaler, n_reflections, verbose=0)

Initialize target.

Parameters:

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

forward()

Compute and return the loss. Override in subclasses.

stats()

class torchref.refinement.targets.adp.ScalerLogScaleTrendTarget(scaler, n_reflections, verbose=0)

Bases: Target

Pin out the Debye-Waller-like trend in the per-bin log_scale.

Per-bin scales exist to absorb localized data-quality issues — an outlier bin, a slightly mis-merged shell. They are not supposed to absorb the global resolution-dependent attenuation envelope; that is what atomic B-factors are for. A log_scale[i] ≈ a + b·s²[i] structure with nonzero b is exactly a B-factor masquerading as a per-bin scale: it shifts B_eff = B_atom − 4·b, letting atoms drift broader or sharper while the overall F_scaled amplitudes stay unchanged.

The target fits the least-squares slope of log_scale against the bin-mean |s|² and penalizes slope². The intercept a (the overall scale) is free. Residuals off the fit line are also free — those encode the outlier absorption the scales are supposed to do.

Penalty slope² · N_ref / nbins — the / nbins matches how xray gradient on a single log_scale[i] scales; the N_ref factor brings the total into xray’s order of magnitude.

name: str = 'adp/scaler_log_scale'

__init__(scaler, n_reflections, verbose=0)

Initialize target.

Parameters:

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

forward()

Compute and return the loss. Override in subclasses.

stats()

Submodules

• torchref.refinement.targets.adp.base module
  • ADPTarget
    • ADPTarget.__init__()
• torchref.refinement.targets.adp.entropy module
  • ADPEntropyTarget
    • ADPEntropyTarget.name
    • ADPEntropyTarget.__init__()
    • ADPEntropyTarget.forward()
    • ADPEntropyTarget.stats()
• torchref.refinement.targets.adp.locality module
  • ADPLocalityTarget
    • ADPLocalityTarget.name
    • ADPLocalityTarget.__init__()
    • ADPLocalityTarget.k_neighbors
    • ADPLocalityTarget.correlation_length
    • ADPLocalityTarget.scale
    • ADPLocalityTarget.forward()
    • ADPLocalityTarget.stats()
• torchref.refinement.targets.adp.rigid_bond module
  • RigidBondTarget
    • RigidBondTarget.name
    • RigidBondTarget.__init__()
    • RigidBondTarget.forward()
    • RigidBondTarget.get_delta_z_stats()
    • RigidBondTarget.stats()
• torchref.refinement.targets.adp.scaler_log_scale module
  • ScalerLogScaleTrendTarget
    • ScalerLogScaleTrendTarget.name
    • ScalerLogScaleTrendTarget.__init__()
    • ScalerLogScaleTrendTarget.forward()
    • ScalerLogScaleTrendTarget.stats()
• torchref.refinement.targets.adp.scaler_u module
  • ScalerURegularizationTarget
    • ScalerURegularizationTarget.name
    • ScalerURegularizationTarget.__init__()
    • ScalerURegularizationTarget.forward()
    • ScalerURegularizationTarget.stats()
• torchref.refinement.targets.adp.similarity module
  • ADPSimilarityTarget
    • ADPSimilarityTarget.name
    • ADPSimilarityTarget.__init__()
    • ADPSimilarityTarget.simu_sigma
    • ADPSimilarityTarget.forward()
    • ADPSimilarityTarget.stats()