\(\renewcommand\AA{\text{Å}}\)

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(wavelength=None, energy=None)

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.

replace(source, target, portion=1)

Create a new formula with one atom/isotope substituted for another.

formula is the formula being updated.

source is the isotope/element to be substituted.

target is the replacement isotope/element.

portion is the proportion of source which is substituted for target.

volume(*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.

Note: a single non-keyword argument is interpreted as a packing factor rather than a lattice spacing of ‘a’.

xray_sld(energy=None, wavelength=None)

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.