Elements

The elements module provides lookups for chemical elements and their isotopes.

class tacular.elements.Element(*values)

Bases: StrEnum

Enumeration of element symbols.

Ac = 'Ac'

Ag = 'Ag'

Al = 'Al'

Am = 'Am'

Ar = 'Ar'

As = 'As'

At = 'At'

Au = 'Au'

B = 'B'

Ba = 'Ba'

Be = 'Be'

Bh = 'Bh'

Bi = 'Bi'

Bk = 'Bk'

Br = 'Br'

C = 'C'

Ca = 'Ca'

Cd = 'Cd'

Ce = 'Ce'

Cf = 'Cf'

Cl = 'Cl'

Cm = 'Cm'

Cn = 'Cn'

Co = 'Co'

Cr = 'Cr'

Cs = 'Cs'

Cu = 'Cu'

Db = 'Db'

Ds = 'Ds'

Dy = 'Dy'

Er = 'Er'

Es = 'Es'

Eu = 'Eu'

F = 'F'

Fe = 'Fe'

Fl = 'Fl'

Fm = 'Fm'

Fr = 'Fr'

Ga = 'Ga'

Gd = 'Gd'

Ge = 'Ge'

H = 'H'

He = 'He'

Hf = 'Hf'

Hg = 'Hg'

Ho = 'Ho'

Hs = 'Hs'

I = 'I'

In = 'In'

Ir = 'Ir'

K = 'K'

Kr = 'Kr'

La = 'La'

Li = 'Li'

Lr = 'Lr'

Lu = 'Lu'

Lv = 'Lv'

Mc = 'Mc'

Md = 'Md'

Mg = 'Mg'

Mn = 'Mn'

Mo = 'Mo'

Mt = 'Mt'

N = 'N'

Na = 'Na'

Nb = 'Nb'

Nd = 'Nd'

Ne = 'Ne'

Nh = 'Nh'

Ni = 'Ni'

No = 'No'

Np = 'Np'

O = 'O'

Og = 'Og'

Os = 'Os'

P = 'P'

Pa = 'Pa'

Pb = 'Pb'

Pd = 'Pd'

Pm = 'Pm'

Po = 'Po'

Pr = 'Pr'

Pt = 'Pt'

Pu = 'Pu'

Ra = 'Ra'

Rb = 'Rb'

Re = 'Re'

Rf = 'Rf'

Rg = 'Rg'

Rh = 'Rh'

Rn = 'Rn'

Ru = 'Ru'

S = 'S'

Sb = 'Sb'

Sc = 'Sc'

Se = 'Se'

Sg = 'Sg'

Si = 'Si'

Sm = 'Sm'

Sn = 'Sn'

Sr = 'Sr'

Ta = 'Ta'

Tb = 'Tb'

Tc = 'Tc'

Te = 'Te'

Th = 'Th'

Ti = 'Ti'

Tl = 'Tl'

Tm = 'Tm'

Ts = 'Ts'

U = 'U'

V = 'V'

W = 'W'

Xe = 'Xe'

Y = 'Y'

Yb = 'Yb'

Zn = 'Zn'

Zr = 'Zr'

classmethod from_str(symbol)

Get Element enum from string

Return type:

Element

Parameters:

symbol (str)

class tacular.elements.ElementInfo(number, mass_number, symbol, mass, abundance, average_mass, is_monoisotopic)

Bases: object

Represents an element or specific isotope with its properties.

Parameters:

• number (int)

• mass_number (int | None)

• symbol (str)

• mass (float)

• abundance (float | None)

• average_mass (float)

• is_monoisotopic (bool | None)

number

Atomic number (number of protons)

mass_number

Atomic mass number (protons + neutrons), None for non-specific element

symbol

Element symbol (e.g., ‘C’, ‘H’, ‘O’)

mass

Isotopic mass in Daltons

abundance

Natural abundance as fraction (0.0-1.0), None for synthetic isotopes

average_mass

Average atomic mass for the element

is_monoisotopic

True if most abundant isotope, False if not, None if element is non-specific

abundance: float | None

average_mass: float

get_mass(monoisotopic=True)

Get the mass of this element isotope.

Parameters:

monoisotopic (bool) – If True, return isotopic mass; if False, return average mass

Return type:

float

is_monoisotopic: bool | None

property is_radioactive: bool

