torchref.refinement.targets.adp.rigid_bond module

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

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)[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 rigid bond restraint.

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

get_delta_z_stats()[source]

Get statistics of Δz values for analysis.

Returns:

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

Return type:

dict

stats()[source]

Get rigid bond restraint statistics.

Returns statistics including Δz values along bonds.