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

Core table

periodictable.core

Core classes for the periodic table.

  • PeriodicTable

    The periodic table with attributes for each element.

    Note

    PeriodicTable is not a singleton class. Use periodictable.element to access the common table.

  • Element

    Element properties such as name, symbol, mass, density, etc.

  • Isotope

    Isotope properties such as mass, density and neutron scattering factors.

  • Ion

    Ion properties such as charge.

Elements are accessed from a periodic table using table[number], table.name or table.symbol where symbol is the two letter symbol. Individual isotopes are accessed using element[isotope]. Individual ions are references using element.ion[charge]. Note that element[isotope].ion[charge].mass will depend on the particular charge since we subtract the charge times the rest mass of the electron from the overall mass.

Helper functions:

See also

Adding properties for details on extending the periodic table with your own attributes.

Custom tables for details on managing your own periodic table with custom values for the attributes.

class periodictable.core.Ion(element, charge)

Bases: object

Periodic table entry for an individual ion.

An ion is associated with an element. In addition to the element properties (symbol, name, atomic number), it has specific ion properties (charge). Properties not specific to the ion (i.e., charge) are retrieved from the associated element.

mass
xray

X-ray scattering properties for the elements.

Reference:
Center for X-Ray optics. Henke. L., Gullikson. E. M., and Davis. J. C.
class periodictable.core.Isotope(element, isotope_number)

Bases: object

Periodic table entry for an individual isotope.

An isotope is associated with an element. In addition to the element properties (symbol, name, atomic number), it has specific isotope properties (isotope number, nuclear spin, relative abundance). Properties not specific to the isotope (e.g., x-ray scattering factors) are retrieved from the associated element.

abundance

Natural abundance.

Parameters:isotope : Isotope
Returns:abundance : float | %
Reference:
Coursey. J. S., Schwab. D. J, and Dragoset. R. A., NIST Atomic Weights and Isotopic Composition Database.
density

Element density for natural abundance. For isotopes, return the equivalent density assuming identical inter-atomic spacing as the naturally occuring material.

Parameters:
iso_el : isotope or element

Name of the element or isotope.

Returns:

density : float | g·cm-3

Reference:
ILL Neutron Data Booklet, original values from CRC Handbook of Chemistry and Physics, 80th ed. (1999).
mass

Atomic weight.

Parameters:

isotope : Isotope

Returns:
mass : float | u

Atomic weight of the element.

Reference:
Coursey. J. S., Schwab. D. J, and Dragoset. R. A., NIST Atomic Weights and Isotopic Composition Database.
neutron

Neutron scattering factors, nuclear_spin and abundance properties for elements and isotopes.

Reference:
Rauch. H. and Waschkowski. W., ILL Nuetron Data Booklet.
neutron_activation

Neutron activation calculations for isotopes and formulas.

Reference:
IAEA 273: Handbook on Nuclear Activation Data. NBSIR 85-3151: Compendium of Benchmark Neutron Field.
class periodictable.core.Element(name, symbol, Z, ions, table)

Bases: object

Periodic table entry for an element.

An element is a name, symbol and number, plus a set of properties. Individual isotopes can be referenced as element[isotope_number]. Individual ionization states can be referenced by element.ion[charge].

add_isotope(number)

Add an isotope for the element.

Parameters:
number : integer

Isotope number, which is the number protons plus neutrons.

Returns:

None

K_alpha

X-ray emission lines for various elements, including Ag, Pd, Rh, Mo, Zn, Cu, Ni, Co, Fe, Mn, Cr and Ti. K_alpha is the average of K_alpha1 and K_alpha2 lines.

K_alpha_units

X-ray emission lines for various elements, including Ag, Pd, Rh, Mo, Zn, Cu, Ni, Co, Fe, Mn, Cr and Ti. K_alpha is the average of K_alpha1 and K_alpha2 lines.

K_beta1

X-ray emission lines for various elements, including Ag, Pd, Rh, Mo, Zn, Cu, Ni, Co, Fe, Mn, Cr and Ti. K_alpha is the average of K_alpha1 and K_alpha2 lines.

