pymatgen.core.composition module

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

Bases: dict, monty.json.MSONable

Class to 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:**kwargs (*args,) –

any valid dict init arguments

get_energy(composition, strict=True)[source]

Calculates the energy of a composition.

Parameters:
  • composition (Composition) – input composition
  • strict (bool) – Whether all potentials must be specified
class Composition(*args, **kwargs)[source]

Bases: collections.abc.Hashable, collections.abc.Mapping, monty.json.MSONable

Represents a Composition, which is essentially a {element:amount} mapping type. Composition is written to be immutable and hashable, unlike a standard Python dict.

Note that the key can be either an Element or a Specie. Elements and Specie are treated differently. i.e., a Fe2+ is not the same as a Fe3+ Specie and would be put in separate keys. This differentiation is deliberate to support using Composition to determine the fraction of a particular Specie.

Works almost completely like a standard python dictionary, except that __getitem__ is overridden to return 0 when an element is not found. (somewhat like a defaultdict, except it is immutable).

Also adds more convenience methods relevant to compositions, e.g., get_fraction.

It should also be noted that many Composition related functionality takes in a standard string as a convenient input. For example, even though the internal representation of a Fe2O3 composition is {Element(“Fe”): 2, Element(“O”): 3}, you can obtain the amount of Fe simply by comp[“Fe”] instead of the more verbose comp[Element(“Fe”)].

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

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

Parameters:
  • form supported by the Python built-in dict() function. (Any) –
  • A dict of either {Element/Specie (1.) –

    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.

  • Keyword arg initialization, similar to a dict, e.g., (2.) – Composition(Li = 2, O = 1)
  • addition, the Composition constructor also allows a single (In) –
  • as an input formula. E.g., Composition (string) –
  • allow_negative – Whether to allow negative compositions. This argument must be popped from the **kwargs due to *args ambiguity.
almost_equals(other, rtol=0.1, atol=1e-08)[source]

Returns true if compositions are equal within a tolerance.

Parameters:
  • other (Composition) – Other composition to check
  • rtol (float) – Relative tolerance
  • atol (float) – Absolute tolerance
alphabetical_formula

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

amount_tolerance = 1e-08

Special formula handling for peroxides and certain elements. This is so that formula output does not write LiO instead of Li2O2 for example.

anonymized_formula

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_dict()[source]
Returns:dict with species symbol and (unreduced) amount e.g., {“Fe”: 4.0, “O”:6.0} or {“Fe3+”: 4.0, “O2-“:6.0}
average_electroneg
copy()[source]
element_composition

Returns the composition replacing any species by the corresponding element.

elements

Returns view of elements in Composition.

formula

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

fractional_composition

Returns the normalized composition which the number of species sum to 1.

Returns:Normalized composition which the number of species sum to 1.
classmethod from_dict(d)[source]

Creates 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:d (dict) – {symbol: amount} dict.
get_atomic_fraction(el)[source]

Calculate atomic fraction of an Element or Specie.

Parameters:el (Element/Specie) – Element or Specie to get fraction for.
Returns:Atomic fraction for element el in Composition
get_el_amt_dict()[source]
Returns:Dict with element symbol and (unreduced) amount e.g., {“Fe”: 4.0, “O”:6.0} or {“Fe3+”: 4.0, “O2-“:6.0}
get_integer_formula_and_factor(max_denominator=10000)[source]

Calculates 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
Returns:A pretty 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()[source]

Calculates a reduced composition and factor.

Returns:A normalized composition and a multiplicative factor, i.e., Li4Fe4P4O16 returns (Composition(“LiFePO4”), 4).
get_reduced_formula_and_factor()[source]

Calculates a reduced formula and factor.

Returns:A pretty normalized formula and a multiplicative factor, i.e., Li4Fe4P4O16 returns (LiFePO4, 4).
get_wt_fraction(el)[source]

Calculate weight fraction of an Element or Specie.

Parameters:el (Element/Specie) – Element or Specie to get fraction for.
Returns:Weight fraction for element el in Composition
hill_formula
is_element

True if composition is for an element.

num_atoms

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

oxi_prob = None
oxi_state_guesses(oxi_states_override=None, target_charge=0, all_oxi_states=False, max_sites=None)[source]

Checks 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, an element defaults to all oxidation states in pymatgen Element.icsd_oxidation_states. Otherwise, default is Element.common_oxidation_states. Note that the full oxidation state list is very inclusive and can produce nonsensical results.
  • max_sites (int) – if possible, will reduce Compositions to at most this many many sites to speed up oxidation state guesses. Set to -1 to just reduce fully.
Returns:

A list of dicts - 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.

static ranked_compositions_from_indeterminate_formula(fuzzy_formula, lock_if_strict=True)[source]

Takes in a formula where capitilization 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

reduced_composition

Returns the reduced composition,i.e. amounts normalized by greatest common denominator. e.g., Composition(“FePO4”) for Composition(“Fe4P4O16”).

reduced_formula

Returns a pretty normalized formula, i.e., LiFePO4 instead of Li4Fe4P4O16.

special_formulas = {'LiO': 'Li2O2', 'NaO': 'Na2O2', 'KO': 'K2O2', 'HO': 'H2O2', 'CsO': 'Cs2O2', 'RbO': 'Rb2O2', 'O': 'O2', 'N': 'N2', 'F': 'F2', 'Cl': 'Cl2', 'H': 'H2'}
to_data_dict

Returns – A dict with many keys and values relating to Composition/Formula, including reduced_cell_composition, unit_cell_composition, reduced_cell_formula, elements and nelements.

to_reduced_dict

Returns – Dict with element symbol and reduced amount e.g., {“Fe”: 2.0, “O”:3.0}

weight
exception CompositionError[source]

Bases: Exception

Exception class for composition errors

reduce_formula(sym_amt)[source]

Helper method to reduce a sym_amt dict to a reduced formula and factor.

Parameters:sym_amt (dict) – {symbol: amount}.
Returns:(reduced_formula, factor).