pymatgen.analysis.chemenv.coordination_environments package
Package for analyzing coordination environments.
Subpackages
Submodules
pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies module
This module provides so-called “strategies” to determine the coordination environments of an atom in a structure. Some strategies can favour larger or smaller environments. Some strategies uniquely identifies the environments while some others can identify the environment as a “mix” of several environments, each of which is assigned with a given fraction. The choice of the strategy depends on the purpose of the user.
- class AbstractChemenvStrategy(structure_environments=None, symmetry_measure_type='csm_wcs_ctwcc')[source]
Bases:
MSONableClass used to define a Chemenv strategy for the neighbors and coordination environment to be applied to a StructureEnvironments object.
Abstract constructor for the all chemenv strategies. :param structure_environments: StructureEnvironments object containing all the information on the
coordination of the sites in a structure.
- abstract as_dict()[source]
Bson-serializable dict representation of the SimplestChemenvStrategy object. :return: Bson-serializable dict representation of the SimplestChemenvStrategy object.
- equivalent_site_index_and_transform(psite)[source]
Get the equivalent site and corresponding symmetry+translation transformations.
- Parameters:
psite – Periodic site.
- Returns:
Equivalent site in the unit cell, translations and symmetry transformation.
- classmethod from_dict(d)[source]
Reconstructs the SimpleAbundanceChemenvStrategy object from a dict representation of the SimpleAbundanceChemenvStrategy object created using the as_dict method. :param d: dict representation of the SimpleAbundanceChemenvStrategy object :return: StructureEnvironments object.
- get_site_ce_fractions_and_neighbors(site, full_ce_info=False, strategy_info=False)[source]
Applies the strategy to the structure_environments object in order to get coordination environments, their fraction, csm, geometry_info, and neighbors :param site: Site for which the above information is seeked :return: The list of neighbors of the site. For complex strategies, where one allows multiple solutions, this can return a list of list of neighbors.
- abstract get_site_coordination_environment(site)[source]
Applies the strategy to the structure_environments object in order to define the coordination environment of a given site. :param site: Site for which the coordination environment is looked for :return: The coordination environment of the site. For complex strategies, where one allows multiple
solutions, this can return a list of coordination environments for the site.
- abstract get_site_coordination_environments(site)[source]
Applies the strategy to the structure_environments object in order to define the coordination environment of a given site. :param site: Site for which the coordination environment is looked for :return: The coordination environment of the site. For complex strategies, where one allows multiple
solutions, this can return a list of coordination environments for the site.
- abstract get_site_coordination_environments_fractions(site, isite=None, dequivsite=None, dthissite=None, mysym=None, ordered=True, min_fraction=0, return_maps=True, return_strategy_dict_info=False)[source]
Applies the strategy to the structure_environments object in order to define the coordination environment of a given site. :param site: Site for which the coordination environment is looked for :return: The coordination environment of the site. For complex strategies, where one allows multiple
solutions, this can return a list of coordination environments for the site.
- abstract get_site_neighbors(site)[source]
Applies the strategy to the structure_environments object in order to get the neighbors of a given site. :param site: Site for which the neighbors are looked for :param structure_environments: StructureEnvironments object containing all the information needed to get the
neighbors of the site
- Returns:
The list of neighbors of the site. For complex strategies, where one allows multiple solutions, this can return a list of list of neighbors.
- prepare_symmetries()[source]
Prepare the symmetries for the structure contained in the structure environments.
- set_option(option_name, option_value)[source]
Set up a given option for this strategy.
- Parameters:
option_name – Name of the option.
option_value – Value for this option.
- Returns:
None
- set_structure_environments(structure_environments)[source]
Set the structure environments to this strategy.
- Parameters:
structure_environments – StructureEnvironments object.
- Returns:
None
- class AdditionalConditionInt(integer)[source]
Bases:
int,StrategyOptionInteger representing an additional condition in a strategy.
Special int representing additional conditions.
- allowed_values: str | None = "Integer amongst :\n - 0 for 'No additional condition'\n - 1 for 'Only anion-cation bonds'\n - 2 for 'No element-element bonds (same elements)'\n - 3 for 'Only anion-cation bonds and no element-element bonds (same elements)'\n - 4 for 'Only element-oxygen bonds'\n"[source]
- class AngleCutoffFloat(myfloat)[source]
Bases:
float,StrategyOptionAngle cutoff in a strategy.
Special float that should be between 0 and 1.
- Parameters:
myfloat – Angle cutoff.
- class AngleNbSetWeight(aa=1)[source]
Bases:
NbSetWeightWeight of neighbors set based on the angle.
Initialize AngleNbSetWeight estimator.
- Parameters:
aa – Exponent of the angle for the estimator.
- static angle_sum(nb_set)[source]
Sum of all angles in a neighbors set.
- Parameters:
nb_set – Neighbors set.
- Returns:
Sum of solid angles for the neighbors set.
- angle_sumn(nb_set)[source]
Sum of all angles to a given power in a neighbors set.
- Parameters:
nb_set – Neighbors set.
- Returns:
Sum of solid angles to the power aa for the neighbors set.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class AnglePlateauNbSetWeight(angle_function=None, weight_function=None)[source]
Bases:
NbSetWeightWeight of neighbors set based on the angle.
Initialize AnglePlateauNbSetWeight.
- Parameters:
angle_function – Angle function to use.
weight_function – Ratio function to use.
- classmethod from_dict(dd)[source]
Initialize from dict.
- Parameters:
dd – Dict representation of AnglePlateauNbSetWeight.
- Returns:
AnglePlateauNbSetWeight.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class CNBiasNbSetWeight(cn_weights, initialization_options)[source]
Bases:
NbSetWeightWeight of neighbors set based on specific biases towards specific coordination numbers.
Initialize CNBiasNbSetWeight.
- Parameters:
cn_weights – Weights for each coordination.
initialization_options – Options for initialization.
- classmethod explicit(cn_weights)[source]
Initializes weights explicitly for each coordination.
- Parameters:
cn_weights – Weights for each coordination.
- Returns:
CNBiasNbSetWeight.
- classmethod from_description(dd)[source]
Initializes weights from description.
- Parameters:
dd – Dictionary description.
- Returns:
CNBiasNbSetWeight.
- classmethod from_dict(dd)[source]
Initialize from dict.
- Parameters:
dd – Dict representation of CNBiasNbSetWeight.
- Returns:
CNBiasNbSetWeight.
- classmethod geometrically_equidistant(weight_cn1, weight_cn13)[source]
Initializes geometrically equidistant weights for each coordination.
- Parameters:
weight_cn1 – Weight of coordination 1.
weight_cn13 – Weight of coordination 13.
- Returns:
CNBiasNbSetWeight.
- classmethod linearly_equidistant(weight_cn1, weight_cn13)[source]
Initializes linearly equidistant weights for each coordination.
- Parameters:
weight_cn1 – Weight of coordination 1.
weight_cn13 – Weight of coordination 13.
- Returns:
CNBiasNbSetWeight.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class CSMFloat(myfloat)[source]
Bases:
float,StrategyOptionReal number representing a Continuous Symmetry Measure.
Special float that should be between 0 and 100.
- Parameters:
myfloat – CSM.
- class DeltaCSMNbSetWeight(effective_csm_estimator={'function': 'power2_inverse_decreasing', 'options': {'max_csm': 8.0}}, weight_estimator={'function': 'smootherstep', 'options': {'delta_csm_max': 3.0, 'delta_csm_min': 0.5}}, delta_cn_weight_estimators=None, symmetry_measure_type='csm_wcs_ctwcc')[source]
Bases:
NbSetWeightWeight of neighbors set based on the differences of CSM.
Initialize SelfCSMNbSetWeight.
- Parameters:
effective_csm_estimator – Ratio function used for the effective CSM (comparison between neighbors sets).
weight_estimator – Weight estimator within a given neighbors set.
delta_cn_weight_estimators – Specific weight estimators for specific cn
symmetry_measure_type – Type of symmetry measure to be used.
- DEFAULT_EFFECTIVE_CSM_ESTIMATOR = {'function': 'power2_inverse_decreasing', 'options': {'max_csm': 8.0}}[source]
- DEFAULT_WEIGHT_ESTIMATOR = {'function': 'smootherstep', 'options': {'delta_csm_max': 3.0, 'delta_csm_min': 0.5}}[source]
- classmethod delta_cn_specifics(delta_csm_mins=None, delta_csm_maxs=None, function='smootherstep', symmetry_measure_type='csm_wcs_ctwcc', effective_csm_estimator={'function': 'power2_inverse_decreasing', 'options': {'max_csm': 8.0}})[source]
Initializes DeltaCSMNbSetWeight from specific coordination number differences.
- Parameters:
delta_csm_mins – Minimums for each coordination number.
delta_csm_maxs – Maximums for each coordination number.
function – Ratio function used.
symmetry_measure_type – Type of symmetry measure to be used.
effective_csm_estimator – Ratio function used for the effective CSM (comparison between neighbors sets).
- Returns:
DeltaCSMNbSetWeight.
- classmethod from_dict(dd)[source]
Initialize from dict.
- Parameters:
dd – Dict representation of DeltaCSMNbSetWeight.
- Returns:
DeltaCSMNbSetWeight.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class DeltaDistanceNbSetWeight(weight_function=None, nbs_source='voronoi')[source]
Bases:
NbSetWeightWeight of neighbors set based on the difference of distances.
Initialize DeltaDistanceNbSetWeight.
- Parameters:
weight_function – Ratio function to use.
nbs_source – Source of the neighbors.
- classmethod from_dict(dd)[source]
Initialize from dict.
- Parameters:
dd – Dict representation of DeltaDistanceNbSetWeight.
- Returns:
DeltaDistanceNbSetWeight.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class DistanceAngleAreaNbSetWeight(weight_type='has_intersection', surface_definition={'angle_bounds': {'lower': 0.1, 'upper': 0.8}, 'distance_bounds': {'lower': 1.2, 'upper': 1.8}, 'type': 'standard_elliptic'}, nb_sets_from_hints='fallback_to_source', other_nb_sets='0_weight', additional_condition=1, smoothstep_distance=None, smoothstep_angle=None)[source]
Bases:
NbSetWeightWeight of neighbors set based on the area in the distance-angle space.
Initialize CNBiasNbSetWeight.
- Parameters:
weight_type – Type of weight.
surface_definition – Definition of the surface.
nb_sets_from_hints – How to deal with neighbors sets obtained from “hints”.
other_nb_sets – What to do with other neighbors sets.
additional_condition – Additional condition to be used.
smoothstep_distance – Smoothstep distance.
smoothstep_angle – Smoothstep angle.
- DEFAULT_SURFACE_DEFINITION = {'angle_bounds': {'lower': 0.1, 'upper': 0.8}, 'distance_bounds': {'lower': 1.2, 'upper': 1.8}, 'type': 'standard_elliptic'}[source]
- classmethod from_dict(dd)[source]
Initialize from dict.
- Parameters:
dd – Dict representation of DistanceAngleAreaNbSetWeight.
- Returns:
DistanceAngleAreaNbSetWeight.
- rectangle_crosses_area(d1, d2, a1, a2)[source]
Whether a given rectangle crosses the area defined by the upper and lower curves.
- Parameters:
d1 – lower d.
d2 – upper d.
a1 – lower a.
a2 – upper a.
- Returns:
- w_area_has_intersection(nb_set, structure_environments, cn_map, additional_info)[source]
Get intersection of the neighbors set area with the surface.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments.
cn_map – Mapping index of the neighbors set.
additional_info – Additional information.
- Returns:
Area intersection between neighbors set and surface.
- w_area_intersection_nbsfh_fbs_onb0(nb_set, structure_environments, cn_map, additional_info)[source]
Get intersection of the neighbors set area with the surface.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments.
cn_map – Mapping index of the neighbors set.
additional_info – Additional information.
- Returns:
Area intersection between neighbors set and surface.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class DistanceCutoffFloat(myfloat)[source]
Bases:
float,StrategyOptionDistance cutoff in a strategy.
Special float that should be between 1 and infinity.
- Parameters:
myfloat – Distance cutoff.
- class DistanceNbSetWeight(weight_function=None, nbs_source='voronoi')[source]
Bases:
NbSetWeightWeight of neighbors set based on the distance.
Initialize DistanceNbSetWeight.
- Parameters:
weight_function – Ratio function to use.
nbs_source – Source of the neighbors.
- classmethod from_dict(dd)[source]
Initialize from dict.
- Parameters:
dd – Dict representation of DistanceNbSetWeight.
- Returns:
DistanceNbSetWeight.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class DistancePlateauNbSetWeight(distance_function=None, weight_function=None)[source]
Bases:
NbSetWeightWeight of neighbors set based on the distance.
Initialize DistancePlateauNbSetWeight.
- Parameters:
distance_function – Distance function to use.
weight_function – Ratio function to use.
- classmethod from_dict(dd)[source]
Initialize from dict.
- Parameters:
dd – Dict representation of DistancePlateauNbSetWeight.
- Returns:
DistancePlateauNbSetWeight.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class MultiWeightsChemenvStrategy(structure_environments=None, additional_condition=1, symmetry_measure_type='csm_wcs_ctwcc', dist_ang_area_weight=None, self_csm_weight=None, delta_csm_weight=None, cn_bias_weight=None, angle_weight=None, normalized_angle_distance_weight=None, ce_estimator={'function': 'power2_inverse_power2_decreasing', 'options': {'max_csm': 8.0}})[source]
Bases:
WeightedNbSetChemenvStrategyMultiWeightsChemenvStrategy.
Constructor for the MultiWeightsChemenvStrategy. :param structure_environments: StructureEnvironments object containing all the information on the
coordination of the sites in a structure.
- DEFAULT_CE_ESTIMATOR = {'function': 'power2_inverse_power2_decreasing', 'options': {'max_csm': 8.0}}[source]
- as_dict()[source]
- Returns:
Bson-serializable dict representation of the MultiWeightsChemenvStrategy object.
- classmethod from_dict(d)[source]
Reconstructs the MultiWeightsChemenvStrategy object from a dict representation of the MultipleAbundanceChemenvStrategy object created using the as_dict method. :param d: dict representation of the MultiWeightsChemenvStrategy object :return: MultiWeightsChemenvStrategy object.
- class NbSetWeight[source]
Bases:
MSONableAbstract object for neighbors sets weights estimations.
- abstract weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class NormalizedAngleDistanceNbSetWeight(average_type, aa, bb)[source]
Bases:
NbSetWeightWeight of neighbors set based on the normalized angle/distance.
Initialize NormalizedAngleDistanceNbSetWeight.
- Parameters:
average_type – Average function.
aa – Exponent for the angle values.
bb – Exponent for the distance values.
- static ang(nb_set)[source]
Angle weight.
- Parameters:
nb_set – Neighbors set.
- Returns:
List of angle weights.
- static anginvdist(nb_set)[source]
Angle/distance weight.
- Parameters:
nb_set – Neighbors set.
- Returns:
List of angle/distance weights.
- anginvndist(nb_set)[source]
Angle/power distance weight.
- Parameters:
nb_set – Neighbors set.
- Returns:
List of angle/power distance weights.
- angn(nb_set)[source]
Power angle weight.
- Parameters:
nb_set – Neighbors set.
- Returns:
List of power angle weights.
- angninvdist(nb_set)[source]
Power angle/distance weight.
- Parameters:
nb_set – Neighbors set.
- Returns:
List of power angle/distance weights.
- angninvndist(nb_set)[source]
Power angle/power distance weight.
- Parameters:
nb_set – Neighbors set.
- Returns:
List of power angle/power distance weights.
- static aweight(fda_list)[source]
Standard mean of the weights.
- Parameters:
fda_list – List of estimator weights for each neighbor.
- Returns:
Standard mean of the weights.
- classmethod from_dict(dd)[source]
Initialize from dict.
- Parameters:
dd – Dict representation of NormalizedAngleDistanceNbSetWeight.
- Returns:
NormalizedAngleDistanceNbSetWeight.
- static gweight(fda_list)[source]
Geometric mean of the weights.
- Parameters:
fda_list – List of estimator weights for each neighbor.
- Returns:
Geometric mean of the weights.
- static invdist(nb_set)[source]
Inverse distance weight.
- Parameters:
nb_set – Neighbors set.
- Returns:
List of inverse distances.
- invndist(nb_set)[source]
Inverse power distance weight.
- Parameters:
nb_set – Neighbors set.
- Returns:
List of inverse power distances.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class SelfCSMNbSetWeight(effective_csm_estimator={'function': 'power2_inverse_decreasing', 'options': {'max_csm': 8.0}}, weight_estimator={'function': 'power2_decreasing_exp', 'options': {'alpha': 1, 'max_csm': 8.0}}, symmetry_measure_type='csm_wcs_ctwcc')[source]
Bases:
NbSetWeightWeight of neighbors set based on the Self CSM.
Initialize SelfCSMNbSetWeight.
- Parameters:
effective_csm_estimator – Ratio function used for the effective CSM (comparison between neighbors sets).
weight_estimator – Weight estimator within a given neighbors set.
symmetry_measure_type – Type of symmetry measure to be used.
- DEFAULT_EFFECTIVE_CSM_ESTIMATOR = {'function': 'power2_inverse_decreasing', 'options': {'max_csm': 8.0}}[source]
- DEFAULT_WEIGHT_ESTIMATOR = {'function': 'power2_decreasing_exp', 'options': {'alpha': 1, 'max_csm': 8.0}}[source]
- classmethod from_dict(dd)[source]
Initialize from dict.
- Parameters:
dd – Dict representation of SelfCSMNbSetWeight.
- Returns:
SelfCSMNbSetWeight.
- weight(nb_set, structure_environments, cn_map=None, additional_info=None)[source]
Get the weight of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
structure_environments – Structure environments used to estimate weight.
cn_map – Mapping index for this neighbors set.
additional_info – Additional information.
- Returns:
Weight of the neighbors set.
- class SimpleAbundanceChemenvStrategy(structure_environments=None, additional_condition=1, symmetry_measure_type='csm_wcs_ctwcc')[source]
Bases:
AbstractChemenvStrategySimple ChemenvStrategy using the neighbors that are the most “abundant” in the grid of angle and distance parameters for the definition of neighbors in the Voronoi approach. The coordination environment is then given as the one with the lowest continuous symmetry measure.
Constructor for the SimpleAbundanceChemenvStrategy. :param structure_environments: StructureEnvironments object containing all the information on the
coordination of the sites in a structure.
- STRATEGY_DESCRIPTION: str | None = ' Simple Abundance ChemenvStrategy using the most "abundant" neighbors map \n for the definition of neighbors in the Voronoi approach. \n The coordination environment is then given as the one with the \n lowest continuous symmetry measure.'[source]
- STRATEGY_OPTIONS: ClassVar[dict[str, dict]] = {'additional_condition': {'default': 1, 'internal': '_additional_condition', 'type': <class 'pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies.AdditionalConditionInt'>}, 'surface_calculation_type': {}}[source]
- as_dict()[source]
Bson-serializable dict representation of the SimpleAbundanceChemenvStrategy object. :return: Bson-serializable dict representation of the SimpleAbundanceChemenvStrategy object.
- classmethod from_dict(d)[source]
Reconstructs the SimpleAbundanceChemenvStrategy object from a dict representation of the SimpleAbundanceChemenvStrategy object created using the as_dict method. :param d: dict representation of the SimpleAbundanceChemenvStrategy object :return: StructureEnvironments object.
- get_site_coordination_environment(site, isite=None, dequivsite=None, dthissite=None, mysym=None, return_map=False)[source]
Get the coordination environment of a given site.
- Parameters:
site – Site for which coordination environment is needed.
isite – Index of the site.
dequivsite – Translation of the equivalent site.
dthissite – Translation of this site.
mysym – Symmetry to be applied.
return_map – Whether to return cn_map (identifies the NeighborsSet used).
- Returns:
Coordination environment of site.
- get_site_coordination_environments(site, isite=None, dequivsite=None, dthissite=None, mysym=None, return_maps=False)[source]
Get the coordination environments of a given site.
- Parameters:
site – Site for which coordination environment is needed.
isite – Index of the site.
dequivsite – Translation of the equivalent site.
dthissite – Translation of this site.
mysym – Symmetry to be applied.
return_maps – Whether to return cn_maps (identifies all the NeighborsSet used).
- Returns:
List of coordination environment.
- class SimplestChemenvStrategy(structure_environments=None, distance_cutoff=1.4, angle_cutoff=0.3, additional_condition=1, continuous_symmetry_measure_cutoff=10, symmetry_measure_type='csm_wcs_ctwcc')[source]
Bases:
AbstractChemenvStrategySimplest ChemenvStrategy using fixed angle and distance parameters for the definition of neighbors in the Voronoi approach. The coordination environment is then given as the one with the lowest continuous symmetry measure.
Constructor for this SimplestChemenvStrategy. :param distance_cutoff: Distance cutoff used :param angle_cutoff: Angle cutoff used.
- STRATEGY_DESCRIPTION: str | None = ' Simplest ChemenvStrategy using fixed angle and distance parameters \n for the definition of neighbors in the Voronoi approach. \n The coordination environment is then given as the one with the \n lowest continuous symmetry measure.'[source]
- STRATEGY_OPTIONS: ClassVar[dict[str, dict]] = {'additional_condition': {'default': 1, 'internal': '_additional_condition', 'type': <class 'pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies.AdditionalConditionInt'>}, 'angle_cutoff': {'default': 0.3, 'internal': '_angle_cutoff', 'type': <class 'pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies.AngleCutoffFloat'>}, 'continuous_symmetry_measure_cutoff': {'default': 10, 'internal': '_continuous_symmetry_measure_cutoff', 'type': <class 'pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies.CSMFloat'>}, 'distance_cutoff': {'default': 1.4, 'internal': '_distance_cutoff', 'type': <class 'pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies.DistanceCutoffFloat'>}}[source]
- add_strategy_visualization_to_subplot(subplot, visualization_options=None, plot_type=None)[source]
Add a visual of the strategy on a distance-angle plot.
- Parameters:
subplot – Axes object onto the visual should be added.
visualization_options – Options for the visual.
plot_type – Type of distance-angle plot.
- Returns:
None
- as_dict()[source]
Bson-serializable dict representation of the SimplestChemenvStrategy object. :return: Bson-serializable dict representation of the SimplestChemenvStrategy object.
- classmethod from_dict(d)[source]
Reconstructs the SimplestChemenvStrategy object from a dict representation of the SimplestChemenvStrategy object created using the as_dict method. :param d: dict representation of the SimplestChemenvStrategy object :return: StructureEnvironments object.
- get_site_coordination_environment(site, isite=None, dequivsite=None, dthissite=None, mysym=None, return_map=False)[source]
Get the coordination environment of a given site.
- Parameters:
site – Site for which coordination environment is needed.
isite – Index of the site.
dequivsite – Translation of the equivalent site.
dthissite – Translation of this site.
mysym – Symmetry to be applied.
return_map – Whether to return cn_map (identifies the NeighborsSet used).
- Returns:
Coordination environment of site.
- get_site_coordination_environments(site, isite=None, dequivsite=None, dthissite=None, mysym=None, return_maps=False)[source]
Get the coordination environments of a given site.
- Parameters:
site – Site for which coordination environment is needed.
isite – Index of the site.
dequivsite – Translation of the equivalent site.
dthissite – Translation of this site.
mysym – Symmetry to be applied.
return_maps – Whether to return cn_maps (identifies all the NeighborsSet used).
- Returns:
List of coordination environment.
- get_site_coordination_environments_fractions(site, isite=None, dequivsite=None, dthissite=None, mysym=None, ordered=True, min_fraction=0, return_maps=True, return_strategy_dict_info=False)[source]
Get the coordination environments of a given site and additional information.
- Parameters:
site – Site for which coordination environment is needed.
isite – Index of the site.
dequivsite – Translation of the equivalent site.
dthissite – Translation of this site.
mysym – Symmetry to be applied.
ordered – Whether to order the list by fractions.
min_fraction – Minimum fraction to include in the list
return_maps – Whether to return cn_maps (identifies all the NeighborsSet used).
return_strategy_dict_info – Whether to add the info about the strategy used.
- Returns:
List of Dict with coordination environment, fraction and additional info.
- get_site_neighbors(site, isite=None, dequivsite=None, dthissite=None, mysym=None)[source]
Get the neighbors of a given site.
- Parameters:
site – Site for which neighbors are needed.
isite – Index of the site.
dequivsite – Translation of the equivalent site.
dthissite – Translation of this site.
mysym – Symmetry to be applied.
- Returns:
List of coordinated neighbors of site.
- class StrategyOption[source]
Bases:
MSONableAbstract class for the options of the chemenv strategies.
- class TargettedPenaltiedAbundanceChemenvStrategy(structure_environments=None, truncate_dist_ang=True, additional_condition=1, max_nabundant=5, target_environments=('O:6',), target_penalty_type='max_csm', max_csm=5.0, symmetry_measure_type='csm_wcs_ctwcc')[source]
Bases:
SimpleAbundanceChemenvStrategySimple ChemenvStrategy using the neighbors that are the most “abundant” in the grid of angle and distance parameters for the definition of neighbors in the Voronoi approach, with a bias for a given list of target environments. This can be useful in the case of, e.g. connectivity search of some given environment. The coordination environment is then given as the one with the lowest continuous symmetry measure.
Initializes strategy.
Not yet implemented. :param structure_environments: :param truncate_dist_ang: :param additional_condition: :param max_nabundant: :param target_environments: :param target_penalty_type: :param max_csm: :param symmetry_measure_type:
- as_dict()[source]
Bson-serializable dict representation of the TargettedPenaltiedAbundanceChemenvStrategy object. :return: Bson-serializable dict representation of the TargettedPenaltiedAbundanceChemenvStrategy object.
- classmethod from_dict(d)[source]
Reconstructs the TargettedPenaltiedAbundanceChemenvStrategy object from a dict representation of the TargettedPenaltiedAbundanceChemenvStrategy object created using the as_dict method. :param d: dict representation of the TargettedPenaltiedAbundanceChemenvStrategy object :return: TargettedPenaltiedAbundanceChemenvStrategy object.
- get_site_coordination_environment(site, isite=None, dequivsite=None, dthissite=None, mysym=None, return_map=False)[source]
Get the coordination environment of a given site.
- Parameters:
site – Site for which coordination environment is needed.
isite – Index of the site.
dequivsite – Translation of the equivalent site.
dthissite – Translation of this site.
mysym – Symmetry to be applied.
return_map – Whether to return cn_map (identifies the NeighborsSet used).
- Returns:
Coordination environment of site.
- class WeightedNbSetChemenvStrategy(structure_environments=None, additional_condition=1, symmetry_measure_type='csm_wcs_ctwcc', nb_set_weights=None, ce_estimator={'function': 'power2_inverse_power2_decreasing', 'options': {'max_csm': 8.0}})[source]
Bases:
AbstractChemenvStrategyWeightedNbSetChemenvStrategy.
Constructor for the WeightedNbSetChemenvStrategy. :param structure_environments: StructureEnvironments object containing all the information on the
coordination of the sites in a structure.
- DEFAULT_CE_ESTIMATOR = {'function': 'power2_inverse_power2_decreasing', 'options': {'max_csm': 8.0}}[source]
- as_dict()[source]
Bson-serializable dict representation of the WeightedNbSetChemenvStrategy object. :return: Bson-serializable dict representation of the WeightedNbSetChemenvStrategy object.
- classmethod from_dict(d)[source]
Reconstructs the WeightedNbSetChemenvStrategy object from a dict representation of the WeightedNbSetChemenvStrategy object created using the as_dict method. :param d: dict representation of the WeightedNbSetChemenvStrategy object :return: WeightedNbSetChemenvStrategy object.
- get_site_coordination_environment(site)[source]
Get the coordination environment of a given site.
Not implemented for this strategy
- get_site_coordination_environments(site, isite=None, dequivsite=None, dthissite=None, mysym=None, return_maps=False)[source]
Get the coordination environments of a given site.
- Parameters:
site – Site for which coordination environment is needed.
isite – Index of the site.
dequivsite – Translation of the equivalent site.
dthissite – Translation of this site.
mysym – Symmetry to be applied.
return_maps – Whether to return cn_maps (identifies all the NeighborsSet used).
- Returns:
List of coordination environment.
- get_site_coordination_environments_fractions(site, isite=None, dequivsite=None, dthissite=None, mysym=None, ordered=True, min_fraction=0, return_maps=True, return_strategy_dict_info=False, return_all=False)[source]
Get the coordination environments of a given site and additional information.
- Parameters:
site – Site for which coordination environment is needed.
isite – Index of the site.
dequivsite – Translation of the equivalent site.
dthissite – Translation of this site.
mysym – Symmetry to be applied.
ordered – Whether to order the list by fractions.
min_fraction – Minimum fraction to include in the list
return_maps – Whether to return cn_maps (identifies all the NeighborsSet used).
return_strategy_dict_info – Whether to add the info about the strategy used.
- Returns:
List of Dict with coordination environment, fraction and additional info.
- get_effective_csm(nb_set, cn_map, structure_environments, additional_info, symmetry_measure_type, max_effective_csm, effective_csm_estimator_ratio_function)[source]
Get the effective continuous symmetry measure of a given neighbors set.
- Parameters:
nb_set – Neighbors set.
cn_map – Mapping index of this neighbors set.
structure_environments – Structure environments.
additional_info – Additional information for the neighbors set.
symmetry_measure_type – Type of symmetry measure to be used in the effective CSM.
max_effective_csm – Max CSM to use for the effective CSM calculation.
effective_csm_estimator_ratio_function – Ratio function to use to compute effective CSM.
- Returns:
Effective CSM of a given Neighbors set.
- set_info(additional_info, field, isite, cn_map, value)[source]
Set additional information for the weights.
- Parameters:
additional_info – Additional information.
field – Type of additional information.
isite – Index of site to add info.
cn_map – Mapping index of the neighbors set.
value – Value of this additional information.
- Returns:
None
pymatgen.analysis.chemenv.coordination_environments.coordination_geometries module
This module contains the class describing the coordination geometries that can exist in a given structure. These “model” coordination geometries are described in the following articles :
Pure Appl. Chem., Vol. 79, No. 10, pp. 1779–1799, 2007.
Acta Cryst. A, Vol. 46, No. 1, pp. 1–11, 1990.
The module also contains descriptors of part of these geometries (plane of separation, …) that are used in the identification algorithms.
- class AbstractChemenvAlgorithm(algorithm_type)[source]
Bases:
MSONableBase class used to define a Chemenv algorithm used to identify the correct permutation for the computation of the Continuous Symmetry Measure.
Base constructor for ChemenvAlgorithm.
- Parameters:
algorithm_type (str) – Type of algorithm.
- class AllCoordinationGeometries(permutations_safe_override=False, only_symbols=None)[source]
Bases:
dictClass used to store all the reference “coordination geometries” (list with instances of the CoordinationGeometry classes).
Initializes the list of Coordination Geometries.
- Parameters:
permutations_safe_override – Whether to use safe permutations.
only_symbols – Whether to restrict the list of environments to be identified.
- get_geometries(coordination=None, returned='cg')[source]
Returns a list of coordination geometries with the given coordination number.
- Parameters:
coordination – The coordination number of which the list of coordination geometries are returned.
returned – Type of objects in the list.
- get_geometry_from_IUCr_symbol(IUCr_symbol)[source]
Returns the coordination geometry of the given IUCr symbol.
- Parameters:
IUCr_symbol – The IUCr symbol of the coordination geometry.
- get_geometry_from_IUPAC_symbol(IUPAC_symbol)[source]
Returns the coordination geometry of the given IUPAC symbol.
- Parameters:
IUPAC_symbol – The IUPAC symbol of the coordination geometry.
- get_geometry_from_mp_symbol(mp_symbol)[source]
Returns the coordination geometry of the given mp_symbol.
- Parameters:
mp_symbol – The mp_symbol of the coordination geometry.
- get_geometry_from_name(name)[source]
Returns the coordination geometry of the given name.
- Parameters:
name – The name of the coordination geometry.
- get_implemented_geometries(coordination=None, returned='cg', include_deactivated=False)[source]
Returns a list of the implemented coordination geometries with the given coordination number.
- Parameters:
coordination – The coordination number of which the list of implemented coordination geometries are returned.
returned – Type of objects in the list.
include_deactivated – Whether to include CoordinationGeometry that are deactivated.
- get_not_implemented_geometries(coordination=None, returned='mp_symbol')[source]
Returns a list of the implemented coordination geometries with the given coordination number.
- Parameters:
coordination – The coordination number of which the list of implemented coordination geometries are returned.
returned – Type of objects in the list.
- get_symbol_cn_mapping(coordination=None)[source]
Return a dictionary mapping the symbol of a CoordinationGeometry to its coordination.
- Parameters:
coordination – Whether to restrict the dictionary to a given coordination.
Returns: Dictionary mapping the symbol of a CoordinationGeometry to its coordination.
- get_symbol_name_mapping(coordination=None)[source]
Return a dictionary mapping the symbol of a CoordinationGeometry to its name.
- Parameters:
coordination – Whether to restrict the dictionary to a given coordination.
Returns: Dictionary mapping the symbol of a CoordinationGeometry to its name.
- is_a_valid_coordination_geometry(mp_symbol=None, IUPAC_symbol=None, IUCr_symbol=None, name=None, cn=None) bool[source]
Checks whether a given coordination geometry is valid (exists) and whether the parameters are coherent with each other.
- Parameters:
mp_symbol – The mp_symbol of the coordination geometry.
IUPAC_symbol – The IUPAC_symbol of the coordination geometry.
IUCr_symbol – The IUCr_symbol of the coordination geometry.
name – The name of the coordination geometry.
cn – The coordination of the coordination geometry.
- pretty_print(type='implemented_geometries', maxcn=8, additional_info=None)[source]
Return a string with a list of the Coordination Geometries.
- Parameters:
type – Type of string to be returned (all_geometries, all_geometries_latex_images, all_geometries_latex, implemented_geometries).
maxcn – Maximum coordination.
additional_info – Whether to add some additional info for each coordination geometry.
Returns: String describing the list of coordination geometries.
- class CoordinationGeometry(mp_symbol, name, alternative_names=None, IUPAC_symbol=None, IUCr_symbol=None, coordination=None, central_site=None, points=None, solid_angles=None, permutations_safe_override=False, deactivate=False, faces=None, edges=None, algorithms=None, equivalent_indices=None, neighbors_sets_hints=None)[source]
Bases:
objectClass used to store the ideal representation of a chemical environment or “coordination geometry”.
Initializes one “coordination geometry” according to [Pure Appl. Chem., Vol. 79, No. 10, pp. 1779–1799, 2007] and [Acta Cryst. A, Vol. 46, No. 1, pp. 1–11, 1990].
- Parameters:
mp_symbol – Symbol used internally for the coordination geometry.
name – Name of the coordination geometry.
alternative_names – Alternative names for this coordination geometry.
IUPAC_symbol – The IUPAC symbol of this coordination geometry.
IUCr_symbol – The IUCr symbol of this coordination geometry.
coordination – The coordination number of this coordination geometry (number of neighboring atoms).
central_site – The coordinates of the central site of this coordination geometry.
points – The list of the coordinates of all the points of this coordination geometry.
solid_angles – The list of solid angles for each neighbor in this coordination geometry.
permutations_safe_override – Computes all the permutations if set to True (overrides the plane separation algorithms or any other algorithm, for testing purposes)
deactivate – Whether to deactivate this coordination geometry
faces – List of the faces with their vertices given in a clockwise or anticlockwise order, for drawing purposes.
edges – List of edges, for drawing purposes.
algorithms – Algorithms used to identify this coordination geometry.
equivalent_indices – The equivalent sets of indices in this coordination geometry (can be used to skip equivalent permutations that have already been performed).
neighbors_sets_hints – Neighbors sets hints for this coordination geometry.
- property IUCr_symbol_str[source]
Returns a string representation of the IUCr symbol of this coordination geometry.
- property IUPAC_symbol_str[source]
Returns a string representation of the IUPAC symbol of this coordination geometry.
- class NeighborsSetsHints(hints_type, options)[source]
Bases:
objectClass used to describe neighbors sets hints.
This allows to possibly get a lower coordination from a capped-like model polyhedron.
Constructor for this NeighborsSetsHints.
- Parameters:
hints_type – type of hint (single, double or triple cap)
options – options for the “hinting”, e.g. the maximum csm value beyond which no additional neighbors set could be found from a “cap hint”.
- double_cap_hints(hints_info)[source]
Return hints for an additional neighbors set, i.e. the voronoi indices that constitute this new neighbors set, in case of a “Double cap” hint.
- Parameters:
hints_info – Info needed to build new “hinted” neighbors set.
Returns: Voronoi indices of the new “hinted” neighbors set.
- classmethod from_dict(dd)[source]
Reconstructs the NeighborsSetsHints from its JSON-serializable dict representation.
- Parameters:
dd – a JSON-serializable dict representation of a NeighborsSetsHints.
Returns: a NeighborsSetsHints.
- hints(hints_info)[source]
Return hints for an additional neighbors set, i.e. the voronoi indices that constitute this new neighbors set.
- Parameters:
hints_info – Info needed to build new “hinted” neighbors set.
Returns: Voronoi indices of the new “hinted” neighbors set.
- single_cap_hints(hints_info)[source]
Return hints for an additional neighbors set, i.e. the voronoi indices that constitute this new neighbors set, in case of a “Single cap” hint.
- Parameters:
hints_info – Info needed to build new “hinted” neighbors set.
Returns: Voronoi indices of the new “hinted” neighbors set.
- triple_cap_hints(hints_info)[source]
Return hints for an additional neighbors set, i.e. the voronoi indices that constitute this new neighbors set, in case of a “Triple cap” hint.
- Parameters:
hints_info – Info needed to build new “hinted” neighbors set.
Returns: Voronoi indices of the new “hinted” neighbors set.
- property algorithms[source]
Returns the list of algorithms that are used to identify this coordination geometry.
- property coordination_number[source]
Returns the coordination number of this coordination geometry.
- property distfactor_max[source]
The maximum distfactor for the perfect CoordinationGeometry.
Returns: Maximum distfactor for the perfect CoordinationGeometry (usually 1.0 for symmetric polyhedrons).
- edges(sites, permutation=None, input='sites')[source]
Returns the list of edges of this coordination geometry. Each edge is given as a list of its end vertices coordinates.
- faces(sites, permutation=None)[source]
Returns the list of faces of this coordination geometry. Each face is given as a list of its vertices coordinates.
- classmethod from_dict(dct)[source]
Reconstructs the CoordinationGeometry from its JSON-serializable dict representation.
- Parameters:
dct – a JSON-serializable dict representation of a CoordinationGeometry.
Returns: a CoordinationGeometry.
- get_pmeshes(sites, permutation=None)[source]
Returns the pmesh strings used for jmol to show this geometry.
- property number_of_permutations[source]
Returns the number of permutations of this coordination geometry.
- property pauling_stability_ratio[source]
Returns the theoretical Pauling stability ratio (rC/rA) for this environment.
- ref_permutation(permutation)[source]
Returns the reference permutation for a set of equivalent permutations.
Can be useful to skip permutations that have already been performed.
- Parameters:
permutation – Current permutation
Returns: Reference permutation of the perfect CoordinationGeometry.
- class ExplicitPermutationsAlgorithm(permutations)[source]
Bases:
AbstractChemenvAlgorithmClass representing the algorithm doing the explicit permutations for the calculation of the Continuous Symmetry Measure.
Initializes a separation plane for a given perfect coordination geometry.
- Parameters:
permutations – Permutations used for this algorithm.
- property as_dict[source]
Return the JSON-serializable dict representation of this ExplicitPermutationsAlgorithm algorithm.
Returns: a JSON-serializable dict representation of this ExplicitPermutationsAlgorithm algorithm.
- class SeparationPlane(plane_points, mirror_plane=False, ordered_plane=False, point_groups=None, ordered_point_groups=None, explicit_permutations=None, minimum_number_of_points=None, explicit_optimized_permutations=None, multiplicity=None, other_plane_points=None)[source]
Bases:
AbstractChemenvAlgorithmClass representing the algorithm using separation planes for the calculation of the Continuous Symmetry Measure.
Initializes a separation plane for a given perfect coordination geometry.
- Parameters:
plane_points – Indices of the points that are in the plane in the perfect structure (and should be found in the defective one as well).
mirror_plane – True if the separation plane is a mirror plane, in which case there is a correspondence of the points in each point_group (can reduce the number of permutations).
ordered_plane – True if the order of the points in the plane can be taken into account to reduce the number of permutations.
point_groups – Indices of the points in the two groups of points separated by the plane.
ordered_point_groups – Whether the order of the points in each group of points can be taken into account to reduce the number of permutations.
explicit_permutations – Explicit permutations to be performed in this separation plane algorithm.
minimum_number_of_points – Minimum number of points needed to initialize a separation plane for this algorithm.
explicit_optimized_permutations – Optimized set of explicit permutations to be performed in this separation plane algorithm.
multiplicity – Number of such planes in the model geometry.
other_plane_points – Indices of the points that are in the plane in the perfect structure for the other planes. The multiplicity should be equal to the length of this list + 1 (“main” separation plane + the other ones).
- property argsorted_ref_separation_perm[source]
“Arg sorted” ordered indices of the separation plane.
This is used in the identification of the final permutation to be used.
Returns: list of the “arg sorted” ordered indices of the separation plane.
- property as_dict[source]
Return the JSON-serializable dict representation of this SeparationPlane algorithm.
Returns: a JSON-serializable dict representation of this SeparationPlane algorithm.
- classmethod from_dict(dct)[source]
Reconstructs the SeparationPlane algorithm from its JSON-serializable dict representation.
- Parameters:
dd – a JSON-serializable dict representation of an SeparationPlane algorithm.
Returns: a SeparationPlane algorithm.
- property permutations[source]
Permutations used for this separation plane algorithm.
Returns: List of permutations to be performed.
- property ref_separation_perm[source]
Ordered indices of the separation plane.
Examples
For a separation plane of type 2|4|3, with plane_points indices [0, 3, 5, 8] and point_groups indices [1, 4] and [2, 7, 6], the list of ordered indices is : [0, 3, 5, 8, 1, 4, 2, 7, 6].
Returns: list of ordered indices of this separation plane.
- safe_separation_permutations(ordered_plane=False, ordered_point_groups=None, add_opposite=False)[source]
Simple and safe permutations for this separation plane.
This is not meant to be used in production. Default configuration for ChemEnv does not use this method.
- Parameters:
ordered_plane – Whether the order of the points in the plane can be used to reduce the number of permutations.
ordered_point_groups – Whether the order of the points in each point group can be used to reduce the number of permutations.
add_opposite – Whether to add the permutations from the second group before the first group as well.
Returns: List of safe permutations.
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: David Waroquiers, Xavier Gonze, Gian-Marco Rignanese, Cathrin Welker-Nieuwoudt, 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 D. Waroquiers, J. George, M. Horton, S. Schenk, K. A. Persson, G.-M. Rignanese, X. Gonze, G. Hautier “ChemEnv: a fast and robust coordination environment identification tool”, Acta Cryst. B 2020, 76, pp 683-695, DOI: 10.1107/S2052520620007994.
- class AbstractGeometry(central_site=None, bare_coords=None, centering_type='standard', include_central_site_in_centroid=False, optimization=None)[source]
Bases:
objectClass 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.
- class LocalGeometryFinder(permutations_safe_override: bool = False, plane_ordering_override: bool = True, plane_safe_permutations: bool = False, only_symbols=None)[source]
Bases:
objectMain class used to find the local environments in a structure.
- Parameters:
permutations_safe_override – If set to True, all permutations are tested (very time-consuming for large
numbers!) (coordination) –
plane_ordering_override – If set to False, the ordering of the points in the plane is disabled
plane_safe_permutations – Whether to use safe permutations.
only_symbols – Whether to restrict the list of environments to be identified.
- BVA_DISTANCE_SCALE_FACTORS = {'GGA_relaxed': 1.015, 'LDA_relaxed': 0.995, 'experimental': 1.0}[source]
- DEFAULT_STRATEGY = <pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies.MultiWeightsChemenvStrategy object>[source]
- 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}}[source]
- _cg_csm_separation_plane(coordination_geometry, sep_plane, local_plane, plane_separations, dist_tolerances=None, testing=False, tested_permutations=False, points_perfect=None)[source]
- _cg_csm_separation_plane_optim1(coordination_geometry, sepplane, local_plane, points_perfect=None, separation_indices=None)[source]
- _cg_csm_separation_plane_optim2(coordination_geometry, sepplane, local_plane, points_perfect=None, separation_indices=None)[source]
- compute_coordination_environments(structure, indices=None, only_cations=True, strategy=<pymatgen.analysis.chemenv.coordination_environments.chemenv_strategies.MultiWeightsChemenvStrategy object>, valences='bond-valence-analysis', 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, voronoi_distance_cutoff=None, 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
voronoi_distance_cutoff – determines distance of considered neighbors. Especially important to increase it for molecules in a box.
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 :param coordination_geometry: The coordination geometry to be investigated :param NRANDOM: Number of random permutations to be tested :return: 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 …
- Parameters:
coordination_geometry – The coordination geometry to be investigated.
separation_plane_algo – Separation Plane algorithm used.
points_perfect – Points corresponding to the perfect geometry.
nb_set – Neighbor set for this set of points. (used to store already computed separation planes)
optimization – Optimization level (1 or 2).
- Returns:
- Continuous symmetry measures for the given coordination geometry for each plane and permutation
investigated, corresponding permutations, corresponding algorithms, corresponding mappings from local to perfect environment and corresponding mappings from perfect to local environment.
- Return type:
tuple
- 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 :param coordination_geometry: The coordination geometry to be investigated :return: 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: 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 CN-1 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 over-estimation 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: 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 least-square sense. :param points_distorted: List of points describing a given (distorted) polyhedron for which the rotation that
aligns these points in a least-square 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 least-square 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.
pymatgen.analysis.chemenv.coordination_environments.structure_environments module
This module contains objects that are used to describe the environments in a structure. The most detailed object (StructureEnvironments) contains a very thorough analysis of the environments of a given atom but is difficult to used as such. The LightStructureEnvironments object is a lighter version that is obtained by applying a “strategy” on the StructureEnvironments object. Basically, the LightStructureEnvironments provides the coordination environment(s) and possibly some fraction corresponding to these.
- class ChemicalEnvironments(coord_geoms=None)[source]
Bases:
MSONableClass used to store all the information about the chemical environment of a given site for a given list of coordinated neighbors (internally called “cn_map”).
Initializes the ChemicalEnvironments object containing all the information about the chemical environment of a given site.
- Parameters:
coord_geoms – coordination geometries to be added to the chemical environment.
- add_coord_geom(mp_symbol, symmetry_measure, algo='UNKNOWN', permutation=None, override=False, local2perfect_map=None, perfect2local_map=None, detailed_voronoi_index=None, other_symmetry_measures=None, rotation_matrix=None, scaling_factor=None)[source]
Adds a coordination geometry to the ChemicalEnvironments object.
- Parameters:
mp_symbol – Symbol of the coordination geometry added.
symmetry_measure – Symmetry measure of the coordination geometry added.
algo – Algorithm used for the search of the coordination geometry added.
permutation – Permutation of the neighbors that leads to the csm stored.
override – If set to True, the coordination geometry will override the existent one if present.
local2perfect_map – Mapping of the local indices to the perfect indices.
perfect2local_map – Mapping of the perfect indices to the local indices.
detailed_voronoi_index – Index in the voronoi containing the neighbors set.
other_symmetry_measures – Other symmetry measure of the coordination geometry added (with/without the central atom, centered on the central atom or on the centroid with/without the central atom).
rotation_matrix – Rotation matrix mapping the local geometry to the perfect geometry.
scaling_factor – Scaling factor mapping the local geometry to the perfect geometry.
- Raises:
ChemenvError if the coordination geometry is already added and override is set to False –
- as_dict()[source]
Returns a dictionary representation of the ChemicalEnvironments object.
- Returns:
A dictionary representation of the ChemicalEnvironments object.
- classmethod from_dict(d)[source]
Reconstructs the ChemicalEnvironments object from a dict representation of the ChemicalEnvironments created using the as_dict method.
- Parameters:
d – dict representation of the ChemicalEnvironments object.
- Returns:
ChemicalEnvironments object.
- is_close_to(other, rtol=0.0, atol=1e-08) bool[source]
Whether this ChemicalEnvironments object is close to another one.
- Parameters:
other – Another ChemicalEnvironments object.
rtol – Relative tolerance for the comparison of Continuous Symmetry Measures.
atol – Absolute tolerance for the comparison of Continuous Symmetry Measures.
- Returns:
True if the two ChemicalEnvironments objects are close to each other.
- minimum_geometries(n=None, symmetry_measure_type=None, max_csm=None)[source]
Returns a list of geometries with increasing continuous symmetry measure in this ChemicalEnvironments object.
- Parameters:
n – Number of geometries to be included in the list.
- Returns:
List of geometries with increasing continuous symmetry measure in this ChemicalEnvironments object.
- Raises:
ValueError if no coordination geometry is found in this ChemicalEnvironments object. –
- minimum_geometry(symmetry_measure_type=None, max_csm=None)[source]
Returns the geometry with the minimum continuous symmetry measure of this ChemicalEnvironments.
- Returns:
tuple (symbol, csm) with symbol being the geometry with the minimum continuous symmetry measure and csm being the continuous symmetry measure associated to it.
- Raises:
ValueError if no coordination geometry is found in this ChemicalEnvironments object. –
- class LightStructureEnvironments(strategy, coordination_environments=None, all_nbs_sites=None, neighbors_sets=None, structure=None, valences=None, valences_origin=None)[source]
Bases:
MSONableClass used to store the chemical environments of a given structure obtained from a given ChemenvStrategy. Currently, only strategies leading to the determination of a unique environment for each site is allowed This class does not store all the information contained in the StructureEnvironments object, only the coordination environment found.
Constructor for the LightStructureEnvironments object.
- Parameters:
strategy – ChemEnv strategy used to get the environments.
coordination_environments – The coordination environments identified.
all_nbs_sites – All the possible neighbors for each site in the structure.
neighbors_sets – The neighbors sets of each site in the structure.
structure – The structure.
valences – The valences used to get the environments (if needed).
valences_origin – How the valences were obtained (e.g. from the Bond-valence analysis or from the original structure).
- DEFAULT_STATISTICS_FIELDS = ('anion_list', 'anion_atom_list', 'cation_list', 'cation_atom_list', 'neutral_list', 'neutral_atom_list', 'atom_coordination_environments_present', 'ion_coordination_environments_present', 'fraction_atom_coordination_environments_present', 'fraction_ion_coordination_environments_present', 'coordination_environments_atom_present', 'coordination_environments_ion_present')[source]
- class NeighborsSet(structure: Structure, isite, all_nbs_sites, all_nbs_sites_indices)[source]
Bases:
objectClass used to store a given set of neighbors of a given site (based on a list of sites, the voronoi container is not part of the LightStructureEnvironments object).
Constructor for NeighborsSet.
- Parameters:
structure – Structure object.
isite – Index of the site for which neighbors are stored in this NeighborsSet.
all_nbs_sites – All the possible neighbors for this site.
all_nbs_sites_indices – Indices of the sites in all_nbs_sites that make up this NeighborsSet.
- classmethod from_dict(dd, structure: Structure, all_nbs_sites)[source]
Reconstructs the NeighborsSet algorithm from its JSON-serializable dict representation, together with the structure and all the possible neighbors sites.
As an inner (nested) class, the NeighborsSet is not supposed to be used anywhere else that inside the LightStructureEnvironments. The from_dict method is thus using the structure and all_nbs_sites when reconstructing itself. These two are both in the LightStructureEnvironments object.
- Parameters:
dd – a JSON-serializable dict representation of a NeighborsSet.
structure – The structure.
all_nbs_sites – The list of all the possible neighbors for a given site.
Returns: a NeighborsSet.
- as_dict()[source]
- Returns:
Bson-serializable representation of the LightStructureEnvironments object.
- Return type:
dict
- clear_environments(conditions=None)[source]
Get the clear environments in the structure.
- Parameters:
conditions – Conditions to be checked for an environment to be “clear”.
Returns: Set of clear environments in this structure.
- contains_only_one_anion(anion)[source]
Whether this LightStructureEnvironments concerns a structure with only one given anion type.
- Parameters:
anion – Anion (e.g. O2-, …).
Returns: True if this LightStructureEnvironments concerns a structure with only one given anion.
- contains_only_one_anion_atom(anion_atom)[source]
Whether this LightStructureEnvironments concerns a structure with only one given anion atom type.
- Parameters:
anion_atom – Anion (e.g. O, …). The structure could contain O2- and O- though.
Returns: True if this LightStructureEnvironments concerns a structure with only one given anion_atom.
- environments_identified()[source]
Return the set of environments identified in this structure.
Returns: Set of environments identified in this structure.
- classmethod from_dict(d)[source]
Reconstructs the LightStructureEnvironments object from a dict representation of the LightStructureEnvironments created using the as_dict method.
- Parameters:
d – dict representation of the LightStructureEnvironments object.
- Returns:
LightStructureEnvironments object.
- classmethod from_structure_environments(strategy, structure_environments, valences=None, valences_origin=None)[source]
Construct a LightStructureEnvironments object from a strategy and a StructureEnvironments object.
- Parameters:
strategy – ChemEnv strategy used.
structure_environments – StructureEnvironments object from which to construct the LightStructureEnvironments.
valences – The valences of each site in the structure.
valences_origin – How the valences were obtained (e.g. from the Bond-valence analysis or from the original structure).
Returns: a LightStructureEnvironments object.
- get_site_info_for_specie_allces(specie, min_fraction=0)[source]
Get list of indices that have the given specie.
- Parameters:
specie – Species to get.
min_fraction – Minimum fraction of the coordination environment.
- Returns: Dictionary with the list of coordination environments for the given species, the indices of the sites
in which they appear, their fractions and continuous symmetry measures.
- get_site_info_for_specie_ce(specie, ce_symbol)[source]
Get list of indices that have the given specie with a given Coordination environment.
- Parameters:
specie – Species to get.
ce_symbol – Symbol of the coordination environment to get.
- Returns: Dictionary with the list of indices in the structure that have the given specie in the given
environment, their fraction and continuous symmetry measures.
- get_statistics(statistics_fields=('anion_list', 'anion_atom_list', 'cation_list', 'cation_atom_list', 'neutral_list', 'neutral_atom_list', 'atom_coordination_environments_present', 'ion_coordination_environments_present', 'fraction_atom_coordination_environments_present', 'fraction_ion_coordination_environments_present', 'coordination_environments_atom_present', 'coordination_environments_ion_present'), bson_compatible=False)[source]
Get the statistics of environments for this structure.
- Parameters:
statistics_fields – Which statistics to get.
bson_compatible – Whether to make the dictionary BSON-compatible.
- Returns:
A dictionary with the requested statistics.
- setup_statistic_lists()[source]
Set up the statistics of environments for this LightStructureEnvironments.
- site_contains_environment(isite, ce_symbol)[source]
Whether a given site contains a given coordination environment.
- Parameters:
isite – Index of the site.
ce_symbol – Symbol of the coordination environment.
Returns: True if the site contains the given coordination environment.
- site_has_clear_environment(isite, conditions=None)[source]
Whether a given site has a “clear” environments.
A “clear” environment is somewhat arbitrary. You can pass (multiple) conditions, e.g. the environment should have a continuous symmetry measure lower than this, a fraction higher than that, …
- Parameters:
isite – Index of the site.
conditions – Conditions to be checked for an environment to be “clear”.
Returns: True if the site has a clear environment.
- structure_contains_atom_environment(atom_symbol, ce_symbol)[source]
Checks whether the structure contains a given atom in a given environment.
- Parameters:
atom_symbol – Symbol of the atom.
ce_symbol – Symbol of the coordination environment.
- Returns:
True if the coordination environment is found, False otherwise
- structure_has_clear_environments(conditions=None, skip_none=True, skip_empty=False)[source]
Whether all sites in a structure have “clear” environments.
- Parameters:
conditions – Conditions to be checked for an environment to be “clear”.
skip_none – Whether to skip sites for which no environments have been computed.
skip_empty – Whether to skip sites for which no environments could be found.
- Returns:
True if all the sites in the structure have clear environments.
- Return type:
bool
- class StructureEnvironments(voronoi, valences, sites_map, equivalent_sites, ce_list, structure, neighbors_sets=None, info=None)[source]
Bases:
MSONableClass used to store the chemical environments of a given structure.
Constructor for the StructureEnvironments object.
- Parameters:
voronoi – VoronoiContainer object for the structure.
valences – Valences provided.
sites_map – Mapping of equivalent sites to the unequivalent sites that have been computed.
equivalent_sites – List of list of equivalent sites of the structure.
ce_list – List of chemical environments.
structure – Structure object.
neighbors_sets – List of neighbors sets.
info – Additional information for this StructureEnvironments object.
- class NeighborsSet(structure: Structure, isite, detailed_voronoi, site_voronoi_indices, sources=None)[source]
Bases:
objectClass used to store a given set of neighbors of a given site (based on the detailed_voronoi).
Constructor for NeighborsSet.
- Parameters:
structure – Structure object.
isite – Index of the site for which neighbors are stored in this NeighborsSet.
detailed_voronoi – Corresponding DetailedVoronoiContainer object containing all the possible neighbors of the give site.
site_voronoi_indices – Indices of the voronoi sites in the DetailedVoronoiContainer object that make up this NeighborsSet.
sources – Sources for this NeighborsSet, i.e. how this NeighborsSet was generated.
- add_source(source)[source]
Add a source to this NeighborsSet.
- Parameters:
source – Information about the generation of this NeighborsSet.
- property coords[source]
Coordinates of the current central atom and its neighbors for this NeighborsSet.
- classmethod from_dict(dd, structure: Structure, detailed_voronoi)[source]
Reconstructs the NeighborsSet algorithm from its JSON-serializable dict representation, together with the structure and the DetailedVoronoiContainer.
As an inner (nested) class, the NeighborsSet is not supposed to be used anywhere else that inside the StructureEnvironments. The from_dict method is thus using the structure and detailed_voronoi when reconstructing itself. These two are both in the StructureEnvironments object.
- Parameters:
dd – a JSON-serializable dict representation of a NeighborsSet.
structure – The structure.
detailed_voronoi – The Voronoi object containing all the neighboring atoms from which the subset of neighbors for this NeighborsSet is extracted.
Returns: a NeighborsSet.
- get_neighb_voronoi_indices(permutation)[source]
Return the indices in the detailed_voronoi corresponding to the current permutation.
- Parameters:
permutation – Current permutation for which the indices in the detailed_voronoi are needed.
Returns: List of indices in the detailed_voronoi.
- property neighb_coordsOpt[source]
Optimized access to the coordinates of neighbors for this NeighborsSet.
- property neighb_sites_and_indices[source]
List of neighbors for this NeighborsSet as pymatgen Sites and their index in the original structure.
- property source[source]
Returns the source of this NeighborsSet (how it was generated, e.g. from which Voronoi cut-offs, or from hints).
- voronoi_grid_surface_points(additional_condition=1, other_origins='DO_NOTHING')[source]
Get the surface points in the Voronoi grid for this neighbor from the sources. The general shape of the points should look like a staircase such as in the following figure :
^
- 0.0|
- B—-C| || |
a | k D——-E n | | | g | | | l | | | e | j F—-n———G
| || |A—-g——-h—-i———H- 1.0+————————————————->
1.0 distance 2.0 ->+Inf
- Parameters:
additional_condition – Additional condition for the neighbors.
other_origins – What to do with sources that do not come from the Voronoi grid (e.g. “from hints”).
- add_neighbors_set(isite, nb_set)[source]
Adds a neighbor set to the list of neighbors sets for this site.
- Parameters:
isite – Index of the site under consideration.
nb_set – NeighborsSet to be added.
- as_dict()[source]
Bson-serializable dict representation of the StructureEnvironments object.
- Returns:
Bson-serializable dict representation of the StructureEnvironments object.
- differences_wrt(other)[source]
Return differences found in the current StructureEnvironments with respect to another StructureEnvironments.
- Parameters:
other – A StructureEnvironments object.
- Returns:
List of differences between the two StructureEnvironments objects.
- classmethod from_dict(d)[source]
Reconstructs the StructureEnvironments object from a dict representation of the StructureEnvironments created using the as_dict method.
- Parameters:
d – dict representation of the StructureEnvironments object.
- Returns:
StructureEnvironments object.
- get_coordination_environments(isite, cn, nb_set)[source]
Get the ChemicalEnvironments for a given site, coordination and neighbors set.
- Parameters:
isite – Index of the site for which the ChemicalEnvironments is looked for.
cn – Coordination for which the ChemicalEnvironments is looked for.
nb_set – Neighbors set for which the ChemicalEnvironments is looked for.
Returns: a ChemicalEnvironments object.
- get_csm(isite, mp_symbol)[source]
Get the continuous symmetry measure for a given site in the given coordination environment.
- Parameters:
isite – Index of the site.
mp_symbol – Symbol of the coordination environment for which we want the continuous symmetry measure.
Returns: Continuous symmetry measure of the given site in the given environment.
- get_csm_and_maps(isite, max_csm=8.0, figsize=None, symmetry_measure_type=None)[source]
Plotting of the coordination numbers of a given site for all the distfactor/angfactor parameters. If the chemical environments are given, a color map is added to the plot, with the lowest continuous symmetry measure as the value for the color of that distfactor/angfactor set.
- Parameters:
isite – Index of the site for which the plot has to be done.
max_csm – Maximum continuous symmetry measure to be shown.
figsize – Size of the figure.
symmetry_measure_type – Type of continuous symmetry measure to be used.
- Returns:
Matplotlib figure and axes representing the csm and maps.
- get_csms(isite, mp_symbol)[source]
- Returns the continuous symmetry measure(s) of site with index isite with respect to the
perfect coordination environment with mp_symbol. For some environments, a given mp_symbol might not be available (if there is no voronoi parameters leading to a number of neighbors corresponding to the coordination number of environment mp_symbol). For some environments, a given mp_symbol might lead to more than one csm (when two or more different voronoi parameters lead to different neighbors but with same number of neighbors).
- Parameters:
isite – Index of the site.
mp_symbol – MP symbol of the perfect environment for which the csm has to be given.
- Returns:
List of csms for site isite with respect to geometry mp_symbol
- get_environments_figure(isite, plot_type=None, title='Coordination numbers', max_dist=2.0, colormap=None, figsize=None, strategy=None)[source]
Plotting of the coordination environments of a given site for all the distfactor/angfactor regions. The chemical environments with the lowest continuous symmetry measure is shown for each distfactor/angfactor region as the value for the color of that distfactor/angfactor region (using a colormap).
- Parameters:
isite – Index of the site for which the plot has to be done.
plot_type – How to plot the coordinations.
title – Title for the figure.
max_dist – Maximum distance to be plotted when the plotting of the distance is set to ‘initial_normalized’ or ‘initial_real’ (Warning: this is not the same meaning in both cases! In the first case, the closest atom lies at a “normalized” distance of 1.0 so that 2.0 means refers to this normalized distance while in the second case, the real distance is used).
colormap – Color map to be used for the continuous symmetry measure.
figsize – Size of the figure.
strategy – Whether to plot information about one of the Chemenv Strategies.
- Returns:
Matplotlib figure and axes representing the environments.
- init_neighbors_sets(isite, additional_conditions=None, valences=None)[source]
Initialize the list of neighbors sets for the current site.
- Parameters:
isite – Index of the site under consideration.
additional_conditions – Additional conditions to be used for the initialization of the list of neighbors sets, e.g. “Only anion-cation bonds”, …
valences – List of valences for each site in the structure (needed if an additional condition based on the valence is used, e.g. only anion-cation bonds).
- plot_csm_and_maps(isite, max_csm=8.0)[source]
Plotting of the coordination numbers of a given site for all the distfactor/angfactor parameters. If the chemical environments are given, a color map is added to the plot, with the lowest continuous symmetry measure as the value for the color of that distfactor/angfactor set.
- Parameters:
isite – Index of the site for which the plot has to be done
max_csm – Maximum continuous symmetry measure to be shown.
- plot_environments(isite, plot_type=None, title='Coordination numbers', max_dist=2.0, figsize=None, strategy=None)[source]
Plotting of the coordination numbers of a given site for all the distfactor/angfactor parameters. If the chemical environments are given, a color map is added to the plot, with the lowest continuous symmetry measure as the value for the color of that distfactor/angfactor set.
- Parameters:
isite – Index of the site for which the plot has to be done.
plot_type – How to plot the coordinations.
title – Title for the figure.
max_dist – Maximum distance to be plotted when the plotting of the distance is set to ‘initial_normalized’ or ‘initial_real’ (Warning: this is not the same meaning in both cases! In the first case, the closest atom lies at a “normalized” distance of 1.0 so that 2.0 means refers to this normalized distance while in the second case, the real distance is used).
figsize – Size of the figure.
strategy – Whether to plot information about one of the Chemenv Strategies.
- save_environments_figure(isite, imagename='image.png', plot_type=None, title='Coordination numbers', max_dist=2.0, figsize=None)[source]
Saves the environments figure to a given file.
- Parameters:
isite – Index of the site for which the plot has to be done.
imagename – Name of the file to which the figure has to be saved.
plot_type – How to plot the coordinations.
title – Title for the figure.
max_dist – Maximum distance to be plotted when the plotting of the distance is set to ‘initial_normalized’ or ‘initial_real’ (Warning: this is not the same meaning in both cases! In the first case, the closest atom lies at a “normalized” distance of 1.0 so that 2.0 means refers to this normalized distance while in the second case, the real distance is used).
figsize – Size of the figure.
- update_coordination_environments(isite, cn, nb_set, ce)[source]
Updates the coordination environment for this site, coordination and neighbor set.
- Parameters:
isite – Index of the site to be updated.
cn – Coordination to be updated.
nb_set – Neighbors set to be updated.
ce – ChemicalEnvironments object for this neighbors set.
pymatgen.analysis.chemenv.coordination_environments.voronoi module
This module contains the object used to describe the possible bonded atoms based on a Voronoi analysis.
- class DetailedVoronoiContainer(structure=None, voronoi_list2=None, voronoi_cutoff=10.0, isites=None, normalized_distance_tolerance=1e-05, normalized_angle_tolerance=0.001, additional_conditions=None, valences=None, maximum_distance_factor=None, minimum_angle_factor=None)[source]
Bases:
MSONableClass used to store the full Voronoi of a given structure.
Constructor for the VoronoiContainer object. Either a structure is given, in which case the Voronoi is computed, or the different components of the VoronoiContainer are given (used in the from_dict method).
- Parameters:
structure – Structure for which the Voronoi is computed.
voronoi_list2 – List of voronoi polyhedrons for each site.
voronoi_cutoff – cutoff used for the voronoi.
isites – indices of sites for which the Voronoi has to be computed.
normalized_distance_tolerance – Tolerance for two normalized distances to be considered equal.
normalized_angle_tolerance – Tolerance for two normalized angles to be considered equal.
additional_conditions – Additional conditions to be used.
valences – Valences of all the sites in the structure (used when additional conditions require it).
maximum_distance_factor – The maximum distance factor to be considered.
minimum_angle_factor – The minimum angle factor to be considered.
- Raises:
RuntimeError if the Voronoi cannot be constructed. –
- as_dict()[source]
Bson-serializable dict representation of the VoronoiContainer.
- Returns:
dictionary that is BSON-encodable.
- classmethod from_dict(dct)[source]
Reconstructs the VoronoiContainer object from a dict representation of the VoronoiContainer created using the as_dict method.
- Parameters:
dct – dict representation of the VoronoiContainer object.
- Returns:
VoronoiContainer object.
- get_rdf_figure(isite, normalized=True, figsize=None, step_function=None)[source]
Get the Radial Distribution Figure for a given site.
- Parameters:
isite – Index of the site.
normalized – Whether to normalize distances.
figsize – Size of the figure.
step_function – Type of step function to be used for the RDF.
- Returns:
Matplotlib figure.
- get_sadf_figure(isite, normalized=True, figsize=None, step_function=None)[source]
Get the Solid Angle Distribution Figure for a given site.
- Parameters:
isite – Index of the site.
normalized – Whether to normalize angles.
figsize – Size of the figure.
step_function – Type of step function to be used for the SADF.
- Returns:
Matplotlib figure.
- is_close_to(other, rtol=0.0, atol=1e-08) bool[source]
Whether two DetailedVoronoiContainer objects are close to each other.
- Parameters:
other – Another DetailedVoronoiContainer to be compared with.
rtol – Relative tolerance to compare values.
atol – Absolute tolerance to compare values.
- Returns:
True if the two DetailedVoronoiContainer are close to each other.
- maps_and_surfaces(isite, surface_calculation_type=None, max_dist=2.0, additional_conditions=None)[source]
Get the different surfaces and their cn_map corresponding to the different distance-angle cutoffs for a given site.
- Parameters:
isite – Index of the site
surface_calculation_type – How to compute the surface.
max_dist – The maximum distance factor to be considered.
additional_conditions – If additional conditions have to be considered.
- Returns:
Surfaces and cn_map’s for each distance-angle cutoff.
- maps_and_surfaces_bounded(isite, surface_calculation_options=None, additional_conditions=None)[source]
Get the different surfaces (using boundaries) and their cn_map corresponding to the different distance-angle cutoffs for a given site.
- Parameters:
isite – Index of the site
surface_calculation_options – Options for the boundaries.
additional_conditions – If additional conditions have to be considered.
- Returns:
Surfaces and cn_map’s for each distance-angle cutoff.
- neighbors(isite, distfactor, angfactor, additional_condition=None)[source]
Get the neighbors of a given site corresponding to a given distance and angle factor.
- Parameters:
isite – Index of the site.
distfactor – Distance factor.
angfactor – Angle factor.
additional_condition – Additional condition to be used (currently not implemented).
- Returns:
List of neighbors of the given site for the given distance and angle factors.
- neighbors_surfaces(isite, surface_calculation_type=None, max_dist=2.0)[source]
Get the different surfaces corresponding to the different distance-angle cutoffs for a given site.
- Parameters:
isite – Index of the site
surface_calculation_type – How to compute the surface.
max_dist – The maximum distance factor to be considered.
- Returns:
Surfaces for each distance-angle cutoff.
- neighbors_surfaces_bounded(isite, surface_calculation_options=None)[source]
Get the different surfaces (using boundaries) corresponding to the different distance-angle cutoffs for a given site.
- Parameters:
isite – Index of the site.
surface_calculation_options – Options for the boundaries.
- Returns:
Surfaces for each distance-angle cutoff.
- setup_neighbors_distances_and_angles(indices)[source]
Initializes the angle and distance separations.
- Parameters:
indices – Indices of the sites for which the Voronoi is needed.
- setup_voronoi_list(indices, voronoi_cutoff)[source]
Set up of the voronoi list of neighbors by calling qhull.
- Parameters:
indices – indices of the sites for which the Voronoi is needed.
voronoi_cutoff – Voronoi cutoff for the search of neighbors.
- Raises:
RuntimeError – If an infinite vertex is found in the voronoi construction.
- to_bson_voronoi_list2()[source]
Transforms the voronoi_list into a vlist + bson_nb_voro_list, that are BSON-encodable.
- Returns:
[vlist, bson_nb_voro_list], to be used in the as_dict method.
- voronoi_parameters_bounds_and_limits(isite, plot_type, max_dist)[source]
Get the different boundaries and limits of the distance and angle factors for the given site.
- Parameters:
isite – Index of the site.
plot_type – Types of distance/angle parameters to get.
max_dist – Maximum distance factor.
- Returns:
Distance and angle bounds and limits.
- from_bson_voronoi_list2(bson_nb_voro_list2, structure)[source]
Returns the voronoi_list needed for the VoronoiContainer object from a bson-encoded voronoi_list.
- Parameters:
bson_nb_voro_list2 – List of periodic sites involved in the Voronoi.
structure – Structure object.
- Returns:
The voronoi_list needed for the VoronoiContainer (with PeriodicSites as keys of the dictionary - not allowed in the BSON format).