pymatgen.core package

Subpackages

Submodules

pymatgen.core.adsorption module

This module provides classes used to enumerate surface sites and to find adsorption sites on slabs.

class AdsorbateSiteFinder(slab: Slab | Structure, selective_dynamics: bool = False, height: float = 0.9, mi_vec: ArrayLike | None = None)[source]

Bases: object

This class finds adsorbate sites on slabs and generates adsorbate structures according to user-defined criteria.

The algorithm for finding sites is essentially as follows:

1. Determine “surface sites” by finding those within

   a height threshold along the miller index of the highest site

2. Create a network of surface sites using the Delaunay

   triangulation of the surface sites

3. Assign on-top, bridge, and hollow adsorption sites

   at the nodes, edges, and face centers of the Del. Triangulation

4. Generate structures from a molecule positioned at

   these sites

Create an AdsorbateSiteFinder object.

Parameters:

• slab (Slab) – slab object for which to find adsorbate sites

• selective_dynamics (bool) – flag for whether to assign non-surface sites as fixed for selective dynamics

• height (float) – height criteria for selection of surface sites

• mi_vec (3-D array-like) – vector corresponding to the vector concurrent with the miller index, this enables use with slabs that have been reoriented, but the miller vector must be supplied manually

add_adsorbate(molecule: Molecule, ads_coord, repeat=None, translate=True, reorient=True)[source]

Add an adsorbate at a particular coordinate. Adsorbate represented by a Molecule object and is translated to (0, 0, 0) if translate is True, or positioned relative to the input adsorbate coordinate if translate is False.

Parameters:

• molecule (Molecule) – molecule object representing the adsorbate

• ads_coord (array) – coordinate of adsorbate position

• repeat (3-tuple or list) – input for making a supercell of slab prior to placing the adsorbate

• translate (bool) – flag on whether to translate the molecule so that its CoM is at the origin prior to adding it to the surface

• reorient (bool) – flag on whether to reorient the molecule to have its z-axis concurrent with miller index

adsorb_both_surfaces(molecule, repeat=None, min_lw=5.0, translate=True, reorient=True, find_args=None)[source]

Generate all adsorption structures for a given molecular adsorbate on both surfaces of a slab. This is useful for calculating surface energy where both surfaces need to be equivalent or if we want to calculate nonpolar systems.

Parameters:

• molecule (Molecule) – molecule corresponding to adsorbate

• repeat (3-tuple or list) – repeat argument for supercell generation

• min_lw (float) – minimum length and width of the slab, only used if repeat is None

• translate (bool) – flag on whether or not to translate adsorbate to the adsorption site

• reorient (bool) – flag on whether or not to reorient adsorbate along the miller index

• find_args (dict) – dictionary of arguments to be passed to the call to self.find_adsorption_sites, e.g. {“distance”:2.0}

classmethod assign_selective_dynamics(slab)[source]

Helper function to assign selective dynamics site_properties based on surface, subsurface site properties.

Parameters:

slab (Slab) – slab for which to assign selective dynamics

assign_site_properties(slab: Slab, height=0.9)[source]

Assign site properties.

classmethod ensemble_center(site_list, indices, cartesian=True)[source]

Find the center of an ensemble of sites selected from a list of sites. Helper method for the find_adsorption_sites algorithm.

Parameters:

• site_list (list[Site]) – sites from which to select

• indices (list[int]) – indices of sites from which to select sites from site list

• cartesian (bool) – whether to get average fractional or Cartesian coordinate

find_adsorption_sites(distance=2.0, put_inside=True, symm_reduce=0.01, near_reduce=0.01, positions=('ontop', 'bridge', 'hollow'), no_obtuse_hollow=True)[source]

Find surface sites according to the above algorithm. Returns a list of corresponding Cartesian coordinates.

Parameters:

• distance (float) – distance from the coordinating ensemble of atoms along the miller index for the site (i.e. the distance from the slab itself)

• put_inside (bool) – whether to put the site inside the cell

• symm_reduce (float) – symm reduction threshold

• near_reduce (float) – near reduction threshold

• positions (list) –

  which positions to include in the site finding “ontop”: sites on top of surface sites “bridge”: sites at edges between surface sites in Delaunay

  triangulation of surface sites in the miller plane

  ”hollow”: sites at centers of Delaunay triangulation faces “subsurface”: subsurface positions projected into miller plane

• no_obtuse_hollow (bool) – flag to indicate whether to include obtuse triangular ensembles in hollow sites

find_surface_sites_by_height(slab: Slab, height=0.9, xy_tol=0.05)[source]

Find surface sites by determining which sites are within a threshold value in height from the topmost site in a list of sites.

Parameters:

• slab (Slab) – slab for which to find surface sites

• height (float) – threshold in angstroms of distance from topmost site in slab along the slab c-vector to include in surface site determination

• xy_tol (float) – if supplied, will remove any sites which are within a certain distance in the miller plane.

Returns:

list of sites selected to be within a threshold of the highest

classmethod from_bulk_and_miller(structure, miller_index, min_slab_size=8.0, min_vacuum_size=10.0, max_normal_search=None, center_slab=True, selective_dynamics=False, undercoord_threshold=0.09) → Self[source]

Construct the adsorbate site finder from a bulk structure and a miller index, which allows the surface sites to be determined from the difference in bulk and slab coordination, as opposed to the height threshold.

Parameters:

• structure (Structure) – structure from which slab input to the ASF is constructed

• miller_index (3-tuple or list) – miller index to be used

• min_slab_size (float) – min slab size for slab generation

• min_vacuum_size (float) – min vacuum size for slab generation

• max_normal_search (int) – max normal search for slab generation

• center_slab (bool) – whether to center slab in slab generation

• selective_dynamics (bool) – whether to assign surface sites to selective dynamics

• undercoord_threshold (float) – threshold of “undercoordation” to use for the assignment of surface sites. Default is 0.1, for which surface sites will be designated if they are 10% less coordinated than their bulk counterpart

generate_adsorption_structures(molecule, repeat=None, min_lw=5.0, translate=True, reorient=True, find_args=None)[source]

Generate all adsorption structures for a given molecular adsorbate. Can take repeat argument or minimum length/width of precursor slab as an input.

Parameters:

• molecule (Molecule) – molecule corresponding to adsorbate

• repeat (3-tuple or list) – repeat argument for supercell generation

• min_lw (float) – minimum length and width of the slab, only used if repeat is None

• translate (bool) – flag on whether to translate the molecule so that its CoM is at the origin prior to adding it to the surface

• reorient (bool) – flag on whether or not to reorient adsorbate along the miller index

• find_args (dict) – dictionary of arguments to be passed to the call to self.find_adsorption_sites, e.g. {“distance”:2.0}

generate_substitution_structures(atom, target_species=None, sub_both_sides=False, range_tol=0.01, dist_from_surf=0)[source]

Perform substitution-type doping on the surface and returns all possible configurations where one dopant is substituted per surface. Can substitute one surface or both.

Parameters:

• atom (str) – atom corresponding to substitutional dopant

• sub_both_sides (bool) – If true, substitute an equivalent site on the other surface

• target_species (list) – Specific species to substitute

• range_tol (float) – Find viable substitution sites at a specific distance from the surface +- this tolerance

