torchref.symmetry.map_symmetry_interpolation module

Map-level symmetry operations for electron density maps.

This module provides efficient symmetry operations applied directly to density maps, which is much faster than applying symmetry to individual atoms.

class torchref.symmetry.map_symmetry_interpolation.MapSymmetry(space_group, map_shape, cell_params, dtype_float=torch.float32, verbose=1, device=device(type='cpu'))

Bases: DeviceMixin, Module

Applies crystallographic symmetry operations to electron density maps.

This class handles space group symmetry by:

1. Taking a density map calculated for the asymmetric unit

2. Applying rotation and translation operations in fractional coordinates

3. Interpolating the transformed maps

4. Summing all symmetry-related maps

This is much more efficient than generating symmetry mates for each atom and recalculating density.

space_group

Space group name.

Type:

str

map_shape

Shape of the density map (nx, ny, nz).

Type:

tuple of int

cell_params

Unit cell parameters.

Type:

numpy.ndarray

symmetry

Symmetry operations handler.

Type:

Symmetry

n_ops

Number of symmetry operations.

Type:

int

Examples

map_sym = MapSymmetry(space_group='P21', map_shape=(64, 64, 64), cell_params=cell)
asymmetric_map = model.build_density_map()
symmetric_map = map_sym(asymmetric_map)

__init__(space_group, map_shape, cell_params, dtype_float=torch.float32, verbose=1, device=device(type='cpu'))

Initialize map symmetry operator.

Parameters:

• space_group (str) – Space group name (e.g., ‘P1’, ‘P21’, ‘P-1’, etc.).

• map_shape (tuple of int) – Shape of the density map (nx, ny, nz).

• cell_params (array-like, shape (6,)) – Unit cell parameters [a, b, c, alpha, beta, gamma] in Å and degrees.

• dtype_float (torch.dtype, default torch.float32) – Floating point precision to use.

• verbose (int, default 1) – Verbosity level.

• device (torch.device, default: configured device.current) – Device to use for computation.

get_symmetry_mate(density_map, operation_index)

Apply a single symmetry operation to get one symmetry mate.

Parameters:

• density_map (torch.Tensor, shape (nx, ny, nz)) – Electron density map (typically from asymmetric unit).

• operation_index (int) – Index of the symmetry operation to apply (0 to n_ops-1).

Returns:

Density map after applying the symmetry operation.

Return type:

torch.Tensor, shape (nx, ny, nz)

get_all_symmetry_mates(density_map)

Get all symmetry mates as a list.

Parameters:

density_map (torch.Tensor, shape (nx, ny, nz)) – Electron density map (typically from asymmetric unit).

Returns:

List of symmetry-related maps, one for each operation.

Return type:

list of torch.Tensor

forward(density_map, apply_symmetry=True, combine_mode='sum')

Apply symmetry operations to density map.

Parameters:

• density_map (torch.Tensor, shape (nx, ny, nz)) – Electron density map (typically from asymmetric unit).

• apply_symmetry (bool, default True) – If True, apply all symmetry operations and combine them. If False, return input map unchanged (useful for P1 or debugging).

• combine_mode (str, default 'sum') –

  How to combine symmetry mates:

  • ’sum’: Sum all symmetry mates (for electron density)

  • ’max’: Take maximum across symmetry mates (for masks/boolean data)

Returns:

Symmetry-expanded density map (combined symmetry mates).

Return type:

torch.Tensor, shape (nx, ny, nz)

__call__(density_map, apply_symmetry=True, combine_mode='sum')

Make the class callable like a PyTorch module.

get_symmetry_info()

Get information about symmetry operations.

Returns:

Dictionary with the following keys:

• ’space_group’ : str

• ’n_operations’ : int

• ’matrices’ : torch.Tensor, shape (n_ops, 3, 3)

• ’translations’ : torch.Tensor, shape (n_ops, 3)

Return type:

dict