torchref.refinement.targets.realspace module

Real-Space Targets for Crystallographic Refinement.

This module provides target (loss) functions that compare electron density maps in real space rather than reciprocal space. Two targets are provided:

  1. RealSpaceCorrelationTarget: Maximizes RSCC between 2mFo-DFc and Fcalc density

  2. RealSpaceDifferenceTarget: Minimizes mean squared Fo-Fc difference density

Both targets use a molecular mask (inverse of solvent mask) to restrict comparison to the protein region, and follow the phase detachment pattern from PhaseInformedDifferenceTarget to ensure correct gradient flow.

class torchref.refinement.targets.realspace.RealSpaceTarget(data=None, model=None, scaler=None, map_type='2mFo-DFc', mask_solvent=True, solvent_radius=1.1, erosion_radius=0.9, verbose=0, target_value=0.0, sigma=0.5)[source]

Bases: DataTarget

Base class for real-space electron density targets.

Inherits from DataTarget to get model, data, and scaler references. Provides common infrastructure for computing observed maps, model density, and molecular masks used by the concrete subclasses.

Gradient Flow Design

  • Model density: gradients flow through Fcalc -> grid -> IFFT -> density

  • Observed map (2mFo-DFc): phases and |Fcalc| detached, no gradients

  • Observed map (Fo-Fc): |Fcalc| retains gradients, phases detached

  • Molecular mask: boolean, no gradients

param data:

Observed reflection data.

type data:

ReflectionData

param model:

Model for computing Fcalc.

type model:

ModelFT

param scaler:

Scaler for Fcalc (applied before map coefficient computation).

type scaler:

Scaler, optional

param map_type:

"2mFo-DFc" or "Fo-Fc".

type map_type:

str

param mask_solvent:

Whether to apply molecular mask. Default True.

type mask_solvent:

bool

param solvent_radius:

Probe radius for mask dilation in Angstroms. Default 1.1.

type solvent_radius:

float

param erosion_radius:

Radius for mask erosion in Angstroms. Default 0.9.

type erosion_radius:

float

param verbose:

Verbosity level. Default 0.

type verbose:

int

param target_value:

Target value for loss. Default 0.0.

type target_value:

float

param sigma:

Sigma for weighting. Default 0.5.

type sigma:

float

VALID_MAP_TYPES = ('2mFo-DFc', 'Fo-Fc')
__init__(data=None, model=None, scaler=None, map_type='2mFo-DFc', mask_solvent=True, solvent_radius=1.1, erosion_radius=0.9, verbose=0, target_value=0.0, sigma=0.5)[source]

Initialize data 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, F_calc must be provided when calling forward().

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

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

update_mask()[source]

Explicitly recompute the molecular mask.

class torchref.refinement.targets.realspace.RealSpaceCorrelationTarget(data=None, model=None, scaler=None, mask_solvent=True, solvent_radius=1.1, erosion_radius=0.9, verbose=0)[source]

Bases: RealSpaceTarget

Real-space correlation coefficient (RSCC) target.

Computes RSCC between a 2mFo-DFc observed map and Fcalc model density within the molecular mask. The loss is 1 - RSCC.

The observed map uses detached model phases and amplitudes, so gradients flow only through the model density side.

Parameters:

  • data (ReflectionData) – Observed reflection data.

  • model (ModelFT) – Model for computing Fcalc.

  • scaler (Scaler, optional) – Scaler for Fcalc.

  • mask_solvent (bool) – Whether to apply molecular mask. Default True.

  • solvent_radius (float) – Probe radius for mask in Angstroms. Default 1.1.

  • erosion_radius (float) – Radius for mask erosion in Angstroms. Default 0.9.

  • verbose (int) – Verbosity level. Default 0.

name: str = 'realspace/correlation'
__init__(data=None, model=None, scaler=None, mask_solvent=True, solvent_radius=1.1, erosion_radius=0.9, verbose=0)[source]

Initialize data 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, F_calc must be provided when calling forward().

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

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

forward()[source]

Compute 1 - RSCC loss.

Returns:

Scalar loss value (1 - RSCC).

Return type:

torch.Tensor

