pymatgen.symmetry package

Submodules

pymatgen.symmetry.analyzer module

An interface to the excellent spglib library by Atsushi Togo (http://spglib.sourceforge.net/) for pymatgen.

v1.0 - Now works with both ordered and disordered structure. v2.0 - Updated for spglib 1.6. v3.0 - pymatgen no longer ships with spglib. Instead, spglib (the python

version) is now a dependency and the SpacegroupAnalyzer merely serves as an interface to spglib for pymatgen Structures.

class PointGroupAnalyzer(mol, tolerance=0.3, eigen_tolerance=0.01, matrix_tolerance=0.1)[source]

Bases: object

A class to analyze the point group of a molecule.

The general outline of the algorithm is as follows:

1. Center the molecule around its center of mass.

2. Compute the inertia tensor and the eigenvalues and eigenvectors.

3. Handle the symmetry detection based on eigenvalues.

   1. Linear molecules have one zero eigenvalue. Possible symmetry operations are C*v or D*v

   2. Asymmetric top molecules have all different eigenvalues. The maximum rotational symmetry in such molecules is 2

   3. Symmetric top molecules have 1 unique eigenvalue, which gives a unique rotation axis. All axial point groups are possible except the cubic groups (T & O) and I.

   4. Spherical top molecules have all three eigenvalues equal. They have the rare T, O or I point groups.

Attribute:

sch_symbol (str): Schoenflies symbol of the detected point group.

The default settings are usually sufficient.

Parameters:

• mol (Molecule) – Molecule to determine point group for.

• tolerance (float) – Distance tolerance to consider sites as symmetrically equivalent. Defaults to 0.3 Angstrom.

• eigen_tolerance (float) – Tolerance to compare eigen values of the inertia tensor. Defaults to 0.01.

• matrix_tolerance (float) – Tolerance used to generate the full set of symmetry operations of the point group.

get_equivalent_atoms()[source]

Returns sets of equivalent atoms with symmetry operations.

Returns:

with two possible keys:

eq_sets: A dictionary of indices mapping to sets of indices, each key maps to

indices of all equivalent atoms. The keys are guaranteed to be not equivalent.

sym_ops: Twofold nested dictionary. operations[i][j] gives the symmetry

operation that maps atom i unto j.

Return type:

dict

get_pointgroup()[source]

Returns a PointGroup object for the molecule.

get_rotational_symmetry_number()[source]

Return the rotational symmetry number.

get_symmetry_operations()[source]

Return symmetry operations as a list of SymmOp objects. Returns Cartesian coord symmops.

Returns:

symmetry operations.

Return type:

list[SymmOp]

inversion_op = SymmOp(affine_matrix=array([[-1., -0., -0.,  0.],        [-0., -1., -0.,  0.],        [-0., -0., -1.,  0.],        [-0., -0., -0.,  1.]]))[source]

is_valid_op(symmop) → bool[source]

Check if a particular symmetry operation is a valid symmetry operation for a molecule, i.e., the operation maps all atoms to another equivalent atom.

Parameters:

symmop (SymmOp) – Symmetry operation to test.

Returns:

Whether SymmOp is valid for Molecule.

Return type:

bool

symmetrize_molecule()[source]

Returns a symmetrized molecule.

The equivalent atoms obtained via get_equivalent_atoms() are rotated, mirrored… unto one position. Then the average position is calculated. The average position is rotated, mirrored… back with the inverse of the previous symmetry operations, which gives the symmetrized molecule

Returns:

with three possible keys:

sym_mol: A symmetrized molecule instance. eq_sets: A dictionary of indices mapping to sets of indices, each key maps to indices

of all equivalent atoms. The keys are guaranteed to be not equivalent.

sym_ops: Twofold nested dictionary. operations[i][j] gives the symmetry operation

that maps atom i unto j.

Return type:

dict

class PointGroupOperations(sch_symbol, operations, tol: float = 0.1)[source]

Bases: list

Defines a point group, which is essentially a sequence of symmetry operations.

sch_symbol[source]

Schoenflies symbol of the point group.

Type:

str

Parameters:

• sch_symbol (str) – Schoenflies symbol of the point group.

• operations ([SymmOp]) – Initial set of symmetry operations. It is sufficient to provide only just enough operations to generate the full set of symmetries.

• tol (float) – Tolerance to generate the full set of symmetry operations.

class SpacegroupAnalyzer(structure: Structure, symprec: float | None = 0.01, angle_tolerance: float = 5.0)[source]

Bases: object

Takes a pymatgen Structure object and a symprec.

Uses spglib to perform various symmetry finding operations.

Parameters:

• structure (Structure/IStructure) – Structure to find symmetry

• symprec (float) – Tolerance for symmetry finding. Defaults to 0.01, which is fairly strict and works well for properly refined structures with atoms in the proper symmetry coordinates. For structures with slight deviations from their proper atomic positions (e.g., structures relaxed with electronic structure codes), a looser tolerance of 0.1 (the value used in Materials Project) is often needed.

• angle_tolerance (float) – Angle tolerance for symmetry finding.

find_primitive(keep_site_properties=False)[source]

Find a primitive version of the unit cell.

Parameters:

keep_site_properties (bool) – Whether to keep the input site properties (including magnetic moments) on the sites that are still present after the refinement. Note: This is disabled by default because the magnetic moments are not always directly transferable between unit cell definitions. For instance, long-range magnetic ordering or antiferromagnetic character may no longer be present (or exist in the same way) in the returned structure. If keep_site_properties is True, each site retains the same site property as in the original structure without further adjustment.

Returns:

A primitive cell in the input cell is searched and returned as a Structure object. If no primitive cell is found, None is returned.

get_conventional_standard_structure(international_monoclinic=True, keep_site_properties=False)[source]

Gives a structure with a conventional cell according to certain standards. The standards are defined in Setyawan, W., & Curtarolo, S. (2010). High-throughput electronic band structure calculations: Challenges and tools. Computational Materials Science, 49(2), 299-312. doi:10.1016/j.commatsci.2010.05.010 They basically enforce as much as possible norm(a1)<norm(a2)<norm(a3). NB This is not necessarily the same as the standard settings within the International Tables of Crystallography, for which get_refined_structure should be used instead.

Parameters:

• international_monoclinic (bool) – Whether to convert to proper international convention such that beta is the non-right angle.

• keep_site_properties (bool) – Whether to keep the input site properties (including magnetic moments) on the sites that are still present after the refinement. Note: This is disabled by default because the magnetic moments are not always directly transferable between unit cell definitions. For instance, long-range magnetic ordering or antiferromagnetic character may no longer be present (or exist in the same way) in the returned structure. If keep_site_properties is True, each site retains the same site property as in the original structure without further adjustment.

Returns:

The structure in a conventional standardized cell

get_conventional_to_primitive_transformation_matrix(international_monoclinic=True)[source]

Gives the transformation matrix to transform a conventional unit cell to a primitive cell according to certain standards the standards are defined in Setyawan, W., & Curtarolo, S. (2010). High-throughput electronic band structure calculations: Challenges and tools. Computational Materials Science, 49(2), 299-312. doi:10.1016/j.commatsci.2010.05.010.

Parameters:

international_monoclinic (bool) – Whether to convert to proper international convention such that beta is the non-right angle.

Returns:

Transformation matrix to go from conventional to primitive cell

get_crystal_system() → CrystalSystem[source]

Get the crystal system for the structure, e.g., (triclinic, orthorhombic, cubic, etc.).

Raises:

ValueError – on invalid space group numbers < 1 or > 230.

Returns:

Crystal system for structure

Return type:

str

get_hall() → str[source]

Returns Hall symbol for structure.

Returns:

Hall symbol

Return type:

str

get_ir_reciprocal_mesh(mesh=(10, 10, 10), is_shift=(0, 0, 0))[source]

k-point mesh of the Brillouin zone generated taken into account symmetry.The method returns the irreducible kpoints of the mesh and their weights.

Parameters:

• mesh (3x1 array) – The number of kpoint for the mesh needed in each direction

• is_shift (3x1 array) – Whether to shift the kpoint grid. (1, 1,

• 0.5 (1) means all points are shifted by) –

• 0.5 –

• 0.5. –

Returns:

A list of irreducible kpoints and their weights as a list of tuples [(ir_kpoint, weight)], with ir_kpoint given in fractional coordinates

get_ir_reciprocal_mesh_map(mesh=(10, 10, 10), is_shift=(0, 0, 0))[source]

Same as ‘get_ir_reciprocal_mesh’ but the full grid together with the mapping that maps a reducible to an irreducible kpoint is returned.

Parameters:

• mesh (3x1 array) – The number of kpoint for the mesh needed in each direction

• is_shift (3x1 array) – Whether to shift the kpoint grid. (1, 1,

• 0.5 (1) means all points are shifted by) –

• 0.5 –

• 0.5. –

Returns:

A tuple containing two numpy.ndarray. The first is the mesh in fractional coordinates and the second is an array of integers that maps all the reducible kpoints from to irreducible ones.

get_kpoint_weights(kpoints, atol=1e-05)[source]

Calculate the weights for a list of kpoints.

Parameters:

• kpoints (Sequence) – Sequence of kpoints. np.arrays is fine. Note that the code does not check that the list of kpoints provided does not contain duplicates.

• atol (float) – Tolerance for fractional coordinates comparisons.

Returns:

List of weights, in the SAME order as kpoints.

get_lattice_type() → Literal['cubic', 'hexagonal', 'monoclinic', 'orthorhombic', 'rhombohedral', 'tetragonal', 'triclinic'][source]

Get the lattice for the structure, e.g., (triclinic, orthorhombic, cubic, etc.).This is the same as the crystal system with the exception of the hexagonal/rhombohedral lattice.

Raises:

ValueError – on invalid space group numbers < 1 or > 230.

Returns:

Lattice type for structure

Return type:

str

get_point_group_operations(cartesian=False)[source]

Return symmetry operations as a list of SymmOp objects. By default returns fractional coord symm ops. But Cartesian can be returned too.

Parameters:

cartesian (bool) – Whether to return SymmOps as Cartesian or direct coordinate operations.

Returns:

Point group symmetry operations.

Return type:

list[SymmOp]

get_point_group_symbol() → str[source]

Get the point group associated with the structure.

Returns:

Point group for structure.

Return type:

Pointgroup

get_primitive_standard_structure(international_monoclinic=True, keep_site_properties=False)[source]

Gives a structure with a primitive cell according to certain standards. The standards are defined in Setyawan, W., & Curtarolo, S. (2010). High-throughput electronic band structure calculations: Challenges and tools. Computational Materials Science, 49(2), 299-312. doi:10.1016/j.commatsci.2010.05.010.

Parameters:

• international_monoclinic (bool) – Whether to convert to proper international convention such that beta is the non-right angle.

• keep_site_properties (bool) – Whether to keep the input site properties (including magnetic moments) on the sites that are still present after the refinement. Note: This is disabled by default because the magnetic moments are not always directly transferable between unit cell definitions. For instance, long-range magnetic ordering or antiferromagnetic character may no longer be present (or exist in the same way) in the returned structure. If keep_site_properties is True, each site retains the same site property as in the original structure without further adjustment.

Returns:

The structure in a primitive standardized cell

get_refined_structure(keep_site_properties=False)[source]

Get the refined structure based on detected symmetry. The refined structure is a conventional cell setting with atoms moved to the expected symmetry positions.

Parameters:

keep_site_properties (bool) – Whether to keep the input site properties (including magnetic moments) on the sites that are still present after the refinement. Note: This is disabled by default because the magnetic moments are not always directly transferable between unit cell definitions. For instance, long-range magnetic ordering or antiferromagnetic character may no longer be present (or exist in the same way) in the returned structure. If keep_site_properties is True, each site retains the same site property as in the original structure without further adjustment.

Returns:

Refined structure.

get_space_group_number() → int[source]

Get the international spacegroup number (e.g., 62) for structure.

Returns:

International spacegroup number for structure.

Return type:

int

get_space_group_operations() → SpacegroupOperations[source]

Get the SpacegroupOperations for the Structure.

Returns:

SpacegroupOperations object.

get_space_group_symbol() → str[source]

Get the spacegroup symbol (e.g., Pnma) for structure.

Returns:

Spacegroup symbol for structure.

Return type:

str

get_symmetrized_structure()[source]

Get a symmetrized structure. A symmetrized structure is one where the sites have been grouped into symmetrically equivalent groups.

Returns:

pymatgen.symmetry.structure.SymmetrizedStructure object.

get_symmetry_dataset()[source]

Returns the symmetry dataset as a dict.

Returns:

With the following properties:

number: International space group number international: International symbol hall: Hall symbol transformation_matrix: Transformation matrix from lattice of input cell to Bravais lattice L^bravais = L^original * Tmat origin shift: Origin shift in the setting of “Bravais lattice” rotations, translations: Rotation matrices and translation vectors. Space group operations are obtained by [(r,t) for r, t in zip(rotations, translations)] wyckoffs: Wyckoff letters

Return type:

dict

get_symmetry_operations(cartesian=False)[source]

Return symmetry operations as a list of SymmOp objects. By default returns fractional coord sym_ops. But Cartesian can be returned too.

Returns:

symmetry operations.

Return type:

list[SymmOp]

is_laue() → bool[source]

Check if the point group of the structure has Laue symmetry (centrosymmetry).

class SpacegroupOperations(int_symbol, int_number, symmops)[source]

Bases: list

Represents a space group, which is a collection of symmetry operations.

Parameters:

• int_symbol (str) – International symbol of the spacegroup.

• int_number (int) – International number of the spacegroup.

• symmops ([SymmOp]) – Symmetry operations associated with the spacegroup.

are_symmetrically_equivalent(sites1, sites2, symm_prec=0.001) → bool[source]

Given two sets of PeriodicSites, test if they are actually symmetrically equivalent under this space group. Useful, for example, if you want to test if selecting atoms 1 and 2 out of a set of 4 atoms are symmetrically the same as selecting atoms 3 and 4, etc.

One use is in PartialRemoveSpecie transformation to return only symmetrically distinct arrangements of atoms.

Parameters:

• sites1 ([PeriodicSite]) – 1st set of sites

• sites2 ([PeriodicSite]) – 2nd set of sites

• symm_prec (float) – Tolerance in atomic distance to test if atoms are symmetrically similar.

Returns:

Whether the two sets of sites are symmetrically equivalent.

Return type:

bool

cluster_sites(mol: Molecule, tol: float, give_only_index: bool = False) → tuple[Site | None, dict][source]

Cluster sites based on distance and species type.

Parameters:

• mol (Molecule) – Molecule with origin at center of mass.

• tol (float) – Tolerance to use.

• give_only_index (bool) – Whether to return only the index of the origin site, instead of the site itself. Defaults to False.

Returns:

origin_site is a site at the center of mass (None if there are no origin atoms). clustered_sites is a dict of {(avg_dist, species_and_occu): [list of sites]}

Return type:

(origin_site, clustered_sites)

generate_full_symmops(symmops: Sequence[SymmOp], tol: float) → Sequence[SymmOp][source]

Recursive algorithm to permute through all possible combinations of the initially supplied symmetry operations to arrive at a complete set of operations mapping a single atom to all other equivalent atoms in the point group. This assumes that the initial number already uniquely identifies all operations.

Parameters:

• symmops (list[SymmOp]) – Initial set of symmetry operations.

• tol (float) – Tolerance for detecting symmetry.

Returns:

Full set of symmetry operations.

Return type:

list[SymmOp]

iterative_symmetrize(mol, max_n=10, tolerance=0.3, epsilon=0.01)[source]

Returns a symmetrized molecule.

The equivalent atoms obtained via get_equivalent_atoms() are rotated, mirrored… unto one position. Then the average position is calculated. The average position is rotated, mirrored… back with the inverse of the previous symmetry operations, which gives the symmetrized molecule

Parameters:

• mol (Molecule) – A pymatgen Molecule instance.

• max_n (int) – Maximum number of iterations.

• tolerance (float) – Tolerance for detecting symmetry. Gets passed as Argument into ~pymatgen.analyzer.symmetry.PointGroupAnalyzer.

• epsilon (float) – If the element-wise absolute difference of two subsequently symmetrized structures is smaller epsilon, the iteration stops before max_n is reached.

Returns:

with three possible keys:

sym_mol: A symmetrized molecule instance. eq_sets: A dictionary of indices mapping to sets of indices, each key maps to indices

of all equivalent atoms. The keys are guaranteed to be not equivalent.

sym_ops: Twofold nested dictionary. operations[i][j] gives the symmetry operation

that maps atom i unto j.

Return type:

dict

pymatgen.symmetry.bandstructure module

Provides a class for interacting with KPath classes to generate high-symmetry k-paths using different conventions.

class HighSymmKpath(structure, has_magmoms=False, magmom_axis=None, path_type='setyawan_curtarolo', symprec=0.01, angle_tolerance=5, atol=1e-05)[source]

Bases: KPathBase

This class generates path along high symmetry lines in the Brillouin zone according to different conventions. The class is designed to be used with a specific primitive cell setting. The definitions for the primitive cell used can be found in: Computational Materials Science, 49(2), 299-312. doi:10.1016/j.commatsci.2010.05.010. The space group analyzer can be used to produce the correct primitive structure (method get_primitive_standard_structure(international_monoclinic=False)). Ensure input structure is correct before ‘get_kpoints()’ method is used. See individual KPath classes for details on specific conventions.

Parameters:

• structure (Structure) – Structure object

• has_magmoms (bool) – Whether the input structure contains magnetic moments as site properties with the key ‘magmom.’ Values may be in the form of 3-component vectors given in the basis of the input lattice vectors, in which case the spin axis will default to a_3, the third real-space lattice vector (this triggers a warning).

• magmom_axis (list or numpy array) – 3-component vector specifying direction along which magnetic moments given as scalars should point. If all magnetic moments are provided as vectors then this argument is not used.

• path_type (str) – Chooses which convention to use to generate the high symmetry path. Options are: ‘setyawan_curtarolo’, ‘hinuma’, ‘latimer_munro’ for the Setyawan & Curtarolo, Hinuma et al., and Latimer & Munro conventions. Choosing ‘all’ will generate one path with points from all three conventions. Equivalent labels between each will also be generated. Order will always be Latimer & Munro, Setyawan & Curtarolo, and Hinuma et al. Lengths for each of the paths will also be generated and output as a list. Note for ‘all’ the user will have to alter the labels on their own for plotting.

• symprec (float) – Tolerance for symmetry finding

• angle_tolerance (float) – Angle tolerance for symmetry finding.

• atol (float) – Absolute tolerance used to determine symmetric equivalence of points and lines on the BZ.

property equiv_labels[source]

Returns: The correspondence between the kpoint symbols in the Latimer and Munro convention, Setyawan and Curtarolo, and Hinuma conventions respectively. Only generated when path_type = ‘all’.

static get_continuous_path(bandstructure)[source]

Obtain a continuous version of an inputted path using graph theory. This routine will attempt to add connections between nodes of odd-degree to ensure a Eulerian path can be formed. Initial k-path must be able to be converted to a connected graph. See npj Comput Mater 6, 112 (2020). 10.1038/s41524-020-00383-7 for more details.

Parameters:

bandstructure (BandstructureSymmLine) – BandstructureSymmLine object.

Returns:

New BandstructureSymmLine object with continuous path.

Return type:

bandstructure (BandstructureSymmLine)

property label_index[source]

Returns:

The correspondence between numbers and kpoint symbols for the

combined kpath generated when path_type = ‘all’. None otherwise.

property path_lengths[source]

Returns: List of lengths of the Latimer and Munro, Setyawan and Curtarolo, and Hinuma conventions in the combined HighSymmKpath object when path_type = ‘all’ respectively. None otherwise.

property path_type[source]

Returns: The type of kpath chosen.

pymatgen.symmetry.groups module

Defines SymmetryGroup parent class and PointGroup and SpaceGroup classes. Shyue Ping Ong thanks Marc De Graef for his generous sharing of his SpaceGroup data as published in his textbook “Structure of Materials”.

class PointGroup(*args, **kwargs)[source]

Bases: PointGroup

Class representing a Point Group, with generators and symmetry operations.

symbol[source]

Full International or Hermann-Mauguin Symbol.

Type:

str

generators[source]

List of generator matrices. Note that 3x3 matrices are used for Point Groups.

Type:

list

symmetry_ops[source]

Full set of symmetry operations as matrices.

Type:

list

Initializes a Point Group from its international symbol.

Parameters:

int_symbol (str) – International or Hermann-Mauguin Symbol.

class SpaceGroup(*args, **kwargs)[source]

Bases: SpaceGroup

Class representing a SpaceGroup.

symbol[source]

Full International or Hermann-Mauguin Symbol.

Type:

str

int_number[source]

International number.

Type:

int

generators[source]

List of generator matrices. Note that 4x4 matrices are used for Space Groups.

Type:

list

order[source]

Order of Space Group.

Type:

int

Initializes a Space Group from its full or abbreviated international symbol. Only standard settings are supported.

Parameters:

int_symbol (str) – Full International (e.g., “P2/m2/m2/m”) or Hermann-Mauguin Symbol (“Pmmm”) or abbreviated symbol. The notation is a LaTeX-like string, with screw axes being represented by an underscore. For example, “P6_3/mmc”. Alternative settings can be accessed by adding a “:identifier”. For example, the hexagonal setting for rhombohedral cells can be accessed by adding a “:H”, e.g., “R-3m:H”. To find out all possible settings for a spacegroup, use the get_settings() classmethod. Alternative origin choices can be indicated by a translation vector, e.g., ‘Fm-3m(a-1/4,b-1/4,c-1/4)’.

class SymmetryGroup[source]

Bases: Sequence, Stringify, ABC

Abstract class representing a symmetry group.

is_subgroup(supergroup: SymmetryGroup) → bool[source]

True if this group is a subgroup of the supplied group.

Parameters:

supergroup (SymmetryGroup) – Supergroup to test.

Returns:

True if this group is a subgroup of the supplied group.

Return type:

bool

is_supergroup(subgroup: SymmetryGroup) → bool[source]

True if this group is a supergroup of the supplied group.

Parameters:

subgroup (SymmetryGroup) – Subgroup to test.

Returns:

True if this group is a supergroup of the supplied group.

Return type:

bool

abstract property symmetry_ops: set[SymmOp][source]

Returns: List of symmetry operations associated with the group.

to_latex_string() → str[source]

Returns:

A latex formatted group symbol with proper subscripts and overlines.

in_array_list(array_list: list[ndarray] | ndarray, arr: ndarray, tol: float = 1e-05) → bool[source]

Extremely efficient nd-array comparison using numpy’s broadcasting. This function checks if a particular array a, is present in a list of arrays. It works for arrays of any size, e.g., even matrix searches.

Parameters:

• array_list ([array]) – A list of arrays to compare to.

• arr (array) – The test array for comparison.

• tol (float) – The tolerance. Defaults to 1e-5. If 0, an exact match is done.

Returns:

(bool)

sg_symbol_from_int_number(int_number: int, hexagonal: bool = True) → str[source]

Obtains a SpaceGroup name from its international number.

Parameters:

• int_number (int) – International number.

• hexagonal (bool) – For rhombohedral groups, whether to return the hexagonal setting (default) or rhombohedral setting.

Returns:

Spacegroup symbol

Return type:

str

pymatgen.symmetry.kpath module

Provides classes for generating high-symmetry k-paths using different conventions.

class KPathBase(structure: Structure, symprec: float = 0.01, angle_tolerance=5, atol=1e-05, *args, **kwargs)[source]

Bases: ABC

This is the base class for classes used to generate high-symmetry paths in reciprocal space (k-paths) for band structure calculations.

Parameters:

• structure (Structure) – Structure object.

• symprec (float) – Tolerance for symmetry finding.

• angle_tolerance (float) – Angle tolerance for symmetry finding.

• atol (float) – Absolute tolerance used to compare structures and determine symmetric equivalence of points and lines in the BZ.

• *args – Other arguments supported by subclasses.

• **kwargs – Other keyword arguments supported by subclasses.

get_kpoints(line_density=20, coords_are_cartesian=True)[source]

Returns:

kpoints along the path in Cartesian coordinates

together with the critical-point labels.

property kpath[source]

Returns: The symmetry line path in reciprocal space.

property lattice[source]

Returns: The real space lattice.

property rec_lattice[source]

Returns: The reciprocal space lattice.

property structure[source]

Returns: The input structure.

class KPathLatimerMunro(structure, has_magmoms=False, magmom_axis=None, symprec=0.01, angle_tolerance=5, atol=1e-05)[source]

Bases: KPathBase

This class looks for a path along high-symmetry lines in the Brillouin zone. It is based on the method outlined in: npj Comput Mater 6, 112 (2020). 10.1038/s41524-020-00383-7 The user should ensure that the unit cell of the input structure is as reduced as possible, i.e. that there is no linear combination of lattice vectors which can produce a vector of lesser magnitude than the given set (this is required to obtain the correct Brillouin zone within the current implementation). This is checked during initialization and a warning is issued if the condition is not fulfilled. In the case of magnetic structures, care must also be taken to provide the magnetic primitive cell (i.e. that which reproduces the entire crystal, including the correct magnetic ordering, upon application of lattice translations). There is no algorithm to

check for this, so if the input structure is

incorrect, the class will output the incorrect k-path without any warning being issued.

Parameters:

• structure (Structure) – Structure object

• has_magmoms (bool) – Whether the input structure contains magnetic moments as site properties with the key ‘magmom.’ Values may be in the form of 3-component vectors given in the basis of the input lattice vectors, or as scalars, in which case the spin axis will default to a_3, the third real-space lattice vector (this triggers a warning).

• magmom_axis (list or numpy array) – 3-component vector specifying direction along which magnetic moments given as scalars should point. If all magnetic moments are provided as vectors then this argument is not used.

• symprec (float) – Tolerance for symmetry finding

• angle_tolerance (float) – Angle tolerance for symmetry finding.

• atol (float) – Absolute tolerance used to determine symmetric equivalence of points and lines in the BZ.

static label_points(index)[source]

Axes used in generating labels for Latimer-Munro convention.

static label_symbol(index)[source]

Letters used in generating labels for the Latimer-Munro convention.

property mag_type[source]

Returns: The type of magnetic space group as a string. Current implementation does not distinguish between types 3 and 4, so return value is ‘3/4’. If has_magmoms is False, returns ‘0’.

class KPathSeek(structure: Structure, symprec: float = 0.01, angle_tolerance=5, atol=1e-05, system_is_tri=True)[source]

Bases: KPathBase

This class looks for a path along high-symmetry lines in the Brillouin zone. It is based on Hinuma, Y., Pizzi, G., Kumagai, Y., Oba, F., & Tanaka, I. (2017). Band structure diagram paths based on crystallography. Computational Materials Science, 128, 140-184. https://doi.org/10.1016/j.commatsci.2016.10.015. It should be used with primitive structures that comply with the definition given in the paper. The symmetry is determined by spglib using the SpacegroupAnalyzer class. k-points are generated using the get_kpoints() method for the reciprocal cell basis defined in the paper.

Parameters:

• structure (Structure) – Structure object

• symprec (float) – Tolerance for symmetry finding

• angle_tolerance (float) – Angle tolerance for symmetry finding.

• atol (float) – Absolute tolerance used to determine edge cases for settings of structures.

• system_is_tri (bool) – Indicates if the system is time-reversal invariant.

class KPathSetyawanCurtarolo(structure: Structure, symprec: float = 0.01, angle_tolerance=5, atol=1e-05)[source]

Bases: KPathBase

This class looks for a path along high-symmetry lines in the Brillouin zone. It is based on Setyawan, W., & Curtarolo, S. (2010). High-throughput electronic band structure calculations: Challenges and tools. Computational Materials Science, 49(2), 299-312. doi:10.1016/j.commatsci.2010.05.010 It should be used with primitive structures that comply with the definition given in the paper. The symmetry is determined by spglib using the SpacegroupAnalyzer class. The analyzer can be used to produce the correct primitive structure with the method get_primitive_standard_structure(international_monoclinic=False). A warning will signal possible compatibility problems with the given structure. k-points generated using the get_kpoints() method are returned for the reciprocal cell basis defined in the paper.

Parameters:

• structure (Structure) – Structure object.

• symprec (float) – Tolerance for symmetry finding.

• angle_tolerance (float) – Angle tolerance for symmetry finding.

• atol (float) – Absolute tolerance used to compare the input structure with the one expected as primitive standard. A warning will be issued if the cells don’t match.

bcc()[source]

BCC Path.

bctet1(c, a)[source]

BCT1 Path.

bctet2(c, a)[source]

BCT2 Path.

property conventional[source]

Returns: The conventional cell structure.

cubic()[source]

CUB Path.

fcc()[source]

FCC Path.

hex()[source]

HEX Path.

mcl(b, c, beta)[source]

MCL Path.

mclc1(a, b, c, alpha)[source]

MCLC1 Path.

mclc2(a, b, c, alpha)[source]

MCLC2 Path.

mclc3(a, b, c, alpha)[source]

MCLC3 Path.

mclc4(a, b, c, alpha)[source]

MCLC4 Path.

mclc5(a, b, c, alpha)[source]

MCLC5 Path.

orc()[source]

ORC Path.

orcc(a, b, c)[source]

ORCC Path.

orcf1(a, b, c)[source]

ORFC1 Path.

orcf2(a, b, c)[source]

ORFC2 Path.

orcf3(a, b, c)[source]

ORFC3 Path.

orci(a, b, c)[source]

ORCI Path.

property prim[source]

Returns: The primitive cell structure.

property prim_rec[source]

Returns: The primitive reciprocal cell structure.

rhl1(alpha)[source]

RHL1 Path.

rhl2(alpha)[source]

RHL2 Path.

tet()[source]

TET Path.

tria()[source]

TRI1a Path.

trib()[source]

TRI1b Path.

pymatgen.symmetry.maggroups module

Magnetic space groups.

class MagneticSpaceGroup(*args, **kwargs)[source]

Bases: MagneticSpaceGroup

Representation of a magnetic space group.

Initializes a MagneticSpaceGroup from its Belov, Neronova and Smirnova (BNS) number supplied as a list or its label supplied as a string. To create a magnetic structure in pymatgen, the Structure.from_magnetic_spacegroup() method can be used, which relies on this class.

The main difference between magnetic space groups and normal crystallographic space groups is the inclusion of a time reversal operator that acts on an atom’s magnetic moment. This is indicated by a prime symbol (’) next to the respective symmetry operation in its label, e.g. the standard crystallographic space group Pnma has magnetic subgroups Pn’ma, Pnm’a, Pnma’, Pn’m’a, Pnm’a’, Pn’ma’, Pn’m’a’.

The magnetic space groups are classified as one of 4 types where G = magnetic space group, and F = parent crystallographic space group:

1. G=F no time reversal, i.e. the same as corresponding

   crystallographic group

2. G=F+F1’, “grey” groups, where avg. magnetic moment is zero,

   e.g. a paramagnet in zero ext. mag. field

3. G=D+(F-D)1’, where D is an equi-translation subgroup of F of

   index 2, lattice translations do not include time reversal

4. G=D+(F-D)1’, where D is an equi-class subgroup of F of index 2

There are two common settings for magnetic space groups, BNS and OG. In case 4, the BNS setting != OG setting, and so a transformation to go between the two settings is required: specifically, the BNS setting is derived from D, and the OG setting is derived from F.

This means that the OG setting refers to the unit cell if magnetic order is neglected, and requires multiple unit cells to reproduce the full crystal periodicity when magnetic moments are present. This does not make the OG setting, in general, useful for electronic structure calculations and the BNS setting is preferred. However, this class does contain information on the OG setting and can be initialized from OG labels or numbers if required.

Conventions: ITC monoclinic unique axis b, monoclinic cell choice 1, hexagonal axis for trigonal groups, origin choice 2 for groups with more than one origin choice (ISO-MAG).

Raw data comes from ISO-MAG, ISOTROPY Software Suite, iso.byu.edu http://stokes.byu.edu/iso/magnetic_data.txt with kind permission from Professor Branton Campbell, BYU

Data originally compiled from: (1) Daniel B. Litvin, Magnetic Group Tables (International Union

of Crystallography, 2013) www.iucr.org/publ/978-0-9553602-2-0.

2. C. J. Bradley and A. P. Cracknell, The Mathematical Theory of Symmetry in Solids (Clarendon Press, Oxford, 1972).

See http://stokes.byu.edu/iso/magneticspacegroupshelp.php for more information on magnetic symmetry.

Parameters:

• label – BNS number supplied as list of 2 ints or BNS label as str or index as int (1-1651) to iterate over all space groups

• setting_transformation – Transformation to apply to convert from BNS to OG setting, default is ‘a,b,c;0,0,0’ which means no transformation, i.e. BNS setting is the same as OG setting.

pymatgen.symmetry.settings module

This module provides classes for non-standard space-group settings.

class JonesFaithfulTransformation(P, p)[source]

Bases: object

Transformation for space-groups defined in a non-standard setting.

Transform between settings using matrix P and origin shift vector p, using same notation as reference.

Should initialize using from_transformation_str in Jones faithful notation, given by a string specifying both a transformation matrix and an origin shift, with parts delimited by a semi-colon. Best shown by example:

• a,b,c;0,0,0 is the identity (no change)

• -b+c,a+c,-a+b+c;0,0,0 is R3:r to R3:h (rhombohedral to hexagonal setting)

• a,b,c;-1/4,-1/4,-1/4 is Pnnn:1 to Pnnn:2 (change in origin choice)

• b,c,a;-1/2,-1/2,-1/2 is Bbab:1 to Ccca:2 (change setting and origin)

Can transform points (coords), lattices and symmetry operations.

Used for transforming magnetic space groups since these are commonly used in multiple settings, due to needing to transform between magnetic and non-magnetic settings.

See: International Tables for Crystallography (2016). Vol. A, Chapter 1.5, pp. 75-106.

property P: list[list[float]][source]

Transformation matrix.

classmethod from_origin_shift(origin_shift='0,0,0')[source]

Construct SpaceGroupTransformation from its origin shift string.

Parameters:

origin_shift (str, optional) – Defaults to “0,0,0”.

Returns:

JonesFaithfulTransformation

classmethod from_transformation_str(transformation_string='a,b,c;0,0,0')[source]

Construct SpaceGroupTransformation from its transformation string.

Parameters:

transformation_string (str, optional) – Defaults to “a,b,c;0,0,0”.

Returns:

JonesFaithfulTransformation

property inverse: JonesFaithfulTransformation[source]

JonesFaithfulTransformation.

property p: list[float][source]

Translation vector.

static parse_transformation_string(transformation_string: str = 'a,b,c;0,0,0') → tuple[list[list[float]] | ndarray, list[float]][source]

Parameters:

transformation_string (str, optional) – Defaults to “a,b,c;0,0,0”.

Raises:

ValueError – When transformation string fails to parse.

Returns:

transformation matrix & vector

Return type:

tuple[list[list[float]] | np.ndarray, list[float]]

transform_coords(coords: list[list[float]] | ndarray) → list[list[float]][source]

Takes a list of coordinates and transforms them.

transform_lattice(lattice: Lattice) → Lattice[source]

Transforms a lattice.

transform_symmop(symmop: SymmOp | MagSymmOp) → SymmOp | MagSymmOp[source]

Takes a symmetry operation and transforms it.

property transformation_string: str[source]

Transformation string.

pymatgen.symmetry.site_symmetries module

Provides analysis of site symmetries.

get_shared_symmetry_operations(struct: Structure, pointops: list[list[SymmOp]], tol: float = 0.1)[source]

Get all the point group operations shared by a pair of atomic sites in the form [[point operations of site index 1],[],…,[]].

Parameters:

• struct – Pymatgen structure

• pointops – list of point group operations from get_site_symmetries method

• tol (float) – tolerance to find symmetry operations

Returns:

list of lists of shared point operations for each pair of atomic sites

get_site_symmetries(struct: Structure, precision: float = 0.1) → list[list[SymmOp]][source]

Get all the point group operations centered on each atomic site in the form [[point operations of site index 1]…[[point operations of site index N]]].

Parameters:

• struct – Pymatgen structure

• precision (float) – tolerance to find symmetry operations

Returns:

list of lists of point operations for each atomic site

pymatgen.symmetry.structure module

This module implements symmetry-related structure forms.

class SymmetrizedStructure(structure: Structure, spacegroup: SpacegroupOperations, equivalent_positions: Sequence[int], wyckoff_letters: Sequence[str])[source]

Bases: Structure

This class represents a symmetrized structure, i.e. a structure where the spacegroup and symmetry operations are defined. This class is typically not called but instead is typically obtained by calling pymatgen.symmetry.analyzer.SpacegroupAnalyzer.get_symmetrized_structure.

equivalent_indices[source]

A list of lists of indices of the sites in the structure that are considered equivalent based on the symmetry operations of the space group.

Type:

list[List[int]]

Parameters:

• structure (Structure) – Original structure

• spacegroup (SpacegroupOperations) – An input SpacegroupOperations from SpacegroupAnalyzer.

• equivalent_positions (list[int]) – Equivalent positions from SpacegroupAnalyzer.

• wyckoff_letters (list[str]) – Wyckoff letters.

as_dict()[source]

MSONable dict.

copy()[source]

Copy of structure.

find_equivalent_sites(site: PeriodicSite) → list[PeriodicSite][source]

Finds all symmetrically equivalent sites for a particular site.

Parameters:

site (PeriodicSite) – A site in the structure

Raises:

ValueError – if site is not in the structure.

Returns:

all symmetrically equivalent sites.

Return type:

list[PeriodicSite]

classmethod from_dict(dct: dict) → Self[source]

Parameters:

dct (dict) – Dict representation.

Returns:

SymmetrizedStructure