Chemical formula type

Warning

This module is preliminary! API may change or disappear in the future.

class ase.formula.Formula(formula: str = '', _tree: Union[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'.

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

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

Return dictionary mapping chemical symbol to number of atoms.

Example

>>> Formula('H2O').count()
{'H': 2, 'O': 1}
reduce() → Tuple[ase.formula.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[ase.formula.Formula, ase.formula.Formula, int][source]

Reduce to unique stoichiomerty 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

  • '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', '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]) → ase.formula.Formula[source]

Convert dict to Formula.

from_list()[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: Union[str, Formula]) → bool[source]

Check if formula contains chemical symbols in f.

Type of f must be str or Formula.

Example

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

Equality check.

Note that order is not important.

Example

>>> Formula('CO') == Formula('OC')
True
__add__(other: Union[str, Formula]) → ase.formula.Formula[source]

Add two formulas.

__mul__(N: int) → ase.formula.Formula[source]

Repeat formula \(N\) times.

__divmod__(other: Union[Formula, str]) → Tuple[int, ase.formula.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'))