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_tol=0.1)[source]¶ Bases:
object
A class to analyze the point group of a molecule. The general outline of the algorithm is as follows:
Center the molecule around its center of mass.
Compute the inertia tensor and the eigenvalues and eigenvectors.
Handle the symmetry detection based on eigenvalues.
Linear molecules have one zero eigenvalue. Possible symmetry operations are C*v or D*v
Asymetric top molecules have all different eigenvalues. The maximum rotational symmetry in such molecules is 2
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.
Spherical top molecules have all three eigenvalues equal. They have the rare T, O or I point groups.
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_tol (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
 Parameters
None –
 Returns
The returned dictionary has 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 atomi
untoj
. Return type
dict

get_symmetry_operations
()[source]¶ Return symmetry operations as a list of SymmOp objects. Returns Cartesian coord symmops.
 Returns
List of symmetry operations.
 Return type
([SymmOp])

is_valid_op
(symmop)[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 Parameters
None –
 Returns
The returned dictionary has 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 atomi
untoj
. Return type
dict

class
PointGroupOperations
(sch_symbol, operations, tol=0.1)[source]¶ Bases:
list
Defines a point group, which is essentially a sequence of symmetry operations.
 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, symprec=0.01, angle_tolerance=5.0)[source]¶ Bases:
object
Takes a pymatgen.core.structure.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
()[source]¶ Find a primitive version of the unit cell.
 Returns
A primitive cell in the input cell is searched and returned as an Structure object. If no primitive cell is found, None is returned.

get_conventional_standard_structure
(international_monoclinic=True)[source]¶ Gives a structure with a conventional cell according to certain standards. The standards are defined in Setyawan, W., & Curtarolo, S. (2010). Highthroughput electronic band structure calculations: Challenges and tools. Computational Materials Science, 49(2), 299312. 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.
 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). Highthroughput electronic band structure calculations: Challenges and tools. Computational Materials Science, 49(2), 299312. doi:10.1016/j.commatsci.2010.05.010
 Returns
Transformation matrix to go from conventional to primitive cell

get_crystal_system
()[source]¶ Get the crystal system for the structure, e.g., (triclinic, orthorhombic, cubic, etc.).
 Returns
Crystal system for structure or None if system cannot be detected.
 Return type
(str)

get_ir_reciprocal_mesh
(mesh=10, 10, 10, is_shift=0, 0, 0)[source]¶ kpoint 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,
means all points are shifted by 0.5, 0.5, 0.5. (1)) –
 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_kpoint_weights
(kpoints, atol=1e05)[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
()[source]¶ Get the lattice for the structure, e.g., (triclinic, orthorhombic, cubic, etc.).This is the same than the crystal system with the exception of the hexagonal/rhombohedral lattice
 Returns
Lattice type for structure or None if type cannot be detected.
 Return type
(str)

get_point_group_operations
(cartesian=False)[source]¶ Return symmetry operations as a list of SymmOp objects. By default returns fractional coord symmops. But cartesian can be returned too.
 Parameters
cartesian (bool) – Whether to return SymmOps as cartesian or direct coordinate operations.
 Returns
List of point group symmetry operations.
 Return type
([SymmOp])

get_point_group_symbol
()[source]¶ Get the point group associated with the structure.
 Returns
Point group for structure.
 Return type
(Pointgroup)

get_primitive_standard_structure
(international_monoclinic=True)[source]¶ Gives a structure with a primitive cell according to certain standards the standards are defined in Setyawan, W., & Curtarolo, S. (2010). Highthroughput electronic band structure calculations: Challenges and tools. Computational Materials Science, 49(2), 299312. doi:10.1016/j.commatsci.2010.05.010
 Returns
The structure in a primitive standardized cell

get_refined_structure
()[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.
 Returns
Refined structure.

get_space_group_number
()[source]¶ Get the international spacegroup number (e.g., 62) for structure.
 Returns
International spacegroup number for structure.
 Return type
(int)

get_space_group_operations
()[source]¶ Get the SpacegroupOperations for the Structure.
 Returns
SpacgroupOperations object.

get_space_group_symbol
()[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

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)

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)[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, tol, give_only_index=False)[source]¶ Cluster sites based on distance and species type.
 Parameters
mol (Molecule) – Molecule with origin at center of mass.
tol (float) – Tolerance to use.
 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, tol)[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 ([SymmOp]) – Initial set of symmetry operations.
 Returns
Full set of symmetry operations.

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
PointGroupAnalyzer
.epsilon (float) – If the elementwise absolute difference of two subsequently symmetrized structures is smaller epsilon, the iteration stops before
max_n
is reached.
 Returns
The returned dictionary has 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 atomi
untoj
. Return type
dict