• dist_from_surf (float) – Distance from the surface to find viable substitution sites, defaults to 0 to substitute at the surface

get_extended_surface_mesh(repeat=(5, 5, 1))[source]

Get an extended surface mesh for to use for adsorption site finding by constructing supercell of surface sites.

Parameters:

repeat (3-tuple) – repeat for getting extended surface mesh

near_reduce(coords_set, threshold=0.0001)[source]

Prune coordinate set for coordinates that are within threshold.

Parameters:

• coords_set (Nx3 array-like) – list or array of coordinates

• threshold (float) – threshold value for distance

subsurface_sites()[source]

Convenience method to return list of subsurface sites.

property surface_sites[source]

Convenience method to return a list of surface sites.

symm_reduce(coords_set, threshold=1e-06)[source]

Reduce the set of adsorbate sites by finding removing symmetrically equivalent duplicates.

Parameters:

• coords_set – coordinate set in Cartesian coordinates

• threshold – tolerance for distance equivalence, used as input to in_coord_list_pbc for dupl. checking

get_mi_vec(slab)[source]

Convenience function which returns the unit vector aligned with the miller index.

get_rot(slab: Slab) → SymmOp[source]

Get the transformation to rotate the z axis into the miller index.

plot_slab(slab: Slab, ax: Axes, scale=0.8, repeat=5, window=1.5, draw_unit_cell=True, decay=0.2, adsorption_sites=True, inverse=False)[source]

Help visualize the slab in a 2-D plot, for convenient viewing of output of AdsorbateSiteFinder.

Parameters:

• slab (slab) – Slab object to be visualized

• ax (axes) – matplotlib axes with which to visualize

• scale (float) – radius scaling for sites

• repeat (int) – number of repeating unit cells to visualize

• window (float) – window for setting the axes limits, is essentially a fraction of the unit cell limits

• draw_unit_cell (bool) – flag indicating whether or not to draw cell

• adsorption_sites (bool) – whether to plot adsorption sites

• decay (float) – how the alpha-value decays along the z-axis

• inverse (bool) – invert z axis to plot opposite surface

put_coord_inside(lattice, cart_coordinate)[source]

Convert a Cartesian coordinate such that it is inside the unit cell.

reorient_z(structure)[source]

Reorient a structure such that the z axis is concurrent with the normal to the A-B plane.

pymatgen.core.bond_valence module

This module implements classes to perform bond valence analyses.

class BVAnalyzer(symm_tol=0.1, max_radius=4, max_permutations=100000, distance_scale_factor=1.015, charge_neutrality_tolerance=1e-05, forbidden_species=None)[source]

Bases: object

This class implements a maximum a posteriori (MAP) estimation method to determine oxidation states in a structure. The algorithm is as follows: 1) The bond valence sum of all symmetrically distinct sites in a structure is calculated using the element-based parameters in M. O’Keefe, & N. Brese, JACS, 1991, 113(9), 3226-3229. doi:10.1021/ja00009a002. 2) The posterior probabilities of all oxidation states is then calculated using: P(oxi_state/BV) = K * P(BV/oxi_state) * P(oxi_state), where K is a constant factor for each element. P(BV/oxi_state) is calculated as a Gaussian with mean and std deviation determined from an analysis of the ICSD. The posterior P(oxi_state) is determined from a frequency analysis of the ICSD. 3) The oxidation states are then ranked in order of decreasing probability and the oxidation state combination that result in a charge neutral cell is selected.

Initialize the BV analyzer, with useful defaults.

Parameters:

• symm_tol – Symmetry tolerance used to determine which sites are symmetrically equivalent. Set to 0 to turn off symmetry.

• max_radius – Maximum radius in Angstrom used to find nearest neighbors.

• max_permutations – The maximum number of permutations of oxidation states to test.

• distance_scale_factor – A scale factor to be applied. This is useful for scaling distances, esp in the case of calculation-relaxed structures which may tend to under (GGA) or over bind (LDA). The default of 1.015 works for GGA. For experimental structure, set this to 1.

• charge_neutrality_tolerance – Tolerance on the charge neutrality when unordered structures are at stake.

• forbidden_species – List of species that are forbidden (example : [“O-”] cannot be used) It is used when e.g. someone knows that some oxidation state cannot occur for some atom in a structure or list of structures.

CHARGE_NEUTRALITY_TOLERANCE = 1e-05[source]

get_oxi_state_decorated_structure(structure: Structure) → Structure[source]

Get an oxidation state decorated structure. This currently works only for ordered structures only.

Parameters:

structure – Structure to analyze

Returns:

modified with oxidation state decorations.

Return type:

Structure

Raises:

ValueError if the valences cannot be determined. –

get_valences(structure: Structure)[source]

Get a list of valences for each site in the structure.

Parameters:

structure – Structure to analyze

Returns:

A list of valences for each site in the structure (for an ordered structure), e.g. [1, 1, -2] or a list of lists with the valences for each fractional element of each site in the structure (for an unordered structure), e.g. [[2, 4], [3], [-2], [-2], [-2]]

Raises:

A ValueError if the valences cannot be determined. –

add_oxidation_state_by_site_fraction(structure: Structure, oxidation_states: list[list[int]]) → Structure[source]

Add oxidation states to a structure by fractional site.

Parameters:

• structure (Structure) – Structure to which oxidation states are added.

• oxidation_states (list[list[int]]) – List of list of oxidation states for each site fraction for each site. e.g. [[2, 4], [3], [-2], [-2], [-2]]

calculate_bv_sum(site, nn_list, scale_factor=1.0)[source]

Calculate the BV sum of a site.

Parameters:

• site (PeriodicSite) – The central site to calculate the bond valence

• nn_list ([Neighbor]) – A list of namedtuple Neighbors having “distance” and “site” attributes

• scale_factor (float) – A scale factor to be applied. This is useful for scaling distance, esp in the case of calculation-relaxed structures which may tend to under (GGA) or over bind (LDA).

calculate_bv_sum_unordered(site, nn_list, scale_factor=1)[source]

Calculate the BV sum of a site for unordered structures.

Parameters:

• site (PeriodicSite) – The central site to calculate the bond valence

• nn_list ([Neighbor]) – A list of namedtuple Neighbors having “distance” and “site” attributes

• scale_factor (float) – A scale factor to be applied. This is useful for scaling distance, esp in the case of calculation-relaxed structures which may tend to under (GGA) or over bind (LDA).

get_z_ordered_elmap(comp)[source]

Arbitrary ordered element map on the elements/species of a composition of a given site in an unordered structure. Returns a list of tuples ( element_or_specie: occupation) in the arbitrary order.

The arbitrary order is based on the Z of the element and the smallest fractional occupations first. Example : {“Ni3+”: 0.2, “Ni4+”: 0.2, “Cr3+”: 0.15, “Zn2+”: 0.34, “Cr4+”: 0.11} will yield the species in the following order : Cr4+, Cr3+, Ni3+, Ni4+, Zn2+ … or Cr4+, Cr3+, Ni4+, Ni3+, Zn2+

pymatgen.core.bonds module

This module implements definitions for various kinds of bonds. Typically used in Molecule analysis.

