index | modules | gitlab | page source

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