decaydata

The decaydata module defines the DecayData, DecayMatricesScipy and DecayMatricesSympy classes. DecayMatricesScipy and DecayMatricesSympy instances store data used for decay calculations and other inventory transformations (using double-precision floating point and SymPy arbitrary precision numbers, respectively). DecayData instances store DecayMatricesScipy, DecayMatricesSympy and unit converter objects, along with other decay data for reporting to users (this data is not used for calculations).

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

>>> import radioactivedecay as rd

Constants

DEFAULTDATADecayData: Default radioactive decay dataset used by radioactivedecay. This is currently ICRP-107 for decay data and AME2020 and Nubase2020 for atomic mass data.

radioactivedecay.decaydata.load_dataset(dataset_name: str, dir_path: str | None = None, load_sympy: bool = False) → DecayData

Load a decay dataset, either from a set of data files packaged within radioactivedecay, or by specifying a local directory containing the data files.

Parameters:

dataset_name (str) – Name of the decay dataset (or sub-package directory name).
dir_path (None or str, optional) – Path to the directory containing the decay dataset files. Use None to load data that are bundled as a sub-package of radioactivedecay (dataset_name should match the sub-package name in this case). Default is None.
load_sympy (bool, optional) – Load SymPy version of the decay data for arbitrary-precision decay calculations. Default is False.

Returns:

A decay dataset used by radioactivedecay.

Return type:

DecayData

DecayData

class radioactivedecay.decaydata.DecayData(dataset_name: str, bfs: ndarray, float_year_conv: float, hldata: ndarray, modes: ndarray, nuclides: ndarray, progeny: ndarray, scipy_data: DecayMatricesScipy, sympy_data: DecayMatricesSympy | None = None, sympy_year_conv: Expr | None = None)

Instances of DecayData store a complete radioactive decay dataset. It stores data for decay calculations and inventory transformations using DecayMatrices attributes. Other decay data which are reported to users but not used incalculations are stored in other instance attributes.

Parameters:

dataset_name (str) – Name of the decay dataset.
bfs (numpy.ndarray) – NumPy array of lists with branching fraction data.
float_year_conv (float) – Number of days in one year for float time unit conversions.
hldata (numpy.ndarray) – List of tuples containing half-life floats, time unit strings and readable format half-life strings.
modes (numpy.ndarray) – NumPy array of lists with decay mode data.
nuclides (numpy.ndarray) – NumPy array of nuclides in the dataset (string format is ‘H-3’, etc.).
progeny (numpy.ndarray) – NumPy array of lists with direct progeny data.
scipy_data (DecayMatricesScipy) – Dataset of double precision decay matrices (SciPy/NumPy objects).
sympy_data (None or DecayMatricesSympy) – Dataset of arbitrary-precision decay matrices (SymPy objects). Or None if SymPy functionality is not used. Default is None.
sympy_year_conv (None or Expr) – Number of days in one year for SymPy time unit conversions.

bfs

NumPy array of lists with branching fraction data.

Type:: numpy.ndarray

dataset_name

Name of the decay dataset.

Type:: str

float_year_conv

Number of days in one year for float time unit conversions.

Type:: float

hldata

List of tuples containing half-life floats, time unit strings and readable format half-life strings.

Type:: numpy.ndarray

modes

NumPy array of lists with decay mode data.

Type:: numpy.ndarray

nuclides

NumPy array of nuclides in the dataset (string format is ‘H-3’, etc.).

Type:: numpy.ndarray

nuclide_dict

Dictionary containing nuclide strings as keys and positions in the matrices as values.

Type:: dict

progeny

NumPy array of lists with direct progeny data.

Type:: numpy.ndarray

_scipy_data

Dataset of double precision decay matrices (SciPy/NumPy objects).

Type:: DecayMatricesScipy

_sympy_year_conv

Number of days in one year for SymPy time unit conversions.

Type:: None or Expr

branching_fraction(parent: str, progeny: str) → float

Returns the branching fraction for parent to progeny (if it exists).

Parameters:

parent (str) – Nuclide string of the parent.
progeny (str) – Nuclide string of the progeny (can be stable or radioactive nuclide).

Returns:

Branching fraction (or zero if progeny is not actually a direct progeny of parent).

Return type:

float

Examples

>>> rd.DEFAULTDATA.branching_fraction('K-40', 'Ca-40')
0.8914

decay_mode(parent: str, progeny: str) → str

Returns the type of decay mode between parent and progeny (if one exists). Note: the decay mode string returned is not a list of all the different radiation types emitted during the decay process between parent and progeny. It is the label defined in the decay dataset to classify the decay type (e.g. ‘α’, ‘β-’ or ‘IT’).

Parameters:

parent (str) – Nuclide string of the parent.
progeny (str) – Nuclide string of the progeny.

Returns:

Decay mode (or ‘’ if progeny is not actually a direct progeny of the parent).

Return type:

str

Examples

>>> rd.DEFAULTDATA.decay_mode('K-40', 'Ca-40')
'β-'

half_life(nuclide: str, units: str = 's') → float | str

Returns the half-life of the nuclide as a float in your chosen units, or as a human-readable string with appropriate units.