class CovalentBond(site1: Site, site2: Site)[source]

Bases: object

A covalent bond between two sites.

Initializes the object with two site instances.

This constructor method assigns the provided site1 and site2 parameters to the instance attributes, enabling interaction with two separate Site objects.

Parameters:

• site1 – The first site object.

• site2 – The second site object.

get_bond_order(tol: float = 0.2, default_bl: float | None = None) → float[source]

The bond order according the distance between the two sites.

Parameters:

• tol (float) – Relative tolerance to test. (1 + tol) * the longest bond distance is considered to be the threshold length for a bond to exist. (1 - tol) * the shortest bond distance is considered to be the shortest possible bond length Defaults to 0.2.

• default_bl – If a particular type of bond does not exist, use this bond length as a default value (bond order = 1). If None, a ValueError will be thrown.

Returns:

value of bond order. E.g. 1.7 for C-C bond in benzene.

Return type:

float

static is_bonded(site1: Site, site2: Site, tol: float = 0.2, bond_order: float | None = None, default_bl: float | None = None) → bool[source]

Check if two sites are bonded, up to a certain limit.

Parameters:

• site1 (Site) – First site

• site2 (Site) – Second site

• tol (float) – Relative tolerance to test. Basically, the code checks if the distance between the sites is less than (1 + tol) * typical bond distances. Defaults to 0.2, i.e., 20% longer.

• bond_order – Bond order to test. If None, the code simply checks against all possible bond data. Defaults to None.

• default_bl – If a particular type of bond does not exist, use this bond length. If None, a ValueError will be thrown.

Returns:

True if two sites are bonded.

Return type:

bool

property length: float[source]

Length of the bond.

get_bond_length(sp1: SpeciesLike, sp2: SpeciesLike, bond_order: float = 1) → float[source]

Get the bond length between two species.

Parameters:

• sp1 (Species) – First specie.

• sp2 (Species) – Second specie.

• bond_order – For species with different possible bond orders, this allows one to obtain the bond length for a particular bond order. For example, to get the C=C bond length instead of the C-C bond length, this should be set to 2. Defaults to 1.

Returns:

Bond length in Angstrom. If no data is available,

the sum of the atomic radius is used.

Return type:

float

get_bond_order(sp1: SpeciesLike, sp2: SpeciesLike, dist: float, tol: float = 0.2, default_bl: float | None = None) → float[source]

Calculate the bond order given the distance of 2 species.

Parameters:

• sp1 (Species) – First specie.

• sp2 (Species) – Second specie.

• dist (float) – Distance in angstrom

• tol (float) – Relative tolerance to test. Basically, the code checks if the distance between the sites is larger than (1 + tol) * the longest bond distance or smaller than (1 - tol) * the shortest bond distance to determine if they are bonded or the distance is too short. Defaults to 0.2.

• default_bl – If a particular type of bond does not exist, use this bond length (bond order = 1). If None, a ValueError will be thrown.

Returns:

Bond order. For example, 1.7 for C-C bond in benzene.

Return type:

float

obtain_all_bond_lengths(sp1: SpeciesLike, sp2: SpeciesLike, default_bl: float | None = None) → dict[float, float][source]

Obtain bond lengths for all bond orders from bond length database.

Parameters:

• sp1 (Species) – First specie.

• sp2 (Species) – Second specie.

• default_bl – If a particular type of bond does not exist, use this bond length as a default value (bond order = 1). If None, a ValueError will be thrown.

Returns:

mapping bond order to bond length in Angstrom.

Return type:

dict[float, float]

pymatgen.core.composition module

This module implements a Composition class to represent compositions, and a ChemicalPotential class to represent potentials.

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

Bases: dict, MSONable

Represent set of chemical potentials.

Can be:

• multiplied/divided by a Number

• multiplied by a Composition (returns an energy)

• added/subtracted with other ChemicalPotentials

Parameters:

• *args – any valid dict init arguments

• **kwargs – any valid dict init arguments.

get_energy(composition: Composition, strict: bool = True) → float[source]

Calculate the energy of a composition.

Parameters:

• composition (Composition) – input composition

• strict (bool) – Whether all potentials must be specified

class Composition(*args, strict: bool = False, **kwargs)[source]

Bases: Hashable, Mapping, MSONable, Stringify

Represents a Composition, a mapping of {element/species: amount} with enhanced functionality tailored for handling chemical compositions. The class is immutable, hashable, and designed for robust usage in material science and chemistry computations.

Key Features:

• Supports both Element and Species as keys, with differentiation

between oxidation states (e.g., Fe2+ and Fe3+ are distinct keys). - Behaves like a dictionary but returns 0 for missing keys, making it similar to a defaultdict while remaining immutable. - Provides numerous utility methods for chemical computations, such as calculating fractions, weights, and formula representations.

Highlights:

• Input Flexibility: Accepts formulas as strings, dictionaries, or

keyword arguments for construction. - Convenience Methods: Includes get_fraction, reduced_formula, and weight-related utilities. - Enhanced Formula Representation: Supports reduced, normalized, and IUPAC-sorted formulas.

Examples

>>> comp = Composition("LiFePO4")
>>> comp.get_atomic_fraction(Element("Li"))
0.14285714285714285
>>> comp.num_atoms
7.0
>>> comp.reduced_formula
'LiFePO4'
>>> comp.formula
'Li1 Fe1 P1 O4'
>>> comp.get_wt_fraction(Element("Li"))
0.04399794666951898
>>> comp.num_atoms
7.0

- `amount_tolerance`

Tolerance for distinguishing composition

Type:

float

amounts. Default is 1e-8 to minimize floating-point errors.

- `charge_balanced_tolerance`

Tolerance for verifying charge balance.

Type:

float

- `special_formulas`

Custom formula mappings for specific compounds

Type:

dict

(e.g., `"LiO"` → `"Li2O2"`).

- `oxi_prob`

Prior probabilities of oxidation states, used

Type:

dict or None

for oxidation state guessing.

Functionality:

• Arithmetic Operations: Add, subtract, multiply, or divide compositions.

For example:

>>> comp1 = Composition("Fe2O3")
>>> comp2 = Composition("FeO")
>>> result = comp1 + comp2  # Produces "Fe3O4"

• Representation:

  • formula: Full formula string with elements sorted by electronegativity.

  • reduced_formula: Simplified formula with minimal ratios.

  • hill_formula: Hill notation (C and H prioritized, others alphabetically sorted).

• Utilities:

  • get_atomic_fraction: Returns the atomic fraction of a given element/species.

  • get_wt_fraction: Returns the weight fraction of a given element/species.

  • is_element: Checks if the composition is a pure element.

  • reduced_composition: Normalizes the composition by the greatest common denominator.

  • fractional_composition: Returns the normalized composition where sums equal 1.

• Oxidation State Handling:

  • oxi_state_guesses: Suggests charge-balanced oxidation states.

  • charge_balanced: Checks if the composition is charge balanced.

  • add_charges_from_oxi_state_guesses: Assigns oxidation states based on guesses.

• Validation:

  • valid: Ensures all elements/species are valid.

Notes

• When constructing from strings, both Element and Species types are

handled. For example:

• Composition(“Fe2+”) differentiates Fe2+ from Fe3+.

