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)

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

Reformat this formula as a new Formula.

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

count() → Dict[str, int]

Return dictionary mapping chemical symbol to number of atoms.

Example

>>> Formula('H2O').count()
{'H': 2, 'O': 1}

reduce() → Tuple[Formula, int]

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]

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

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

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

Convert dict to Formula.

>>> Formula.from_dict({'H': 2})
Formula('H2')

static from_list(symbols: Sequence[str]) → Formula

Convert list of chemical symbols to Formula.

__len__() → int

Number of atoms.

__getitem__(symb: str) → int

Number of atoms with chemical symbol symb.

__contains__(f: str | Formula) → bool

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

Equality check.

Note that order is not important.

Example

>>> Formula('CO') == Formula('OC')
True

__add__(other: str | Formula) → Formula

Add two formulas.

__mul__(N: int) → Formula

Repeat formula \(N\) times.

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

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