index | modules | gitlab | page source

# Chemical formula type

Warning

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

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

  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]

    Return dictionary mapping chemical symbol to number of atoms.

    Example

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

  `reduce`() → Tuple[ase.formula.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[ase.formula.Formula, ase.formula.Formula, int]

    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

    Format formula as string.

    Formats:

    - `'hill'`: alphabetically ordered with C and H first
    - `'metal'`: alphabetically ordered with metals first
    - `'abc'`: count ordered first then alphabetically ordered
    - `'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'`, `'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

    Convert dict to Formula.

  `from_list`()

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

    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

    Equality check.

    Note that order is not important.

    Example

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

  `__add__`(other: Union[str, Formula]) → ase.formula.Formula

    Add two formulas.

  `__mul__`(N: int) → ase.formula.Formula

    Repeat formula \(N\) times.

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

Documentation v: 3.19.0

Versions
  3.20.0b1 (development)
  3.19.0 (latest stable)