`chemistry_tools.formulae`¶

Table of Contents

chemistry_tools.formulae
- composition
- compound
- dataarray
- formula
- html
- iso_dist
- latex
- parser
- species
- unicode
- utils

Note

This module has the following additional requirements:

mathematical>=0.1.7
pandas>=1.0.1
pyparsing>=2.2.0
tabulate>=0.8.3
cawdrey>=0.1.2
quantities>=0.12.4

These can be installed as follows:

$ python -m pip install chemistry_tools[formulae]

Parse formulae into a Python object

class chemistry_tools.formulae.Compound(name, formula=None, data=None, latex_name=None, unicode_name=None, html_name=None)[source]¶

Class representing a chemical compound.

name : str latex_name : str unicode_name : str html_name : str formula: Formula

The chemical formula of the compound. If none this is generated from the name

data : dict: Free form dictionary. Could be simple such as {'mp': 0, 'bp': 100} or considerably more involved, e.g.: {'diffusion_coefficient': { 'water': lambda T: 2.1*m**2/s/K*(T - 273.15*K)}}.

mass: The mass of the compound
formula:: The Formula object representing the compound
data: Free form dictionary of additional properties.

charge¶: Convenience property for accessing charge of the formula

mass¶: Convenience property for accessing the mass of the formula

molar_mass()[source]¶

Returns the molar mass (with units) of the substance

>>> nh4p = Compound.from_formula('NH4+')
>>> from chemistry_tools.units import quantities
>>> nh4p.molar_mass(quantities)
array(18.0384511...) * g/mol

class chemistry_tools.formulae.Formula(composition=None, charge=0)[source]¶

A Formula object stores a chemical composition of a compound. It is based on dict, with the symbols of chemical elements as keys and the values equal to the number of atoms of the corresponding element in the compound.

average_mass¶

Calculate the average mass of a Formula.

Note that mass is not averaged for elements with specified isotopes.

Returns:	mass
Return type:	float

average_mz¶

composition¶

Returns a Composition object representing the elemental composition of the Formula

Returns:
Return type:

copy() → a shallow copy of D.[source]¶

elements¶: Returns a list of the element symbols in the formula.

empirical_formula¶

Returns the empirical formula in Hill notation.

The empirical formula has the simplest whole number ratio of atoms of each element present in formula.

>>> Formula.from_string('H2O').empirical
'H2O'
>>> Formula.from_string('S4').empirical
'S'
>>> Formula.from_string('C6H12O6').empirical
'CH2O'

Return type:	str

exact_mass¶

Calculate the monoisotopic mass of a Formula. If any isotopes are already present in the formula, the mass of these will be preserved

Returns:	mass
Return type:	float

classmethod from_kwargs(*, charge=0, **kwargs)[source]¶

Create a new Formula object from keyword arguments representing the elements in the compound

Parameters:	charge (int, optional) –
Return type:	`Formula`

classmethod from_mass_fractions(fractions, charge=0, maxcount=10, precision=0.0001)[source]¶

Create a new Formula object from elemental mass fractions by parsing a string

Note

Isotopes cannot (currently) be parsed using this method

Parameters:	fractions (dict) – A dictionary of elements and mass fractions charge (int, optional) –
Return type:	`Formula`

>>> Formula.from_mass_fractions({'H': 0.112, 'O': 0.888})
'H2O'
>>> Formula.from_mass_fractions({'D': 0.2, 'O': 0.8})
'O[2H]2'
>>> Formula.from_mass_fractions({'H': 8.97, 'C': 59.39, 'O': 31.64})
'C5H9O2'
>>> Formula.from_mass_fractions({'O': 0.26, '30Si': 0.74})
'O2[30Si]3'

classmethod from_string(formula, charge=0)[source]¶

Create a new Formula object by parsing a string

Note

Isotopes cannot (currently) be parsed using this method

Parameters:	formula – A string with a chemical formula charge (int, optional) –
Return type:	`Formula`

# TODO: should throw error for unrecognised elements CGCGAATTCGCG

get_mz(average=True, charge=None)[source]¶

Calculate the average mass:charge ratio (m/z) of a Formula.