K_beta1_units

X-ray emission lines for various elements, including Ag, Pd, Rh, Mo, Zn, Cu, Ni, Co, Fe, Mn, Cr and Ti. K_alpha is the average of K_alpha1 and K_alpha2 lines.

abundance_units = '%'
charge = 0
covalent_radius

covalent radius: average atomic radius when bonded to C, N or O.

covalent_radius_uncertainty

covalent radius: average atomic radius when bonded to C, N or O.

covalent_radius_units

covalent radius: average atomic radius when bonded to C, N or O.

crystal_structure

Add crystal_structure property to the elements.

Reference:
Ashcroft and Mermin.
density

Element density for natural abundance. For isotopes, return the equivalent density assuming identical inter-atomic spacing as the naturally occuring material.

Parameters:
iso_el : isotope or element

Name of the element or isotope.

Returns:

density : float | g·cm-3

Reference:
ILL Neutron Data Booklet, original values from CRC Handbook of Chemistry and Physics, 80th ed. (1999).
density_units = 'g/cm^3'
interatomic_distance

Estimated interatomic distance from atomic weight and density. The distance between isotopes is assumed to match that between atoms in the natural abundance.

Parameters:
element : Element

The element whose interatomic distance is to be calculated.

Returns:
distance : float | Å

Estimated interatomic distance.

Interatomic distance is computed using:

\[d = (m/(\rho_m N_A 10^{-24}))^{1/3}\]

with units:

\[(\rm (g\cdot mol^{-1}) / ( (g\cdot cm^{-3}) (atoms\cdot mol^{-1}) (10^{-8} cm\cdot \AA^{-1})^3))^{1/3} = \AA\]
interatomic_distance_units = 'angstrom'
isotopes

List of all isotopes

magnetic_ff

Magnetic Form Fators. These values are directly from CrysFML.

Reference:
Brown. P. J.(Section 4.4.5) International Tables for Crystallography Volume C, Wilson. A.J.C.(ed).
mass

Atomic weight.

Parameters:

isotope : Isotope

Returns:
mass : float | u

Atomic weight of the element.

Reference:
Coursey. J. S., Schwab. D. J, and Dragoset. R. A., NIST Atomic Weights and Isotopic Composition Database.
mass_units = 'u'
neutron

Neutron scattering factors, nuclear_spin and abundance properties for elements and isotopes.

Reference:
Rauch. H. and Waschkowski. W., ILL Nuetron Data Booklet.
number_density

Estimate the number density from atomic weight and density. The density for isotopes is assumed to match that of between atoms in natural abundance.

Parameters:
element : element

Name of the element whose number density needs to be calculated.

Returns:
Nb : float | cm-3

Number density of a element.

Number density is computed using:

\[d = N_A \frac{\rho}{m}\]

with units:

\[\rm (atoms\cdot mol^{-1}) (g\cdot cm^{-3}) / (g\cdot mol^{-1}) = atoms\cdot cm^{-3}\]
number_density_units = '1/cm^3'
table = 'public'
xray

X-ray scattering properties for the elements.

Reference:
Center for X-Ray optics. Henke. L., Gullikson. E. M., and Davis. J. C.
class periodictable.core.PeriodicTable(table)

Bases: object

Defines the periodic table of the elements with isotopes. Individidual elements are accessed by name, symbol or atomic number. Individual isotopes are addressable by element[mass_number] or elements.isotope(element name), elements.isotope(element symbol).

For example, the following all retrieve iron:

>>> from periodictable import *
>>> print(elements[26])
Fe
>>> print(elements.Fe)
Fe
>>> print(elements.symbol('Fe'))
Fe
>>> print(elements.name('iron'))
Fe
>>> print(elements.isotope('Fe'))
Fe

To get iron-56, use:

>>> print(elements[26][56])
56-Fe
>>> print(elements.Fe[56])
56-Fe
>>> print(elements.isotope('56-Fe'))
56-Fe

