qimpy.symmetries.Symmetries
- class Symmetries(*, checkpoint_in=CheckpointPath(checkpoint=None, path=''), lattice, labeled_positions=None, axes={}, tolerance=1e-06, override=None)
Bases:
TreeNode
Space group symmetries. Detects space group from lattice and ions, and provides methods to symmetrize properties such as positions, forces and densities.
- Parameters
checkpoint_in (CheckpointPath) –
lattice (Lattice) –
labeled_positions (Optional[LabeledPositions]) –
axes (dict[str, numpy.ndarray]) –
tolerance (float) –
override (Union[None, str, list, ndarray]) –
- __init__(*, checkpoint_in=CheckpointPath(checkpoint=None, path=''), lattice, labeled_positions=None, axes={}, tolerance=1e-06, override=None)
Determine space group from lattice and ions.
- Parameters
lattice (Lattice) – Lattice vectors for determining point group.
positions – List of covariant coordinates of eg. atoms to deduce space group.
scalar_labels –
tolerance (float) – [Input file] Threshold for detecting symmetries.
override (Union[None, str, list, ndarray]) – [Input file] Override with identity-only or manual list of operations. By default (override = None), use automatically-detected symmetries. If override = ‘identity’, disable symmetries by only keeping identity. Otherwise, specify a N x 4 x 3 array or nested list of N operations, each as a 4 x 3 matrix, where the first three rows are the rotation rot and the final row is the translation trans of the space group operation. The operations are specified in lattice coordinates, which means that rot must be composed only of integers.
checkpoint_in (CheckpointPath) –
labeled_positions (Optional[LabeledPositions]) –
axes (dict[str, numpy.ndarray]) –
- Return type
None
Methods
Determine space group from lattice and ions.
add_child
Construct child object self.`attr_name` of type cls.
add_child_one_of
Invoke add_child on one of several child options in args.
Check whether grid dimensions are compatible with symmetries.
Check that operations (rot, trans) form a group.
Detect space group: rotations, translations and mapping of ions.
Enforce symmetries exactly on lattice and ions.
Find indices of operations (rot_in, trans_in) within (rot, trans).
Find index of identity matrix in space group.
Find list of indices of space group operations with inversion.
Smallest symmetric, FFT-suitable shape >= shape_min.
Reduce lattice (point group) symmetries by any global axes.
Print symmetry matrices.
save_checkpoint
Save self and all children in hierarchy to cp_path.
Symmetrize forces positions_grad (n_ions x 3) in lattice coordinates.
Symmetrize lattice vectors Rbasis (3 x 3).
Symmetrize Cartesian matrix mat (3 x 3).
Symmetrize positions (n_ions x 3)
Attributes
Symmetry rotation matrices in Cartesian coordinates.
Corresponding lattice vectors
Positions determining space group
Relative error threshold in detecting symmetries
Number of space group operations
Rotations in fractional coordinates (n_sym x 3 x 3)
Translations in fractional coordinates (n_sym x 3)
Index each position maps to (n_sym x n_positions)
Index of identity operation within space group
Indices of any inversion operations in space group
- check_grid_shape(shape)
Check whether grid dimensions are compatible with symmetries.
- Raises
ValueError – If incommensurate, raise ValueError with the error string including the reduced symmetry of specified grid shape
- Parameters
self (Symmetries) –
shape (Sequence[int]) –
- Return type
None
- static check_group(rot, trans, tolerance)
Check that operations (rot, trans) form a group. Raises exceptions if any group condition not satisfied.
- Parameters
rot (Tensor) –
trans (Tensor) –
tolerance (float) –
- Return type
None
- static detect(lattice, labeled_positions, axes, tolerance)
Detect space group: rotations, translations and mapping of ions.
- Parameters
lattice (Lattice) –
labeled_positions (Optional[LabeledPositions]) –
axes (dict[str, numpy.ndarray]) –
tolerance (float) –
- Return type
tuple[torch.Tensor, torch.Tensor, torch.Tensor]
- enforce(lattice, positions)
Enforce symmetries exactly on lattice and ions.
- Parameters
lattice (Lattice) –
positions (Optional[Tensor]) –
- Return type
None
- static find(rot, trans, rot_in, trans_in, tolerance)
Find indices of operations (rot_in, trans_in) within (rot, trans). Raise KeyError if any operations are not found within specified tolerance.
- Parameters
rot (Tensor) –
trans (Tensor) –
rot_in (Tensor) –
trans_in (Tensor) –
tolerance (float) –
- Return type
list[int]
- static find_identity(rot, trans, tolerance)
Find index of identity matrix in space group.
- Parameters
rot (Tensor) –
trans (Tensor) –
tolerance (float) –
- Return type
int
- static find_inversion(rot, tolerance)
Find list of indices of space group operations with inversion.
- Parameters
rot (Tensor) –
tolerance (float) –
- Return type
list[int]
- get_grid_shape(shape_min)
Smallest symmetric, FFT-suitable shape >= shape_min.
- Parameters
self (Symmetries) –
shape_min (ndarray) –
- Return type
ndarray
- static reduce_axes(lattice_sym, lattice, axes, tolerance)
Reduce lattice (point group) symmetries by any global axes.
- Parameters
lattice_sym (Tensor) –
lattice (Lattice) –
axes (dict[str, numpy.ndarray]) –
tolerance (float) –
- Return type
Tensor
- report()
Print symmetry matrices.
- Return type
None
- symmetrize_forces(positions_grad)
Symmetrize forces positions_grad (n_ions x 3) in lattice coordinates. Note that these are contravariant lattice coordinates, as in dE/dpositions.
- Parameters
self (Symmetries) –
positions_grad (Tensor) –
- Return type
Tensor
- symmetrize_lattice(Rbasis)
Symmetrize lattice vectors Rbasis (3 x 3).
- Parameters
self (Symmetries) –
Rbasis (Tensor) –
- Return type
Tensor
- symmetrize_matrix(mat)
Symmetrize Cartesian matrix mat (3 x 3). Suitable to symmetrize, e.g., stress tensors.
- Parameters
self (Symmetries) –
mat (Tensor) –
- Return type
Tensor
- symmetrize_positions(positions)
Symmetrize positions (n_ions x 3)
- Parameters
self (Symmetries) –
positions (Tensor) –
- Return type
Tensor
- i_id: int
Index of identity operation within space group
- i_inv: list[int]
Indices of any inversion operations in space group
- labeled_positions: Optional[LabeledPositions]
Positions determining space group
- n_sym: int
Number of space group operations
- position_map: Tensor
Index each position maps to (n_sym x n_positions)
- rot: Tensor
Rotations in fractional coordinates (n_sym x 3 x 3)
- property rot_cart: Tensor
Symmetry rotation matrices in Cartesian coordinates.
- tolerance: float
Relative error threshold in detecting symmetries
- trans: Tensor
Translations in fractional coordinates (n_sym x 3)