torchref.base.french_wilson module

PyTorch implementation of French-Wilson conversion from intensities to structure factors.

Reference: French, S. & Wilson, K. (1978). Acta Cryst. A34, 517-525 Based on Phenix implementation in cctbx/french_wilson.py

Usage - PyTorch Module (Recommended):

import torch
from french_wilson_pytorch import FrenchWilsonModule

# Miller indices for your reflections
hkl = torch.tensor([[1, 2, 3], [2, 0, 0], [0, 3, 0], [1, 1, 1]])

# Cell: [a, b, c, alpha, beta, gamma] in Å and degrees
cell = [50.0, 60.0, 70.0, 90.0, 90.0, 90.0]

# Create module (does all preprocessing)
fw_module = FrenchWilsonModule(hkl, cell, space_group='P212121')

# Apply conversion (can be called repeatedly with different I, sigma_I)
I = torch.tensor([100.0, 50.0, 30.0, 200.0])
sigma_I = torch.tensor([10.0, 8.0, 7.0, 15.0])
F, sigma_F = fw_module(I, sigma_I)
print(f"F = {F}")

Usage - Functional API (for one-off conversions):

from french_wilson_pytorch import french_wilson_auto

F, sigma_F, valid = french_wilson_auto(
    I, sigma_I, hkl, d_spacings, space_group='P212121'
)
torchref.base.french_wilson.interpolate_table(h, table, h_min=-4.0)[source]

Interpolate values from French-Wilson lookup table.

Parameters:

  • h (torch.Tensor) – Normalized parameter (tensor of any shape).

  • table (torch.Tensor) – Lookup table tensor (1D).

  • h_min (float, optional) – Minimum h value. Default is -4.0.

Returns:

Interpolated values (same shape as h).

Return type:

torch.Tensor

torchref.base.french_wilson.french_wilson_acentric(I, sigma_I, mean_intensity, h_min=-4.0, i_sig_min=-3.7)[source]

French-Wilson conversion for acentric reflections.

Parameters:

  • I (torch.Tensor) – Measured intensities (any shape).

  • sigma_I (torch.Tensor) – Standard deviations of intensities (same shape as I).

  • mean_intensity (torch.Tensor) – Mean intensity for each reflection’s resolution bin (same shape as I).

  • h_min (float, optional) – Minimum h value for rejection. Default is -4.0.

  • i_sig_min (float, optional) – Minimum I/sigma_I for rejection. Default is -3.7 (h_min + 0.3).

Returns:

  • F (torch.Tensor) – Structure factor amplitudes (same shape as I).

  • sigma_F (torch.Tensor) – Standard deviations of F (same shape as I).

  • valid_mask (torch.Tensor) – Boolean mask indicating valid (not rejected) reflections.

Return type:

tuple[Tensor, Tensor, Tensor]

torchref.base.french_wilson.french_wilson_centric(I, sigma_I, mean_intensity, h_min=-4.0, i_sig_min=-3.7)[source]

French-Wilson conversion for centric reflections.

Parameters:

  • I (torch.Tensor) – Measured intensities (any shape).

  • sigma_I (torch.Tensor) – Standard deviations of intensities (same shape as I).

  • mean_intensity (torch.Tensor) – Mean intensity for each reflection’s resolution bin (same shape as I).

  • h_min (float, optional) – Minimum h value for rejection. Default is -4.0.

  • i_sig_min (float, optional) – Minimum I/sigma_I for rejection. Default is -3.7 (h_min + 0.3).

Returns:

  • F (torch.Tensor) – Structure factor amplitudes (same shape as I).

  • sigma_F (torch.Tensor) – Standard deviations of F (same shape as I).

  • valid_mask (torch.Tensor) – Boolean mask indicating valid (not rejected) reflections.

Return type:

tuple[Tensor, Tensor, Tensor]

torchref.base.french_wilson.french_wilson(I, sigma_I, mean_intensity, is_centric=None, h_min=-4.0)[source]

French-Wilson conversion from intensities to structure factors.

Automatically handles both centric and acentric reflections.

Parameters:

  • I (torch.Tensor) – Measured intensities of shape (…).

  • sigma_I (torch.Tensor) – Standard deviations of intensities of shape (…).

  • mean_intensity (torch.Tensor) – Mean intensity for each reflection’s resolution bin of shape (…).

  • is_centric (torch.Tensor, optional) – Boolean mask indicating centric reflections of shape (…). If None, assumes all reflections are acentric.

  • h_min (float, optional) – Minimum h value for rejection. Default is -4.0.

Returns:

  • F (torch.Tensor) – Structure factor amplitudes of shape (…).

  • sigma_F (torch.Tensor) – Standard deviations of F of shape (…).

  • valid_mask (torch.Tensor) – Boolean mask indicating valid (not rejected) reflections of shape (…).

Return type:

tuple[Tensor, Tensor, Tensor]

Examples

I = torch.tensor([100.0, 5.0, -15.0, 200.0])
sigma_I = torch.tensor([10.0, 10.0, 10.0, 15.0])
mean_I = torch.tensor([80.0, 80.0, 80.0, 150.0])
F, sigma_F, valid = french_wilson(I, sigma_I, mean_I)
print(f"F = {F}")
torchref.base.french_wilson.is_centric_from_hkl(hkl, space_group='P1')[source]

Determine if reflections are centric based on Miller indices and space group.

Uses symmetry operations to check if reflections are invariant under inversion through the origin (Friedel mates). A reflection is centric if -h,-k,-l is symmetry equivalent to h,k,l.

Parameters:

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

  • space_group (str, int, or gemmi.SpaceGroup, optional) – Space group specification. Default is “P1”.

Returns:

