torchref.symmetry.map_symmetry 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.
This module uses a factory pattern: calling MapSymmetry() will automatically return either MapSymmetryDirect (fast, no interpolation) or MapSymmetryInterpolation (fallback with interpolation) depending on grid compatibility.
Space groups can be specified as strings, integers (1-230), or gemmi.SpaceGroup objects.
- torchref.symmetry.map_symmetry.MapSymmetry(space_group, map_shape, cell_params, dtype_float=torch.float32, verbose=1, device=device(type='cpu'))[source]
Factory function to create the appropriate MapSymmetry implementation.
This function checks if the grid size is compatible with direct indexing (no interpolation needed). If compatible, returns MapSymmetryDirect for maximum performance. Otherwise, returns MapSymmetryInterpolation as fallback.
- Parameters:
space_group (str, int, or gemmi.SpaceGroup) – Space group specification (e.g., ‘P21’, 4, gemmi.SpaceGroup(‘P 21’)).
map_shape (tuple of int) – Shape of the density map (nx, ny, nz).
cell_params (torch.Tensor, 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 (0=silent, 1=info, 2=debug).
device (torch.device, default: configured device.current) – Device to use for computation.
- Returns:
The appropriate implementation based on grid compatibility.
- Return type:
MapSymmetryDirect or MapSymmetryInterpolation
- class torchref.symmetry.map_symmetry.MapSymmetryDirect(space_group, map_shape, cell_params, dtype_float=torch.float32, verbose=1, device=device(type='cpu'))[source]
Bases:
DeviceMixin,ModuleFast direct-indexing implementation of crystallographic symmetry operations.
Computes symmetry mates one operation at a time (streaming) so that memory usage is O(grid) regardless of the number of symmetry operations, rather than O(n_ops * grid) for storing precomputed index grids.
NOTE: Do not instantiate this class directly. Use the MapSymmetry() factory function instead, which will automatically select the appropriate implementation.
- __init__(space_group, map_shape, cell_params, dtype_float=torch.float32, verbose=1, device=device(type='cpu'))[source]
- get_symmetry_mate(density_map, operation_index)[source]
Apply a single symmetry operation via direct indexing.
- forward(density_map, apply_symmetry=True, combine_mode='sum')[source]
Apply symmetry operations to density map.
Computes one symmetry mate at a time and accumulates into the result, so peak memory is only 1 index grid + 2 density maps regardless of the number of symmetry operations.