Periodic Table

Full access to the periodic table is also available within QCElemental. This includes mass, atomic number, symbol, and name information. Data is indexed many ways so that many possible aliases can lead to a single quantity. For example, to obtain the mass (in a.m.u) of of Carbon atomic number, symbol, isotope symbol, and name can all be passed:

>>> qcel.periodictable.to_mass(6)
12.0
>>> qcel.periodictable.to_mass("C")
12.0
>>> qcel.periodictable.to_mass("C12")
12.0
>>> qcel.periodictable.to_mass("Carbon")
12.0

A variety of infomation can be accessed in this manner. Taking ‘Carbon’ as an example for mass information:

>>> qcel.periodictable.to_mass("Carbon")
12.0
>>> qcel.periodictable.to_mass_number("Carbon")
12
>>> qcel.periodictable.to_atomic_number("Carbon")
6

Symbol information:

>>> qcel.periodictable.to_symbol("Carbon")
'C'
>>> qcel.periodictable.to_name("Carbon")
'Carbon'

Table position information:

>>> qcel.periodictable.to_period("Carbon")
2
>>> qcel.periodictable.to_group("Carbon")
14

API

Top level user functions:

to_mass(*[, return_decimal])

Get atomic mass of atom.

to_mass_number()

Get mass number of atom.

to_atomic_number([strict])

Get atomic number of atom.

to_symbol([strict])

Get element symbol of atom.

to_name([strict])

Get element name of atom.

to_period()

Get period (horizontal row in periodic table) of atom.

to_group()

Get group (vertical column in periodic table) of atom.

Function Definitions

qcelemental.periodictable.to_mass(atom, *, return_decimal=False)

Get atomic mass of atom.

Parameters

  • atom (Union[int, str]) – Identifier for element or nuclide, e.g., H, D, H2, He, hE4.

  • return_decimal (bool) – Whether to preserve significant figures information by returning as Decimal (True) or to convert to float (False).

Returns

Atomic mass [u]. See above for type.

  • If atom is nuclide (e.g., “Li6”), the reported mass.

  • If atom is stable element (e.g., “Li”), the mass of the most abundant isotope, “Li7”.

  • If atom is unstable element (e.g., “Pu”), the mass of the longest-lived isotope, “Pu244”.

Return type

decimal.Decimal or float

Raises

NotAnElementError – If atom cannot be resolved into an element or nuclide.

qcelemental.periodictable.to_mass_number(atom)

Get mass number of atom.

Functions to_A() and to_mass_number() are aliases.

Parameters

atom (Union[int, str]) – Identifier for element or nuclide, e.g., H, D, H2, He, hE4.

Returns

Mass number, number of protons and neutrons.

  • If atom is nuclide (e.g., “Li6”), the corresponding mass number, 6.

  • If atom is stable element (e.g., “Li”), the mass number of the most abundant isotope, 7.

  • If atom is unstable element (e.g., “Pu”), the mass number of the longest-lived isotope, 244.

Return type

int

Raises

NotAnElementError – If atom cannot be resolved into an element or nuclide.

qcelemental.periodictable.to_atomic_number(atom, strict=False)

Get atomic number of atom.

Functions to_Z() and to_atomic_number() are aliases.

Parameters

  • atom (Union[int, str]) – Identifier for element or nuclide, e.g., H, D, H2, He, hE4.

  • strict (bool) – Allow only element identification in atom, not nuclide.

Returns

Atomic number, number of protons.

Return type

int

Raises

NotAnElementError – If atom cannot be resolved into an element or nuclide. If strict=True and atom resolves into nuclide, not element.

qcelemental.periodictable.to_symbol(atom, strict=False)

Get element symbol of atom.

Functions to_E() and to_symbol() are aliases.

Parameters

  • atom (Union[int, str]) – Identifier for element or nuclide, e.g., H, D, H2, He, hE4.

  • strict (bool) – Allow only element identification in atom, not nuclide.

Returns

Element symbol, capitalized.

Return type

str

Raises

NotAnElementError – If atom cannot be resolved into an element or nuclide. If strict=True and atom resolves into nuclide, not element.

qcelemental.periodictable.to_name(atom, strict=False)

Get element name of atom.

Functions to_element() and to_name() are aliases.

Parameters

  • atom (Union[int, str]) – Identifier for element or nuclide, e.g., H, D, H2, He, hE4.

  • strict (bool) – Allow only element identification in atom, not nuclide.

Returns

Element name, capitalized.

Return type

str

Raises

NotAnElementError – If atom cannot be resolved into an element or nuclide. If strict=True and atom resolves into nuclide, not element.

qcelemental.periodictable.to_period(atom)

Get period (horizontal row in periodic table) of atom.

Parameters

atom (Union[int, str]) – Identifier for element or nuclide, e.g., H, D, H2, He, hE4.

Returns

Period between 1 (e.g., He) and 7 (e.g., U238).

Return type

int

Raises

NotAnElementError – If atom cannot be resolved into an element or nuclide.

qcelemental.periodictable.to_group(atom)

Get group (vertical column in periodic table) of atom.

Parameters

atom (Union[int, str]) – Identifier for element or nuclide, e.g., H, D, H2, He, hE4.

Return type

Optional[int]

Returns

  • int – Group between 1 (e.g., Li) and 18 (e.g., KR84).

  • None – If one of the 30 Lanthanides (Z=57-71) or Actinides (Z=89-103).

Raises

NotAnElementError – If atom cannot be resolved into an element or nuclide.