Deuterium and tritium are defined as ‘D’ and ‘T’. Some neutron properties are available in elements[0].

To show all the elements in the table, use the iterator:

>>> from periodictable import *
>>> for el in elements:  # lists the element symbols
...     print("%s %s"%(el.symbol, el.name))  
n neutron
H hydrogen
He helium
...
Og oganesson

Note

Properties can be added to the elements as needed, including mass, nuclear and X-ray scattering cross sections. See section Adding properties for details.

isotope(input)

Lookup the element or isotope in the periodic table. Elements are assumed to be given by the standard element symbols. Isotopes are given by number-symbol, or ‘D’ and ‘T’ for 2-H and 3-H.

Parameters:
input : string

Element name or isotope to be looked up in periodictable.

Returns:

Element

Raises:

ValueError if element or isotope is not defined.

For example, print the element corresponding to ‘58-Ni’.

>>> import periodictable
>>> print(periodictable.elements.isotope('58-Ni'))
58-Ni
list(*props, **kw)

Print a list of elements with the given set of properties.

Parameters:
prop1, prop2, … : string

Name of the properties to print

format: string

Template for displaying the element properties, with one % for each property.

Returns:

None

For example, print a table of mass and density.

>>> from periodictable import elements
>>> elements.list('symbol', 'mass', 'density',
...     format="%-2s: %6.2f u %5.2f g/cm^3") 
H :   1.01 u   0.07 g/cm^3
He:   4.00 u   0.12 g/cm^3
Li:   6.94 u   0.53 g/cm^3
...
Bk: 247.00 u  14.00 g/cm^3
name(input)

Lookup an element given its name.

Parameters:
input : string

Element name to be looked up in periodictable.

Returns:

Element

Raises:

ValueError if element does not exist.

For example, print the element corresponding to ‘iron’:

>>> import periodictable
>>> print(periodictable.elements.name('iron'))
Fe
symbol(input)

Lookup the an element in the periodic table using its symbol. Symbols are included for ‘D’ and ‘T’, deuterium and tritium.

Parameters:
input : string

Element symbol to be looked up in periodictable.

Returns:

Element

Raises:

ValueError if the element symbol is not defined.

For example, print the element corresponding to ‘Fe’:

>>> import periodictable
>>> print(periodictable.elements.symbol('Fe'))
Fe
periodictable.core.delayed_load(all_props, loader, element=True, isotope=False, ion=False)

Delayed loading of an element property table. When any of property is first accessed the loader will be called to load the associated data. The help string starts out as the help string for the loader function. The attribute may be associated with any of Isotope, Ion, or Element. Some properties, such as mass, have both an isotope property for the mass of specific isotopes, as well as an element property for the mass of the collection of isotopes at natural abundance. Set the keyword flags element, isotope and/or ion to specify which of these classes will be assigned specific information on load.

periodictable.core.define_elements(table, namespace)

Define external variables for each element in namespace. Elements are defined both by name and by symbol.

This is called from __init__ as:

elements = core.default_table()
__all__  += core.define_elements(elements, globals())
Parameters:
table : PeriodicTable

Set of elements

namespace : dict

Namespace in which to add the symbols.

Returns:

[string, …] A sequence listing the names defined.

Note

This will only work for namespace globals(), not locals()!

periodictable.core.get_data_path(data)

Locate the directory for the tables for the named extension.

Parameters:
data : string

Name of the extension data directory. For example, the xsf extension has data in the ‘xsf’ data directory.

Returns:

string Path to the data.

periodictable.core.default_table(table=None)

Return the default table unless a specific table has been requested.

This is to be used in a context like:

def summary(table=None):
    table = core.default_table(table)
    ...
periodictable.core.change_table(atom, table)

Search for the same element, isotope or ion from a different table

periodictable.core.isatom(val)

Return true if value is an element, isotope or ion

periodictable.core.iselement(val)

Return true if value is an element or ion in natural abundance

periodictable.core.isisotope(val)

Return true if value is an isotope or isotope ion.

periodictable.core.ision(val)

Return true if value is a specific ion of an element or isotope