Core functions

Core functions#

Summary#

Spgrep provides its core functions to enumerate irreducible representations (irreps) from given

  • crystal structures ((lattice, positions, numbers)) or magnetic crystal structures ((lattice, positions, numbers, magmoms)),

  • symmetry operations of space groups ((rotations, translations)) or magnetic space groups ((rotations, translations, time_reversals)),

  • and symmetry operations of crystallographic point groups (rotations).

For a given crystal structure or symmetry operations, Spgrep calculates the following representations:

The following tables summarize core functions for a combination of representations and inputs.

Functions for (magnetic) crystal structure#

Tasks

(Magnetic) crystal structure

Linear irreps

spgrep.get_spacegroup_irreps()

Projective irreps for spinor

spgrep.get_spacegroup_spinor_irreps()

Projective co-reps for spinor

spgrep.get_spacegroup_spinor_irreps() with magmoms

Functions for (magnetic) space-group symmetry operations#

Tasks

(Magnetic) space group

Linear irreps

spgrep.get_spacegroup_irreps_from_primitive_symmetry()

Physically irreps

spgrep.get_spacegroup_irreps_from_primitive_symmetry() with real=True

Projective irreps for spinor

spgrep.get_spacegroup_spinor_irreps_from_primitive_symmetry()

Projective co-reps for spinor

spgrep.get_spacegroup_spinor_irreps_from_primitive_symmetry() with time_reversals

Functions for (magnetic) crystallographic point-group symmetry operations#

Tasks

(Magnetic) point group

Linear irreps

spgrep.get_crystallographic_pointgroup_irreps_from_symmetry()

Physically irreps

spgrep.get_crystallographic_pointgroup_irreps_from_symmetry() with real=True

Projective irreps for spinor

spgrep.get_crystallographic_pointgroup_spinor_irreps_from_symmetry()

Projective co-reps for spinor

spgrep.get_crystallographic_pointgroup_spinor_irreps_from_symmetry() with time_reversals

Linear representation#

Space group#

spgrep.get_spacegroup_irreps(lattice, positions, numbers, kpoint, method='Neto', reciprocal_lattice=None, symprec=1e-05, rtol=1e-05, atol=1e-08, max_num_random_generations=4)[source]#

Compute all irreducible representations of space group of given structure up to unitary transformation.

Parameters:

  • lattice (array, (3, 3)) – Row-wise basis vectors. lattice[i, :] is the i-th lattice vector.

  • positions (array, (num_atoms, 3)) – Fractional coordinates of sites

  • numbers (array, (num_atoms, )) – Integer list specifying atomic species

  • kpoint (array, (3, )) –

    Reciprocal vector with respect to reciprocal_lattice For pure translation \(\mathbf{t}\), returned irrep \(\Gamma^{(\alpha)}\) takes

    \[\Gamma^{(\alpha)}((E, \mathbf{t})) = e^{ -i\mathbf{k}\cdot\mathbf{t} } \mathbf{1}.\]

  • method (str, 'Neto' or 'random') – ‘Neto’: construct irreps from a fixed chain of subgroups of little co-group ‘random’: construct irreps by numerically diagonalizing a random matrix commute with regular representation

  • reciprocal_lattice ((Optional) array, (3, 3)) – reciprocal_lattice[i, :] is the i-th basis vector of reciprocal lattice for kpoint without 2 * pi factor. If not specified, reciprocal_lattice is set to np.linalg.inv(lattice).T.

  • symprec (float) – Parameter for searching symmetry operation in Spglib

  • rtol (float) – Relative tolerance for comparing float values

  • atol (float) – Absolute tolerance to distinguish difference eigenvalues

  • max_num_random_generations (int) – Maximum number of trials to generate random matrix

Returns:

  • irreps (list of Irreps with (little_group_order, dim, dim)) – irreps[alpha][i, :, :] is the alpha-th irreducible matrix representation of (little_rotations[i], little_translations[i]).

  • rotations (array[int], (num_sym, 3, 3)) – Linear parts of symmetry operations

  • translations (array, (num_sym, 3)) – Translation parts of symmetry operations

  • mapping_little_group (array, (little_group_order, )) – Let i = mapping_little_group[idx]. (rotations[i], translations[i]) belongs to the little group of given space space group and kpoint.

spgrep.get_spacegroup_irreps_from_primitive_symmetry(rotations, translations, kpoint, real=False, method='Neto', rtol=1e-05, atol=1e-08, max_num_random_generations=4)[source]#

