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 builtin Python dict(). Also extended to allow simple string init.
Parameters:  form supported by the Python builtin 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=1e08)[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
= 1e08¶ 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
¶

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

is_element
¶ True if composition is for an element.

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

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
¶