• Composition(“Fe2O3”) auto-parses standard formulas.

Very flexible Composition construction, similar to the built-in Python dict(). Also extended to allow simple string init.

Takes any inputs supported by the Python built-in dict function.

1. A dict of either {Element/Species: amount},

   {string symbol:amount}, or {atomic number:amount} or any mixture of these. e.g. {Element(“Li”): 2, Element(“O”): 1}, {“Li”:2, “O”:1}, {3: 2, 8: 1} all result in a Li2O composition.

2. Keyword arg initialization, similar to a dict, e.g.

   Composition(Li = 2, O = 1)

In addition, the Composition constructor also allows a single string as an input formula. e.g. Composition(“Li2O”).

Parameters:

• *args – Any number of 2-tuples as key-value pairs.

• strict (bool) – Only allow valid Elements and Species in the Composition. Defaults to False.

• allow_negative (bool) – Whether to allow negative compositions. Defaults to False.

• **kwargs – Additional kwargs supported by the dict() constructor.

add_charges_from_oxi_state_guesses(oxi_states_override: dict | None = None, target_charge: float = 0, all_oxi_states: bool = False, max_sites: int | None = None) → Self[source]

Assign oxidation states based on guessed oxidation states.

See oxi_state_guesses for an explanation of how oxidation states are guessed. This operation uses the set of oxidation states for each site that were determined to be most likely from the oxidation state guessing routine.

Parameters:

• oxi_states_override (dict[str, list[float]]) – Override an element’s common oxidation states, e.g. {“V”: [2, 3, 4, 5]}

• target_charge (float) – the desired total charge on the structure. Default is 0 signifying charge balance.

• all_oxi_states (bool) – if True, all oxidation states of an element, even rare ones, are used in the search for guesses. However, the full oxidation state list is very inclusive and can produce nonsensical results. If False, the icsd_oxidation_states list is used when present, or the common_oxidation_states is used when icsd_oxidation_states is not present. These oxidation states lists comprise more commonly occurring oxidation states and results in more reliable guesses, albeit at the cost of missing some uncommon situations. The default is False.

• max_sites (int) – If possible, will reduce Compositions to at most this many sites to speed up oxidation state guesses. If the composition cannot be reduced to this many sites a ValueError will be raised. Set to -1 to just reduce fully. If set to a number less than -1, the formula will be fully reduced but a ValueError will be thrown if the number of atoms in the reduced formula is greater than abs(max_sites).

Returns:

Composition, where the elements are assigned oxidation states based on the results form guessing oxidation states. If no oxidation state is possible, returns a Composition where all oxidation states are 0.

almost_equals(other: Composition, rtol: float = 0.1, atol: float = 1e-08) → bool[source]

Get true if compositions are equal within a tolerance.

Parameters:

• other (Composition) – Other composition to check

• rtol (float) – Relative tolerance

• atol (float) – Absolute tolerance

property alphabetical_formula: str[source]

A formula string, with elements sorted by alphabetically e.g. Fe4 Li4 O16 P4.

amount_tolerance: ClassVar[float] = 1e-08[source]

property anonymized_formula: str[source]

An anonymized formula. Unique species are arranged in ordering of increasing amounts and assigned ascending alphabets. Useful for prototyping formulas. For example, all stoichiometric perovskites have anonymized_formula ABC3.

as_data_dict() → dict[Literal['reduced_cell_composition', 'unit_cell_composition', 'reduced_cell_formula', 'elements', 'nelements'], Any][source]

Returns:

• reduced_cell_composition

• unit_cell_composition

• reduced_cell_formula

• elements

• nelements.

Return type:

dict with the following keys

as_dict() → dict[str, float][source]

Subtly different from get_el_amt_dict in that they keys here are str(Element) instead of Element.symbol.

Returns:

element symbol and (unreduced) amount. E.g.

{“Fe”: 4.0, “O”: 6.0} or {“Fe3+”: 4.0, “O2-”: 6.0}

Return type:

dict[str, float]

as_reduced_dict() → dict[str, float][source]

Returns:

element symbols mapped to reduced amount e.g. {“Fe”: 2.0, “O”: 3.0}.

Return type:

dict[str, float]

as_weight_dict() → dict[str, float][source]

Returns:

weight fractions of each component, e.g. {“Ti”: 0.90, “V”: 0.06, “Al”: 0.04}.

Return type:

dict[str, float]

property average_electroneg: float[source]

Average electronegativity of the composition.

property charge: float | None[source]

Total charge based on oxidation states. If any oxidation states are None or they’re all 0, returns None. Use add_charges_from_oxi_state_guesses to assign oxidation states to elements based on charge balancing.

property charge_balanced: bool | None[source]

True if composition is charge balanced, False otherwise. If any oxidation states are None, returns None. Use add_charges_from_oxi_state_guesses to assign oxidation states to elements.

charge_balanced_tolerance: ClassVar[float] = 1e-08[source]

property chemical_system: str[source]

The chemical system of a Composition, for example “O-Si” for SiO2. Chemical system is a string of a list of elements sorted alphabetically and joined by dashes, by convention for use in database keys.

property chemical_system_set: set[str][source]

The set of elements in the Composition. E.g. {“O”, “Si”} for SiO2.

contains_element_type(category: str) → bool[source]

Check if Composition contains any elements matching a given category.

Parameters:

category (str) – one of “noble_gas”, “transition_metal”, “post_transition_metal”, “rare_earth_metal”, “metal”, “metalloid”, “alkali”, “alkaline”, “halogen”, “chalcogen”, “lanthanoid”, “actinoid”, “radioactive”, “quadrupolar”, “s-block”, “p-block”, “d-block”, “f-block”.

Returns:

True if any elements in Composition match category.

Return type:

bool

copy() → Self[source]

A copy of the composition.

property element_composition: Self[source]

The composition replacing any species by the corresponding element.

property elements: list[Element | Species | DummySpecies][source]

List of elements in Composition.

property formula: str[source]

A formula string, with elements sorted by electronegativity, e.g. Li4 Fe4 P4 O16.

property fractional_composition: Self[source]

The normalized composition in which the amounts of each species sum to 1. E.g. “Fe2 O3”.fractional_composition = “Fe0.4 O0.6”.

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

Create a composition from a dict generated by as_dict(). Strictly not necessary given that the standard constructor already takes in such an input, but this method preserves the standard pymatgen API of having from_dict methods to reconstitute objects generated by as_dict(). Allows for easier introspection.

Parameters:

dct (dict) – {symbol: amount} dict.

classmethod from_weight_dict(weight_dict: dict[SpeciesLike, float], strict: bool = True, **kwargs) → Self[source]

Create a Composition based on a dict of atomic fractions calculated from a dict of weight fractions. Allows for quick creation of the class from weight-based notations commonly used in the industry, such as Ti6V4Al and Ni60Ti40.

Parameters:

• weight_dict (dict) – {symbol: weight_fraction} dict.

• strict (bool) – Only allow valid Elements and Species in the Composition. Defaults to True.

• **kwargs – Additional kwargs supported by the dict() constructor.

Returns:

Composition in molar fractions.

Examples