Compute all irreducible representations of given space group up to unitary transformation.

Note that rotations and translations should be specified in a primitive cell.

Parameters:

  • rotations (array[int], (order, 3, 3)) –

    Assume a fractional coordinates x are transformed by the i-th symmetry operation as follows:

    np.dot(rotations[i, :, :], x) + translations[i, :]

  • translations (array, (order, 3))

  • kpoint (array, (3, )) –

    Reciprocal vector with respect to reciprocal lattice. For pure translation \(\mathbf{t}\), returned irrep \(\Gamma^{(\alpha)}\) takes

    \[\Gamma^{(\alpha)}((E, \mathbf{t})) = e^{ -i\mathbf{k}\cdot\mathbf{t} } \mathbf{1}.\]

    See Physically irreducible representation (PIR) for details.

  • real (bool, default=False) –

    If True, return irreps over real vector space (so called physically irreducible representations). For type-II and type-III cases, representation matrix for translation \((\mathbf{E}, \mathbf{t})\) is chosen as

    \[\begin{split}\begin{pmatrix} \cos (\mathbf{k} \cdot \mathbf{t}) \mathbf{1}_{d} & -\sin (\mathbf{k} \cdot \mathbf{t}) \mathbf{1}_{d} \\ \sin (\mathbf{k} \cdot \mathbf{t}) \mathbf{1}_{d} & \cos (\mathbf{k} \cdot \mathbf{t}) \mathbf{1}_{d} \\ \end{pmatrix}\end{split}\]

    where \(\mathbf{k}\) is kpoint.

  • method (str, 'Neto' or 'random') – ‘Neto’: construct irreps from a fixed chain of subgroups of little co-group ‘random’: construct irreps by numerically diagonalizing a random matrix commute with regular representation

  • rtol (float) – Relative tolerance

  • atol (float) – Absolute tolerance to distinguish difference eigenvalues

  • max_num_random_generations (int) – Maximum number of trials to generate random matrix

Returns:

  • irreps (list of Irreps with (little_group_order, dim, dim)) – Let i = mapping_little_group[idx]. irreps[alpha][i, :, :] is the alpha-th irreducible matrix representation of (rotations[i], translations[i]).

  • mapping_little_group (array, (little_group_order, )) – Let i = mapping_little_group[idx]. (rotations[i], translations[i]) belongs to the little group of given space space group and kpoint.

Crystallographic point group#

spgrep.get_crystallographic_pointgroup_irreps_from_symmetry(rotations, real=False, method='Neto', rtol=1e-05, atol=1e-08, max_num_random_generations=4)[source]#

Compute all irreducible representations of given crystallographic point group up to unitary transformation.

Assume matrix representation of given crystallographic point group is in “standard” setting shown in Table 3.2.3.3 of International Table for Crystallography Vol. A (2016).

Parameters:

  • rotations (array[int], (order, 3, 3)) – Assume a point coordinates x are transformed into np.dot(rotations[i, :, :], x) by the i-th symmetry operation.

  • real (bool, default=False) – If True, return irreps over real vector space (so called physically irreducible representations). See Physically irreducible representation (PIR) for details.

  • method (str, 'Neto' or 'random') – ‘Neto’: construct irreps from a fixed chain of subgroups of little co-group ‘random’: construct irreps by numerically diagonalizing a random matrix commute with regular representation

  • rtol (float) – Relative tolerance to distinguish difference eigenvalues

  • atol (float) – Absolute tolerance to distinguish difference eigenvalues

  • max_num_random_generations (int) – Maximum number of trials to generate random matrix

Returns:

irreps

Return type:

list of Irreps with (order, dim, dim)

Spin representation#

Space group#

spgrep.get_spacegroup_spinor_irreps(lattice, positions, numbers, magmoms=None, kpoint=None, method='Neto', reciprocal_lattice=None, symprec=1e-05, rtol=1e-05, atol=1e-08, max_num_random_generations=4)[source]#

Compute all irreducible representations \(\mathbf{\Gamma}^{\mathbf{k}\alpha}\) of space group of given structure up to unitary transformation for spinor.

Each irrep \(\mathbf{\Gamma}^{\mathbf{k}\alpha}\) satisfies

\[\mathbf{\Gamma}^{\mathbf{k}\alpha}((\mathbf{S}_{i}, \mathbf{w}_{i})) \mathbf{\Gamma}^{\mathbf{k}\alpha}((\mathbf{S}_{j}, \mathbf{w}_{j})) = z(\mathbf{S}_{i}, \mathbf{S}_{j}) \mathbf{\Gamma}^{\mathbf{k}\alpha}((\mathbf{S}_{i}, \mathbf{w}_{i})(\mathbf{S}_{j}, \mathbf{w}_{j})).\]