Parameters:

nuclide (str) – Nuclide string.
units (str, optional) – Units for half-life. Options are ‘ps’, ‘ns’, ‘μs’, ‘us’, ‘ms’, ‘s’, ‘m’, ‘h’, ‘d’, ‘y’, ‘ky’, ‘My’, ‘By’, ‘Gy’, ‘Ty’, ‘Py’, and common spelling variations. Default is ‘s’, i.e. seconds. Use ‘readable’ to get a string of the half-life in human-readable units.

Returns:

Nuclide half-life.

Return type:

float or str

Examples

>>> rd.DEFAULTDATA.half_life('Rn-222', 'd')
3.8235
>>> rd.DEFAULTDATA.half_life('H-3')
388781329.30560005
>>> rd.DEFAULTDATA.half_life('H-3', 'readable')
'12.32 y'
>>> rd.DEFAULTDATA.half_life('He-3')
inf
>>> rd.DEFAULTDATA.half_life('He-3', 'readable')
'stable'

property sympy_data: DecayMatricesSympy

Property to return DecayMatricesSympy instance if it exists, or raise an error if the dataset does not contain SymPy data.

Raises:: ValueError – If the DecayData instance does not contain any SymPy decay data.

property sympy_year_conv: Expr

Property to return SymPy number of days in one year if it exists, or raise an error if the dataset does not contain SymPy data.

Raises:: ValueError – If the DecayData instance does not contain any SymPy decay data.

DecayMatricesScipy

class radioactivedecay.decaydata.DecayMatricesScipy(atomic_masses: ndarray | MutableDenseMatrix, decay_consts: ndarray | MutableDenseMatrix, matrix_c: csr_matrix | MutableDenseMatrix, matrix_c_inv: csr_matrix | MutableDenseMatrix)

Bases: DecayMatrices

Version of DecayMatrices with data for SciPy double-precision floating point decay calculations.

Parameters:

atomic_masses (numpy.ndarray) – Column vector of the atomic masses (in g/mol).
decay_consts (numpy.ndarray) – Column vector of the decay constants (in s^-1).
matrix_c (scipy.sparse.csr.csr_matrix) – A pre-calculated sparse lower traingular matrix used in decay calculations.
matrix_c_inv (scipy.sparse.csr.csr_matrix) – The inverse of matrix_c, also used in decay calculations.

atomic_masses

Column vector of the atomic masses (in g/mol).

Type:: numpy.ndarray

decay_consts

Column vector of the decay constants (in s^-1).

Type:: numpy.ndarray

ln2

Constant natural logarithm of 2.

Type:: float

matrix_c

A precalculated sparse lower triangular matrix used in decay calculations.

Type:: scipy.sparse.csr.csr_matrix

matrix_c_inv

The inverse of matrix_c, also used in decay calculations.

Type:: scipy.sparse.csr.csr_matrix

matrix_e

The matrix exponential that is used in radioactive decay calculations. It is a diagonal matrix that is pre-allocted for performance reasons.

Type:: scipy.sparse.csr.csr_matrix

vector_n0

Column vector for the number of atoms of each nuclide. It is pre-allocted here to improve the performance of decay calculations.

Type:: numpy.ndarray

DecayMatricesSympy

class radioactivedecay.decaydata.DecayMatricesSympy(atomic_masses: ndarray | MutableDenseMatrix, decay_consts: ndarray | MutableDenseMatrix, matrix_c: csr_matrix | MutableDenseMatrix, matrix_c_inv: csr_matrix | MutableDenseMatrix)

Bases: DecayMatrices

Version of DecayMatrices with data for SymPy arbitrary precision decay calculations.

Parameters:

atomic_masses (sympy.matrices.dense.MutableDenseMatrix) – Column vector of the atomic masses (in g/mol).
decay_consts (sympy.matrices.dense.MutableDenseMatrix) – Column vector of the decay constants (in s^-1).
matrix_c (sympy.matrices.sparse.MutableSparseMatrix) – A pre-calculated sparse lower traingular matrix used in decay calculations.
matrix_c_inv (sympy.matrices.sparse.MutableSparseMatrix) – The inverse of matrix_c, also used in decay calculations.

atomic_masses

Column vector of the atomic masses (in g/mol).

Type:: sympy.matrices.dense.MutableDenseMatrix

decay_consts

Column vector of the decay constants (in s^-1).

Type:: sympy.matrices.dense.MutableDenseMatrix

ln2

Constant natural logarithm of 2.

Type:: sympy.log

matrix_c

A precalculated sparse lower triangular matrix used in decay calculations.

Type:: sympy.matrices.sparse.MutableSparseMatrix

matrix_c_inv

The inverse of matrix_c, also used in decay calculations.

Type:: sympy.matrices.sparse.MutableSparseMatrix

matrix_e

The matrix exponential that is used in radioactive decay calculations. It is a diagonal matrix that is pre-allocted for performance reasons.

Type:: sympy.matrices.sparse.MutableSparseMatrix

vector_n0

Column vector for the number of atoms of each nuclide. It is pre-allocted here to improve the performance of decay calculations.

Type:: sympy.matrices.dense.MutableDenseMatrix