Periodic Table (chemicals.elements)

This module contains a complete periodic table, routines for working with chemical formulas, computing molecular weight, computing mass fractions and atom fractions, and assorted other tasks.

For reporting bugs, adding feature requests, or submitting pull requests, please use the GitHub issue tracker.

Periodic Table and Elements

chemicals.elements.periodic_table = <chemicals.elements.PeriodicTable object>

Single instance of the PeriodicTable class. Use this, not the PeriodicTable class directly.

A brief overview of using the periodic table and its elements:

>>> periodic_table.Na
<Element Sodium (Na), number 11, MW=22.9898>
>>> periodic_table.U.MW
238.02891
>>> periodic_table['Th'].CAS
'7440-29-1'
>>> periodic_table.lead.protons
82
>>> periodic_table['7440-57-5'].symbol
'Au'
>>> len(periodic_table)
118
>>> 'gold' in periodic_table
True
>>> periodic_table.He.protons, periodic_table.He.neutrons, periodic_table.He.electrons # Standard number of protons, neutrons, electrons
(2, 2, 2)
>>> periodic_table.He.phase # Phase of the element in the standard state
'g'
>>> periodic_table.He.Hf # Heat of formation in standard state in J/mol - by definition 0
0.0
>>> periodic_table.He.S0 # Absolute entropy (J/(mol*K) in standard state - non-zero)
126.2
>>> periodic_table.Kr.block, periodic_table.Kr.period, periodic_table.Kr.group
('p', 4, 18)
>>> periodic_table.Rn.InChI
'Rn'
>>> periodic_table.Rn.smiles
'[Rn]'
>>> periodic_table.Pu.number
94
>>> periodic_table.Pu.PubChem
23940
>>> periodic_table.Bi.InChI_key
'JCXGWMGPZLAOME-UHFFFAOYSA-N'

class chemicals.elements.Element(number: int, symbol: str, name: str, MW: float, CAS: str, AReneg: float | None, rcov: float | None, rvdw: float | None, maxbonds: int | None, elneg: float | None, ionization: float | None, elaffinity: float | None, period: int, group: int | None, PubChem: int | None, phase: str, Hf: float | None, S0: float | None, InChI_key: str | None = None)

Class for storing data on chemical elements. Supports most common properties. If a property is not available, it is set to None.

The elements are created automatically and should be accessed via the periodic_table interface.

Attributes:

numberint

Atomic number, [-]

namestr

name, [-]

symbolstr

Elemental symbol, [-]

MWfloat

Molecular weight, [g/mol]

CASstr

CAS number, [-]

periodstr

Period in the periodic table, [-]

groupstr

Group in the periodic table, [-]

blockstr

Which block of the periodic table the element is in.

ARenegfloat

Allred and Rochow electronegativity, [-]

rcovfloat

Covalent radius, [Angstrom]

rvdwfloat

Van der Waals radius, [Angstrom]

maxbondsfloat

Maximum valence of a bond with this element, [-]

elnegfloat

Pauling electronegativity, [-]

ionizationfloat

Ionization potential, [eV]

elaffinityfloat

Electron affinity, [eV]

protonsint

The number of protons of the element.

electronsint

The number of electrons of the element.

InChIstr

The InChI identifier of the element.

InChI_keystr

25-character hash of the compound’s InChI, [-]

smilesstr

The SMILES identification string of the element.

PubChemint

PubChem Compound identifier (CID) of the chemical, [-]

phasestr

Standard state at 1 atm and 298.15 K, [-]

Hffloat

Enthalpy of formation of the element in its standard state (0 by definition), [J/mol]

S0float

Standard absolute entropy of the element in its standard state (1 bar, 298.15 K), [J/mol/K]

class chemicals.elements.PeriodicTable(elements: list[Element])

Periodic Table object for use in dealing with elements.

As there is only one periodic table of elements, this is automatically initialized into the object periodic_table; there is no need to construct a new instance of this class.

Parameters:

elementslist[Element]

List of Element objects, [-]

See also

periodic_table

Element

Notes