See Spin representation for Spgrep’s convention of spin-derived factor system \(z(\mathbf{S}_{i}, \mathbf{S}_{j})\).

Parameters:

  • lattice (array, (3, 3)) – Row-wise basis vectors. lattice[i, :] is the i-th lattice vector.

  • positions (array, (num_atoms, 3)) – Fractional coordinates of sites

  • numbers (array, (num_atoms, )) – Integer list specifying atomic species

  • magmoms ((Optional) array, (num_atoms, )) – Collinear magnetic moments. If specified, return co-representations. See :ref:{corep} for details.

  • kpoint (array, (3, )) –

    Reciprocal vector with respect to reciprocal_lattice For pure translation \(\mathbf{t}\), returned irrep \(\Gamma^{(\alpha)}\) takes

    \[\Gamma^{(\alpha)}((E, \mathbf{t})) = e^{ -i\mathbf{k}\cdot\mathbf{t} } \mathbf{1}.\]

  • method (str, 'Neto' or 'random') – ‘Neto’: construct irreps from a fixed chain of subgroups of little co-group ‘random’: construct irreps by numerically diagonalizing a random matrix commute with regular representation

  • reciprocal_lattice ((Optional) array, (3, 3)) – reciprocal_lattice[i, :] is the i-th basis vector of reciprocal lattice for kpoint without 2 * pi factor. If not specified, reciprocal_lattice is set to np.linalg.inv(lattice).T.

  • symprec (float) – Parameter for searching symmetry operation in Spglib

  • rtol (float) – Relative tolerance for comparing float values

  • atol (float) – Absolute tolerance to distinguish difference eigenvalues

  • max_num_random_generations (int) – Maximum number of trials to generate random matrix

Returns:

  • irreps (list of Irreps with (little_group_order, dim, dim)) – irreps[alpha][i, :, :] is the alpha-th irreducible matrix representation of (little_rotations[i], little_translations[i]).

  • little_spinor_factor_system (array, (little_group_order, little_group_order)) – spinor_factor_system[i, j] stands for factor system \(z(\mathbf{S}_{i}, \mathbf{S}_{j})\)

  • little_unitary_rotations (array, (little_group_order, 2, 2)) – SU(2) rotations on spinor.

  • anti_linear ((Optional) array[bool], (little_group_order, )) – Appeared when time_reversal is specified. If anti_linear[i] == True, the i-th operator is anti-linear.

  • rotations (array[int], (num_sym, 3, 3))

  • translations (array, (num_sym, 3))

  • time_reversals (array[int], (num_sym, ))

  • mapping_little_group (array, (little_group_order, )) – Let i = mapping_little_group[idx]. (rotations[i], translations[i]) belongs to the little group of given space space group and kpoint.

spgrep.get_spacegroup_spinor_irreps_from_primitive_symmetry(lattice, rotations, translations, time_reversals=None, kpoint=None, method='Neto', rtol=1e-05, atol=1e-08, max_num_random_generations=4)[source]#

Compute all irreducible representations \(\mathbf{\Gamma}^{\mathbf{k}\alpha}\) of given space group up to unitary transformation for spinor.

Each irrep \(\mathbf{\Gamma}^{\mathbf{k}\alpha}\) satisfies

\[\mathbf{\Gamma}^{\mathbf{k}\alpha}((\mathbf{S}_{i}, \mathbf{w}_{i})) \mathbf{\Gamma}^{\mathbf{k}\alpha}((\mathbf{S}_{j}, \mathbf{w}_{j})) = z(\mathbf{S}_{i}, \mathbf{S}_{j}) \mathbf{\Gamma}^{\mathbf{k}\alpha}((\mathbf{S}_{i}, \mathbf{w}_{i})(\mathbf{S}_{j}, \mathbf{w}_{j})).\]

Note that rotations and translations should be specified in a primitive cell. See Spin representation for Spgrep’s convention of spin-derived factor system \(z(\mathbf{S}_{i}, \mathbf{S}_{j})\).