>>> Composition.from_weights({"Fe": 0.5, "Ni": 0.5})
Composition('Fe0.512434 Ni0.487566')
>>> Composition.from_weights({"Ti": 60, "Ni": 40})
Composition('Ti0.647796 Ni0.352204')

classmethod from_weights(*args, strict: bool = True, **kwargs) → Self[source]

Create a Composition from a weight-based formula.

Parameters:

• *args – Any number of 2-tuples as key-value pairs.

• strict (bool) – Only allow valid Elements and Species in the Composition. Defaults to False.

• allow_negative (bool) – Whether to allow negative compositions. Defaults to False.

• **kwargs – Additional kwargs supported by the dict() constructor.

Returns:

Composition in molar fractions.

Examples

>>> Composition.from_weights("Fe50Ti50")
Composition('Fe0.461538 Ti0.538462')
>>> Composition.from_weights({"Fe": 0.5, "Ni": 0.5})
Composition('Fe0.512434 Ni0.487566')

get_atomic_fraction(el: SpeciesLike) → float[source]

Calculate atomic fraction of an Element or Species.

Parameters:

el (SpeciesLike) – Element or Species to get fraction for.

Returns:

Atomic fraction for element el in Composition

get_el_amt_dict() → dict[str, float][source]

Returns:

element symbol and (unreduced) amount. E.g.

{“Fe”: 4.0, “O”: 6.0}.

Return type:

dict[str, float]

get_integer_formula_and_factor(max_denominator: int = 10000, iupac_ordering: bool = False) → tuple[str, float][source]

Calculate an integer formula and factor.

Parameters:

• max_denominator (int) – all amounts in the el_amt dict are first converted to a Fraction with this maximum denominator.

• iupac_ordering (bool, optional) – Whether to order the formula by the IUPAC “electronegativity” series, defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actinides and hydrogen. Note that polyanions will still be determined based on the true electronegativity of the elements.

Returns:

A normalized formula and a multiplicative factor, i.e., “Li0.5O0.25” returns (Li2O, 0.25). “O0.25” returns (O2, 0.125)

get_reduced_composition_and_factor() → tuple[Self, float][source]

Calculate a reduced composition and factor.

Returns:

Normalized Composition and multiplicative factor, i.e. “Li4Fe4P4O16” returns (Composition(“LiFePO4”), 4).

Return type:

tuple[Composition, float]

get_reduced_formula_and_factor(iupac_ordering: bool = False) → tuple[str, float][source]

Calculate a reduced formula and factor.

Parameters:

iupac_ordering (bool, optional) – Whether to order the formula by the IUPAC “electronegativity” series, defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except for Lanthanides, Actinides and hydrogen. Note that polyanions will still be determined based on the true electronegativity of the elements.

Returns:

Normalized formula and multiplicative factor,

i.e., “Li4Fe4P4O16” returns (LiFePO4, 4).

Return type:

tuple[str, float]

get_wt_fraction(el: SpeciesLike) → float[source]

Calculate weight fraction of an Element or Species.

Parameters:

el (Element | Species) – Element or Species to get fraction for.

Returns:

Weight fraction for element el in Composition.

Return type:

float

property hill_formula: str[source]

The Hill system (or Hill notation) is a system of writing empirical chemical formulas, molecular chemical formulas and components of a condensed formula such that the number of carbon atoms in a molecule is indicated first, the number of hydrogen atoms next, and then the number of all other chemical elements subsequently, in alphabetical order of the chemical symbols. When the formula contains no carbon, all the elements, including hydrogen, are listed alphabetically.

property is_element: bool[source]

True if composition is an element.

items() → ItemsView[Species | Element | DummySpecies, int | float][source]

Returns Dict.items() for the Composition dict.

property iupac_formula: str[source]

A formula string, with elements sorted by the IUPAC electronegativity ordering defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actinides and hydrogen. Polyanions are still determined based on the true electronegativity of the elements. e.g. CH2(SO4)2.

property num_atoms: float[source]

Total number of atoms in Composition. For negative amounts, sum of absolute values.

oxi_prob: ClassVar[dict | None] = None[source]

oxi_state_guesses(oxi_states_override: dict | None = None, target_charge: float = 0, all_oxi_states: bool = False, max_sites: int | None = None) → tuple[source]

Check if the composition is charge-balanced and returns back all charge-balanced oxidation state combinations. Composition must have integer values. Note that more num_atoms in the composition gives more degrees of freedom. e.g. if possible oxidation states of element X are [2,4] and Y are [-3], then XY is not charge balanced but X2Y2 is. Results are returned from most to least probable based on ICSD statistics. Use max_sites to improve performance if needed.

Parameters:

• oxi_states_override (dict) – dict of str->list to override an element’s common oxidation states, e.g. {“V”: [2,3,4,5]}

• target_charge (int) – the desired total charge on the structure. Default is 0 signifying charge balance.

• all_oxi_states (bool) – if True, all oxidation states of an element, even rare ones, are used in the search for guesses. However, the full oxidation state list is very inclusive and can produce nonsensical results. If False, the icsd_oxidation_states list is used when present, or the common_oxidation_states is used when icsd_oxidation_states is not present. These oxidation states lists comprise more commonly occurring oxidation states and results in more reliable guesses, albeit at the cost of missing some uncommon situations. The default is False.

• max_sites (int) – if possible, will reduce Compositions to at most this many sites to speed up oxidation state guesses. If the composition cannot be reduced to this many sites a ValueError will be raised. Set to -1 to just reduce fully. If set to a number less than -1, the formula will be fully reduced but a ValueError will be thrown if the number of atoms in the reduced formula is greater than abs(max_sites).

Returns:

each dict reports an element symbol and average

oxidation state across all sites in that composition. If the composition is not charge balanced, an empty list is returned.

Return type:

list[dict]

static ranked_compositions_from_indeterminate_formula(fuzzy_formula: str, lock_if_strict: bool = True) → list[Composition][source]

Takes in a formula where capitalization might not be correctly entered, and suggests a ranked list of potential Composition matches. Author: Anubhav Jain.

Parameters:

• fuzzy_formula (str) – A formula string, such as “co2o3” or “MN”, that may or may not have multiple interpretations

• lock_if_strict (bool) – If true, a properly entered formula will only return the one correct interpretation. For example, “Co1” will only return “Co1” if true, but will return both “Co1” and “C1 O1” if false.

Returns:

A ranked list of potential Composition matches

property reduced_composition: Self[source]

The reduced composition, i.e. amounts normalized by greatest common denominator. E.g. “Fe4 P4 O16”.reduced_composition = “Fe P O4”.

property reduced_formula: str[source]

A normalized formula, i.e., “LiFePO4” instead of “Li4Fe4P4O16”.

remove_charges() → Self[source]

Get a new Composition with charges from each Species removed.

Returns:

Composition object without charge decoration, for example {“Fe3+”: 2.0, “O2-“:3.0} becomes {“Fe”: 2.0, “O”:3.0}

replace(elem_map: dict[str, str | dict[str, float]]) → Self[source]

Replace elements in a composition. Returns a new Composition, leaving the old one unchanged.

Parameters:

elem_map (dict[str, str | dict[str, float]]) – dict of elements or species to swap. E.g. {“Li”: “Na”} performs a Li for Na substitution. The target can be a {species: factor} dict. For example, in Fe2O3 you could map {“Fe”: {“Mg”: 0.5, “Cu”:0.5}} to obtain MgCuO3.

