torchref.refinement.targets.xray.base module

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