Parameters:

  • lattice (array, (3, 3)) – Row-wise basis vectors. lattice[i, :] is the i-th lattice vector.

  • rotations (array[int], (order, 3, 3)) –

    Assume a fractional coordinates x are transformed by the i-th symmetry operation as follows:

    np.dot(rotations[i, :, :], x) + translations[i, :]

  • translations (array, (order, 3))

  • time_reversals (array[int] | None, (order, )) – If specified, return co-representations See :ref:{corep} for details.

  • kpoint (array, (3, )) –

    Reciprocal vector with respect to reciprocal lattice. For pure translation \(\mathbf{t}\), returned irrep \(\Gamma^{(\alpha)}\) takes

    \[\mathbf{\Gamma}^{\mathbf{k}\alpha}((E, \mathbf{t})) = e^{ -i\mathbf{k}\cdot\mathbf{t} } \mathbf{1}.\]

  • method (str, 'Neto' or 'random') – ‘Neto’: construct irreps from a fixed chain of subgroups of little co-group ‘random’: construct irreps by numerically diagonalizing a random matrix commute with regular representation

  • rtol (float) – Relative tolerance

  • atol (float) – Absolute tolerance to distinguish difference eigenvalues

  • max_num_random_generations (int) – Maximum number of trials to generate random matrix

Returns:

  • irreps (list of Irreps with (little_group_order, dim, dim)) – Let i = mapping_little_group[idx]. irreps[alpha][i, :, :] is the alpha-th irreducible matrix representation of (rotations[i], translations[i]).

  • indicators ((Optional) list[int]) – Appeared when time_reversal is specified. Frobenius-Schur indicators for each small representation

  • little_spinor_factor_system (array, (little_group_order, little_group_order)) – spinor_factor_system[i, j] stands for factor system \(z(\mathbf{S}_{i}, \mathbf{S}_{j})\)

  • little_unitary_rotations (array, (little_group_order, 2, 2)) – SU(2) rotations on spinor.

  • anti_linear ((Optional) array[bool], (order, )) – Appeared when time_reversal is specified. If anti_linear[i] == True, the i-th operator is anti-linear.

  • mapping_little_group (array, (little_group_order, )) – Let i = mapping_little_group[idx]. (rotations[i], translations[i]) belongs to the little group of given space space group and kpoint.

Crystallographic point group#

spgrep.get_crystallographic_pointgroup_spinor_irreps_from_symmetry(lattice, rotations, time_reversals=None, method='Neto', rtol=1e-05, atol=1e-08, max_num_random_generations=4)[source]#

Compute all irreducible representations \(\mathbf{D}^{\alpha}\) of given crystallographic point group up to unitary transformation for spinor.

Each irrep \(\mathbf{D}^{\alpha}\) satisfies

\[\mathbf{D}^{\alpha}(\mathbf{S}_{i}) \mathbf{D}^{\alpha}(\mathbf{S}_{j}) = z(\mathbf{S}_{i}, \mathbf{S}_{j}) \mathbf{D}^{\alpha}(\mathbf{S}_{k}).\]

Assume matrix representation of given crystallographic point group is in “standard” setting shown in Table 3.2.3.3 of International Table for Crystallography Vol. A (2016).

See Spin representation for Spgrep’s convention of spinor-derived factor system \(z(\mathbf{S}_{i}, \mathbf{S}_{j})\).

Parameters:

  • lattice (array, (3, 3)) – Row-wise basis vectors. lattice[i, :] is the i-th lattice vector.

  • rotations (array[int], (order, 3, 3)) – Assume a point coordinates x are transformed into np.dot(rotations[i, :, :], x) by the i-th symmetry operation.

  • time_reversals (array[int] | None, (order, )) – If specified, return co-representations See :ref:{corep} for details.

  • method (str, 'Neto' or 'random') – ‘Neto’: construct irreps from a fixed chain of subgroups of little co-group ‘random’: construct irreps by numerically diagonalizing a random matrix commute with regular representation

  • rtol (float) – Relative tolerance to distinguish difference eigenvalues

  • atol (float) – Absolute tolerance to distinguish difference eigenvalues

  • max_num_random_generations (int) – Maximum number of trials to generate random matrix

Returns:

  • irreps (list of unitary irreps with (order, dim, dim))

  • indicators ((Optional) list[int]) – Appeared when time_reversal is specified. Frobenius-Schur indicators for each small representation

  • factor_system (array, (order, order)) – factor_system[i, j] stands for factor system \(z(\mathbf{S}_{i}, \mathbf{S}_{j})\)

  • unitary_rotations (array, (order, 2, 2)) – SU(2) rotations on spinor.

  • anti_linear ((Optional) array[bool], (order, )) – Appeared when time_reversal is specified. If anti_linear[i] == True, the i-th operator is anti-linear.

Contents