Parameters:	average – If `True` then the average m/z is calculated. Note that mass is not averaged for elements with specified isotopes. Default is `True`. charge – The charge of the compound. If `None` then the existing charge of the Formula is used
Type:	average: bool, optional
Type:	charge: int, optional
Returns:	mass
Return type:	float

hill_formula¶

Returns formula in Hill notation

>>> Formula.from_string('BrC2H5').hill_formula
'C2H5Br'
>>> Formula.from_string('HBr').hill_formula
'BrH'
>>> Formula.from_string('[(CH3)3Si2]2NNa').hill_formula
'C6H18NNaSi4'

Return type:	str

isotope_distribution()[source]¶

Returns a IsotopeDistribution object representing the distribution of the isotopologues of the formula

Return type:	`IsotopeDistribution`

isotopic_composition_abundance¶

Calculate the relative abundance of the current isotopic composition of this molecule.

Returns:	The relative abundance of the current isotopic composition.
Return type:	float

iter_isotopologues(report_abundance=False, elements_with_isotopes=None, isotope_threshold=0.0005, overall_threshold=0)[source]¶

Iterate over possible isotopic states of the molecule.

The space of possible isotopic compositions is restrained by parameters elements_with_isotopes, isotope_threshold, overall_threshold.

Parameters:	report_abundance – If `True`, the output will contain 2-tuples: (composition, abundance). Otherwise, only compositions are yielded. Default is `False`. elements_with_isotopes – A set of elements to be considered in isotopic distribution (by default, every element has an isotopic distribution). isotope_threshold – The threshold abundance of a specific isotope to be considered. Default is `5e-4`. overall_threshold – The threshold abundance of the calculated isotopic composition. Default is `0`.
Type:	report_abundance: bool, optional
Type:	elements_with_isotopes: container of str, optional
Type:	isotope_threshold: float, optional
Type:	overall_threshold: float, optional
Returns:	Iterator over possible isotopic compositions.
Return type:	iterator

mass¶

Calculate the average mass of a Formula.

Note that mass is not averaged for elements with specified isotopes.

Returns:	mass
Return type:	float

monoisotopic_mass¶

Calculate the monoisotopic mass of a Formula. If any isotopes are already present in the formula, the mass of these will be preserved

Returns:	mass
Return type:	float

most_probable_isotopic_composition(elements_with_isotopes=None)[source]¶

Calculate the most probable isotopic composition of a molecule/ion.

For each element, only two most abundant isotopes are considered. Any isotopes already in the Formula will be changed to the most abundant isotope

Parameters:	elements_with_isotopes – A set of elements to be considered in isotopic distribution (by default, every element has an isotopic distribution).
Type:	elements_with_isotopes: container of str, optional
Returns:	A tuple with the most probable isotopic composition and its relative abundance.
Return type:	(Formula, float)

mz¶

n_atoms¶

Return the number of atoms in the formula.

>>> Formula.from_string('CH3COOH').n_atoms
8

n_elements¶

Return the number of elements in the formula.

>>> Formula.from_string('CH3COOH').n_elements
3

no_isotope_hill_formula¶

Returns formula in Hill notation, without any isotopes specified

>>> Formula.from_string('BrC2H5').no_isotope_hill_formula
'C2H5Br'
>>> Formula.from_string('HBr').no_isotope_hill_formula
'BrH'
>>> Formula.from_string('[(CH3)3Si2]2NNa').no_isotope_hill_formula
'C6H18NNaSi4'

Return type:	str

nominal_mass¶

Calculate the monoisotopic mass of a Formula. If any isotopes are already present in the formula, the mass of these will be preserved

Returns:	mass
Return type:	float

class chemistry_tools.formulae.Species(composition=None, charge=0, phase=None)[source]¶

Formula with phase information (e.g. solid, liquid, gas, or aqueous)

Species extends Formula with the new attribute phase

phase: Either “s”, “l”, “g”, or “aq”. None represents an unknown phase.

copy() → a shallow copy of D.[source]¶

empirical_formula¶

Returns:
Return type:	str

classmethod from_kwargs(*, charge=0, phase=None, **kwargs)[source]¶

Create a new Species object from keyword arguments representing the elements in the compound

Parameters:	charge (int, optional) –
Return type:	`Formula`

classmethod from_string(formula, phase=None, charge=0)[source]¶

Create a new Species object by parsing a string

