pymatgen.symmetry.analyzer module

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:

  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. Asymetric 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.
sch_symbol

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_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 atom i unto j.

Return type:dict
get_pointgroup()[source]

Returns a PointGroup object for the molecule.

inversion_op = Rot: [[-1. -0. -0.] [-0. -1. -0.] [-0. -0. -1.]] tau [ 0. 0. 0.]
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 atom i unto j.

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.
sch_symbol

Schoenflies symbol of the point group.

class SpacegroupAnalyzer(structure, symprec=0.01, angle_tolerance=5)[source]

Bases: object

Takes a pymatgen.core.structure.Structure object and a symprec. Uses pyspglib to perform various symmetry finding operations.

Parameters:
  • structure (Structure/IStructure) – Structure to find symmetry
  • symprec (float) – Tolerance for symmetry finding. Defaults to 1e-3, 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). 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)

Returns:The structure in a conventional standardized cell
get_crystal_system()[source]

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

Returns:Crystal system for structure.
Return type:(str)
get_hall()[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,
  • 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=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()[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.
Return type:(str)
get_point_group(*args, **kwargs)
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). High-throughput electronic band structure calculations: Challenges and tools. Computational Materials Science, 49(2), 299-312. 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(*args, **kwargs)
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: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 symmops. But cartesian can be returned too.

Returns:List of symmetry operations.
Return type:([SymmOp])
is_laue()[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)[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 ([Site]) – 1st set of sites
  • sites2 ([Site]) – 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 atom i unto j.

Return type:

dict