Skip to content

nuclide

Nuclide name parsing, including the spellings the regulations use.

nuclide

Nuclide name parsing, validation and normalisation.

The canonical form used throughout this package is the one OpenMC and GND use, Co60 and Ag108_m1, because the most common source of an inventory is an OpenMC material and matching it avoids a translation layer at the boundary.

Regulatory tables spell nuclides differently again (Co-60, Ag-108m, U-238sec, Sr-90+), so parse_regulatory handles those and separates the secular-equilibrium marker from the nuclide identity.

Classes:

Functions:

  • parse –

    Split a nuclide name into element symbol, mass number and metastable level.

  • normalise –

    Return a nuclide name in canonical form.

  • parse_regulatory –

    Read a nuclide name as spelled in a regulatory table.

  • element –

    Return the element symbol of a nuclide, for example Co for Co60.

  • mass_number –

    Return the mass number of a nuclide, for example 60 for Co60.

  • metastable_state –

    Return the metastable level of a nuclide, 0 for a ground state.

  • atomic_number –

    Return the proton number of a nuclide, for example 27 for Co60.

  • is_valid –

    Whether a string can be read as a single nuclide.

NuclideNameError

Bases: ValueError

Raised when a string cannot be read as a single nuclide.

parse 

parse(name: str) -> tuple[str, int, int]

Split a nuclide name into element symbol, mass number and metastable level.

Parameters:

  • name

    (str) –

    A nuclide name in any accepted spelling, such as Co60, Co-60, Ag-108m or Ag108_m1.

Returns:

  • str –

    (symbol, mass_number, metastable_level), where the level is 0 for a

  • int –

    ground state and 1 or 2 for a metastable state. The symbol is returned

  • int –

    in its canonical capitalisation regardless of the input's.

Raises:

  • NuclideNameError –

    If the name is not a single nuclide. A bare element such as Fe raises, because a clearance limit applies to a nuclide and silently guessing a mass number would be wrong.

normalise 

normalise(name: str) -> str

Return a nuclide name in canonical form.

Co-60 and co 60 both become Co60; Ag-108m becomes Ag108_m1 and Hf-178n becomes Hf178_m2. A trailing + is stripped, since it marks a secular equilibrium value rather than a different nuclide, but sec is not accepted here because a sec value is a separate table entry. Use parse_regulatory when reading a regulatory table.

Parameters:

  • name

    (str) –

    A nuclide name in any accepted spelling.

Returns:

  • str –

    The canonical name, such as Co60 or Ag108_m1.

Raises:

parse_regulatory 

parse_regulatory(label: str) -> tuple[str, str | None]

Read a nuclide name as spelled in a regulatory table.

Regulatory tables mark parent nuclides whose limit already accounts for daughters in secular equilibrium, with + for the daughters tabulated alongside and sec for the whole decay chain. The marker is not part of the nuclide's identity but it does select a different limit value, so it is returned separately rather than discarded.

Parameters:

  • label

    (str) –

    A table cell such as Sr-90+, U-238sec or Th-232 sec.

Returns:

  • str –

    (canonical_name, marker) where marker is "+", "sec" or

  • str | None –

    None.

Raises:

element 

element(name: str) -> str

Return the element symbol of a nuclide, for example Co for Co60.

mass_number 

mass_number(name: str) -> int

Return the mass number of a nuclide, for example 60 for Co60.

metastable_state 

metastable_state(name: str) -> int

Return the metastable level of a nuclide, 0 for a ground state.

atomic_number 

atomic_number(name: str) -> int

Return the proton number of a nuclide, for example 27 for Co60.

is_valid 

is_valid(name: str) -> bool

Whether a string can be read as a single nuclide.