Can be checked to sese if an element in in this, can be iterated over, and as a current length of 118 elements.

References

[1]

N M O’Boyle, M Banck, C A James, C Morley, T Vandermeersch, and G R Hutchison. “Open Babel: An open chemical toolbox.” J. Cheminf. (2011), 3, 33. DOI:10.1186/1758-2946-3-33

Working with Formulas

chemicals.elements.simple_formula_parser(formula: str) → dict[str, float]

Basic formula parser, primarily for obtaining element counts from formulas as formated in PubChem. Handles formulas with integer or decimal counts (with period separator), but no brackets, no hydrates, no charges, no isotopes, and no group multipliers.

Strips charges from the end of a formula first. Accepts repeated chemical units. Performs no sanity checking that elements are actually elements. As it uses regular expressions for matching, errors are mostly just ignored.

Parameters:

formulastr

Formula string, very simply formats only.

Returns:

atomsdict

dictionary of counts of individual atoms, indexed by symbol with proper capitalization, [-]

Notes

Inspiration taken from the thermopyl project, at https://github.com/choderalab/thermopyl.

Examples

>>> simple_formula_parser('CO2')
{'C': 1, 'O': 2}

chemicals.elements.nested_formula_parser(formula: str, check: bool = True) → dict[str, float]

Improved formula parser which handles braces and their multipliers, as well as rational element counts.

Strips charges from the end of a formula first. Accepts repeated chemical units. Performs no sanity checking that elements are actually elements. As it uses regular expressions for matching, errors are mostly just ignored.

Parameters:

formulastr

Formula string, very simply formats only.

checkbool

If check is True, a simple check will be performed to determine if a formula is not a formula and an exception will be raised if it is not, [-]

Returns:

atomsdict

dictionary of counts of individual atoms, indexed by symbol with proper capitalization, [-]

Notes

Inspired by the approach taken by CrazyMerlyn on a reddit DailyProgrammer challenge, at https://www.reddit.com/r/dailyprogrammer/comments/6eerfk/20170531_challenge_317_intermediate_counting/

Examples

>>> nested_formula_parser('Pd(NH3)4.0001+2')
{'Pd': 1, 'N': 4.0001, 'H': 12.0003}

chemicals.elements.charge_from_formula(formula: str) → int

Basic formula parser to determine the charge from a formula - given that the charge is already specified as one element of the formula.

Performs no sanity checking that elements are actually elements.

Parameters:

formulastr

Formula string, very simply formats only, ending in one of ‘+x’, ‘-x’, n*’+’, or n*’-’ or any of them surrounded by brackets but always at the end of a formula.

Returns:

chargeint

Charge of the molecule, [faraday]

Examples

>>> charge_from_formula('Br3-')
-1
>>> charge_from_formula('Br3(-)')
-1

chemicals.elements.serialize_formula(formula: str) → str

Basic formula serializer to construct a consistently-formatted formula. This is necessary for handling user-supplied formulas, which are not always well formatted.

Performs no sanity checking that elements are actually elements.

Parameters:

formulastr

Formula string as parseable by the method nested_formula_parser, [-]

Returns:

formulastr

A consistently formatted formula to describe a molecular formula, [-]

Examples

>>> serialize_formula('Pd(NH3)4+3')
'H12N4Pd+3'

chemicals.elements.atoms_to_Hill(atoms: dict[str, int]) → str

Determine the Hill formula of a compound, given a dictionary of its atoms and their counts, in the format {symbol: count}.

Parameters:

atomsdict

dictionary of counts of individual atoms, indexed by symbol with proper capitalization, [-]

Returns:

Hill_formulastr

Hill formula, [-]

Notes

The Hill system is as follows:

If the chemical has ‘C’ in it, this is listed first, and then if it has ‘H’ in it as well as ‘C’, then that goes next. All elements are sorted alphabetically afterwards, including ‘H’ if ‘C’ is not present. All elements are followed by their count, unless it is 1.

References

[1]