Boolean mask of shape (…), True for centric reflections.

Return type:

torch.Tensor

torchref.base.french_wilson.get_centric_acentric_masks(hkl, space_group='P1')[source]

Get both centric and acentric masks for reflections.

Convenience function that returns both masks explicitly.

Parameters:

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

  • space_group (str, int, or gemmi.SpaceGroup, optional) – Space group specification. Default is “P1”.

Returns:

  • centric_mask (torch.Tensor) – Boolean mask of shape (…), True for centric reflections.

  • acentric_mask (torch.Tensor) – Boolean mask of shape (…), True for acentric reflections.

Return type:

tuple[Tensor, Tensor]

torchref.base.french_wilson.estimate_mean_intensity_by_resolution(I, d_spacings, n_bins=60, min_per_bin=40)[source]

Estimate mean intensity for each reflection based on resolution binning.

Uses linear interpolation between bin centers for smooth mean intensity estimates.

Parameters:

  • I (torch.Tensor) – Measured intensities of shape (n_reflections,).

  • d_spacings (torch.Tensor) – Resolution (d-spacing) for each reflection of shape (n_reflections,).

  • n_bins (int, optional) – Number of resolution bins. Default is 60.

  • min_per_bin (int, optional) – Minimum reflections per bin. Default is 40.

Returns:

Estimated mean intensity for each reflection of shape (n_reflections,).

Return type:

torch.Tensor

torchref.base.french_wilson.french_wilson_auto(I, sigma_I, hkl, d_spacings, space_group='P1', n_bins=60, min_per_bin=40, h_min=-4.0)[source]

Automatic French-Wilson conversion with binning and centric determination.

This function automatically: 1. Bins reflections by resolution 2. Calculates mean intensity per bin 3. Determines centric vs acentric from Miller indices 4. Applies appropriate French-Wilson conversion

Parameters:

  • I (torch.Tensor) – Measured intensities of shape (n_reflections,).

  • sigma_I (torch.Tensor) – Standard deviations of intensities of shape (n_reflections,).

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

  • d_spacings (torch.Tensor) – Resolution (d-spacing) for each reflection of shape (n_reflections,).

  • space_group (str, int, or gemmi.SpaceGroup, optional) – Space group specification. Default is “P1”.

  • n_bins (int, optional) – Number of resolution bins. Default is 60.

  • min_per_bin (int, optional) – Minimum reflections per bin. Default is 40.

  • h_min (float, optional) – Minimum h value for rejection. Default is -4.0.

Returns:

  • F (torch.Tensor) – Structure factor amplitudes of shape (n_reflections,).

  • sigma_F (torch.Tensor) – Standard deviations of F of shape (n_reflections,).

  • valid_mask (torch.Tensor) – Boolean mask indicating valid (not rejected) reflections.

Return type:

tuple[Tensor, Tensor, Tensor]

Examples

hkl = torch.tensor([[1, 2, 3], [2, 0, 0], [0, 3, 0], [1, 1, 1]])
I = torch.tensor([100.0, 50.0, 30.0, 200.0])
sigma_I = torch.tensor([10.0, 8.0, 7.0, 15.0])
d_spacings = torch.tensor([2.5, 3.0, 2.8, 2.0])
F, sigma_F, valid = french_wilson_auto(I, sigma_I, hkl, d_spacings, "P212121")
class torchref.base.french_wilson.FrenchWilson(hkl, cell, space_group='P1', n_bins=60, min_per_bin=40, h_min=-4.0, verbose=1)[source]

Bases: DeviceMixin, Module

PyTorch module for French-Wilson conversion from intensities to structure factors.

Pre-computes all necessary metadata (d-spacings, centric flags, resolution bins) during initialization, so forward pass only needs I and sigma_I.

Parameters:

  • hkl (torch.Tensor) – Miller indices of shape (n_reflections, 3), integer tensor.

  • cell (torch.Tensor) – Unit cell parameters [a, b, c, alpha, beta, gamma] in Å and degrees.

  • space_group (str, int, or gemmi.SpaceGroup, optional) – Space group specification (e.g., ‘P21’, 4, gemmi.SpaceGroup(‘P 21’)). Default is “P1”.

  • n_bins (int, optional) – Number of resolution bins for mean intensity estimation. Default is 60.

  • min_per_bin (int, optional) – Minimum reflections per bin. Default is 40.

  • h_min (float, optional) – Minimum h value for rejection. Default is -4.0.

  • verbose (int, optional) – Verbosity level (0=silent, 1=basic, 2=detailed). Default is 1.

hkl

Miller indices.

Type:

torch.Tensor

d_spacings

Resolution for each reflection in Å.

Type:

torch.Tensor

is_centric

Boolean mask for centric reflections.

Type:

torch.Tensor

Examples

hkl = torch.tensor([[1, 2, 3], [2, 0, 0], [0, 3, 0], [1, 1, 1]])
cell = [50.0, 60.0, 70.0, 90.0, 90.0, 90.0]
fw_module = FrenchWilson(hkl, cell, 'P212121')
I = torch.tensor([100.0, 50.0, 30.0, 200.0])
sigma_I = torch.tensor([10.0, 8.0, 7.0, 15.0])
F, sigma_F = fw_module(I, sigma_I)
__init__(hkl, cell, space_group='P1', n_bins=60, min_per_bin=40, h_min=-4.0, verbose=1)[source]
forward(I, sigma_I)[source]

Apply French-Wilson conversion.

Args:

I: Measured intensities, shape (n_reflections,) sigma_I: Standard deviations of intensities, shape (n_reflections,)

Returns:

F: Structure factor amplitudes, shape (n_reflections,) sigma_F: Standard deviations of F, shape (n_reflections,)