torchref.model.sf_ds module

SfDS - Structure Factor calculation via Direct Summation.

This module provides a PyTorch nn.Module that handles: - Direct summation structure factor calculations - Support for both isotropic and anisotropic atoms - Crystallographic symmetry handling

The SfDS class provides an alternative to SfFFT for computing structure factors without requiring a grid-based FFT approach.

class torchref.model.sf_ds.SfDS(cell=None, spacegroup=None, dtype_float=torch.float32, device=device(type='cpu'), verbose=0, max_memory_gb=2.0)[source]

Bases: DeviceMixin, Module

Structure Factor calculator using Direct Summation.

This module computes structure factors by directly summing atomic contributions without building an intermediate electron density map. It is initialized with a Cell and optionally a SpaceGroup.

Includes automatic batching to handle memory constraints for large structures or high-resolution data.

Parameters:

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

  • spacegroup (SpaceGroupLike, optional) – Space group specification (string, int, or gemmi.SpaceGroup). If None, defaults to P1.

  • dtype_float (torch.dtype, optional) – Data type for floating point tensors. Default is dtypes.float.

  • device (torch.device, optional) – Computation device. Defaults to the configured device.current.

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

  • max_memory_gb (float, optional) – Maximum memory to use for intermediate tensors in GB. Default is 2.0. Set to None to disable batching.

cell

Unit cell object.

Type:

Cell

spacegroup

Space group object (SpaceGroup nn.Module with matrices and translations).

Type:

SpaceGroup

Examples

Standalone usage:

from torchref.symmetry import Cell
cell = Cell([50, 60, 70, 90, 90, 90])
sf_ds = SfDS(cell, spacegroup='P212121')
sf, _ = sf_ds.compute_structure_factors(
    hkl, xyz_iso, adp_iso, occ_iso, A_iso, B_iso
)

With memory limit for large structures:

sf_ds = SfDS(cell, spacegroup='P212121', max_memory_gb=4.0)
sf, _ = sf_ds.compute_structure_factors(...)  # Auto-batches if needed

Notes

Key differences from SfFFT: - No grid setup required - No build_density_map() or map_to_structure_factors() methods - Computes scattering factors internally from A/B ITC92 coefficients - Returns (sf, None) instead of (sf, density_map) - Automatic batching for memory management

__init__(cell=None, spacegroup=None, dtype_float=torch.float32, device=device(type='cpu'), verbose=0, max_memory_gb=2.0)[source]

Initialize the SfDS module with cell and spacegroup.

Parameters:

  • cell (Cell, optional) – Unit cell object. If None, must be set later.

  • spacegroup (SpaceGroupLike, optional) – Space group specification. If None, defaults to P1.

  • dtype_float (torch.dtype, optional) – Data type for floating point tensors. Default is dtypes.float.

  • device (torch.device, optional) – Computation device. Defaults to the configured device.current.

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

  • max_memory_gb (float, optional) – Maximum memory for intermediate tensors in GB. Default is 2.0.

property cell: Cell | None

Unit cell object.

property spacegroup: SpaceGroup | None

Space group object (SpaceGroup nn.Module).

property fractional_matrix: Tensor | None

Get fractionalization matrix from cell.

property inv_fractional_matrix: Tensor | None

Get orthogonalization matrix from cell.

set_cell_and_spacegroup(cell, spacegroup=None)[source]

Set cell and spacegroup for this SfDS instance.

Parameters:

  • cell (Cell) – Unit cell object.

  • spacegroup (SpaceGroupLike, optional) – Space group specification.

compute_structure_factors(hkl, xyz_iso, adp_iso, occ_iso, A_iso, B_iso, xyz_aniso=None, u_aniso=None, occ_aniso=None, A_aniso=None, B_aniso=None, apply_symmetry=True)[source]

Compute structure factors from atomic parameters using direct summation.

Uses “late symmetry” approach (same as SfFFT): first computes P1 structure factors at symmetry-equivalent HKLs, then combines them with phase shifts.

The symmetry formula is:

F_sym(h) = Σ_ops exp(2πi h.t) * F_P1(R^T @ h)

Parameters:

  • hkl (torch.Tensor) – Miller indices with shape (n_reflections, 3).

  • xyz_iso (torch.Tensor) – Isotropic atom coordinates (Cartesian) with shape (n_iso, 3).

  • adp_iso (torch.Tensor) – Isotropic ADPs (atomic displacement parameters) with shape (n_iso,).

  • occ_iso (torch.Tensor) – Isotropic occupancies with shape (n_iso,).

  • A_iso (torch.Tensor) – ITC92 A parameters for isotropic atoms with shape (n_iso, 5).

  • B_iso (torch.Tensor) – ITC92 B parameters for isotropic atoms with shape (n_iso, 5).

  • xyz_aniso (torch.Tensor, optional) – Anisotropic atom coordinates (Cartesian) with shape (n_aniso, 3).

  • u_aniso (torch.Tensor, optional) – Anisotropic U parameters with shape (n_aniso, 6).

  • occ_aniso (torch.Tensor, optional) – Anisotropic occupancies with shape (n_aniso,).

  • A_aniso (torch.Tensor, optional) – ITC92 A parameters for anisotropic atoms with shape (n_aniso, 5).

  • B_aniso (torch.Tensor, optional) – ITC92 B parameters for anisotropic atoms with shape (n_aniso, 5).

  • apply_symmetry (bool, optional) – If True, apply crystallographic symmetry. Default is True.

Returns:

  • sf (torch.Tensor) – Complex structure factors with shape (n_reflections,).

  • None – Second return value is None (for API compatibility with SfFFT).

Return type:

Tuple[Tensor, None]

reset_cache()[source]

Drop the cached reciprocal-basis matrix; recomputed on next use.

copy()[source]

Create a deep copy of this SfDS module.

Returns:

A new SfDS instance with cloned cell and spacegroup.

Return type:

SfDS