Periodic Table Module#

Classes and methods for getting data and properties of elements.

class nexus.periodic_table.ElementData(symbol: str, atomic_number: int, atomic_weight: float, group: int, isotopes: dict[int, float])[source]#

Bases: object

Dataclass for storing element data.

Methods

`neutrons`([mass_number])	Get the number of neutrons for the isotope with the given mass number.
`principle_isotope`()	Get the mass number and relative atomic weight of the most common isotope.
`protons`()	Alias for `self.atomic_number`.

symbol: str#

atomic_number: int#

atomic_weight: float#

group: int#

isotopes: dict[int, float]#

principle_isotope() → tuple[int, float][source]#

Get the mass number and relative atomic weight of the most common isotope.

Isotopic abundances defined by NIST [1].

Returns:

mass_numberint: Mass number of the most common isotope.
relative_atomic_massfloat: The relative atomic mass of the isotope.

References

[1]

https://www.nist.gov/pml/atomic-weights-and-isotopic-compositions-relative-atomic-masses

protons() → int[source]#: Alias for self.atomic_number.

neutrons(mass_number: int | None = None) → int[source]#

Get the number of neutrons for the isotope with the given mass number.

If no mass number is provided, this defaults to the most common isotope.

Warns:

NexusWarning: If mass number is not in the known isotopes for the element.

class nexus.periodic_table.Elements(*values)[source]#

Bases: ElementData, Enum

Enumeration of all elements in the periodic table.

Attributes:

symbolstr

In titlecase (H, He, …)

atomic_numberint

Use 0 for a dummy element (symbol “Xx”, name “Unknown”, all properties zero)

atomic_weightfloat

Average atomic weight in amu [1].

groupint

Group of the element on the periodic table. Lanthanides and Actinides are 0.

isotopesdict[int, float]

A dictionary of the isotopes for the element [2]. This can be accessed as Element.Name.isotopes[mass_number], which yields the relative atomic mass.

These dictionaries are sorted in order of decreasing isotopic abundance, as defined by NIST [2]. The code to generate the isotope dictionaries can be found at QMCPACK/qmcpack#6006.

Methods

`neutrons`([mass_number])	Get the number of neutrons for the isotope with the given mass number.
`principle_isotope`()	Get the mass number and relative atomic weight of the most common isotope.
`protons`()	Alias for `self.atomic_number`.

References

[1]

https://iupac.qmul.ac.uk/AtWt/

[2] (1,2)

https://www.nist.gov/pml/atomic-weights-and-isotopic-compositions-relative-atomic-masses

Examples

The fastest way to grab element data is with the following signatures:

>>> Elements("Hydrogen") is Elements.Hydrogen
True
>>> Elements("H") is Elements.Hydrogen
True
>>> Elements(1) is Elements.Hydrogen
True

If you’re unsure of the case of the input you can reliably get case-insensitive parsing with the default interface.

>>> Elements("h") is Elements.Hydrogen
True
>>> Elements("hydrogen") is Elements.Hydrogen
True

It can also handle leading and trailing whitespace

>>> Elements("Hydrogen ") is Elements.Hydrogen
True
>>> Elements(" H") is Elements.Hydrogen
True

If you think the input is up to one step from the correct signature, (e.g. Elements(int(val))) you can still expect the default call to work.

>>> Elements("1") is Elements.Hydrogen
True
>>> Elements(1.0) is Elements.Hydrogen
True

Printing an element calls its __str__ method which will return just the atomic symbol.

>>> print(Elements.Hydrogen)
H

This also works with f-strings and str.format calls.

>>> print(f"{Elements.Hydrogen}")
H

If you want to see the data attached to the enum member (minus the isotopes), use repr.

>>> print(repr(Elements.Hydrogen))
<Elements.Hydrogen: symbol='H', atomic_number=1, atomic_weight=1.008, group=1>

You can also get this view by just directly typing the element.

>>> Elements.Hydrogen
<Elements.Hydrogen: symbol='H', atomic_number=1, atomic_weight=1.008, group=1>

All functions defined for ElementData are accessible for members of this enum.

>>> Elements.Carbon.protons()
6
>>> Elements.Carbon.neutrons()
6
>>> Elements.Carbon.neutrons(mass_number=13)
7
>>> Elements.Carbon.most_common_isotope()
(12, 12.0)

static is_element(value: str, return_element: bool = False) → bool | tuple[bool, Elements][source]#

