pymatgen.analysis.chemenv.coordination_environments.coordination_geometry_finder module¶
This module contains the main object used to identify the coordination environments in a given structure. If you use this module, please cite the following:
David Waroquiers, Xavier Gonze, GianMarco Rignanese, Cathrin WelkerNieuwoudt, Frank Rosowski, Michael Goebel, Stephan Schenk, Peter Degelmann, Rute Andre, Robert Glaum, and Geoffroy Hautier, “Statistical analysis of coordination environments in oxides”, Chem. Mater., 2017, 29 (19), pp 8346–8360, DOI: 10.1021/acs.chemmater.7b02766

class
AbstractGeometry
(central_site=None, bare_coords=None, centering_type='standard', include_central_site_in_centroid=False, optimization=None)[source]¶ Bases:
object
Class used to describe a geometry (perfect or distorted)
Constructor for the abstract geometry :param central_site: Coordinates of the central site :param bare_coords: Coordinates of the neighbors of the central site :param centering_type: How to center the abstract geometry :param include_central_site_in_centroid: When the centering is on the centroid, the central site is included
if this parameter is set to True.
 Raise
ValueError if the parameters are not consistent

property
cn
¶ Coordination number
 Type
return

property
coordination_number
¶ Coordination number
 Type
return

class
LocalGeometryFinder
(permutations_safe_override=False, plane_ordering_override=True, debug_level=None, plane_safe_permutations=False, only_symbols=None)[source]¶ Bases:
object
Main class used to find the local environments in a structure
Constructor for the LocalGeometryFinder, initializes the list of coordination geometries :param permutations_safe_override: If set to True, all permutations are tested (very timeconsuming for large
coordination numbers!)
 Parameters
plane_ordering_override – If set to False, the ordering of the points in the plane is disabled

BVA_DISTANCE_SCALE_FACTORS
= {'GGA_relaxed': 1.015, 'LDA_relaxed': 0.995, 'experimental': 1.0}¶

DEFAULT_BVA_DISTANCE_SCALE_FACTOR
= 1.0¶

DEFAULT_SPG_ANALYZER_OPTIONS
= {'angle_tolerance': 5, 'symprec': 0.001}¶

DEFAULT_STRATEGY
= <pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies.MultiWeightsChemenvStrategy object>¶

PRESETS
= {'DEFAULT': {'maximum_distance_factor': 2.0, 'minimum_angle_factor': 0.05, 'optimization': 2, 'voronoi_normalized_angle_tolerance': 0.03, 'voronoi_normalized_distance_tolerance': 0.05}}¶

STRUCTURE_REFINEMENT_NONE
= 'none'¶

STRUCTURE_REFINEMENT_REFINED
= 'refined'¶

STRUCTURE_REFINEMENT_SYMMETRIZED
= 'symmetrized'¶

compute_coordination_environments
(structure, indices=None, only_cations=True, strategy=<pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies.MultiWeightsChemenvStrategy object>, valences='bondvalenceanalysis', initial_structure_environments=None)[source]¶  Parameters
structure –
indices –
only_cations –
strategy –
valences –
initial_structure_environments –
 Returns

compute_structure_environments
(excluded_atoms=None, only_atoms=None, only_cations=True, only_indices=None, maximum_distance_factor=2.0, minimum_angle_factor=0.05, max_cn=None, min_cn=None, only_symbols=None, valences='undefined', additional_conditions=None, info=None, timelimit=None, initial_structure_environments=None, get_from_hints=False, voronoi_normalized_distance_tolerance=0.05, voronoi_normalized_angle_tolerance=0.03, recompute=None, optimization=2)[source]¶ Computes and returns the StructureEnvironments object containing all the information about the coordination environments in the structure :param excluded_atoms: Atoms for which the coordination geometries does not have to be identified :param only_atoms: If not set to None, atoms for which the coordination geometries have to be identified :param only_cations: If set to True, will only compute environments for cations :param only_indices: If not set to None, will only compute environments the atoms of the given indices :param maximum_distance_factor: If not set to None, neighbors beyond
maximum_distance_factor*closest_neighbor_distance are not considered
 Parameters