stats()[source]

Get statistics for the correlation target.

Returns:

Dictionary with loss, rscc, and n_voxels.

Return type:

dict

class torchref.refinement.targets.realspace.RealSpaceDifferenceTarget(data=None, model=None, scaler=None, mask_solvent=True, solvent_radius=1.1, erosion_radius=0.9, verbose=0)[source]

Bases: RealSpaceTarget

Real-space Fo-Fc difference density target.

Computes the mean squared Fo-Fc difference density within the molecular mask. This penalizes unexplained features in the difference map.

The |Fcalc| component retains gradients while phases are detached, providing direct gradient signal for model refinement.

Parameters:

  • data (ReflectionData) – Observed reflection data.

  • model (ModelFT) – Model for computing Fcalc.

  • scaler (Scaler, optional) – Scaler for Fcalc.

  • mask_solvent (bool) – Whether to apply molecular mask. Default True.

  • solvent_radius (float) – Probe radius for mask in Angstroms. Default 1.1.

  • erosion_radius (float) – Radius for mask erosion in Angstroms. Default 0.9.

  • verbose (int) – Verbosity level. Default 0.

name: str = 'realspace/difference'
__init__(data=None, model=None, scaler=None, mask_solvent=True, solvent_radius=1.1, erosion_radius=0.9, verbose=0)[source]

Initialize data 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, F_calc must be provided when calling forward().

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

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

forward()[source]

Compute mean squared Fo-Fc difference density.

Returns:

Scalar loss value (mean squared difference density).

Return type:

torch.Tensor

stats()[source]

Get statistics for the difference target.

Returns:

Dictionary with loss, rms_diff, mean_abs_diff, peak values, and n_voxels.

Return type:

dict

class torchref.refinement.targets.realspace.RealSpaceExtrapolatedTarget(dataset_collection, model_dark=None, model_light=None, model_mixed=None, scaler_dark=None, scaler_mixed=None, scaler_light=None, mask_solvent=True, solvent_radius=1.1, erosion_radius=0.9, verbose=0)[source]

Bases: RealSpaceTarget

Real-space correlation target using extrapolated pure-light density.

Computes the RSCC between an extrapolated pure-light electron density map and the light model’s Fcalc density within the molecular mask. The loss is 1 - RSCC.

The extrapolation combines observed dark/light amplitudes with model-derived phases:

F_extra = (F_light * exp(i*phi_mixed) - w_dark * F_dark * exp(i*phi_dark)) / w_light

where w_dark, w_light are population fractions from the mixed model.

Parameters:

  • dataset_collection (DatasetCollection) – Collection containing ‘dark’ and ‘light’ datasets (aligned HKL).

  • model_dark (ModelFT) – Dark-state model (for dark phases).

  • model_light (ModelFT) – Light-state model (gradients flow through this model’s density).

  • model_mixed (MixedModel) – Mixed model (for mixed-state phases and population fractions).

  • scaler_dark (Scaler, optional) – Scaler for dark Fcalc.

  • scaler_mixed (Scaler, optional) – Scaler for mixed Fcalc.

  • scaler_light (Scaler, optional) – Scaler for light model Fcalc (model density side).

  • mask_solvent (bool, optional) – Whether to apply molecular mask. Default True.

  • solvent_radius (float, optional) – Probe radius for mask in Angstroms. Default 1.1.

  • erosion_radius (float, optional) – Radius for mask erosion in Angstroms. Default 0.9.

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

name: str = 'realspace_extrapolated'
__init__(dataset_collection, model_dark=None, model_light=None, model_mixed=None, scaler_dark=None, scaler_mixed=None, scaler_light=None, mask_solvent=True, solvent_radius=1.1, erosion_radius=0.9, verbose=0)[source]

Initialize data 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, F_calc must be provided when calling forward().

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

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

forward()[source]

Compute 1 - RSCC between extrapolated map and model density.

Returns:

Scalar loss value (1 - RSCC).

Return type:

torch.Tensor

stats()[source]

Get statistics for the extrapolated real-space target.

Returns:

Dictionary with loss, rscc, and n_voxels.

Return type:

dict