qimpy.symmetries.Symmetries

class Symmetries(*, checkpoint_in=(None, ''), 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 (LabeledPositions | None)
axes (dict[str, ndarray])
tolerance (float)
override (None | str | list | ndarray)

__init__(*, checkpoint_in=(None, ''), 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.
labeled_positions (LabeledPositions | None) – List of covariant coordinates of eg. atoms to deduce space group.
tolerance (float) – [Input file] Threshold for detecting symmetries.
override (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)
axes (dict[str, ndarray])

Return type:

None

Methods

`__init__`	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_grid_shape`	Check whether grid dimensions are compatible with symmetries.
`check_group`	Check that operations (rot, trans) form a group.
`detect`	Detect space group: rotations, translations and mapping of ions.
`enforce`	Enforce symmetries exactly on lattice and ions.
`find`	Find indices of operations (rot_in, trans_in) within (rot, trans).
`find_identity`	Find index of identity matrix in space group.
`find_inversion`	Find list of indices of space group operations with inversion.
`get_grid_shape`	Smallest symmetric, FFT-suitable shape >= shape_min.
`reduce_axes`	Reduce lattice (point group) symmetries by any global axes.
`report`	Print symmetry matrices.
`save_checkpoint`	Save self and all children in hierarchy to cp_path.
`symmetrize_forces`	Symmetrize forces positions_grad (n_ions x 3) in lattice coordinates.
`symmetrize_lattice`	Symmetrize lattice vectors Rbasis (3 x 3).
`symmetrize_matrix`	Symmetrize Cartesian matrix mat (3 x 3).
`symmetrize_positions`	Symmetrize positions (n_ions x 3)

Attributes

`rot_cart`	Symmetry rotation matrices in Cartesian coordinates.
`lattice`	Corresponding lattice vectors
`labeled_positions`	Positions determining space group
`tolerance`	Relative error threshold in detecting symmetries
`n_sym`	Number of space group operations
`rot`	Rotations in fractional coordinates (n_sym x 3 x 3)
`trans`	Translations in fractional coordinates (n_sym x 3)
`position_map`	Index each position maps to (n_sym x n_positions)
`i_id`	Index of identity operation within space group
`i_inv`	Indices of any inversion operations in space group
`child_names`	Names of attributes with child objects.
`variant_name`	Version of children having variants (if any)

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 (LabeledPositions | None)
axes (dict[str, ndarray])
tolerance (float)

Return type:

tuple[Tensor, Tensor, Tensor]

enforce(lattice, positions)

Enforce symmetries exactly on lattice and ions.

Parameters:

lattice (Lattice)
positions (Tensor | None)

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, 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: LabeledPositions | None: Positions determining space group

lattice: Lattice: Corresponding lattice vectors

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)