Robust method that will try to match a wide array of element identifier formats, including all that are handled by the parent call signature Elements(value).

Parameters:

valuestr: The string to be checked.
return_elementbool, default=False: Return the element that was identified. This will return value if it could not be identified as an element.

Examples

Regular elements

>>> Elements.is_element("H")
True
>>> Elements.is_element("He")
True

Elements with integer identifiers

>>> Elements.is_element("H1")
True
>>> Elements.is_element("H10")
True
>>> Elements.is_element("He1")
True
>>> Elements.is_element("He10")
True

Elements with integer identifiers and underscores

>>> Elements.is_element("H_1")
True
>>> Elements.is_element("H_10")
True
>>> Elements.is_element("He_1")
True
>>> Elements.is_element("He_10")
True

Elements with integer identifiers and hyphens

>>> Elements.is_element("H-1")
True
>>> Elements.is_element("H-10")
True
>>> Elements.is_element("He-1")
True
>>> Elements.is_element("He-10")
True

You can optionally return the element as well

>>> Elements.is_element("H_10", return_element=True)
(True, <Elements.Hydrogen: symbol='H', atomic_number=1, atomic_weight=1.008, group=1>)
>>> Elements.is_element("He-1", return_element=True)
(True, <Elements.Helium: symbol='He', atomic_number=2, atomic_weight=4.002602, group=18>)

If it can’t determine the element and you asked it to return the element then it will return False and the supplied value.

>>> Elements.is_element("Bean", return_element=True)
(False, 'Bean')

static num_elements() → int[source]#

Unknown = 0#

Hydrogen = 1#

Helium = 2#

Lithium = 3#

Beryllium = 4#

Boron = 5#

Carbon = 6#

Nitrogen = 7#

Oxygen = 8#

Fluorine = 9#

Neon = 10#

Sodium = 11#

Magnesium = 12#

Aluminum = 13#

Silicon = 14#

Phosphorus = 15#

Sulfur = 16#

Chlorine = 17#

Argon = 18#

Potassium = 19#

Calcium = 20#

Scandium = 21#

Titanium = 22#

Vanadium = 23#

Chromium = 24#

Manganese = 25#

Iron = 26#

Cobalt = 27#

Nickel = 28#

Copper = 29#

Zinc = 30#

Gallium = 31#

Germanium = 32#

Arsenic = 33#

Selenium = 34#

Bromine = 35#

Krypton = 36#

Rubidium = 37#

Strontium = 38#

Yttrium = 39#

Zirconium = 40#

Niobium = 41#

Molybdenum = 42#

Technetium = 43#

Ruthenium = 44#

Rhodium = 45#

Palladium = 46#

Silver = 47#

Cadmium = 48#

Indium = 49#

Tin = 50#

Antimony = 51#

Tellurium = 52#

Iodine = 53#

Xenon = 54#

Cesium = 55#

Barium = 56#

Lanthanum = 57#

Cerium = 58#

Praseodymium = 59#

Neodymium = 60#

Promethium = 61#

Samarium = 62#

Europium = 63#

Gadolinium = 64#

Terbium = 65#

Dysprosium = 66#

Holmium = 67#

Erbium = 68#

Thulium = 69#

Ytterbium = 70#

Lutetium = 71#

Hafnium = 72#

Tantalum = 73#

Tungsten = 74#

Rhenium = 75#

Osmium = 76#

Iridium = 77#

Platinum = 78#

Gold = 79#

Mercury = 80#

Thallium = 81#

Lead = 82#

Bismuth = 83#

Polonium = 84#

Astatine = 85#

Radon = 86#

Francium = 87#

Radium = 88#

Actinium = 89#

Thorium = 90#

Protactinium = 91#

Uranium = 92#

Neptunium = 93#

Plutonium = 94#

Americium = 95#

Curium = 96#

Berkelium = 97#

Californium = 98#

Einsteinium = 99#

Fermium = 100#

Mendelevium = 101#

Nobelium = 102#

Lawrencium = 103#

Rutherfordium = 104#

Dubnium = 105#

Seaborgium = 106#

Bohrium = 107#

Hassium = 108#

Meitnerium = 109#

Darmstadtium = 110#

Roentgenium = 111#

Copernicium = 112#

Nihonium = 113#

Flerovium = 114#

Moscovium = 115#

Livermorium = 116#

Tennessine = 117#

Oganesson = 118#