Hill, Edwin A.”“ON A SYSTEM OF INDEXING CHEMICAL LITERATURE; ADOPTED BY THE CLASSIFICATION DIVISION OF THE U. S. PATENT OFFICE.1.” Journal of the American Chemical Society 22, no. 8 (August 1, 1900): 478-94. doi:10.1021/ja02046a005.

Examples

>>> atoms_to_Hill({'H': 5, 'C': 2, 'Br': 1})
'C2H5Br'

Working with Parsed Formulas

chemicals.elements.molecular_weight(atoms: dict[str, int]) → float

Calculates molecular weight of a molecule given a dictionary of its atoms and their counts, in the format {symbol: count}.

$$MW = \sum_i n_i MW_i$$

Parameters:

atomsdict

Dictionary of counts of individual atoms, indexed by symbol with proper capitalization, [-]

Returns:

MWfloat

Calculated molecular weight [g/mol]

Notes

Elemental data is from rdkit, with CAS numbers added. An exception is raised if an incorrect element symbol is given. Elements up to 118 are supported, as are deutreium and tritium.

References

[1]

RDKit: Open-source cheminformatics; http://www.rdkit.org

Examples

>>> molecular_weight({'H': 12, 'C': 20, 'O': 5}) # DNA
332.30628

chemicals.elements.similarity_variable(atoms: dict[str, int], MW: float | None = None) → float

Calculates the similarity variable of an compound, as defined in [1]. Currently only applied for certain heat capacity estimation routines.

$$\alpha = \frac{N}{MW} = \frac{\sum_i n_i}{\sum_i n_i MW_i}$$

Parameters:

atomsdict

dictionary of counts of individual atoms, indexed by symbol with proper capitalization, [-]

MWfloat, optional

Molecular weight, [g/mol]

Returns:

similarity_variablefloat

Similarity variable as defined in [1], [mol/g]

Notes

Molecular weight is optional, but speeds up the calculation slightly. It is calculated using the function molecular_weight if not specified.

References

[1] (1,2)

Laštovka, Václav, Nasser Sallamie, and John M. Shaw. “A Similarity Variable for Estimating the Heat Capacity of Solid Organic Compounds: Part I. Fundamentals.” Fluid Phase Equilibria 268, no. 1-2 (June 25, 2008): 51-60. doi:10.1016/j.fluid.2008.03.019.

Examples

>>> similarity_variable({'H': 32, 'C': 15})
0.2212654140784498

chemicals.elements.index_hydrogen_deficiency(atoms)

Calculate the index of hydrogen deficiency of a compound, given a dictionary of its atoms and their counts, in the format {symbol: count}.

Parameters:

atomsdict

dictionary of counts of individual atoms, indexed by symbol with proper capitalization, [-]

Returns:

HDIfloat

Hydrogen deficiency index, [-]

Notes

The calculation is according to:

$$\text{IDH} = 0.5\left(2C + 2 + N - H -X + 0O \right)$$

where X is the number of halogen atoms. The number of oxygen atoms does not impact this calculation.

References

[1]

Brown, William H., and Thomas Poon. Introduction to Organic Chemistry. 4th edition. Hoboken, NJ: Wiley, 2010.

Examples

Agelastatin A:

>>> index_hydrogen_deficiency({'C': 12, 'H': 13, 'Br': 1, 'N': 4, 'O': 3})
8.0

chemicals.elements.atom_fractions(atoms: dict[str, int]) → dict[str, float]

Calculates the atomic fractions of each element in a compound, given a dictionary of its atoms and their counts, in the format {symbol: count}.

$$a_i = \frac{n_i}{\sum_i n_i}$$

Parameters:

atomsdict

dictionary of counts of individual atoms, indexed by symbol with proper capitalization, [-]

Returns:

afracsdict

dictionary of atomic fractions of individual atoms, indexed by symbol with proper capitalization, [-]

Notes

No actual data on the elements is used, so incorrect or custom compounds would not raise an error.

References

[1]

RDKit: Open-source cheminformatics; http://www.rdkit.org

Examples