Returns:

New object with elements remapped according to elem_map.

Return type:

Composition

special_formulas: ClassVar[dict[str, str]] = {'Cl': 'Cl2', 'CsO': 'Cs2O2', 'F': 'F2', 'H': 'H2', 'HO': 'H2O2', 'KO': 'K2O2', 'LiO': 'Li2O2', 'N': 'N2', 'NaO': 'Na2O2', 'O': 'O2', 'RbO': 'Rb2O2'}[source]

property to_data_dict[source]

Deprecated.

to_pretty_string() → str[source]

Returns:

Same output as __str__() but without spaces.

Return type:

str

property to_reduced_dict[source]

Deprecated.

property to_weight_dict: dict[str, float][source]

Deprecated.

property total_electrons: float[source]

Total number of electrons in composition.

property valid: bool[source]

True if Composition contains valid elements or species and False if the Composition contains any dummy species.

property weight: FloatWithUnit[source]

Total molecular weight of Composition.

exception CompositionError[source]

Bases: Exception

Composition exceptions.

reduce_formula(sym_amt: Mapping[str, float], iupac_ordering: bool = False) → tuple[str, int][source]

Helper function to reduce a symbol-amount mapping.

Parameters:

• sym_amt (dict[str, float]) – Symbol to amount mapping.

• iupac_ordering (bool, optional) – Whether to order the formula by the IUPAC “electronegativity” series, defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except for Lanthanides, Actinides and hydrogen. Note that polyanions will still be determined based on the true electronegativity of the elements.

Returns:

reduced formula and factor.

Return type:

tuple[str, int]

pymatgen.core.energy_models module

This module implements a EnergyModel abstract class and some basic implementations. Basically, an EnergyModel is any model that returns an “energy” for any given structure.

class EnergyModel[source]

Bases: MSONable, ABC

Abstract structure filter class.

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

Parameters:

dct (dict) – Dict representation.

Returns:

EnergyModel

abstractmethod get_energy(structure) → float[source]

Parameters:

structure – Structure.

Returns:

Energy value

class EwaldElectrostaticModel(real_space_cut=None, recip_space_cut=None, eta=None, acc_factor=8.0)[source]

Bases: EnergyModel

Wrapper around EwaldSum to calculate the electrostatic energy.

Initialize the model. Args have the same definitions as in pymatgen.core.ewald.EwaldSummation.

Parameters:

• real_space_cut (float) – Real space cutoff radius dictating how many terms are used in the real space sum. Defaults to None, which means determine automatically using the formula given in gulp 3.1 documentation.

• recip_space_cut (float) – Reciprocal space cutoff radius. Defaults to None, which means determine automatically using the formula given in gulp 3.1 documentation.

• eta (float) – Screening parameter. Defaults to None, which means determine automatically.

• acc_factor (float) – No. of significant figures each sum is converged to.

as_dict()[source]

MSONable dict.

get_energy(structure: Structure)[source]

Parameters:

structure – Structure.

Returns:

Energy value

class IsingModel(j, max_radius)[source]

Bases: EnergyModel

A very simple Ising model, with r^2 decay.

Parameters:

• j (float) – The interaction parameter. E = J * spin1 * spin2.

• max_radius (float) – max_radius for the interaction.

as_dict()[source]

MSONable dict.

get_energy(structure: Structure)[source]

Parameters:

structure – Structure.

Returns:

Energy value

class NsitesModel[source]

Bases: EnergyModel

Sets the energy to the number of sites. More sites => higher “energy”. Used to rank structures from smallest number of sites to largest number of sites after enumeration.

as_dict()[source]

MSONable dict.

get_energy(structure: Structure)[source]

Parameters:

structure – Structure.

Returns:

Energy value

class SymmetryModel(symprec: float = 0.1, angle_tolerance=5)[source]

Bases: EnergyModel

Sets the energy to the negative of the spacegroup number. Higher symmetry => lower “energy”.

Args have same meaning as in pymatgen.symmetry.SpacegroupAnalyzer.

Parameters:

• symprec (float) – Symmetry tolerance. Defaults to 0.1.

• angle_tolerance (float) – Tolerance for angles. Defaults to 5 degrees.

as_dict()[source]

MSONable dict.

get_energy(structure: Structure)[source]

Parameters:

structure – Structure.

Returns:

Energy value

pymatgen.core.entries module

Entries are containers for calculated information, which is used in many analyses. This module contains entry related tools and implements the base Entry class, which is the basic entity that can be used to store calculated information. Other Entry classes such as ComputedEntry and PDEntry inherit from this class. This module implements equivalents of the basic ComputedEntry objects, which is the basic entity that can be used to perform many analyses. ComputedEntries contain calculated information, typically from VASP or other electronic structure codes. For example, ComputedEntries can be used as inputs for phase diagram analysis. Also implements functions to perform various useful operations on entries, such as grouping entries by structure.

class CompositionEnergyAdjustment(adj_per_atom: float, n_atoms: float, uncertainty_per_atom: float = nan, name: str = '', cls: dict | None = None, description: str = 'Composition-based energy adjustment')[source]

Bases: EnergyAdjustment

An energy adjustment applied to a ComputedEntry based on the atomic composition. Used in various DFT energy correction schemes.

Parameters:

• adj_per_atom (float) – energy adjustment to apply per atom, in eV/atom

• n_atoms (float) – number of atoms.

• uncertainty_per_atom (float) – uncertainty in energy adjustment to apply per atom, in eV/atom. (Default: np.nan)

• name (str) – human-readable name of the energy adjustment. (Default: “”)

• cls (dict) – Serialized Compatibility class used to generate the energy adjustment. (Default: None)

• description (str) – human-readable explanation of the energy adjustment.

property explain: str[source]

An explanation of how the energy adjustment is calculated.

normalize(factor: float) → None[source]

Normalize energy adjustment (in place), dividing value/uncertainty by a factor.

Parameters:

factor – factor to divide by.

property uncertainty: float[source]

The value of the energy adjustment in eV.

property value: float[source]

The value of the energy adjustment in eV.

class ComputedEntry(composition: Composition | str | dict[str, float], energy: float, correction: float = 0.0, energy_adjustments: list | None = None, parameters: dict | None = None, data: dict | None = None, entry_id: str | None = None)[source]

Bases: Entry

Lightweight Entry object for computed data. Contains facilities for applying corrections to the energy attribute and for storing calculation parameters.

Initialize a ComputedEntry.

Parameters:

• composition (Composition) – Composition of the entry. For flexibility, this can take the form of all the typical input taken by a Composition, including a {symbol: amt} dict, a string formula, and others.

• energy (float) – Energy of the entry. Usually the final calculated energy from VASP or other electronic structure codes.

• correction (float) – Manually set an energy correction, will ignore energy_adjustments if specified.

• energy_adjustments – An optional list of EnergyAdjustment to be applied to the energy. This is used to modify the energy for certain analyses. Defaults to None.

• parameters – An optional dict of parameters associated with the entry. Defaults to None.

• data – An optional dict of any additional data associated with the entry. Defaults to None.

