chemistry_tools.formulae.species

Attention

This module has the following additional requirements:

cawdrey>=0.5.0
mathematical>=0.5.1
pyparsing>=2.4.6
tabulate>=0.8.9

These can be installed as follows:

python -m pip install chemistry-tools[formulae]

Class to represent a formula with phase information (e.g. solid, liquid, gas, or aqueous).

Data:

S

Invariant TypeVar bound to chemistry_tools.formulae.species.Species.

Classes:

Species([composition, charge, phase])

Formula with phase information (e.g.
S = TypeVar(S, bound=Species)

Type:    TypeVar

Invariant TypeVar bound to chemistry_tools.formulae.species.Species.

class Species(composition=None, charge=0, phase=None)[source]

Bases: Formula

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

Species extends Formula with the new attribute phase

Parameters

  • composition (Optional[Dict[str, int]]) – A Formula object with the elemental composition of a substance, or a dict representing the same. If None an empty object is created. Default None.

  • charge (int) – Default 0.

  • phase (Optional[Literal['s', 'l', 'g', 'aq']]) – Either 's', 'l', 'g', or 'aq'. None represents an unknown phase. Default None.

Methods:

__eq__(other)

Returns self == other.

copy()

Returns a copy of the Species.

from_kwargs(*[, charge, phase])

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

from_string(formula[, charge, phase])

Create a new Species object by parsing a string.

Attributes:

empirical_formula

Returns the empirical formula in Hill notation.

hill_formula

Returns the formula in Hill notation.

phase

The phase of the species (e.g.
__eq__(other)[source]

Returns self == other.

Return type

bool

copy()[source]

Returns a copy of the Species.

Return type

~S

property 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 the formula.

Examples:

>>> Formula.from_string('H2O').empirical_formula
'H2O'
>>> Formula.from_string('S4').empirical_formula
'S'
>>> Formula.from_string('C6H12O6').empirical_formula
'CH2O'
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) – The charge of the compound. Default 0.

  • phase (Optional[Literal['s', 'l', 'g', 'aq']]) – The phase of the compound (e.g. 's' for solid). Default None.

Return type

~S

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

Create a new Species object by parsing a string.

Note

Isotopes cannot (currently) be parsed using this method

Parameters

  • formula (str) – A string with a chemical formula

  • phase (Optional[Literal['s', 'l', 'g', 'aq']]) – Either 's', 'l', 'g', or 'aq'. None represents an unknown phase. Default None.

  • charge (int) – Default 0.

Return type

~S

Examples:

>>> 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
property hill_formula

Returns the formula in Hill notation.

Examples:

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

str

phase

Type:    Optional[Literal['s', 'l', 'g', 'aq']]

The phase of the species (e.g. solid, liquid, gas, or aqueous). None represents an unknown phase.