pymatgen.core.ion module

Module containing class to create an ion

class Ion(composition, charge=0.0, properties=None)[source]

Bases: Composition, MSONable, Stringify

Ion object. Just a Composition object with an additional variable to store charge.

The net charge can either be represented as Mn++, Mn+2, Mn[2+], Mn[++], or Mn[+2]. Note the order of the sign and magnitude in each representation.

Flexible Ion construction, similar to Composition. For more information, please see pymatgen.core.Composition

property alphabetical_formula: str[source]

Returns a formula string, with elements sorted by alphabetically and appended charge

property anonymized_formula: str[source]

An anonymized formula. Appends charge to the end of anonymized composition

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

dict with composition, as well as charge

property charge: float[source]

Charge of the ion

property composition: Composition[source]

Composition of ion.

property formula: str[source]

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

classmethod from_dict(d) Ion[source]

Generates an ion object from a dict created by as_dict().


d – {symbol: amount} dict.

classmethod from_formula(formula: str) Ion[source]

Creates Ion from formula. The net charge can either be represented as Mn++, Mn+2, Mn[2+], Mn[++], or Mn[+2]. Note the order of the sign and magnitude in each representation.

Also note that (aq) can be included in the formula, e.g. “NaOH (aq)”.





get_reduced_formula_and_factor(iupac_ordering: bool = False, hydrates: bool = True) tuple[str, float][source]

Calculates a reduced formula and factor.

Similar to Composition.get_reduced_formula_and_factor except that O-H formulas receive special handling to differentiate between hydrogen peroxide and OH-. Formulas containing HO are written with oxygen first (e.g. ‘Fe(OH)2’ rather than ‘Fe(HO)2’), and special formulas that apply to solids (e.g. Li2O2 instead of LiO) are not used.

Note that the formula returned by this method does not contain a charge. To include charge, use formula or reduced_formula instead.

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

  • hydrates – If True (default), attempt to recognize hydrated metal complexes and separate out the H2O in the reduced formula. For example, Zr(OH)4 becomes ZrO2.2H2O. Applies only to Ions containing metals.


A pretty normalized formula and a multiplicative factor, i.e., H4O4 returns (‘H2O2’, 2.0).

oxi_state_guesses(oxi_states_override: Optional[dict] = None, all_oxi_states: bool = False, max_sites: Optional[int] = None) list[dict[str, float]][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.

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

  • 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 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).


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.

property reduced_formula: str[source]

Returns a reduced formula string with appended charge. The charge is placed in brackets with the sign preceding the magnitude, e.g., ‘Ca[+2]’.

to_pretty_string() str[source]

Pretty string with proper superscripts.

property to_reduced_dict: dict[source]

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