utils

The utils module contains functions to parse nuclide strings and manipulate lists and dictionaries.

The docstring code examples assume that radioactivedecay has been imported as rd:

>>> import radioactivedecay as rd

exception radioactivedecay.utils.NuclideStrError(nuclide: str, additional_message: str, *args)

Custom exception class for invalid nuclide strings.

Parameters:

nuclide (str) – Nuclide string.
additional_message (str) – Message with additional error context.

radioactivedecay.utils.Z_to_elem(Z: int) → str

Converts atomic number to element symbol.

Parameters:: Z (int) – Atomic number.
Returns:: Element string.
Return type:: str

Examples

>>> rd.utils.Z_to_elem(1)
'H'
>>> rd.utils.Z_to_elem(35)
'Br'

radioactivedecay.utils.add_dictionaries(dict_a: Dict[str, float | Expr], dict_b: Dict[str, float | Expr]) → Dict[str, float | Expr]

Adds together two dictionaries of nuclide strings and associated quantities. Supports both floats or SymPy quantities.

Parameters:

dict_a (dict) – First dictionary containing nuclide strings as keys and quantitites as values.
dict_b (dict) – Second dictionary containing nuclide strings as keys and quantitites as values.

Returns:

Combined dictionary containing the nuclides in both dict_a and dict_b, where the quantities have been added together when a nuclide is present in both input dictionaries.

Return type:

dict

Examples

>>> dict_a = {'Pm-141': 1.0, 'Rb-78': 2.0}
>>> dict_b = {'Pm-141': 3.0, 'Rb-90': 4.0}
>>> rd.utils.add_dictionaries(dict_a, dict_b)
{'Pm-141': 4.0, 'Rb-78': 2.0, 'Rb-90': 4.0}

radioactivedecay.utils.build_id(Z: int, A: int, state: str = '') → int

Builds a canonical nuclide id from atomic number, atomic mass, and and energy state.

Parameters:

Z (int) – Atomic number.
A (int) – Atomic mass.
state (str) – energy state.

Returns:

Canonical nuclide id.

Return type:

int

Raises:

ValueError – If the input energy state is invalid.

Examples

>>> rd.utils.build_id(1,2)
10020000
>>> rd.utils.build_id(28,56,'m')
280560001

radioactivedecay.utils.build_nuclide_string(Z: int, A: int, meta_state: str = '') → str

Builds a nuclide string from given atomic mass and number.

Parameters:

Z (int) – Atomic number.
A (int) – Atomic mass.
meta_state (str, optional) – Metastable state indicator character, ex. ‘m’ for the first atomic metastable state.

Returns:

Nuclide string built in symbol - mass number format.

Return type:

str

Raises:

ValueError – If the input atomic number is invalid.

Examples

>>> rd.utils.build_nuclide_string(26, 56)
'Fe-56'
>>> rd.utils.build_nuclide_string(28, 56, 'm')
'Fe-56m'

radioactivedecay.utils.elem_to_Z(sym: str) → int

Converts element symbol to atomic number.

Parameters:: sym (str) – Element string.
Returns:: Atomic number.
Return type:: int

Examples

>>> rd.utils.elem_to_Z('H')
1
>>> rd.utils.elem_to_Z('Br')
35

radioactivedecay.utils.get_metastable_chars() → List[str]

Returns list of allowed metastable state characters. Currently up to sixth metastable state is supported, based on the existence of sixth metastable state isomers in NUBASE2020, e.g. Lu-174x.

Note metastable state chars are “m”, “n”, “p”, “q”, “r”, “x” for the first to sixth metastable state, respectively, i.e. “o” is not a metastable state char, nor letters between “r” and “x”. See NUBASE2020 paper (F.G. Kondev et al 2021 Chinese Phys. C 45 030001) for more details.

radioactivedecay.utils.parse_id(input_id: int) → str

Parses a nuclide canonical id in zzzaaammmm format into symbol - mass number format.

Parameters:: input_id (int) – Nuclide in canonical id format.
Returns:: Nuclide string parsed in symbol - mass number format.
Return type:: str

Examples

>>> rd.utils.parse_id(190400000)
'K-40'
>>> rd.utils.parse_id(280560001)
'Ni-56m'

radioactivedecay.utils.parse_nuclide(input_nuclide: str | int, nuclides: ndarray, dataset_name: str) → str

Parses a nuclide string or canonical id into symbol - mass number format and checks whether the nuclide is contained in the decay dataset.

Parameters:

input_nuclide (str or int) – Nuclide name string or canonical id in zzzaaammmm format.
nuclides (numpy.ndarray) – List of all the nuclides in the decay dataset.
dataset_name (str) – Name of the decay dataset.

Returns:

Nuclide string parsed in symbol - mass number format.

Return type:

str

Raises:

ValueError – If the input nuclide string or id is invalid or the nuclide is not contained in the decay dataset.
TypeError – If the input is an invalid type, a string or integer is expected.

Examples

>>> rd.utils.parse_nuclide('222Rn', rd.DEFAULTDATA.nuclides, rd.DEFAULTDATA.dataset_name)
'Rn-222'
>>> rd.utils.parse_nuclide('Ba137m', rd.DEFAULTDATA.nuclides, rd.DEFAULTDATA.dataset_name)
'Ba-137m'
>>> rd.utils.parse_nuclide(280560001, rd.DEFAULTDATA.nuclides, rd.DEFAULTDATA.dataset_name)
'Ni-56m'

radioactivedecay.utils.parse_nuclide_str(nuclide: str) → str

Parses a nuclide string from e.g. ‘241Pu’ or ‘Pu241’ format to ‘Pu-241’ format. Note this function works for both radioactive and stable nuclides.

Parameters:: nuclide (str) – Nuclide string.
Returns:: Nuclide string parsed in symbol - mass number format.
Return type:: str
Raises:: NuclideStrError – If the input nuclide string is invalid.

Examples

>>> rd.utils.parse_nuclide_str('222Rn')
'Rn-222'
>>> rd.utils.parse_nuclide_str('Ca40')
'Ca-40'

radioactivedecay.utils.sort_dictionary_alphabetically(input_inv_dict: Dict[str, float | Expr]) → Dict[str, float | Expr]

Sorts a dictionary alphabetically by its keys.

Parameters:: input_inv_dict (dict) – Dictionary containing nuclide strings or Nuclide objects as keys and numbers as values.
Returns:: Inventory dictionary which has been sorted by the nuclides alphabetically.
Return type:: dict

Examples

>>> rd.utils.sort_dictionary_alphabetically({'U-235': 1.2, 'Tc-99m': 2.3, 'Tc-99': 5.8})
{'Tc-99': 5.8, 'Tc-99m': 2.3, 'U-235': 1.2}

radioactivedecay.utils.sort_list_according_to_dataset(input_list: List[str], key_dict: Dict[str, int]) → List[str]

Sorts a list of nuclides based on their order of appearence in the decay dataset.

Parameters:

input_list (list) – List of nuclide strings to be sorted.
key_dict (dict) – Dictionary from the decay dataset with nuclide strings as keys and their position (integers) in the decay dataset.

Returns:

Sorted nuclide list.

Return type:

list

Examples

>>> rd.utils.sort_list_according_to_dataset(['Tc-99', 'Tc-99m'], rd.DEFAULTDATA.nuclide_dict)
['Tc-99m', 'Tc-99']