torchref.base.reciprocal.interpolation module

Interpolation functions for reciprocal space grids.

These functions enable structure factor extraction at non-integer HKL positions, which is essential for rotation and translation searches in molecular replacement.

torchref.base.reciprocal.interpolation.interpolate_structure_factor_from_grid(reciprocal_grid, hkl_float, interpolate_amplitude=True)

Interpolate structure factors from reciprocal space grid at non-integer positions.

Parameters:

• reciprocal_grid (torch.Tensor) – Complex tensor of shape (Nx, Ny, Nz).

• hkl_float (torch.Tensor) – Non-integer HKL positions of shape (N, 3).

• interpolate_amplitude (bool, optional) – If True (default), interpolate amplitudes instead of complex values. This avoids phase cancellation issues where linear interpolation of complex numbers with different phases can give incorrect magnitudes (e.g., interpolating F=1 and F=-1 gives 0 instead of 1).

Returns:

Interpolated structure factors of shape (N,). If interpolate_amplitude=True, returns real-valued amplitudes. If interpolate_amplitude=False, returns complex values (use with caution).

Return type:

torch.Tensor

Notes

For a rotation R applied to the model, the structure factor at hkl becomes F(R^T @ hkl), so you would call this with hkl_float = hkl @ R.

WARNING: Complex interpolation (interpolate_amplitude=False) can give incorrect results when neighboring voxels have very different phases. For example, if F1 = A*exp(i*0) and F2 = A*exp(i*π), linear interpolation gives magnitude 0 at the midpoint instead of A. Use interpolate_amplitude=True for rotation functions where only magnitudes matter.

torchref.base.reciprocal.interpolation.interpolate_complex_from_grid(reciprocal_grid, hkl_float)

Interpolate complex structure factors from reciprocal space grid.

Unlike amplitude interpolation, this preserves phase information, which is essential for translation searches where phases are used to compute correlation functions.

Parameters:

• reciprocal_grid (torch.Tensor) – Complex tensor of shape (Nx, Ny, Nz).

• hkl_float (torch.Tensor) – Non-integer HKL positions of shape (N, 3).

Returns:

Interpolated complex structure factors of shape (N,).

Return type:

torch.Tensor

Notes

This function performs trilinear interpolation of complex values. For rotation-only searches (where only magnitudes matter), use interpolate_structure_factor_from_grid(interpolate_amplitude=True) instead.

For translation searches, complex interpolation is needed because the translation function depends on the phase relationship between F_obs and F_calc.

WARNING: Complex interpolation can give reduced magnitudes when neighboring voxels have very different phases. This is acceptable for translation searches where we’re computing correlation functions, but not for rotation searches.

torchref.base.reciprocal.interpolation.trilinear_interpolate_patterson(grid, points, chunk_size=10000000)

Memory-efficient trilinear interpolation on a 3D grid.

Pure torch implementation for GPU acceleration and gradient flow. Replaces scipy.ndimage.map_coordinates for torch tensors.

Parameters:

• grid (torch.Tensor) – 3D grid of values with shape (nx, ny, nz).

• points (torch.Tensor) – Coordinates to sample with shape (n_points, 3). Should be in fractional coordinates [0, 1) for ‘wrap’ mode. Or batch K, n_points, 3 for multiple batches.

• chunk_size (int, optional) – Number of points to process at once. Default is 1M.

Returns:

Interpolated values with shape (n_points,) or (batch, n_points).

Return type:

torch.Tensor

Notes

Supports automatic differentiation for gradient-based optimization. Uses chunked processing and in-place accumulation to reduce memory.

torchref.base.reciprocal.interpolation.interpolate_for_rotation(hkl, R, cell, reciprocal_space_grid)

Interpolate structure factors for rotated HKL positions. This works for all cells. :param hkl: HKL positions, shape (N, 3). :type hkl: torch.Tensor :param R: Rotation matrix, shape (B, 3, 3). :type R: torch.Tensor :param cell: Unit cell object with reciprocal_basis_matrix. :type cell: Cell :param reciprocal_space_grid: Reciprocal space grid of structure factors, shape (Nx, Ny, Nz). :type reciprocal_space_grid: torch.Tensor

Returns:

Interpolated structure factors, shape (B, N) / (N)

Return type:

torch.Tensor

torchref.base.reciprocal.interpolation.smooth_reciprocal_grid(reciprocal_grid, sigma, mode='amplitude_phase')

Apply Gaussian smoothing to a reciprocal space grid using native PyTorch.

Parameters:

• reciprocal_grid (torch.Tensor) – Complex tensor of shape (Nx, Ny, Nz).

• sigma (float) – Standard deviation of the Gaussian kernel in voxel units.

• mode (str, optional) –

  Smoothing mode. Options: - “amplitude_phase”: Smooth amplitude and phase separately using

  circular mean for phases. This avoids phase cancellation while preserving the relationship between amplitude and phase. Default.

  • ”amplitude_only”: Smooth only amplitudes, preserve original phases. Useful when phase accuracy is critical.

  • ”complex”: Smooth real and imaginary parts separately. WARNING: This can cause phase cancellation when neighboring voxels have different phases (e.g., averaging exp(i*0) and exp(i*π) gives 0).

Returns:

Smoothed reciprocal space grid of shape (Nx, Ny, Nz).

Return type:

torch.Tensor

Notes

Uses FFT-based convolution for efficient 3D Gaussian smoothing with periodic (wrap) boundary conditions.