• entry_id – An optional id to uniquely identify the entry.

as_dict() → dict[source]

MSONable dict.

copy() → ComputedEntry[source]

Get a copy of the ComputedEntry.

property correction: float[source]

Returns: float: the total energy correction / adjustment applied to the entry in eV.

property correction_per_atom: float[source]

Returns: float: the total energy correction / adjustment applied to the entry in eV/atom.

property correction_uncertainty: float[source]

Returns: float: the uncertainty of the energy adjustments applied to the entry in eV.

property correction_uncertainty_per_atom: float[source]

Returns: float: the uncertainty of the energy adjustments applied to the entry in eV/atom.

property energy: float[source]

The corrected energy of the entry.

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

Parameters:

dct (dict) – Dict representation.

Returns:

ComputedEntry

normalize(mode: Literal['formula_unit', 'atom'] = 'formula_unit') → ComputedEntry[source]

Normalize the entry’s composition and energy.

Parameters:

mode ("formula_unit" | "atom") – “formula_unit” (the default) normalizes to composition.reduced_formula. “atom” normalizes such that the composition amounts sum to 1.

property uncorrected_energy: float[source]

Returns: float: the uncorrected energy of the entry.

property uncorrected_energy_per_atom: float[source]

Returns: float: the uncorrected energy of the entry, normalized by atoms in eV/atom.

class ComputedStructureEntry(structure: Structure, energy: float, correction: float = 0.0, composition: Composition | str | dict[str, float] | None = None, energy_adjustments: list | None = None, parameters: dict | None = None, data: dict | None = None, entry_id: str | None = None)[source]

Bases: ComputedEntry

A heavier version of ComputedEntry which contains a structure as well. The structure is needed for some analyses.

Initialize a ComputedStructureEntry.

Parameters:

• structure (Structure) – The actual structure of an entry.

• energy (float) – Energy of the entry. Usually the final calculated energy from VASP or other electronic structure codes.

• correction (float, optional) – A correction to the energy. This is mutually exclusive with energy_adjustments, i.e. pass either or neither but not both. Defaults to 0.

• composition (Composition) – Composition of the entry. For flexibility, this can take the form of all the typical input taken by a Composition, including a {symbol: amt} dict, a string formula, and others.

• energy_adjustments – An optional list of EnergyAdjustment to be applied to the energy. This is used to modify the energy for certain analyses. Defaults to None.

• parameters – An optional dict of parameters associated with the entry. Defaults to None.

• data – An optional dict of any additional data associated with the entry. Defaults to None.

• entry_id – An optional id to uniquely identify the entry.

as_dict() → dict[source]

MSONable dict.

copy() → ComputedStructureEntry[source]

Get a copy of the ComputedStructureEntry.

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

Parameters:

dct (dict) – Dict representation.

Returns:

ComputedStructureEntry

normalize(mode: Literal['formula_unit', 'atom'] = 'formula_unit') → ComputedStructureEntry[source]

Normalize the entry’s composition and energy. The structure remains unchanged.

Parameters:

mode ("formula_unit" | "atom") – “formula_unit” (the default) normalizes to composition.reduced_formula. “atom” normalizes such that the composition amounts sum to 1.

property structure: Structure[source]

The structure of the entry.

class ConstantEnergyAdjustment(value: float, uncertainty: float = nan, name: str = 'Constant energy adjustment', cls: dict | None = None, description: str = 'Constant energy adjustment')[source]

Bases: EnergyAdjustment

A constant energy adjustment applied to a ComputedEntry. Useful in energy referencing schemes such as the Aqueous energy referencing scheme.

Parameters:

• value (float) – the energy adjustment in eV

• uncertainty (float) – uncertainty of the energy adjustment in eV. (Default: np.nan)

• name (str) – human-readable name of the energy adjustment. (Default: Constant energy adjustment)

• cls (dict) – Serialized Compatibility class used to generate the energy adjustment. (Default: None)

• description (str) – human-readable explanation of the energy adjustment.

property explain: str[source]

An explanation of how the energy adjustment is calculated.

normalize(factor: float) → None[source]

Normalize energy adjustment (in place), dividing value/uncertainty by a factor.

Parameters:

factor (float) – factor to divide by.

class EnergyAdjustment(value: float, uncertainty: float = nan, name: str = 'Manual adjustment', cls: dict | None = None, description: str = '')[source]

Bases: MSONable

Lightweight class to contain information about an energy adjustment or energy correction.

Parameters:

• value (float) – value of the energy adjustment in eV

• uncertainty (float) – uncertainty of the energy adjustment in eV. Default: np.nan

• name (str) – human-readable name of the energy adjustment. (Default: Manual adjustment)

• cls (dict) – Serialized Compatibility class used to generate the energy adjustment. Defaults to {}.

• description (str) – human-readable explanation of the energy adjustment.

abstract property explain: str[source]

Return an explanation of how the energy adjustment is calculated.

abstractmethod normalize(factor: float) → None[source]

Scale the value of the current energy adjustment by factor in-place.

This method is utilized in ComputedEntry.normalize() to scale the energies to a formula unit basis (e.g. E_Fe6O9 = 3 x E_Fe2O3).

property uncertainty: float[source]

The uncertainty in the value of the energy adjustment in eV.

property value: float[source]

The value of the energy correction in eV.

class Entry(composition: Composition | str | dict[str, float], energy: float)[source]

Bases: MSONable, ABC

A lightweight object containing the energy associated with a specific chemical composition. This base class is not intended to be instantiated directly. Note that classes which inherit from Entry must define a .energy property.

Initialize an Entry.

Parameters:

• composition (Composition) – Composition of the entry. For flexibility, this can take the form of all the typical input taken by a Composition, including a {symbol: amt} dict, a string formula, and others.

• energy (float) – Energy of the entry.

as_dict() → dict[source]

MSONable dict.

property composition: Composition[source]

The composition of the entry.

property elements: list[Element | Species | DummySpecies][source]

The set of elements in the entry.

abstract property energy: float[source]

The energy of the entry.

property energy_per_atom: float[source]

The energy per atom of the entry.

property formula: str[source]

The formula of the entry.

property is_element: bool[source]

Whether composition of entry is an element.

normalize(mode: Literal['formula_unit', 'atom'] = 'formula_unit') → Entry[source]

Normalize the entry’s composition and energy.

Parameters:

mode ("formula_unit" | "atom") – “formula_unit” (the default) normalizes to composition.reduced_formula. “atom” normalizes such that the composition amounts sum to 1.

property reduced_formula: str[source]

The reduced formula of the entry.

class ManualEnergyAdjustment(value: float)[source]

Bases: ConstantEnergyAdjustment

A manual energy adjustment applied to a ComputedEntry.

Parameters:

value (float) – the energy adjustment in eV.

class TemperatureEnergyAdjustment(adj_per_deg: float, temp: float, n_atoms: float, uncertainty_per_deg: float = nan, name: str = '', cls: dict | None = None, description: str = 'Temperature-based energy adjustment')[source]

Bases: EnergyAdjustment

An energy adjustment applied to a ComputedEntry based on the temperature. Used, for example, to add entropy to DFT energies.

Parameters:

• adj_per_deg (float) – energy adjustment to apply per degree K, in eV/atom

