enumerate_superlattices#

libcasm.xtal.enumerate_superlattices(
unit_lattice: Lattice,
point_group: list[SymOp],
max_volume: int,
min_volume: int = 1,
dirs: str = 'abc',
unit_cell: numpy.ndarray[numpy.int32[3, 3]] | None = None,
diagonal_only: bool = False,
fixed_shape: bool = False,
) → list[Lattice]#

Enumerate symmetrically distinct superlattices

Superlattices satify:

S = L @ T,

where S and L are, respectively, the superlattice and unit lattice vectors as columns of shape=(3, 3) matrices, and T is an integer shape=(3,3) transformation matrix.

Superlattices S1 and S2 are symmetrically equivalent if there exists p and A such that:

S2 = p.matrix() @ S1 @ A,

where p is an element in the point group, and A is a unimodular matrix (integer matrix, with abs(det(A))==1).

Parameters:

  • unit_lattice (Lattice) – The unit lattice.

  • point_group (list[SymOp]) – The point group symmetry that determines if superlattices are equivalent. Depending on the use case, this is often the prim crystal point group, make_crystal_point_group(), or the lattice point group, make_point_group().

  • max_volume (int) – The maximum volume superlattice to enumerate. The volume is measured relative the unit cell being used to generate supercells.

  • min_volume (int, default=1) – The minimum volume superlattice to enumerate. The volume is measured relative the unit cell being used to generate supercells.

  • dirs (str, default="abc") – A string indicating which lattice vectors to enumerate over. Some combination of ‘a’, ‘b’, and ‘c’, where ‘a’ indicates the first lattice vector of the unit cell, ‘b’ the second, and ‘c’ the third.

  • unit_cell (Optional[np.ndarray] = None,) – An integer shape=(3,3) transformation matrix U allows specifying an alternative unit cell that can be used to generate superlattices of the form S = (L @ U) @ T. If None, U is set to the identity matrix.

  • diagonal_only (bool = False) – If true, restrict \(T\) to diagonal matrices.

  • fixed_shape (bool = False) – If true, restrict T to diagonal matrices with diagonal coefficients [m, 1, 1] (1d), [m, m, 1] (2d), or [m, m, m] (3d), where the dimension is determined from len(dirs).

Returns:

superlattices – A list of superlattices of the unit_lattice which are distinct under application of point_group. The resulting lattices will be in canonical form with respect to point_group.

Return type:

list[Lattice]