>>> atom_fractions({'H': 12, 'C': 20, 'O': 5})
{'H': 0.32432432432432434, 'C': 0.5405405405405406, 'O': 0.13513513513513514}

chemicals.elements.mass_fractions(atoms: dict[str, int], MW: float | None = None) → dict[str, float]

Calculates the mass fractions of each element in a compound, given a dictionary of its atoms and their counts, in the format {symbol: count}.

$$w_i = \frac{n_i MW_i}{\sum_i n_i MW_i}$$

Parameters:

atomsdict

Dictionary of counts of individual atoms, indexed by symbol with proper capitalization, [-]

MWfloat, optional

Molecular weight, [g/mol]

Returns:

mfracsdict

Dictionary of mass fractions of individual atoms, indexed by symbol with proper capitalization, [-]

Notes

Molecular weight is optional, but speeds up the calculation slightly. It is calculated using the function molecular_weight if not specified.

Elemental data is from rdkit, with CAS numbers added. An exception is raised if an incorrect element symbol is given. Elements up to 118 are supported.

References

[1]

RDKit: Open-source cheminformatics; http://www.rdkit.org

Examples

>>> mass_fractions({'H': 12, 'C': 20, 'O': 5})
{'H': 0.03639798802478244, 'C': 0.7228692758981262, 'O': 0.24073273607709128}

chemicals.elements.mixture_atomic_composition(atomss: list[dict[str, int]], zs: list[float]) → dict[str, float]

Simple function to calculate the atomic average composition of a mixture, using the mole fractions of each species and their own atomic compositions.

Parameters:

atomsslist[dict[(str, int)]]

List of dictionaries of atomic compositions, [-]

zslist[float]

Mole fractions of each component, [-]

Returns:

atomsdict[(str, int)]

Atomic composition

Examples

>>> mixture_atomic_composition([{'O': 2}, {'N': 1, 'O': 2}, {'C': 1, 'H': 4}], [0.95, 0.025, .025])
{'O': 1.95, 'N': 0.025, 'C': 0.025, 'H': 0.1}

chemicals.elements.mixture_atomic_composition_ordered(atomss: list[dict[str, int]], zs: list[float]) → tuple[list[float], list[str]]

Simple function to calculate the atomic average composition of a mixture, using the mole fractions of each species and their own atomic compositions. Returns the result as a sorted list with atomic numbers from low to high.

Parameters:

atomsslist[dict[(str, int)]]

List of dictionaries of atomic compositions, [-]

zslist[float]

Mole fractions of each component; this can also be a molar flow rate and then the abundances will be flows, [-]

Returns:

abundanceslist[float]

Number of atoms of each element per mole of the feed, [-]

atom_keyslist[str]

Atomic elements, sorted from lowest atomic number to highest

Notes

Useful to ensure a matrix order is consistent in multiple steps.

Examples

>>> mixture_atomic_composition_ordered([{'O': 2}, {'N': 1, 'O': 2}, {'C': 1, 'H': 4}], [0.95, 0.025, .025])
([0.1, 0.025, 0.025, 1.95], ['H', 'C', 'N', 'O'])

chemicals.elements.atom_matrix(atomss: list[dict[str, int]], atom_IDs: list[str] | None = None) → list[list[float]]

Simple function to create a matrix of elements in each compound, where each row has the same elements.

Parameters:

atomsslist[dict[(str, int)]]

List of dictionaries of atomic compositions, [-]

atom_IDslist[str], optional

Optionally, a subset (or simply ordered differently) of elements to consider, [-]

Returns:

matrixlist[list[float]]

The number of each element in each compound as a matrix, indexed as [compound][element], [-]

Examples

>>> atom_matrix([{'C': 1, 'H': 4}, {'C': 2, 'H': 6}, {'N': 2}, {'O': 2}, {'H': 2, 'O': 1}, {'C': 1, 'O': 2}])
[[4, 1, 0.0, 0.0], [6, 2, 0.0, 0.0], [0.0, 0.0, 2, 0.0], [0.0, 0.0, 0.0, 2], [2, 0.0, 0.0, 1], [0.0, 1, 0.0, 2]]