• temp (float) – temperature in Kelvin

• n_atoms (float) – number of atoms

• uncertainty_per_deg (float) – uncertainty in energy adjustment to apply per degree K, in eV/atom. (Default: np.nan)

• name (str) – human-readable name of the energy adjustment. (Default: “”)

• cls (dict) – Serialized Compatibility class used to generate the energy adjustment. (Default: None)

• description (str) – human-readable explanation of the energy adjustment.

property explain: str[source]

An explanation of how the energy adjustment is calculated.

normalize(factor: float) → None[source]

Normalize energy adjustment (in place), dividing value/uncertainty by a factor.

Parameters:

factor – factor to divide by.

property uncertainty: float[source]

The value of the energy adjustment in eV.

property value: float[source]

The value of the energy correction in eV.

pymatgen.core.ewald module

This module provides classes for calculating the Ewald sum of a structure.

class EwaldMinimizer(matrix, m_list, num_to_return=1, algo=0)[source]

Bases: object

This class determines the manipulations that will minimize an Ewald matrix, given a list of possible manipulations. This class does not perform the manipulations on a structure, but will return the list of manipulations that should be done on one to produce the minimal structure. It returns the manipulations for the n lowest energy orderings. This class should be used to perform fractional species substitution or fractional species removal to produce a new structure. These manipulations create large numbers of candidate structures, and this class can be used to pick out those with the lowest Ewald sum.

An alternative (possibly more intuitive) interface to this class is the order disordered structure transformation.

Author - Will Richards

Parameters:

• matrix – A matrix of the Ewald sum interaction energies. This is stored in the class as a diagonally symmetric array and so self._matrix will not be the same as the input matrix.

• m_list – list of manipulations. each item is of the form (multiplication fraction, number_of_indices, indices, species) These are sorted such that the first manipulation contains the most permutations. this is actually evaluated last in the recursion since I’m using pop.

• num_to_return – The minimizer will find the number_returned lowest energy structures. This is likely to return a number of duplicate

• algo – Algorithm to use for minimization. structures so it may be necessary to overestimate and then remove the duplicates later. (duplicate checking in this process is extremely expensive).

ALGO_BEST_FIRST = 2[source]

ALGO_COMPLETE = 1[source]

ALGO_FAST = 0[source]

ALGO_TIME_LIMIT = 3[source]

add_m_list(matrix_sum, m_list)[source]

Add an m_list to the output_lists and updates the current minimum if the list is full.

best_case(matrix, m_list, indices_left)[source]

Compute a best case given a matrix and manipulation list.

Parameters:

• matrix – the current matrix (with some permutations already performed)

• m_list – [(multiplication fraction, number_of_indices, indices, species)] describing the manipulation

• indices_left – Set of indices which haven’t had a permutation performed on them.

property best_m_list[source]

The best manipulation list found.

classmethod get_next_index(matrix, manipulation, indices_left)[source]

Get an index that should have the most negative effect on the matrix sum.

minimize_matrix()[source]

Get the permutations that produce the lowest Ewald sum calls recursive function to iterate through permutations.

property minimized_sum[source]

The minimized Ewald sum.

property output_lists[source]

Output lists.

class EwaldSummation(structure, real_space_cut=None, recip_space_cut=None, eta=None, acc_factor=12.0, w=0.7071067811865475, compute_forces=False)[source]

Bases: MSONable

Calculates the electrostatic energy of a periodic array of charges using the Ewald technique.

Ref:

Ewald summation techniques in perspective: a survey Abdulnour Y. Toukmaji and John A. Board Jr. DOI: 10.1016/0010-4655(96)00016-1 URL: http://www.ee.duke.edu/~ayt/ewaldpaper/ewaldpaper.html

This matrix can be used to do fast calculations of Ewald sums after species removal.

E = E_recip + E_real + E_point

Atomic units used in the code, then converted to eV.

Initialize and calculate the Ewald sum. Default convergence parameters have been specified, but you can override them if you wish.

Parameters:

• structure (Structure) – Input structure that must have proper Species on all sites, i.e. Element with oxidation state. Use Structure.add_oxidation_state… for example.

• real_space_cut (float) – Real space cutoff radius dictating how many terms are used in the real space sum. Defaults to None, which means determine automatically using the formula given in gulp 3.1 documentation.

• recip_space_cut (float) – Reciprocal space cutoff radius. Defaults to None, which means determine automatically using the formula given in gulp 3.1 documentation.

• eta (float) – The screening parameter. Defaults to None, which means determine automatically.

• acc_factor (float) – No. of significant figures each sum is converged to.

• w (float) – Weight parameter, w, has been included that represents the relative computational expense of calculating a term in real and reciprocal space. Default of 0.7 reproduces result similar to GULP 4.2. This has little effect on the total energy, but may influence speed of computation in large systems. Note that this parameter is used only when the cutoffs are set to None.

• compute_forces (bool) – Whether to compute forces. False by default since it is usually not needed.

CONV_FACT = 14.399645468667815[source]

as_dict(verbosity: int = 0) → dict[source]

JSON-serialization dict representation of EwaldSummation.

Parameters:

verbosity (int) – Verbosity level. Default of 0 only includes the matrix representation. Set to 1 for more details.

compute_partial_energy(removed_indices)[source]

Get total Ewald energy for certain sites being removed, i.e. zeroed out.

compute_sub_structure(sub_structure, tol: float = 0.001)[source]

Get total Ewald energy for an sub structure in the same lattice. The sub_structure must be a subset of the original structure, with possible different charges.

Parameters:

• sub_structure (Structure) – Substructure to compute Ewald sum for.

• tol (float) – Tolerance for site matching in fractional coordinates.

Returns:

Ewald sum of substructure.

property eta[source]

Eta value used in Ewald summation.

property forces[source]

The forces on each site as a Nx3 matrix. Each row corresponds to a site.

classmethod from_dict(dct: dict[str, Any], fmt: str | None = None, **kwargs) → Self[source]

Create an EwaldSummation instance from JSON-serialized dictionary.

Parameters:

• dct (dict) – Dictionary representation

• fmt (str, optional) – Unused. Defaults to None.

• **kwargs – Additional keyword arguments.

Returns:

class instance

Return type:

EwaldSummation

get_site_energy(site_index)[source]

Compute the energy for a single site in the structure.

Parameters:

site_index (int) – Index of site

Returns:

Energy of that site

Return type:

float

property point_energy[source]

The point energy.

property point_energy_matrix[source]

The point space matrix. A diagonal matrix with the point terms for each site in the diagonal elements.

property real_space_energy[source]

The real space energy.

property real_space_energy_matrix[source]

The real space energy matrix. Each matrix element (i, j) corresponds to the interaction energy between site i and site j in real space.

property reciprocal_space_energy[source]

The reciprocal space energy.

property reciprocal_space_energy_matrix[source]

The reciprocal space energy matrix. Each matrix element (i, j) corresponds to the interaction energy between site i and site j in reciprocal space.

property total_energy[source]

The total energy.

property total_energy_matrix[source]

The total energy matrix. Each matrix element (i, j) corresponds to the total interaction energy between site i and site j.

Note that this does not include the charged-cell energy, which is only important when the simulation cell is not charge balanced.