torchref.refinement.targets.xray.bhattacharyya module

Bhattacharyya overlap X-ray target with first-principles model uncertainty.

Loss

For each reflection h:

L_h = (F_obs - |F_calc|)² / (4 · (σ_d² + σ_m²))

  • 0.5 · log( (σ_d² + σ_m²) / (2 σ_d σ_m) )

Total: L = Σ_h L_h.

sigma_m derivation

σ_m is derived from per-atom positional and B-factor uncertainty under the diagonal data-only Fisher information. Atoms are binned on a 2-D grid of (element type k, B-factor b). Within each element type the ITC92 scattering factor f_k(s) is a 1-D function of resolution.

Per-element Fisher-info sums (static — depend only on data and scattering):

f_k²(s_h) = ( Σ_m A_km · exp(-B_km · s_half_sq) )² g_w(k, b) = Σ_h (|s|² · f_k²(s_h) / <σ_d²>) · exp(-2 b · s_half_sq) g_4(k, b) = Σ_h (|s|⁴ · f_k²(s_h) / <σ_d²>) · exp(-2 b · s_half_sq)

Each refinement cycle, the current atomic B-factors are soft-histogrammed by element into hist[k, b]. Then:

σ_m²(h) = scale² · Σ_k f_k²(s_h) · [

3 · |s|² · (hist[k] / g_w(k)) @ exp_table_shared[:, h] (position)

  • s⁴ · (hist[k] / g_4(k)) @ exp_table_shared[:, h] (B-factor)

]

The outer f_k²(s_h) comes from forward propagation of Var(x_j, B_j) into F_calc. The f² inside g_w/g_4 cancels one of the two factors that arise from Var(x_j) ∝ 1/(f² · g), leaving the outer f_k² factor.

class torchref.refinement.targets.xray.bhattacharyya.BhattacharyyaXrayTarget(data=None, model=None, scaler=None, use_work_set=True, sigma_m_scale=1.0, b_grid_min=1.0, b_grid_max=200.0, b_grid_n=100, verbose=0, **kwargs)[source]

Bases: XrayTarget

X-ray target based on the Bhattacharyya overlap between data and model Gaussians.

Parameters:

  • data (ReflectionData, optional)

  • model (Model, optional)

  • scaler (Scaler, optional)

  • use_work_set (bool, optional) – Use work set (default) or test set for loss.

  • sigma_m_scale (float, optional) – Global multiplier applied to σ_m. Default 1.0.

  • b_grid_min (float, int, optional) – Log-spaced B-factor grid for σ_m computation. Default 1–200 Ų, 100 points.

  • b_grid_max (float, int, optional) – Log-spaced B-factor grid for σ_m computation. Default 1–200 Ų, 100 points.

  • b_grid_n (float, int, optional) – Log-spaced B-factor grid for σ_m computation. Default 1–200 Ų, 100 points.

  • verbose (int, optional)

__init__(data=None, model=None, scaler=None, use_work_set=True, sigma_m_scale=1.0, b_grid_min=1.0, b_grid_max=200.0, b_grid_n=100, verbose=0, **kwargs)[source]

Initialize X-ray target.

Parameters:

  • data (ReflectionData, optional) – Reference to the ReflectionData object. Required for forward().

  • model (Model or ModelFT, optional) – Reference to Model object for F_calc computation. If None, fcalc must be provided to forward().

  • scaler (Scaler, optional) – Reference to the Scaler object.

  • use_work_set (bool, optional) – If True, compute loss on work set; if False, on test set. Default is True.

  • sigma_mode (str, optional) –

    Which sigma to use in the likelihood. Options:

    • 'raw' (default): use the raw experimental sigmas from the data file. Empirically gives the best Rfree across the mid-resolution regime (1.5-3.0 A) when paired with appropriate group weights.

    • 'effective': use per-shell effective sigmas estimated from scaling residuals (capped SIGMAA-style correction). Opt-in for high-resolution refinement (< 1.5 A) or datasets with known sigma miscalibration. Note: Scaler.estimate_sigma_eff is always called so the estimates are available regardless of which mode the target uses.

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

forward(fcalc=None)[source]

Compute and return the loss. Override in subclasses.

stats(fcalc=None)[source]

Add σ_m/σ_d diagnostics (mean and max ratio over all reflections).