Analogous to Formula.from_string() but with the addition that the phase is determined from the formula.

formula: str: e.g. ‘H2O’, ‘NaCl(s)’, ‘CO2(aq)’, ‘CO2(g)’

phase: Either “s”, “l”, “g”, or “aq”. None represents an unknown phase.

>>> water = Species.from_string('H2O')
>>> water.phase
None
>>> NaCl = Species.from_string('NaCl(s)')
>>> NaCl.phase
s
>>> Hg_l = Species.from_string('Hg(l)')
>>> Hg_l.phase
l
>>> CO2g = Species.from_string('CO2(g)')
>>> CO2g.phase
g
>>> CO2aq = Species.from_string('CO2(aq)')
>>> CO2aq.phase
aq

hill_formula¶

Returns:
Return type:	str

class chemistry_tools.formulae.IsoDistSort[source]¶

Lookup for sorting isotope distribution output

Abundance = 2¶

Formula = 0¶

Mass = 1¶

Relative_Abundance = 3¶

Relative_abundance = 3¶

abundance = 2¶

formula = 0¶

mass = 1¶

relative_abundance = 3¶

class chemistry_tools.formulae.IsotopeDistribution(formula)[source]¶

Each composition can be accessed with their hill formulae like a dictionary (e.g. iso_dict[“H[1]2O[16]”]

as_array(sort_by=<IsoDistSort.formula: 0>, reverse=False, format_percentage=True)[source]¶

Returns the isotope distribution data as a list of lists

Parameters:	sort_by (IsoDistSort) – The column to sort by.
Param:	Whether the isotopologues should be sorted in reverse order. Default `False`.
Param:	Whether the abundances should be formatted as percentages or not. Default `False`.
Return type:	list[list]

chemistry_tools.formulae.string_to_html(formula, prefixes=None, infixes=None, **kwargs)[source]¶

Convert formula string to html string representation

formula : str: Chemical formula, e.g. ‘H2O’, ‘Fe+3’, ‘Cl-‘
prefixes : dict: Prefix transformations, default: greek letters and .
infixes : dict: Infix transformations, default: .
suffixes : tuple of strings: Suffixes to keep, e.g. (‘(g)’, ‘(s)’)

>>> string_to_html('NH4+')
'NH<sub>4</sub><sup>+</sup>'
>>> string_to_html('Fe(CN)6+2')
'Fe(CN)<sub>6</sub><sup>2+</sup>'
>>> string_to_html('Fe(CN)6+2(aq)')
'Fe(CN)<sub>6</sub><sup>2+</sup>(aq)'
>>> string_to_html('.NHO-(aq)')
'&sdot;NHO<sup>-</sup>(aq)'
>>> string_to_html('alpha-FeOOH(s)')
'&alpha;-FeOOH(s)'

chemistry_tools.formulae.string_to_latex(formula, prefixes=None, infixes=None, **kwargs)[source]¶

Convert formula string to latex representation

formula: str: Chemical formula, e.g. ‘H2O’, ‘Fe+3’, ‘Cl-‘
prefixes: dict: Prefix transofmrations, default: greek letters and .
infixes: dict: Infix transformations, default: .
suffixes: iterable of str: What suffixes not to interpret, default: (s), (l), (g), (aq)

>>> string_to_latex('NH4+')
'NH_{4}^{+}'
>>> string_to_latex('Fe(CN)6+2')
'Fe(CN)_{6}^{2+}'
>>> string_to_latex('Fe(CN)6+2(aq)')
'Fe(CN)_{6}^{2+}(aq)'
>>> string_to_latex('.NHO-(aq)')
'^\\bullet NHO^{-}(aq)'
>>> string_to_latex('alpha-FeOOH(s)')
'\\alpha-FeOOH(s)'

chemistry_tools.formulae.string_to_unicode(formula, prefixes=None, infixes=None, **kwargs)[source]¶

Convert formula string to unicode string representation

formula : str: Chemical formula, e.g. ‘H2O’, ‘Fe+3’, ‘Cl-‘
prefixes : dict: Prefix transofmrations, default: greek letters and .
infixes : dict: Infix transofmrations, default: .
suffixes : tuple of strings: Suffixes to keep, e.g. (‘(g)’, ‘(s)’)

>>> string_to_unicode('NH4+') == u'NH₄⁺'
True
>>> string_to_unicode('Fe(CN)6+2') == u'Fe(CN)₆²⁺'
True
>>> string_to_unicode('Fe(CN)6+2(aq)') == u'Fe(CN)₆²⁺(aq)'
True
>>> string_to_unicode('.NHO-(aq)') == u'⋅NHO⁻(aq)'
True
>>> string_to_unicode('alpha-FeOOH(s)') == u'α-FeOOH(s)'
True

`composition`¶

`compound`¶

Parse formulae into a Python object

class chemistry_tools.formulae.compound.Compound(name, formula=None, data=None, latex_name=None, unicode_name=None, html_name=None)[source]¶

Class representing a chemical compound.

name : str latex_name : str unicode_name : str html_name : str formula: Formula

The chemical formula of the compound. If none this is generated from the name

data : dict: Free form dictionary. Could be simple such as {'mp': 0, 'bp': 100} or considerably more involved, e.g.: {'diffusion_coefficient': { 'water': lambda T: 2.1*m**2/s/K*(T - 273.15*K)}}.

mass: The mass of the compound
formula:: The Formula object representing the compound
data: Free form dictionary of additional properties.

charge¶: Convenience property for accessing charge of the formula

mass¶: Convenience property for accessing the mass of the formula

molar_mass()[source]¶

Returns the molar mass (with units) of the substance

>>> nh4p = Compound.from_formula('NH4+')
>>> from chemistry_tools.units import quantities
>>> nh4p.molar_mass(quantities)
array(18.0384511...) * g/mol

`dataarray`¶

class chemistry_tools.formulae.dataarray.DataArray(formula, data)[source]¶

A class that can output data as an array, to CSV, as a pandas DataFrame, or as a pretty-printed table in a variety of formats.

as_array(*args, **kwargs)[source]¶

as_csv(*args, sep=', ', **kwargs)[source]¶

Returns the data as a CSV formatted string

Parameters:	sep (str, optional) – The separator for the CSV data. Default `,`

Any additional arguments taken by as_array can also be used here.

Return type:	str

as_dataframe(*args, **kwargs)[source]¶

Returns the isotope distribution data as a pandas DataFrame

Any arguments taken by as_array can also be used here.

Return type:	`pandas.DataFrame`

as_table(*args, **kwargs)[source]¶

Returns the isotope distribution data as a table using tabulate

Any arguments taken by as_array can also be used here.

Additionally, any valid keyword argument for tabulate.tabulate() can be used.

Return type:	str

`formula`¶

Parse formulae into a Python object

class chemistry_tools.formulae.formula.Formula(composition=None, charge=0)[source]¶

A Formula object stores a chemical composition of a compound. It is based on dict, with the symbols of chemical elements as keys and the values equal to the number of atoms of the corresponding element in the compound.

average_mass¶

Calculate the average mass of a Formula.

Note that mass is not averaged for elements with specified isotopes.

Returns:	mass
Return type:	float

average_mz¶

composition¶

Returns a Composition object representing the elemental composition of the Formula

Returns:
Return type:

copy() → a shallow copy of D.[source]¶

elements¶: Returns a list of the element symbols in the formula.

empirical_formula¶

Returns the empirical formula in Hill notation.

The empirical formula has the simplest whole number ratio of atoms of each element present in formula.

>>> Formula.from_string('H2O').empirical
'H2O'
>>> Formula.from_string('S4').empirical
'S'
>>> Formula.from_string('C6H12O6').empirical
'CH2O'

Return type:	str

exact_mass¶

Calculate the monoisotopic mass of a Formula. If any isotopes are already present in the formula, the mass of these will be preserved

Returns:	mass
Return type:	float

classmethod from_kwargs(*, charge=0, **kwargs)[source]¶

Create a new Formula object from keyword arguments representing the elements in the compound

Parameters:	charge (int, optional) –
Return type:	`Formula`

classmethod from_mass_fractions(fractions, charge=0, maxcount=10, precision=0.0001)[source]¶

Create a new Formula object from elemental mass fractions by parsing a string

Note

Isotopes cannot (currently) be parsed using this method

Parameters:	fractions (dict) – A dictionary of elements and mass fractions charge (int, optional) –
Return type:	`Formula`

>>> Formula.from_mass_fractions({'H': 0.112, 'O': 0.888})
'H2O'
>>> Formula.from_mass_fractions({'D': 0.2, 'O': 0.8})
'O[2H]2'
>>> Formula.from_mass_fractions({'H': 8.97, 'C': 59.39, 'O': 31.64})
'C5H9O2'
>>> Formula.from_mass_fractions({'O': 0.26, '30Si': 0.74})
'O2[30Si]3'

classmethod from_string(formula, charge=0)[source]¶

Create a new Formula object by parsing a string

Note

Isotopes cannot (currently) be parsed using this method

Parameters:	formula – A string with a chemical formula charge (int, optional) –
Return type:	`Formula`

# TODO: should throw error for unrecognised elements CGCGAATTCGCG

get_mz(average=True, charge=None)[source]¶

Calculate the average mass:charge ratio (m/z) of a Formula.

Parameters:	average – If `True` then the average m/z is calculated. Note that mass is not averaged for elements with specified isotopes. Default is `True`. charge – The charge of the compound. If `None` then the existing charge of the Formula is used
Type:	average: bool, optional
Type:	charge: int, optional
Returns:	mass
Return type:	float

hill_formula¶

Returns formula in Hill notation

>>> Formula.from_string('BrC2H5').hill_formula
'C2H5Br'
>>> Formula.from_string('HBr').hill_formula
'BrH'
>>> Formula.from_string('[(CH3)3Si2]2NNa').hill_formula
'C6H18NNaSi4'

Return type:	str

isotope_distribution()[source]¶

Returns a IsotopeDistribution object representing the distribution of the isotopologues of the formula

Return type:	`IsotopeDistribution`

isotopic_composition_abundance¶

Calculate the relative abundance of the current isotopic composition of this molecule.

Returns:	The relative abundance of the current isotopic composition.
Return type:	float

iter_isotopologues(report_abundance=False, elements_with_isotopes=None, isotope_threshold=0.0005, overall_threshold=0)[source]¶

Iterate over possible isotopic states of the molecule.

The space of possible isotopic compositions is restrained by parameters elements_with_isotopes, isotope_threshold, overall_threshold.

Parameters:	report_abundance – If `True`, the output will contain 2-tuples: (composition, abundance). Otherwise, only compositions are yielded. Default is `False`. elements_with_isotopes – A set of elements to be considered in isotopic distribution (by default, every element has an isotopic distribution). isotope_threshold – The threshold abundance of a specific isotope to be considered. Default is `5e-4`. overall_threshold – The threshold abundance of the calculated isotopic composition. Default is `0`.
Type:	report_abundance: bool, optional
Type:	elements_with_isotopes: container of str, optional
Type:	isotope_threshold: float, optional
Type:	overall_threshold: float, optional
Returns:	Iterator over possible isotopic compositions.
Return type:	iterator

mass¶

Calculate the average mass of a Formula.

Note that mass is not averaged for elements with specified isotopes.

Returns:	mass
Return type:	float

monoisotopic_mass¶

Calculate the monoisotopic mass of a Formula. If any isotopes are already present in the formula, the mass of these will be preserved

Returns:	mass
Return type:	float

most_probable_isotopic_composition(elements_with_isotopes=None)[source]¶

Calculate the most probable isotopic composition of a molecule/ion.

For each element, only two most abundant isotopes are considered. Any isotopes already in the Formula will be changed to the most abundant isotope

Parameters:	elements_with_isotopes – A set of elements to be considered in isotopic distribution (by default, every element has an isotopic distribution).
Type:	elements_with_isotopes: container of str, optional
Returns:	A tuple with the most probable isotopic composition and its relative abundance.
Return type:	(Formula, float)

mz¶

n_atoms¶

Return the number of atoms in the formula.

>>> Formula.from_string('CH3COOH').n_atoms
8

n_elements¶

Return the number of elements in the formula.

>>> Formula.from_string('CH3COOH').n_elements
3

no_isotope_hill_formula¶

Returns formula in Hill notation, without any isotopes specified

>>> Formula.from_string('BrC2H5').no_isotope_hill_formula
'C2H5Br'
>>> Formula.from_string('HBr').no_isotope_hill_formula
'BrH'
>>> Formula.from_string('[(CH3)3Si2]2NNa').no_isotope_hill_formula
'C6H18NNaSi4'

Return type:	str

nominal_mass¶

Calculate the monoisotopic mass of a Formula. If any isotopes are already present in the formula, the mass of these will be preserved

Returns:	mass
Return type:	float

`html`¶

Functions and constants for converting formulae to html

chemistry_tools.formulae.html.string_to_html(formula, prefixes=None, infixes=None, **kwargs)[source]¶

Convert formula string to html string representation

formula : str: Chemical formula, e.g. ‘H2O’, ‘Fe+3’, ‘Cl-‘
prefixes : dict: Prefix transformations, default: greek letters and .
infixes : dict: Infix transformations, default: .
suffixes : tuple of strings: Suffixes to keep, e.g. (‘(g)’, ‘(s)’)

>>> string_to_html('NH4+')
'NH<sub>4</sub><sup>+</sup>'
>>> string_to_html('Fe(CN)6+2')
'Fe(CN)<sub>6</sub><sup>2+</sup>'
>>> string_to_html('Fe(CN)6+2(aq)')
'Fe(CN)<sub>6</sub><sup>2+</sup>(aq)'
>>> string_to_html('.NHO-(aq)')
'&sdot;NHO<sup>-</sup>(aq)'
>>> string_to_html('alpha-FeOOH(s)')
'&alpha;-FeOOH(s)'

`iso_dist`¶

Isotope Distributions

class chemistry_tools.formulae.iso_dist.IsoDistSort[source]¶

Lookup for sorting isotope distribution output

Abundance = 2¶

Formula = 0¶

Mass = 1¶

Relative_Abundance = 3¶

Relative_abundance = 3¶

abundance = 2¶

formula = 0¶

mass = 1¶

relative_abundance = 3¶

class chemistry_tools.formulae.iso_dist.IsotopeDistribution(formula)[source]¶

Each composition can be accessed with their hill formulae like a dictionary (e.g. iso_dict[“H[1]2O[16]”]

as_array(sort_by=<IsoDistSort.formula: 0>, reverse=False, format_percentage=True)[source]¶

Returns the isotope distribution data as a list of lists

Parameters:	sort_by (IsoDistSort) – The column to sort by.
Param:	Whether the isotopologues should be sorted in reverse order. Default `False`.
Param:	Whether the abundances should be formatted as percentages or not. Default `False`.
Return type:	list[list]

`latex`¶

Functions and constants for converting formulae to LaTeX

chemistry_tools.formulae.latex.string_to_latex(formula, prefixes=None, infixes=None, **kwargs)[source]¶

Convert formula string to latex representation

formula: str: Chemical formula, e.g. ‘H2O’, ‘Fe+3’, ‘Cl-‘
prefixes: dict: Prefix transofmrations, default: greek letters and .
infixes: dict: Infix transformations, default: .
suffixes: iterable of str: What suffixes not to interpret, default: (s), (l), (g), (aq)

>>> string_to_latex('NH4+')
'NH_{4}^{+}'
>>> string_to_latex('Fe(CN)6+2')
'Fe(CN)_{6}^{2+}'
>>> string_to_latex('Fe(CN)6+2(aq)')
'Fe(CN)_{6}^{2+}(aq)'
>>> string_to_latex('.NHO-(aq)')
'^\\bullet NHO^{-}(aq)'
>>> string_to_latex('alpha-FeOOH(s)')
'\\alpha-FeOOH(s)'

`parser`¶

Functions and constants for parsing formulae

chemistry_tools.formulae.parser.mass_from_composition(composition, charge=0)[source]¶

Calculates molecular mass from atomic weights

composition: dict: Dictionary mapping str or int (element symbol or atomic number) to int (coefficient)
charge:: The charge of the composition. Can also be given as the “0” key of composition

float: molecular weight in atomic mass units

Atomic number 0 denotes charge or “net electron defficiency”

>>> f'{mass_from_composition({0: -1, "H": 1, 8: 1}):.2f}'
'17.01'

chemistry_tools.formulae.parser.string_to_composition(formula, prefixes=None, suffixes=('(s)', '(l)', '(g)', '(aq)'))[source]¶

Parse composition of formula representing a chemical formula

Composition is represented as a dict mapping int -> int (atomic number -> multiplicity). “Atomic number” 0 represents net charge.

formula: str: Chemical formula, e.g. ‘H2O’, ‘Fe+3’, ‘Cl-‘
prefixes: iterable strings: Prefixes to ignore, e.g. (‘.’, ‘alpha-‘)
suffixes: tuple of strings: Suffixes to ignore, e.g. (‘(g)’, ‘(s)’)

>>> string_to_composition('NH4+') == {0: 1, "H": 4, "N": 1}
True
>>> string_to_composition('.NHO-(aq)') == {0: -1, "H": 1, "N": 1, "O": 1}
True
>>> string_to_composition('Na2CO3.7H2O') == {"Na": 2, "C": 1, "O": 10, "H": 14}
True

chemistry_tools.formulae.parser.to_reaction(line, substance_keys, token, cls, globals_=None, **kwargs)[source]¶

Parses a string into a Reaction object and substances

Reac1 + 2 Reac2 + (2 Reac1) -> Prod1 + Prod2; 10**3.7; ref=’doi:12/ab’ Reac1 = Prod1; 2.1;

line: str: string representation to be parsed
substance_keys: iterable of strings: Allowed names, e.g. (‘H2O’, ‘H+’, ‘OH-‘)
token : str: delimiter token between reactant and product side
cls : class: e.g. subclass of Reaction
globals_: dict (optional): Globals passed on to eval(), when None: chempy.units is used with ‘chempy’ and ‘default_units’ extra entries.

This function calls eval(), hence there are severe security concerns with running this on untrusted data.

`species`¶

class chemistry_tools.formulae.species.Species(composition=None, charge=0, phase=None)[source]¶

Formula with phase information (e.g. solid, liquid, gas, or aqueous)

Species extends Formula with the new attribute phase

phase: Either “s”, “l”, “g”, or “aq”. None represents an unknown phase.

copy() → a shallow copy of D.[source]¶

empirical_formula¶

Returns:
Return type:	str

classmethod from_kwargs(*, charge=0, phase=None, **kwargs)[source]¶

Create a new Species object from keyword arguments representing the elements in the compound

Parameters:	charge (int, optional) –
Return type:	`Formula`

classmethod from_string(formula, phase=None, charge=0)[source]¶

Create a new Species object by parsing a string

Analogous to Formula.from_string() but with the addition that the phase is determined from the formula.

formula: str: e.g. ‘H2O’, ‘NaCl(s)’, ‘CO2(aq)’, ‘CO2(g)’

phase: Either “s”, “l”, “g”, or “aq”. None represents an unknown phase.

>>> water = Species.from_string('H2O')
>>> water.phase
None
>>> NaCl = Species.from_string('NaCl(s)')
>>> NaCl.phase
s
>>> Hg_l = Species.from_string('Hg(l)')
>>> Hg_l.phase
l
>>> CO2g = Species.from_string('CO2(g)')
>>> CO2g.phase
g
>>> CO2aq = Species.from_string('CO2(aq)')
>>> CO2aq.phase
aq

hill_formula¶

Returns:
Return type:	str

`unicode`¶

Functions and constants for convert formulae to unicode

chemistry_tools.formulae.unicode.string_to_unicode(formula, prefixes=None, infixes=None, **kwargs)[source]¶

Convert formula string to unicode string representation

formula : str: Chemical formula, e.g. ‘H2O’, ‘Fe+3’, ‘Cl-‘
prefixes : dict: Prefix transofmrations, default: greek letters and .
infixes : dict: Infix transofmrations, default: .
suffixes : tuple of strings: Suffixes to keep, e.g. (‘(g)’, ‘(s)’)

>>> string_to_unicode('NH4+') == u'NH₄⁺'
True
>>> string_to_unicode('Fe(CN)6+2') == u'Fe(CN)₆²⁺'
True
>>> string_to_unicode('Fe(CN)6+2(aq)') == u'Fe(CN)₆²⁺(aq)'
True
>>> string_to_unicode('.NHO-(aq)') == u'⋅NHO⁻(aq)'
True
>>> string_to_unicode('alpha-FeOOH(s)') == u'α-FeOOH(s)'
True