Chemical formula type

The Formula type collects all formula manipulation functionality in one place (see examples below).

The following string formats are supported:

hill

metal

abc

reduce

ab2

a2b

periodic

latex

html

rest

H2O

H2O

OH2

H2O

OH2

H2O

OH2

H$_{2}$O

H<sub>2</sub>O

H2O

CSi

CSi

CSi

SiC

CSi

CSi

SiC

SiC

SiC

SiC

MoS2

MoS2

MoS2

MoS2

MoS2

S2Mo

MoS2

MoS$_{2}$

MoS<sub>2</sub>

MoS2

AB2

AB2

AB2

AB2

AB2

B2A

AB2

AB$_{2}$

AB<sub>2</sub>

AB2

BN

BN

BN

BN

BN

BN

BN

BN

BN

BN

O2Si

O2Si

SiO2

SiO2

SiO2

O2Si

SiO2

SiO$_{2}$

SiO<sub>2</sub>

SiO2

class ase.formula.Formula(formula: str | Formula = '', *, strict: bool = False, format: str = '', _tree: str | Tuple[str | Tuple[Tree, int] | List[Tree], int] | List[str | Tuple[Tree, int] | List[Tree]] = None, _count: Dict[str, int] = None)[source]

Chemical formula object.

Parameters:
  • formula (str) – Text string representation of formula. Examples: '6CO2', '30Cu+2CO', 'Pt(CO)6'.

  • strict (bool) – Only allow real chemical symbols.

  • format (str) – Reorder according to format. Must be one of hill, metal, ab2, a2b, periodic or reduce.

Examples

>>> from ase.formula import Formula
>>> w = Formula('H2O')
>>> w.count()
{'H': 2, 'O': 1}
>>> 'H' in w
True
>>> w == 'HOH'
True
>>> f'{w:latex}'
'H$_{2}$O'
>>> w.format('latex')
'H$_{2}$O'
>>> divmod(6 * w + 'Cu', w)
(6, Formula('Cu'))
Raises:

ValueError – on malformed formula

convert(fmt: str) Formula[source]

Reformat this formula as a new Formula.

Same formatting rules as Formula(format=…) keyword.

count() Dict[str, int][source]

Return dictionary mapping chemical symbol to number of atoms.

Example

>>> Formula('H2O').count()
{'H': 2, 'O': 1}
reduce() Tuple[Formula, int][source]

Reduce formula.

Returns:

  • formula (Formula) – Reduced formula.

  • n (int) – Number of reduced formula units.

Example

>>> Formula('2H2O').reduce()
(Formula('H2O'), 2)
stoichiometry() Tuple[Formula, Formula, int][source]

Reduce to unique stoichiometry using “chemical symbols” A, B, C, …

Examples

>>> Formula('CO2').stoichiometry()
(Formula('AB2'), Formula('CO2'), 1)
>>> Formula('(H2O)4').stoichiometry()
(Formula('AB2'), Formula('OH2'), 4)
format(fmt: str = '') str[source]

Format formula as string.

Formats:

  • 'hill': alphabetically ordered with C and H first

  • 'metal': alphabetically ordered with metals first

  • 'ab2': count-ordered first then alphabetically ordered

  • 'abc': old name for 'ab2'

  • 'a2b': reverse count-ordered first then alphabetically ordered

  • 'periodic': periodic-table ordered: period first then group

  • 'reduce': Reduce and keep order (ABBBC -> AB3C)

  • 'latex': LaTeX representation

  • 'html': HTML representation

  • 'rest': reStructuredText representation

Example

>>> Formula('H2O').format('html')
'H<sub>2</sub>O'
__format__(fmt: str) str[source]

Format Formula as str.

Possible formats: 'hill', 'metal', 'abc', 'reduce', 'latex', 'html', 'rest'.

Example

>>> f = Formula('OH2')
>>> '{f}, {f:hill}, {f:latex}'.format(f=f)
'OH2, H2O, OH$_{2}$'
static from_dict(dct: Dict[str, int]) Formula[source]

Convert dict to Formula.

>>> Formula.from_dict({'H': 2})
Formula('H2')
static from_list(symbols: Sequence[str]) Formula[source]

Convert list of chemical symbols to Formula.

__len__() int[source]

Number of atoms.

__getitem__(symb: str) int[source]

Number of atoms with chemical symbol symb.

__contains__(f: str | Formula) bool[source]

Check if formula contains chemical symbols in f.

Type of f must be str or Formula.

Examples

>>> 'OH' in Formula('H2O')
True
>>> 'O2' in Formula('H2O')
False
__eq__(other) bool[source]

Equality check.

Note that order is not important.

Example

>>> Formula('CO') == Formula('OC')
True
__add__(other: str | Formula) Formula[source]

Add two formulas.

__mul__(N: int) Formula[source]

Repeat formula \(N\) times.

__divmod__(other: Formula | str) Tuple[int, Formula][source]

Return the tuple (self // other, self % other).

Invariant:

div, mod = divmod(self, other)
div * other + mod == self

Example

>>> divmod(Formula('H2O'), 'H')
(2, Formula('O'))