Return True if this isotope is radioactive (zero natural abundance).

mass: float

mass_number: int | None

property neutron_count: int

Calculate the number of neutrons in this isotope.

number: int

property proton_count: int

Return the number of protons (same as atomic number).

serialize(count)

Serialize the ElementInfo to a ProForma formula element compatible string.

Parameters:

count (int) – Number of atoms of this element

Return type:

str

symbol: str

to_dict(float_precision=6)

Convert the ElementInfo to a dictionary.

Parameters:

float_precision (int) – Number of decimal places for mass values

Return type:

dict[str, object]

update(**kwargs)

Return a new ElementInfo with updated fields.

Parameters:

**kwargs (object) – Field names and new values to update

Return type:

ElementInfo

class tacular.elements.ElementLookup(element_data)

Bases: object

Lookup class for element isotope data.

Supports multiple lookup formats: - (‘C’, 12) -> Carbon-12 - (‘C’, None) -> Most abundant carbon isotope (monoisotopic) - ‘C’ -> Most abundant carbon isotope - ‘13C’ -> Carbon-13 - ‘D’ -> Deuterium (2H) - ‘2H’ -> Deuterium - ‘T’ -> Tritium (3H)

If a specific isotope is not found, it will be automatically generated by adding/subtracting neutron masses from the monoisotopic isotope.

The underlying data structure is a dict with keys: tuple[str, int | None] where the second element is the mass number, or None for monoisotopic.

Parameters:

element_data (dict[tuple[Element, int | None], ElementInfo])

NEUTRON_MASS = 1.00866491595

get(key, default=None)

Get element info by key, or return default if not found.

Parameters:

• key (tuple[str | Element, int | None] | str | Element) – Key in various formats (see __getitem__)

• default (ElementInfo | None) – Value to return if key is not found

Return type:

ElementInfo | None

Returns:

ElementInfo or default if not found

get_all_isotopes(symbol)

Get all isotopes for an element symbol (excluding the None entry).

Parameters:

• symbol (str | Element) – Element symbol (e.g., ‘C’, ‘H’)

• include_generated – If True, include auto-generated isotopes (abundance=0)

Return type:

list[ElementInfo]

Returns:

List of ElementInfo for all isotopes, sorted by mass number

get_elements()

Get list of all element symbols in the lookup.

Return type:

list[str]

Returns:

Sorted list of unique element symbols

get_isotope(symbol, mass_number)

Get a specific isotope by symbol and mass number.

Parameters:

• symbol (str | Element) – Element symbol (e.g., ‘C’, ‘H’)

• mass_number (int) – Mass number (e.g., 13, 2)

• auto_generate – If True, generate missing isotopes automatically

Return type:

ElementInfo

Returns:

ElementInfo for the requested isotope

get_masses_and_abundances(key)

Return type:

list[tuple[float, float]]

Parameters:

key (str | Element | ElementInfo)

get_monoisotopic(symbol)

Get the most abundant (monoisotopic) isotope for an element.

Parameters:

symbol (str | Element) – Element symbol (e.g., ‘C’, ‘H’, ‘N’)

Return type:

ElementInfo

Returns:

ElementInfo for the most abundant isotope

get_neutron_offsets_and_abundances(key)

Return type:

list[tuple[int, float]]

Parameters:

key (str | Element | ElementInfo)

keys()

Get an iterable of all keys in the lookup.

Return type:

list[tuple[str, int | None]]

mass(key, monoisotopic=True)

Get the mass for an element/isotope.

IMPORTANT: If a specific isotope is provided (e.g., ‘13C’, (‘C’, 13)), always returns the exact isotope mass regardless of monoisotopic parameter. The monoisotopic parameter only applies when requesting by symbol alone (e.g., ‘C’).

Parameters:

• key (tuple[str | Element, int | None] | str | Element) – Element key (same formats as __getitem__)

• monoisotopic (bool) – Only applies when key is a symbol without mass number. If True, return monoisotopic mass. If False, return average mass.

Return type:

float

Returns:

Mass in Daltons

values()

Get an iterable of all ElementInfo values in the lookup.

Return type:

list[ElementInfo]

tacular.elements.parse_composition(comp_dict)

Parse a composition dictionary with string keys into ElementInfo keys.

Return type:

dict[ElementInfo, int]

Parameters:

comp_dict (Mapping[str, int])