# Chemical formula operations

## `periodictable.formulas`

Chemical formula parser.

class `periodictable.formulas.``Formula`(structure=(), density=None, natural_density=None, name=None)

  Bases: `object`

  Simple chemical formula representation.

  `change_table`(table)

    Replace the table used for the components of the formula.

  `natural_mass_ratio`()

    Natural mass to isotope mass ratio.

    Returns: | ratio : float

    The ratio is computed from the sum of the masses of the individual elements using natural abundance divided by the sum of the masses of the isotopes used in the formula. If the cell volume is preserved with isotope substitution, then the ratio of the masses will be the ratio of the densities.

  `neutron_sld`(*args, **kw)

    Neutron scattering information for the molecule.

    Parameters:

    wavelength : float | Å

      Wavelength of the neutron beam.

    Returns:

    sld : (float, float, float) | 10-6Å-2

      Neutron scattering length density is returned as the tuple (real, imaginary, incoherent), or as (None, None, None) if the mass density is not known.

    Deprecated since version 0.95: Use periodictable.neutron_sld(formula) instead.

  `volume`(packing_factor='hcp', *args, **kw)

    Estimate unit cell volume.

    The crystal volume can be estimated from the element covalent radius and the atomic packing factor using:

        packing_factor = N_atoms V_atom / V_crystal

    Packing factors for a number of crystal lattice structures are defined.

    Crystal lattice names and packing factors
    Code | Description | Formula | Packing factor
    --- | --- | --- | ---
    cubic | simple cubic | \(\pi/6\) | 0.52360
    bcc | body-centered cubic | \(\pi\sqrt{3/8}\) | 0.68017
    hcp | hexagonal close-packed | \(\pi/\sqrt{18}\) | 0.74048
    fcc | face-centered cubic | \(\pi/\sqrt{18}\) | 0.74048
    diamond | diamond cubic | \(\pi\sqrt{3/16}\) | 0.34009

    Parameters:

    packing_factor = ‘hcp’ : float or string

      Atomic packing factor. If packing_factor is the name of a crystal lattice, use the lattice packing factor.

    a, b, c : float | Å

      Lattice spacings. b and c default to a.

    alpha, beta, gamma : float | °

      Lattice angles. These default to 90°

    Returns:

    volume : float | cm3

      Molecular volume.

    Raises: | KeyError : unknown lattice type TypeError : missing or bad lattice parameters

    Using the cell volume, mass density can be set with:

        formula.density = n*formula.molecular_mass/formula.volume()

    where n is the number of molecules per unit cell.

  `xray_sld`(*args, **kw)

    X-ray scattering length density for the molecule.

    Parameters:

    energy : float | keV

      Energy of atom.

    wavelength : float | Å

      Wavelength of atom.

    Returns:

    sld : (float, float) | 10-6Å-2
      X-ray scattering length density is returned as the tuple

        (real, imaginary), or as (None, None) if the mass density is not known.

    Deprecated since version 0.95: Use periodictable.xray_sld(formula) instead.

  `atoms`

    { atom: count, … }

    Composition of the molecule. Referencing this attribute computes the count as the total number of each element or isotope in the chemical formula, summed across all subgroups.

  `charge`

    Net charge of the molecule.

  `hill`

    Formula

    Convert the formula to a formula in Hill notation. Carbon appears first followed by hydrogen then the remaining elements in alphabetical order.

  `mass`

    atomic mass units u (C[12] = 12 u)

    Molar mass of the molecule. Use molecular_mass to get the mass in grams.

  `mass_fraction`

    Fractional mass representation of each element/isotope/ion.

  `molecular_mass`

    g

    Mass of the molecule in grams.

  `natural_density`

    g·cm-3

    Density of the formula with specific isotopes of each element replaced by the naturally occurring abundance of the element without changing the cell volume.

`periodictable.formulas.``formula`(compound=None, density=None, natural_density=None, name=None, table=None)

  Construct a chemical formula representation from a string, a dictionary of atoms or another formula.

  Parameters:

  compound : Formula initializer

    Chemical formula.

  density : float | g·cm-3

    Material density. Not needed for single element formulas.

  natural_density : float | g·cm-3

    Material density assuming naturally occurring isotopes and no change in cell volume.

  name : string

    Common name for the molecule.

  table : PeriodicTable

    Private table to use when parsing string formulas.

  Exceptions: | ValueError : invalid formula initializer

  After creating a formula, a rough estimate of the density can be computed using:

  > formula.density = formula.molecular_mass/formula.volume(packing_factor=…)

  The volume() calculation uses the covalent radii of the components and the known packing factor or crystal structure name. If the lattice constants for the crystal are known, then they can be used instead:

  > formula.density = formula.molecular_mass/formula.volume(a, b, c, alpha, beta, gamma)

  Formulas are designed for calculating quantities such as molar mass and scattering length density, not for representing bonds or atom positions. The representations are simple, but preserve some of the structure for display purposes.

`periodictable.formulas.``formula_grammar`(table)

  Construct a parser for molecular formulas.

  Parameters:

  table = None : PeriodicTable

    If table is specified, then elements and their associated fields will be chosen from that periodic table rather than the default.

  Returns:

  parser : pyparsing.ParserElement.

    The `parser.parseString()` method returns a list of pairs (count, fragment), where fragment is an isotope, an element or a list of pairs (count, fragment).

`periodictable.formulas.``mix_by_volume`(*args, **kw)

  Generate a mixture which apportions each formula by volume.

  Parameters:

  formula1 : Formula OR string

    Material

  quantity1 : float

    Relative quantity of that material

  formula2 : Formula OR string

    Material

  quantity2 : float

    Relative quantity of that material

  …

  density : float

    Density of the mixture, if known

  natural_density : float

    Density of the mixture with natural abundances, if known.

  name : string

    Name of the mixture

  table : PeriodicTable

    Private table to use when parsing string formulas.

  Returns: | formula : Formula

  If density is not given, then it will be computed from the density of the components, assuming the components take up no more nor less space because they are in the mixture. If component densities are not available, then a ValueError is raised. The density calculation assumes the cell volume remains constant for the original materials, which is not in general the case.

`periodictable.formulas.``mix_by_weight`(*args, **kw)

  Generate a mixture which apportions each formula by weight.

  Parameters:

  formula1 : Formula OR string

    Material

  quantity1 : float

    Relative quantity of that material

  formula2 : Formula OR string

    Material

  quantity2 : float

    Relative quantity of that material

  …

  density : float

    Density of the mixture, if known

  natural_density : float

    Density of the mixture with natural abundances, if known.

  name : string

    Name of the mixture

  table : PeriodicTable

    Private table to use when parsing string formulas.

  Returns: | formula : Formula

  If density is not given, then it will be computed from the density of the components, assuming the components take up no more nor less space because they are in the mixture. If component densities are not available, then the resulting density will not be computed. The density calculation assumes the cell volume remains constant for the original materials, which is not in general the case.

`periodictable.formulas.``parse_formula`(formula_str, table=None)

  Parse a chemical formula, returning a structure with elements from the given periodic table.