minimum_angle_factor – If not set to None, neighbors for which the angle is lower than minimum_angle_factor*largest_angle_neighbor are not considered
max_cn – maximum coordination number to be considered
min_cn – minimum coordination number to be considered
only_symbols – if not set to None, consider only coordination environments with the given symbols
valences – valences of the atoms
additional_conditions – additional conditions to be considered in the bonds (example : only bonds between cation and anion
info – additional info about the calculation
timelimit – time limit (in secs) after which the calculation of the StructureEnvironments object stops
initial_structure_environments – initial StructureEnvironments object (most probably incomplete)
get_from_hints – whether to add neighbors sets from “hints” (e.g. capped environment => test the neighbors without the cap)
voronoi_normalized_distance_tolerance – tolerance for the normalized distance used to distinguish neighbors sets
voronoi_normalized_angle_tolerance – tolerance for the normalized angle used to distinguish neighbors sets
recompute – whether to recompute the sites already computed (when initial_structure_environments is not None)
optimization – optimization algorithm
 Returns
The StructureEnvironments object containing all the information about the coordination environments in the structure

coordination_geometry_symmetry_measures
(coordination_geometry, tested_permutations=False, points_perfect=None, optimization=None)[source]¶ Returns the symmetry measures of a given coordination_geometry for a set of permutations depending on the permutation setup. Depending on the parameters of the LocalGeometryFinder and on the coordination
geometry, different methods are called.
 Parameters
coordination_geometry – Coordination geometry for which the symmetry measures are looked for
 Returns
the symmetry measures of a given coordination_geometry for a set of permutations
 Raise
NotImplementedError if the permutation_setup does not exists

coordination_geometry_symmetry_measures_fallback_random
(coordination_geometry, NRANDOM=10, points_perfect=None)[source]¶ Returns the symmetry measures for a random set of permutations for the coordination geometry “coordination_geometry”. Fallback implementation for the plane separation algorithms measures of each permutation
 Parameters
coordination_geometry – The coordination geometry to be investigated
NRANDOM – Number of random permutations to be tested
 Returns
The symmetry measures for the given coordination geometry for each permutation investigated

coordination_geometry_symmetry_measures_separation_plane
(coordination_geometry, separation_plane_algo, testing=False, tested_permutations=False, points_perfect=None)[source]¶ Returns the symmetry measures of the given coordination geometry “coordination_geometry” using separation facets to reduce the complexity of the system. Caller to the refined 2POINTS, 3POINTS and other … :param coordination_geometry: The coordination geometry to be investigated :return: The symmetry measures for the given coordination geometry for each plane and permutation investigated

coordination_geometry_symmetry_measures_separation_plane_optim
(coordination_geometry, separation_plane_algo, points_perfect=None, nb_set=None, optimization=None)[source]¶ Returns the symmetry measures of the given coordination geometry “coordination_geometry” using separation facets to reduce the complexity of the system. Caller to the refined 2POINTS, 3POINTS and other … :param coordination_geometry: The coordination geometry to be investigated :return: The symmetry measures for the given coordination geometry for each plane and permutation investigated

coordination_geometry_symmetry_measures_sepplane_optim
(coordination_geometry, points_perfect=None, nb_set=None, optimization=None)[source]¶ Returns the symmetry measures of a given coordination_geometry for a set of permutations depending on the permutation setup. Depending on the parameters of the LocalGeometryFinder and on the coordination
geometry, different methods are called.
 Parameters
coordination_geometry – Coordination geometry for which the symmetry measures are looked for
 Returns
the symmetry measures of a given coordination_geometry for a set of permutations
 Raise
NotImplementedError if the permutation_setup does not exists

coordination_geometry_symmetry_measures_standard
(coordination_geometry, algo, points_perfect=None, optimization=None)[source]¶ Returns the symmetry measures for a set of permutations (whose setup depends on the coordination geometry) for the coordination geometry “coordination_geometry”. Standard implementation looking for the symmetry measures of each permutation
 Parameters
coordination_geometry – The coordination geometry to be investigated
 Returns
The symmetry measures for the given coordination geometry for each permutation investigated

get_coordination_symmetry_measures
(only_minimum=True, all_csms=True, optimization=None)[source]¶ Returns the continuous symmetry measures of the current local geometry in a dictionary. :return: the continuous symmetry measures of the current local geometry in a dictionary.

get_coordination_symmetry_measures_optim
(only_minimum=True, all_csms=True, nb_set=None, optimization=None)[source]¶ Returns the continuous symmetry measures of the current local geometry in a dictionary. :return: the continuous symmetry measures of the current local geometry in a dictionary.

get_structure
()[source]¶ Returns the pymatgen Structure that has been setup for the identification of geometries (the initial one might have been refined/symmetrized using the SpaceGroupAnalyzer). :return: The pymatgen Structure that has been setup for the identification of geometries (the initial one might have been refined/symmetrized using the SpaceGroupAnalyzer).

set_structure
(lattice, species, coords, coords_are_cartesian)[source]¶ Sets up the pymatgen structure for which the coordination geometries have to be identified starting from the lattice, the species and the coordinates :param lattice: The lattice of the structure :param species: The species on the sites :param coords: The coordinates of the sites :param coords_are_cartesian: If set to True, the coordinates are given in cartesian coordinates

setup_explicit_indices_local_geometry
(explicit_indices)[source]¶ Sets up explicit indices for the local geometry, for testing purposes :param explicit_indices: explicit indices for the neighbors (set of numbers from 0 to CN1 in a given order)

setup_local_geometry
(isite, coords, optimization=None)[source]¶ Sets up the AbstractGeometry for the local geometry of site with index isite. :param isite: Index of the site for which the local geometry has to be set up :param coords: The coordinates of the (local) neighbors

setup_ordered_indices_local_geometry
(coordination)[source]¶ Sets up ordered indices for the local geometry, for testing purposes :param coordination: coordination of the local geometry

setup_parameter
(parameter, value)[source]¶ Setup of one specific parameter to the given value. The other parameters are unchanged. See setup_parameters method for the list of possible parameters :param parameter: Parameter to setup/update :param value: Value of the parameter

setup_parameters
(centering_type='standard', include_central_site_in_centroid=False, bva_distance_scale_factor=None, structure_refinement='refined', spg_analyzer_options=None)[source]¶ Setup of the parameters for the coordination geometry finder. A reference point for the geometries has to be chosen. This can be the centroid of the structure (including or excluding the atom for which the coordination geometry is looked for) or the atom itself. In the ‘standard’ centering_type, the reference point is the central atom for coordination numbers 1, 2, 3 and 4 and the centroid for coordination numbers > 4. :param centering_type: Type of the reference point (centering) ‘standard’, ‘centroid’ or ‘central_site’ :param include_central_site_in_centroid: In case centering_type is ‘centroid’, the central site is included if
this value is set to True.
 Parameters
bva_distance_scale_factor – Scaling factor for the bond valence analyzer (this might be different whether the structure is an experimental one, an LDA or a GGA relaxed one, or any other relaxation scheme (where under or overestimation of bond lengths is known).
structure_refinement – Refinement of the structure. Can be “none”, “refined” or “symmetrized”.
spg_analyzer_options – Options for the SpaceGroupAnalyzer (dictionary specifying “symprec” and “angle_tolerance”. See pymatgen’s SpaceGroupAnalyzer for more information.

setup_random_indices_local_geometry
(coordination)[source]¶ Sets up random indices for the local geometry, for testing purposes :param coordination: coordination of the local geometry

setup_random_structure
(coordination)[source]¶ Sets up a purely random structure with a given coordination. :param coordination: coordination number for the random structure

setup_structure
(structure)[source]¶ Sets up the structure for which the coordination geometries have to be identified. The structure is analyzed with the space group analyzer and a refined structure is used :param structure: A pymatgen Structure

setup_test_perfect_environment
(symbol, randomness=False, max_random_dist=0.1, symbol_type='mp_symbol', indices='RANDOM', random_translation='NONE', random_rotation='NONE', random_scale='NONE', points=None)[source]¶  Parameters
symbol –
randomness –
max_random_dist –
symbol_type –
indices –
random_translation –
random_rotation –
random_scale –
points –
 Returns

find_rotation
(points_distorted, points_perfect)[source]¶ This finds the rotation matrix that aligns the (distorted) set of points “points_distorted” with respect to the (perfect) set of points “points_perfect” in a leastsquare sense. :param points_distorted: List of points describing a given (distorted) polyhedron for which the rotation that
aligns these points in a leastsquare sense to the set of perfect points “points_perfect”
 Parameters
points_perfect – List of “perfect” points describing a given model polyhedron.
 Returns
The rotation matrix

find_scaling_factor
(points_distorted, points_perfect, rot)[source]¶ This finds the scaling factor between the (distorted) set of points “points_distorted” and the (perfect) set of points “points_perfect” in a leastsquare sense. :param points_distorted: List of points describing a given (distorted) polyhedron for which the scaling factor has
to be obtained.
 Parameters
points_perfect – List of “perfect” points describing a given model polyhedron.
rot – The rotation matrix
 Returns
The scaling factor between the two structures and the rotated set of (distorted) points.

symmetry_measure
(points_distorted, points_perfect)[source]¶ Computes the continuous symmetry measure of the (distorted) set of points “points_distorted” with respect to the (perfect) set of points “points_perfect”. :param points_distorted: List of points describing a given (distorted) polyhedron for which the symmetry measure
has to be computed with respect to the model polyhedron described by the list of points “points_perfect”.
 Parameters
points_perfect – List of “perfect” points describing a given model polyhedron.
 Returns
The continuous symmetry measure of the distorted polyhedron with respect to the perfect polyhedron