torchref.io.datasets.fcalc_data module

FcalcDataset - Dataset for storing calculated structure factors.

This module provides a lightweight container for calculated structure factors (Fcalc) with support for: - Creation from cell/spacegroup/resolution - Complex Fcalc with amplitude/phase decomposition - MTZ file export

class torchref.io.datasets.fcalc_data.FcalcDataset(hkl=None, F=None, F_sigma=None, I=None, I_sigma=None, rfree_flags=None, resolution=None, bin_indices=None, outlier_flags=None, phase=None, fom=None, _centric_flags=None, E=None, E_squared=None, F_squared_corrected=None, U_aniso=None, radial_shell_indices=None, cell=None, spacegroup=None, device=<factory>, verbose=1, rfree_source=None, amplitude_source=None, intensity_source=None, phase_source=None, wilson_b=None, wilson_b_structure=None, wilson_b_solvent=None, wilson_k_sol=None, outlier_detection_params=None, fcalc=None, fcalc_amp=None, fcalc_phase=None)[source]

Bases: CrystalDataset

Dataset for storing calculated structure factors.

Provides a lightweight container for Fcalc values with: - Cell and spacegroup information (using torchref.symmetry types) - HKL indices and resolution - Complex Fcalc with amplitude/phase decomposition - MTZ export capability

This class inherits from CrystalDataset and overrides the spacegroup field to store torchref.symmetry.SpaceGroup instead of gemmi.SpaceGroup.

Parameters:

  • hkl (torch.Tensor, optional) – Miller indices of shape (N, 3).

  • resolution (torch.Tensor, optional) – Resolution per reflection of shape (N,).

  • cell (Cell, optional) – Unit cell object.

  • spacegroup (SpaceGroup, optional) – Space group object (torchref.symmetry.SpaceGroup).

  • fcalc (torch.Tensor, optional) – Complex structure factors of shape (N,).

  • fcalc_amp (torch.Tensor, optional) – Amplitudes |Fcalc| of shape (N,).

  • fcalc_phase (torch.Tensor, optional) – Phases in radians of shape (N,).

  • device (torch.device) – Device for tensors.

Examples

Create from cell and resolution:

from torchref.io.datasets import FcalcDataset

dataset = FcalcDataset.from_cell_and_resolution(
    cell=[50.0, 60.0, 70.0, 90.0, 90.0, 90.0],
    spacegroup='P212121',
    d_min=2.0,
)

# Set Fcalc values (complex tensor)
fcalc = torch.randn(len(dataset), dtype=torch.complex64)
dataset.set_fcalc(fcalc)

# Write to MTZ
dataset.write_mtz('output.mtz')
spacegroup: SpaceGroup | None = None
fcalc: Tensor | None = None
fcalc_amp: Tensor | None = None
fcalc_phase: Tensor | None = None
static from_cell_and_resolution(cell, spacegroup, d_min=2.0, d_max=None, device=device(type='cpu'), dtype=torch.float32)[source]

Create FcalcDataset with HKL generated to given resolution.

Parameters:

  • cell (torch.Tensor, list, or Cell) – Unit cell [a, b, c, alpha, beta, gamma] or Cell object.

  • spacegroup (SpaceGroupLike) – Space group (str, int, gemmi.SpaceGroup, or torchref.symmetry.SpaceGroup).

  • d_min (float, optional) – High resolution limit in Angstroms. Default is 2.0.

  • d_max (float, optional) – Low resolution limit in Angstroms. If provided, reflections with d-spacing > d_max are removed.

  • device (torch.device) – Target device.

  • dtype (torch.dtype) – Float dtype for tensors.

Returns:

New dataset with HKL and resolution populated.

Return type:

FcalcDataset

Examples

from torchref.symmetry import Cell, SpaceGroup

cell = Cell([50.0, 60.0, 70.0, 90.0, 90.0, 90.0])
sg = SpaceGroup('P212121')
dataset = FcalcDataset.from_cell_and_resolution(
    cell=cell, spacegroup=sg, d_min=2.0,
)
print(f"Generated {len(dataset)} reflections")
set_fcalc(fcalc)[source]

Assign complex Fcalc values.

Automatically computes amplitude and phase from complex values.

Parameters:

fcalc (torch.Tensor) – Complex structure factors with shape (N,).

Raises:

ValueError – If fcalc length doesn’t match HKL length.

Examples

# Create complex Fcalc values
fcalc = torch.randn(len(dataset), dtype=torch.complex64)
dataset.set_fcalc(fcalc)

print(dataset.fcalc_amp[:5])   # Amplitudes
print(dataset.fcalc_phase[:5]) # Phases in radians
write_mtz(filepath)[source]

Write Fcalc to MTZ file.

Parameters:

filepath (str) – Output MTZ filename.

Raises:

ValueError – If no Fcalc values have been set.

Examples

dataset.set_fcalc(fcalc_values)
dataset.write_mtz('calculated.mtz')
write_mtz_as_fobs(filepath, sigma_frac=0.05, f_column='F-obs', sigf_column='SIGF-obs', phase_column='PHIF-model')[source]

Write Fcalc to MTZ as if it were observed data (F-obs columns).

Useful for creating simulated “experimental” MTZ files that can be read back by ReflectionData.load_mtz() as observed amplitudes.

Parameters:

  • filepath (str) – Output MTZ filename.

  • sigma_frac (float, optional) – Sigma as a fraction of |F|. Default is 0.05 (5%).

  • f_column (str, optional) – Column name for amplitudes. Default is ‘F-obs’.

  • sigf_column (str, optional) – Column name for sigma. Default is ‘SIGF-obs’.

  • phase_column (str, optional) – Column name for model phases. Default is ‘PHIF-model’.

Examples

dataset.set_fcalc(fcalc_values)
dataset.write_mtz_as_fobs('simulated_obs.mtz', sigma_frac=0.05)
__repr__()[source]

String representation of dataset.

property spacegroup_name: str | None

Get space group name as string (short form, e.g., ‘P212121’).

property spacegroup_hm: str | None

Get space group Hermann-Mauguin name with spaces (e.g., ‘P 21 21 21’).

property spacegroup_number: int | None

Get space group number (1-230).

__init__(hkl=None, F=None, F_sigma=None, I=None, I_sigma=None, rfree_flags=None, resolution=None, bin_indices=None, outlier_flags=None, phase=None, fom=None, _centric_flags=None, E=None, E_squared=None, F_squared_corrected=None, U_aniso=None, radial_shell_indices=None, cell=None, spacegroup=None, device=<factory>, verbose=1, rfree_source=None, amplitude_source=None, intensity_source=None, phase_source=None, wilson_b=None, wilson_b_structure=None, wilson_b_solvent=None, wilson_k_sol=None, outlier_detection_params=None, fcalc=None, fcalc_amp=None, fcalc_phase=None)