torchref.refinement.targets.xray package

class torchref.refinement.targets.xray.XrayTarget(data=None, model=None, scaler=None, use_work_set=True, sigma_mode='raw', verbose=0)[source]

Bases: DataTarget

Base class for X-ray targets.

Provides common functionality for accessing F_obs, F_calc, etc. Supports two modes of operation:

  1. With Model: Computes F_calc from model on each forward pass

  2. Without Model: Uses pre-computed F_calc passed to forward()/get_data()

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.

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

use_work_set

Whether to use work set or test set.

Type:

bool

__init__(data=None, model=None, scaler=None, use_work_set=True, sigma_mode='raw', verbose=0)[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.

name: str = 'xray'
reset_get_data_cache()[source]

Drop the cached bookkeeping tensors.

Call this if you mutate self._data.log_scale / self._data.U_aniso in-place outside of the normal fingerprint- tracked flow, or if you want to free the memory.

get_data(fcalc=None)[source]

Get F_obs, F_calc, sigma, and centric flags for the appropriate set.

Bookkeeping tensors (F_obs_sel, sigma_sel, mask, centric_sel) are cached and reused as long as the upstream scaling parameters (log_scale, U_aniso) of the ReflectionData haven’t been mutated. Only F_calc_sel is recomputed from the live fcalc on each call.

Parameters:

fcalc (torch.Tensor, optional) – Pre-computed structure factors. If provided, uses these instead of computing from model. Useful when model is not set.

Returns:

(F_obs_sel, F_calc_sel, sigma_sel, centric_sel, mask).

Return type:

tuple

stats(fcalc=None)[source]

Get statistics for this X-ray target.

Parameters:

fcalc (torch.Tensor, optional) – Pre-computed structure factors.

Returns:

Statistics dict with StatEntry values containing verbosity levels.

Return type:

dict

class torchref.refinement.targets.xray.GaussianXrayTarget(data=None, model=None, scaler=None, use_work_set=True, sigma_mode='raw', verbose=0)[source]

Bases: XrayTarget

Simple Gaussian NLL target for X-ray data.

NLL = 0.5*(F_obs - |F_calc|)²/σ² + log(σ) + 0.5*log(2π)

target_value: float = 1.0
forward(fcalc=None)[source]

Compute Gaussian NLL loss.

Parameters:

fcalc (torch.Tensor, optional) – Pre-computed structure factors. If provided, uses these instead of computing from model.

Returns:

Mean NLL loss value.

Return type:

torch.Tensor

class torchref.refinement.targets.xray.LeastSquaresXrayTarget(data=None, model=None, scaler=None, weighting='sigma', use_work_set=True, sigma_mode='raw', verbose=0)[source]

Bases: XrayTarget

Least Squares target function. L_LS = Σ w_i * (|F_obs| - k * |F_calc|)²

__init__(data=None, model=None, scaler=None, weighting='sigma', use_work_set=True, sigma_mode='raw', verbose=0)[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 least squares loss.

Parameters:

fcalc (torch.Tensor, optional) – Pre-computed structure factors. If provided, uses these instead of computing from model.

Returns:

Mean weighted least squares loss.

Return type:

torch.Tensor

class torchref.refinement.targets.xray.MaximumLikelihoodXrayTarget(data=None, model=None, scaler=None, use_work_set=True, sigma_mode='raw', verbose=0)[source]

Bases: XrayTarget

Maximum Likelihood target function with proper centric/acentric handling.

forward(fcalc=None)[source]

Compute maximum likelihood loss.

Parameters:

fcalc (torch.Tensor, optional) – Pre-computed structure factors. If provided, uses these instead of computing from model.

Returns:

Mean ML loss value.

Return type:

torch.Tensor

class torchref.refinement.targets.xray.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).

torchref.refinement.targets.xray.create_xray_target(data=None, model=None, scaler=None, mode='gaussian', use_work_set=True, sigma_mode='raw', sigma_m_scale=1.0, verbose=0, device=None)[source]

Factory function to create X-ray target.

Parameters:

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

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

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

  • mode (str, optional) – Target mode: ‘gaussian’, ‘ls’, or ‘ml’. Default is ‘gaussian’.

  • use_work_set (bool, optional) – Use work set (True) or test set (False). Default is True.

  • sigma_mode (str, optional) – ‘effective’ (default) to use per-shell effective sigmas from the scaler (SIGMAA-style, robust), or ‘raw’ to use raw experimental sigmas from the data file.

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

Returns:

Appropriate XrayTarget instance.

Return type:

XrayTarget

Submodules