inventory

The inventory module defines the Inventory and InventoryHP classes. Instances of these classes contain one or more nuclides each with an associated amount (number of atoms). The decay of the nuclide(s) can be calculated by using the decay() method. The Inventory class performs calculations using double-precision floats. The InventoryHP class performs calculations using SymPy high numerical precision operations. A DecayData dataset is associated with Inventory and InventoryHP instances (default is rd.DEFAULTDATA).

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

>>> import radioactivedecay as rd

Inventory

class radioactivedecay.inventory.Inventory(contents: ~typing.Dict[str | int | ~radioactivedecay.nuclide.Nuclide, float | ~sympy.core.expr.Expr], units: str = 'Bq', check: bool = True, decay_data: ~radioactivedecay.decaydata.DecayData = Decay dataset: icrp107_ame2020_nubase2020, contains SymPy data: True)

Bases: AbstractInventory

Inventory instances store nuclides and associated quantities (numbers of atoms) in the contents dictionary. A decay dataset is associated with each instance.

Parameters:

contents (dict) – Dictionary containing nuclide strings/canonical ids or Nuclide instances as keys and quantities (activities, number of atoms, masses or moles) as values.
units (str, optional) – Units of the contents dictionary values. Specify either ‘num’ for number of atoms, or an activity, mass or moles unit. e.g. ‘Bq’, ‘kBq’, ‘Ci’, ‘g’, ‘kg’, ‘mol’, ‘kmol’. Default is ‘Bq’.
check (bool, optional) – Check for the validity of the contents dictionary (nuclides are in the decay dataset, and quantities provided are physical, etc.). Default is True.
decay_data (DecayData, optional) – Decay dataset (default is the ICRP-107 dataset).

contents

Dictionary containing nuclide strings as keys and number of atoms of each nuclide as values. Nuclides are sorted alphabetically in this dictionary.

Type:: dict

decay_data

Decay dataset.

Type:: DecayData

decay_matrices

Float/SciPy version of the DecayMatrices associated with the decay dataset.

Type:: DecayMatricesScipy

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq')
Inventory activities (Bq): {'I-123': 2.3, 'Tc-99m': 5.8}, decay dataset: icrp107_ame2020_nubase2020
>>> H3 = rd.Nuclide('H-3')
>>> rd.Inventory({H3: 3.0}, 'g')
Inventory activities (Bq): {'H-3': 1067957043281807.0}, decay dataset: icrp107_ame2020_nubase2020
>>> rd.Inventory({270570000: 7.2, 922380000: 21.1}, 'Ci')
Inventory activities (Bq): {'Co-57': 266400000000.0, 'U-238': 780700000000.0001}, decay dataset: icrp107_ame2020_nubase2020

activities(units: str = 'Bq') → Dict[str, float]

Returns a dictionary containing the activity of each nuclide within the inventory.

Parameters:: units (str, optional) – Activity units for output, e.g. ‘Bq’, ‘kBq’, ‘mBq’, ‘Ci’, ‘dpm’… Deafult is ‘Bq’.

Examples

>>> rd.Inventory({'Tc-99m': 2300, 'I-123': 5800}, 'Bq').activities('kBq')
{'I-123': 5.8, 'Tc-99m': 2.3}

activity_fractions() → Dict[str, float]

Returns a dictionary containing the activity fraction of each nuclide within the inventory.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').activity_fractions()
{'I-123': 0.7160493827160493, 'Tc-99m': 0.2839506172839506}

add(add_contents: Dict[str | int | Nuclide, float], units: str = 'Bq') → None

Adds a dictionary of nuclides and associated quantities (numbers/activities/masses/moles) to the inventory.

Parameters:

add_contents (dict) – Dictionary containing nuclide strings, canonical ids or Nuclide objects as keys and the amount of each nuclide (with specified units) as values which are added to the Inventory.
units (str, optional) – Units of the values in the dictionary (e.g. ‘Bq’, ‘Ci’, ‘g’, ‘mol’, ‘num’; ‘Bq’ is the default).

Examples

>>> inv = rd.Inventory({'H-3': 1.0}, 'Bq')
>>> inv.add({'C-14': 2.0}, 'kBq')
>>> inv.add({190400000: 20.0})
>>> inv.activities()
{'K-40': 20.0, 'C-14': 2000.0, 'H-3': 1.0}

branching_fractions() → Dict[str, List[float]]

Returns dictionary with the branching fractions of the direct progeny of the nuclides in the inventory.

Returns:: Dictionary with nuclide strings as keys and lists of the branching fractions to the direct progeny of each nuclide as values.
Return type:: dict

Examples

>>> inv = rd.Inventory({'C-14': 1.0, 'K-40': 2.0}, 'Bq')
>>> inv.branching_fractions()
{'C-14': [1.0], 'K-40': [0.8914, 0.1086])

cumulative_decays(decay_time: float, units: str = 's') → Dict[str, float]

Calculates the total number of decays of each nuclide in the inventory between t=0 and t=decay_time. Note no results are reported for stable nuclides, as cumulative decays is zero.

Parameters:

decay_time (float) – Decay time (calculates total number of decays over this period).
units (str, optional) – Units of decay_time (default is seconds). Options are ‘ns’, ‘us’, ‘ms’, ‘s’, ‘m’, ‘h’, ‘d’, ‘y’, ‘ky’, ‘My’, ‘Gy’, ‘Ty’, ‘Py’, and some of the common spelling variations of these time units.

Returns:

Dictionary containing nuclide strings as keys and total number of decays of each nuclide as values (floats).

Return type:

dict

Examples

>>> inv_t0 = rd.Inventory({'Sr-90': 10.0}, 'num')
>>> inv_t0.cumulative_decays(1.0, 'My')
{'Sr-90': 10.0, 'Y-90': 10.000000000000002}

decay(decay_time: float, units: str = 's') → Inventory

Returns a new inventory calculated from the radioactive decay of the current inventory for decay_time.

Parameters:

decay_time (float) – Decay time.
units (str, optional) – Units of decay_time (default is seconds). Options are ‘ns’, ‘us’, ‘ms’, ‘s’, ‘m’, ‘h’, ‘d’, ‘y’, ‘ky’, ‘My’, ‘Gy’, ‘Ty’, ‘Py’, and some of the common spelling variations of these time units.

Returns:

New Inventory after the radioactive decay.

Return type:

Inventory

Examples

>>> inv_t0 = rd.Inventory({'H-3': 1.0}, 'Bq')
>>> inv_t1 = inv_t0.decay(12.32, 'y')
>>> inv_t1.activities()
{'H-3': 0.5, 'He-3': 0.0}

decay_modes() → Dict[str, List[str]]

Returns dictionary with the decay modes of the direct progeny of the nuclides in the inventory. Note: the decay mode strings returned are not lists of all the different radiation types emitted during the parent to progeny decay processes. They are the labels defined in the decay dataset to classify the decay type (e.g. ‘α’, ‘β-’ or ‘IT’).

Returns:: Dictionary with nuclide strings as keys and lists of the decay modes of the parent nuclide
Return type:: dict

Examples

>>> inv = rd.Inventory({'C-14': 1.0, 'K-40': 2.0}, 'Bq')
>>> inv.decay_modes()
{'C-14': ['β-'], 'K-40': ['β-', 'β+ & EC'])

decay_time_series(time_period: float | ndarray, time_units: str = 's', time_scale: str = 'linear', decay_units: str = 'Bq', npoints: int = 501) → Tuple[List[float], Dict[str, List[float]]]

Returns a list, dict tuple with the initial isotope and all decay progeny decayed for the amount of time specified by time_period. The list contains the time data from the decay calculations, and the dict has the isotope as the key, with decay data contained in a list for the value.

Parameters:

time_period (Union[float, np.ndarray]) – Time to decay the chain for. If a float is given, <time_scale> and <npoints> is used to create an evenly spaced array of numbers. If an numpy ndarray is provided, the values contained within are used and <npoints> is ignored.
time_units (str, optional) – Units for time series. 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.
time_scale (str, optional) – The time axis scale type to apply (‘linear’ or ‘log’, default is ‘linear’).
decay_units (str, optional) – Units to use for the decayed values e.g. ‘Bq’, ‘kBq’, ‘Ci’, ‘g’, ‘mol’, ‘num’, ‘activity_frac’, ‘mass_frac’, ‘mol_frac’. Default is ‘Bq’.
npoints (None or int, optional) – Number of time points used to plot graph (default is 501 for normal precision decay calculations, or 51 for high precision decay calculations).

Returns:

List[float] – The time points of the decayed data
Dict[str, List[float]] – The isotopes as the key with the decay values as a list of floats

Raises:

ValueError – If the decay_units parameter is invalid.

Examples

>>> inv = rd.Inventory({'C-14': 1.0})
>>> time, data = inv.decay_time_series_pandas(time_period=10, time_units="ky", decay_units="mass_frac", npoints=4)
>>> time
[0.0, 3.3333333333333335, 6.666666666666667, 10.0]
>>> data
{'C-14': [1.0, 0.6667465897861368, 0.4445504227269143, 0.2964018201597633], 'N-14': [0.0, 0.3332534102138631, 0.5554495772730857, 0.7035981798402366]}

decay_time_series_pandas(time_period: float | ndarray, time_units: str = 's', time_scale: str = 'linear', decay_units: str = 'Bq', npoints: int = 501) → DataFrame

Returns a dataframe with the initial isotope and all decay progeny decayed for the amount of time specified by time_period.

Parameters:

time_period (Union[float, np.ndarray]) – Time to decay the chain for. If a float is given, <time_scale> and <npoints> is used to create an evenly spaced array of numbers. If an numpy ndarray is provided, the values contained within are used and <npoints> is ignored.
time_units (str, optional) – Units for time series. 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.
time_scale (str, optional) – The time axis scale type to apply (‘linear’ or ‘log’, default is ‘linear’).
decay_units (str, optional) – Units to use for the decayed values e.g. ‘Bq’, ‘kBq’, ‘Ci’, ‘g’, ‘mol’, ‘num’, ‘activity_frac’, ‘mass_frac’, ‘mol_frac’. Default is ‘Bq’.
npoints (None or int, optional) – Number of time points used to plot graph (default is 501 for normal precision decay calculations, or 51 for high precision decay calculations).

Returns:

Pandas DataFrame with the data of the decayed Inventory. Each isotope is its own column, with a row for each time increment. The time column is set as the index.

Return type:

pandas.DataFrame

Raises:

ValueError – If the decay_units parameter is invalid.

Examples

>>> inv = rd.Inventory({'C-14': 1.0})
>>> inv.decay_data_as_dataframe(time_period=10, time_units='ky', decay_units='mass_frac', npoints=4)
               C-14      N-14
Time (ky)
0.000000   1.000000  0.000000
3.333333   0.666747  0.333253
6.666667   0.444550  0.555450
10.000000  0.296402  0.703598

half_lives(units: str = 's') → Dict[str, float | str]

Returns dictionary of half-lives of the nuclides in the inventory in your chosen time units, or as a human-readable string with appropriate units.

Parameters:: 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 strings of the half-lives in human-readable units.
Returns:: Dictionary with nuclide strings as keys and half-life floats or human-readable half-life strings as values.
Return type:: dict

Examples

>>> inv = rd.Inventory({'C-14': 1.0, 'K-40': 2.0}, 'Bq')
>>> inv.half_lives('y')
{'C-14': 5700.0, 'K-40': 1251000000.0}
>>> inv.half_lives('readable')
{'C-14': '5.70 ky', 'K-40': '1.251 By'}

mass_fractions() → Dict[str, float]

Returns a dictionary containing the mass fraction of each nuclide within the inventory.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').mass_fractions()
{'I-123': 0.8736297770616593, 'Tc-99m': 0.12637022293834066}

masses(units: str = 'g') → Dict[str, float]

Returns a dictionary containing the mass of each nuclide within the inventory

Parameters:: units (str, optional) – Mass units for output, e.g. ‘Bq’, ‘g’, ‘kg’, ‘mg’, ‘ton’… Deafult is ‘g’.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').masses('pg')
{'I-123': 8.158243973887584e-05, 'Tc-99m': 1.1800869622748502e-05}

mole_fractions() → Dict[str, float]

Returns a dictionary containing the mole fraction of each nuclide within the inventory.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').mole_fractions()
{'I-123': 0.8476385041932588, 'Tc-99m': 0.15236149580674116}

moles(units: str = 'mol') → Dict[str, float]

Returns a dictionary containing the number of atoms of each nuclide within the inventory in moles.

Parameters:: units (str, optional) – Moles units, e.g. ‘mmol’, ‘mol’, ‘kmol’… Deafult is ‘mol’.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').moles()
{'I-123': 6.637813617983513e-19, 'Tc-99m': 1.1931350531142702e-19}

property nuclides: List[str]

Returns a list of the nuclides in the inventory.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').nuclides
['I-123', 'Tc-99m']

numbers() → Dict[str, float]

Returns a dictionary containing the number of atoms of each nuclide within the inventory.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').numbers()
{'I-123': 399738.47946141585, 'Tc-99m': 71852.27235544211}

plot(xmax: float, xunits: str = 's', xmin: float = 0.0, xscale: str = 'linear', yscale: str = 'linear', ymin: float = 0.0, ymax: float | None = None, yunits: str = 'Bq', display: str | List[str] = 'all', order: str = 'dataset', npoints: int = 501, fig: Figure | None = None, axes: Axes | None = None, **kwargs) → Tuple[Figure, Axes]

Plots a decay graph showing the change in activity of the inventory over time. Creates matplotlib fig, axes objects if they are not supplied. Returns fig, axes tuple.

Parameters:

xmax (float) – Maximum decay time on x-axis.
xunits (str, optional) – Units for decay times (default is ‘s’, i.e. seconds). Options are ‘ps’, ‘ns’, ‘us’, ‘ms’, ‘s’, ‘m’, ‘h’, ‘d’, ‘y’, ‘ky’, ‘My’, ‘Gy’, ‘Ty’, ‘Py’, and some of the common spelling variations of these time units.
xmin (float, optional) – Minimum decay time on x-axis (default is 0.0 for linear x-axis, 0.1 for log x-axis).
xscale (str, optional) – The time axis scale type to apply (‘linear’ or ‘log’, default is ‘linear’).
yscale (str, optional) – The y-axis scale type to apply (‘linear’ or ‘log’, default is ‘linear’).
ymin (float, optional) – Minimum value for the y-axis (default is 0.0 for yscale='linear', or 0.95x the minimum quantity that occurs over the decay period for yscale='log').
ymax (None or float, optional) – Maximum value for the y-axis. Default is None, which sets the limit to 1.05x the maximum quantity that occurs over the decay period.
yunits (str, optional) – Units to display on the y-axis e.g. ‘Bq’, ‘kBq’, ‘Ci’, ‘g’, ‘mol’, ‘num’, ‘activity_frac’, ‘mass_frac’, ‘mol_frac’. Default is ‘Bq’.
display (str or list, optional) – Only display the nuclides within this list on the graph. Use this parameter when you want to choose specific nuclide decay curves shown on the graph, either by supplying a string (to show one nuclide) or a list of strings (to show multiple). Default is ‘all’, which displays all nuclides present upon decay of the inventory.
order (str, optional) – Order to display the nuclide decay curves on the graph if you do not specify the order via the display parameter. Default order is by ‘dataset’, which follows the order of the nuclides in the decay dataset (highest to lowest nuclides in the decay chains). Use ‘alphabetical’ if you want the nuclides to be ordered alphabetically.
npoints (None or int, optional) – Number of time points used to plot graph (default is 501 for normal precision decay calculations, or 51 for high precision decay calculations).
fig (None or matplotlib.figure.Figure, optional) – matplotlib figure object to use, or None makes radioactivedecay create one (default is None).
axes (None or matplotlib.axes.Axes, optional) – matplotlib axes object to use, or None makes radioactivedecay create one (default is None).
**kwargs – All additional keyword arguments to supply to matplotlib plot() function.
optional – All additional keyword arguments to supply to matplotlib plot() function.

Returns:

fig (matplotlib.figure.Figure) – matplotlib figure object used to plot decay chain.
axes (matplotlib.axes.Axes) – matplotlib axes object used to plot decay chain.

Raises:

ValueError – If the order parameter is invalid.

progeny() → Dict[str, List[str]]

Returns dictionary with the direct progeny of the nuclides in the inventory.

Returns:: Dictionary with nuclide strings as keys and lists of the direct progeny of each nuclide, ordered by decreasing branching fraction, as values.
Return type:: dict

Examples

>>> inv = rd.Inventory({'C-14': 1.0, 'K-40': 2.0}, 'Bq')
>>> inv.progeny()
{'C-14': ['N-14'], 'K-40': ['Ca-40', 'Ar-40'])

Removes nuclide(s) from the inventory.

Parameters:: delete (str or int or Nuclide or list) – Nuclide string, canonical id, Nuclide object or list of nuclide strings, canonical ids or Nuclide objects to delete from the Inventory object.

Examples

>>> inv = rd.Inventory({'Be-10': 2.0, 'C-14': 3.0, 'H-3': 1.0, 'K-40': 4.0}, 'Bq')
>>> inv.remove('H-3')
>>> inv.activities()
{'Be-10': 2.0, 'C-14': 3.0, 'K-40': 4.0}
>>> inv.remove(['Be-10', 'K-40'])
>>> inv.activities()
{'C-14': 3.0}

subtract(sub_contents: Dict[str | int | Nuclide, float], units: str = 'Bq') → None

Subtracts a dictionary of nuclides and associated numbers/activities/masses from the inventory.

Parameters:

sub_contents (dict) – Dictionary containing nuclide strings or Nuclide objects as keys and the amount of each nuclide (with specified units) as values which are subtracted from the Inventory.
units (str, optional) – Units of the values in the dictionary (e.g. ‘Bq’, ‘Ci’, ‘g’, ‘mol’, ‘num’; ‘Bq’ is the default).

Examples

>>> inv = rd.Inventory({'K-40': 20.0, 'C-14': 2.0, 'H-3': 1.0}, 'Bq')
>>> inv.subtract({'H-3': 1.0})
>>> inv.subtract({190400000: 20.0})
>>> inv.activities()
{'C-14': 2.0, 'H-3': 0.0}

to_csv(filename: str | Path, units: str = 'Bq', delimiter: str = ',', write_units: bool = False, header: List[str] | None = None, encoding: str = 'utf-8') → None

Write the contents of the inventory to a CSV file.

The first column written is the nuclide, the second is the quantity of each nuclide in the chosen units (activity, mass, moles etc.), and optionally (if write_units=True) the third column is the unit.

Parameters:

filename (str or pathlib.Path) – The name or path of the file to write.
units (str, optional) – The units to output each nuclide quantity in. Default is ‘Bq’. Specify ‘num’ if you require the number of atoms of each nuclide.
delimiter (str, optional) – The delimiter to separate entries in the CSV file. Default is a comma. Specify ‘ ‘ for a tab-separated (i.e. TSV) file.
write_units (bool, optional) – Write a third column with the units of each nuclide quantity. Default is False.
header (None or str, optional) – Header row to write on first line of file. Default is None (i.e. no header row). If you want to include a header, pass a list of strings with the name for each column, e.g. ['nuclide', 'quantity', 'units'] if writing a units column.
encoding (str, optional) – Encoding of the file. Default is ‘utf-8’.

Raises:

ValueError – If the specified units are invalid.

InventoryHP

class radioactivedecay.inventory.InventoryHP(contents: ~typing.Dict[str | int | ~radioactivedecay.nuclide.Nuclide, float], units: str = 'Bq', check: bool = True, decay_data: ~radioactivedecay.decaydata.DecayData = Decay dataset: icrp107_ame2020_nubase2020, contains SymPy data: True)

Bases: AbstractInventory

InventoryHP instances store a dictionary of nuclides and associated numbers of atoms, and a DecayData instance of radioactive decay data. Uses SymPy high precision arithmetic for all calculations.

Parameters:

contents (dict) – Dictionary containing nuclide strings/canonical ids or Nuclide objects as keys and quantities as values.
units (str, optional) – Units of the values in the contents dictionary e.g. ‘Bq’, ‘kBq’, ‘Ci’, ‘g’, ‘mol’, ‘num’… (default is ‘Bq’).
check (bool, optional) – Check for the validity of contents and that the supplied decay dataset contains SymPy data (default is True).
data (DecayData, optional) – Decay dataset (default is the ICRP-107 dataset).
sympy_contents (dict, optional) – Version of the contents dictionary with SymPy expressions as values. Setting this requires that data (the decay dataset) contains SymPy data. radioactivedecay will create sympy_contents automatically from contents if None is supplied.

contents

Dictionary containing nuclide strings as keys and number of atoms of each nuclide as values. Nuclides are sorted alphabetically in this dictionary.

Type:: dict

data

Decay dataset.

Type:: DecayData

decay_matrices

SymPy DecayMatrices instance associated with the decay dataset.

Type:: DecayMatricesSympy

sig_fig

Number of significant figures for high precision decay calculations and plots. Deafult is 320.

Type:: int

unit_converter

SymPy version of a convertor for within different units.

Type:: UnitConverterSympy

Examples

>>> rd.InventoryHP({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq')
InventoryHP activities: {'I-123': 2.3, 'Tc-99m': 5.8}, decay dataset: icrp107
>>> H3 = rd.Nuclide('H-3')
>>> rd.InventoryHP({H3: 3.0} 'Bq')
InventoryHP activities: {'H-3': 3.0}, decay dataset: icrp107
>>> rd.InventoryHP({'U-238': 21.1, 'Co-57': 7.2}, 'Ci')
InventoryHP activities: {'Co-57': 7.2, 'U-238': 21.1}, decay dataset: icrp107

activities(units: str = 'Bq') → Dict[str, float]

Returns a dictionary containing the activity of each nuclide (as floats) within this InventoryHP instance.

Parameters:: units (str, optional) – Activity units for output, e.g. ‘Bq’, ‘kBq’, ‘mBq’, ‘Ci’, ‘dpm’… Deafult is ‘Bq’.

activity_fractions() → Dict[str, float]

Returns a dictionary containing the activity fraction of each nuclide within the inventory.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').activity_fractions()
{'I-123': 0.7160493827160493, 'Tc-99m': 0.2839506172839506}

add(add_contents: Dict[str | int | Nuclide, float], units: str = 'Bq') → None

Adds a dictionary of nuclides and associated quantities (numbers/activities/masses/moles) to the inventory.

Parameters:

add_contents (dict) – Dictionary containing nuclide strings, canonical ids or Nuclide objects as keys and the amount of each nuclide (with specified units) as values which are added to the Inventory.
units (str, optional) – Units of the values in the dictionary (e.g. ‘Bq’, ‘Ci’, ‘g’, ‘mol’, ‘num’; ‘Bq’ is the default).

Examples

>>> inv = rd.Inventory({'H-3': 1.0}, 'Bq')
>>> inv.add({'C-14': 2.0}, 'kBq')
>>> inv.add({190400000: 20.0})
>>> inv.activities()
{'K-40': 20.0, 'C-14': 2000.0, 'H-3': 1.0}

branching_fractions() → Dict[str, List[float]]

Returns dictionary with the branching fractions of the direct progeny of the nuclides in the inventory.

Returns:: Dictionary with nuclide strings as keys and lists of the branching fractions to the direct progeny of each nuclide as values.
Return type:: dict

Examples

>>> inv = rd.Inventory({'C-14': 1.0, 'K-40': 2.0}, 'Bq')
>>> inv.branching_fractions()
{'C-14': [1.0], 'K-40': [0.8914, 0.1086])

cumulative_decays(decay_time: float, units: str = 's') → Dict[str, float]

Calculates the total number of decays of each nuclide in the inventory between t=0 and t=decay_time. Uses SymPy high precision calculations. Note no results are reported for stable nuclides, as cumulative decays is zero.

Parameters:

decay_time (float) – Decay time (calculates total number of decays over this period).
units (str, optional) – Units of decay_time (default is seconds). Options are ‘ns’, ‘us’, ‘ms’, ‘s’, ‘m’, ‘h’, ‘d’, ‘y’, ‘ky’, ‘My’, ‘Gy’, ‘Ty’, ‘Py’, and some of the common spelling variations of these time units.

Returns:

Dictionary containing nuclide strings as keys and total number of decays of each nuclide as values (floats).

Return type:

dict

Raises:

ValueError – If self.sig_fig is set to be lower than 1.

Examples

>>> inv_t0 = rd.Inventory({'Sr-90': 10.0}, 'num')
>>> inv_t0.cumulative_decays(1.0, 'My')
{'Sr-90': 10.0, 'Y-90': 10.0}

decay(decay_time: float, units: str = 's') → InventoryHP

Decay calculation with high numerical precision. This uses SymPy arbitrary-precision arithmetic functions for the decay calculation. The results can be more accurate than a normal double precision float calculation with the Inventory class when the decay chains contain radionuclides with very similar half-lives or half-lives that differ by many orders of magnitude.

Parameters:

decay_time (float) – Decay time.
units (str, optional) – Units of decay_time (default is seconds). Options are ‘ns’, ‘us’, ‘ms’, ‘s’, ‘m’, ‘h’, ‘d’, ‘y’, ‘ky’, ‘My’, ‘Gy’, ‘Ty’, ‘Py’, and some of the common spelling variations of these time units.

Returns:

New high precision inventory after the radioactive decay.

Return type:

InventoryHP

Raises:

ValueError – If self.sig_fig is set to be lower than 1.

Examples

>>> inv_t0 = rd.InventoryHP({'Fm-257': 1.0})
>>> inv_t1 = inv_t0.decay(10.0, 'd')
>>> inv_t1.activities()
{'Ac-225': 0.0,
'Am-241': 9.985270042416324e-24,
'Am-245': 5.4061684195880344e-09,
...
'Fm-257': 0.9333548028364793,
...
}

decay_modes() → Dict[str, List[str]]

Returns dictionary with the decay modes of the direct progeny of the nuclides in the inventory. Note: the decay mode strings returned are not lists of all the different radiation types emitted during the parent to progeny decay processes. They are the labels defined in the decay dataset to classify the decay type (e.g. ‘α’, ‘β-’ or ‘IT’).

Returns:: Dictionary with nuclide strings as keys and lists of the decay modes of the parent nuclide
Return type:: dict

Examples

>>> inv = rd.Inventory({'C-14': 1.0, 'K-40': 2.0}, 'Bq')
>>> inv.decay_modes()
{'C-14': ['β-'], 'K-40': ['β-', 'β+ & EC'])

decay_time_series(time_period: float | ndarray, time_units: str = 's', time_scale: str = 'linear', decay_units: str = 'Bq', npoints: int = 501) → Tuple[List[float], Dict[str, List[float]]]

Returns a list, dict tuple with the initial isotope and all decay progeny decayed for the amount of time specified by time_period. The list contains the time data from the decay calculations, and the dict has the isotope as the key, with decay data contained in a list for the value.

Parameters:

time_period (Union[float, np.ndarray]) – Time to decay the chain for. If a float is given, <time_scale> and <npoints> is used to create an evenly spaced array of numbers. If an numpy ndarray is provided, the values contained within are used and <npoints> is ignored.
time_units (str, optional) – Units for time series. 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.
time_scale (str, optional) – The time axis scale type to apply (‘linear’ or ‘log’, default is ‘linear’).
decay_units (str, optional) – Units to use for the decayed values e.g. ‘Bq’, ‘kBq’, ‘Ci’, ‘g’, ‘mol’, ‘num’, ‘activity_frac’, ‘mass_frac’, ‘mol_frac’. Default is ‘Bq’.
npoints (None or int, optional) – Number of time points used to plot graph (default is 501 for normal precision decay calculations, or 51 for high precision decay calculations).

Returns:

List[float] – The time points of the decayed data
Dict[str, List[float]] – The isotopes as the key with the decay values as a list of floats

Raises:

ValueError – If the decay_units parameter is invalid.

Examples

>>> inv = rd.Inventory({'C-14': 1.0})
>>> time, data = inv.decay_time_series_pandas(time_period=10, time_units="ky", decay_units="mass_frac", npoints=4)
>>> time
[0.0, 3.3333333333333335, 6.666666666666667, 10.0]
>>> data
{'C-14': [1.0, 0.6667465897861368, 0.4445504227269143, 0.2964018201597633], 'N-14': [0.0, 0.3332534102138631, 0.5554495772730857, 0.7035981798402366]}

decay_time_series_pandas(time_period: float | ndarray, time_units: str = 's', time_scale: str = 'linear', decay_units: str = 'Bq', npoints: int = 501) → DataFrame

Returns a dataframe with the initial isotope and all decay progeny decayed for the amount of time specified by time_period.

Parameters:

time_period (Union[float, np.ndarray]) – Time to decay the chain for. If a float is given, <time_scale> and <npoints> is used to create an evenly spaced array of numbers. If an numpy ndarray is provided, the values contained within are used and <npoints> is ignored.
time_units (str, optional) – Units for time series. 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.
time_scale (str, optional) – The time axis scale type to apply (‘linear’ or ‘log’, default is ‘linear’).
decay_units (str, optional) – Units to use for the decayed values e.g. ‘Bq’, ‘kBq’, ‘Ci’, ‘g’, ‘mol’, ‘num’, ‘activity_frac’, ‘mass_frac’, ‘mol_frac’. Default is ‘Bq’.
npoints (None or int, optional) – Number of time points used to plot graph (default is 501 for normal precision decay calculations, or 51 for high precision decay calculations).

Returns:

Pandas DataFrame with the data of the decayed Inventory. Each isotope is its own column, with a row for each time increment. The time column is set as the index.

Return type:

pandas.DataFrame

Raises:

ValueError – If the decay_units parameter is invalid.

Examples

>>> inv = rd.Inventory({'C-14': 1.0})
>>> inv.decay_data_as_dataframe(time_period=10, time_units='ky', decay_units='mass_frac', npoints=4)
               C-14      N-14
Time (ky)
0.000000   1.000000  0.000000
3.333333   0.666747  0.333253
6.666667   0.444550  0.555450
10.000000  0.296402  0.703598

half_lives(units: str = 's') → Dict[str, float | str]

Returns dictionary of half-lives of the nuclides in the inventory in your chosen time units, or as a human-readable string with appropriate units.

Parameters:: 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 strings of the half-lives in human-readable units.
Returns:: Dictionary with nuclide strings as keys and half-life floats or human-readable half-life strings as values.
Return type:: dict

Examples

>>> inv = rd.Inventory({'C-14': 1.0, 'K-40': 2.0}, 'Bq')
>>> inv.half_lives('y')
{'C-14': 5700.0, 'K-40': 1251000000.0}
>>> inv.half_lives('readable')
{'C-14': '5.70 ky', 'K-40': '1.251 By'}

mass_fractions() → Dict[str, float]

Returns a dictionary containing the mass fraction of each nuclide within the inventory.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').mass_fractions()
{'I-123': 0.8736297770616593, 'Tc-99m': 0.12637022293834066}

masses(units: str = 'g') → Dict[str, float]

Returns a dictionary containing the mass of each nuclide (as floats) within this InventoryHP instance.

Parameters:: units (str, optional) – Mass units for output, e.g. ‘Bq’, ‘g’, ‘kg’, ‘mg’, ‘ton’… Deafult is ‘g’.

mole_fractions() → Dict[str, float]

Returns a dictionary containing the mole fraction of each nuclide within the inventory.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').mole_fractions()
{'I-123': 0.8476385041932588, 'Tc-99m': 0.15236149580674116}

moles(units: str = 'mol') → Dict[str, float]

Returns a dictionary containing the number of atoms of each nuclide (as floats) within this InventoryHP instance.

Parameters:: units (str, optional) – Moles units, e.g. ‘mmol’, ‘mol’, ‘kmol’… Deafult is ‘mol’.

property nuclides: List[str]

Returns a list of the nuclides in the inventory.

Examples

>>> rd.Inventory({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').nuclides
['I-123', 'Tc-99m']

numbers() → Dict[str, float]

Returns a dictionary containing the number of atoms of each nuclide (as floats) within this InventoryHP instance.

Examples

>>> rd.InventoryHP({'Tc-99m': 2.3, 'I-123': 5.8}, 'Bq').numbers()
{'I-123': 399738.47946141585, 'Tc-99m': 71852.27235544211}

plot(xmax: float, xunits: str = 's', xmin: float = 0.0, xscale: str = 'linear', yscale: str = 'linear', ymin: float = 0.0, ymax: float | None = None, yunits: str = 'Bq', display: str | List[str] = 'all', order: str = 'dataset', npoints: int = 51, fig: Figure | None = None, axes: Axes | None = None, **kwargs) → Tuple[Figure, Axes]

Plots a decay graph using high precision decay calculations. Only difference from normal precision decay plot (Inventory.plot()) is default npoints=51.

Parameters:

xmax (float) – Maximum decay time on x-axis.
xunits (str, optional) – Units for decay times (default is ‘s’, i.e. seconds). Options are ‘ps’, ‘ns’, ‘us’, ‘ms’, ‘s’, ‘m’, ‘h’, ‘d’, ‘y’, ‘ky’, ‘My’, ‘Gy’, ‘Ty’, ‘Py’, and some of the common spelling variations of these time units.
xmin (float, optional) – Minimum decay time on x-axis (default is 0.0 for linear x-axis, 0.1 for log x-axis).
xscale (str, optional) – The time axis scale type to apply (‘linear’ or ‘log’, default is ‘linear’).
yscale (str, optional) – The y-axis scale type to apply (‘linear’ or ‘log’, default is ‘linear’).
ymin (float, optional) – Minimum value for the y-axis (default is 0.0 for yscale='linear', or 0.95x the minimum quantity that occurs over the decay period for yscale='log').
ymax (None or float, optional) – Maximum value for the y-axis. Default is None, which sets the limit to 1.05x the maximum quantity that occurs over the decay period.
yunits (str, optional) – Units to display on the y-axis e.g. ‘Bq’, ‘kBq’, ‘Ci’, ‘g’, ‘mol’, ‘num’, ‘activity_frac’, ‘mass_frac’, ‘mol_frac’. Default is ‘Bq’.
display (str or list, optional) – Only display the nuclides within this list on the graph. Use this parameter when you want to choose specific nuclide decay curves shown on the graph, either by supplying a string (to show one nuclide) or a list of strings (to show multiple). Default is ‘all’, which displays all nuclides present upon decay of the inventory.
order (str, optional) – Order to display the nuclide decay curves on the graph if you do not specify the order via the display parameter. Default order is by ‘dataset’, which follows the order of the nuclides in the decay dataset (highest to lowest nuclides in the decay chains). Use ‘alphabetical’ if you want the nuclides to be ordered alphabetically.
npoints (None or int, optional) – Number of time points used to plot graph. Default is 51.
fig (None or matplotlib.figure.Figure, optional) – matplotlib figure object to use, or None makes radioactivedecay create one (default is None).
axes (None or matplotlib.axes.Axes, optional) – matplotlib axes object to use, or None makes radioactivedecay create one (default is None).
**kwargs – All additional keyword arguments to supply to matplotlib plot() function.
optional – All additional keyword arguments to supply to matplotlib plot() function.

Returns:

fig (matplotlib.figure.Figure) – matplotlib figure object used to plot decay chain.
axes (matplotlib.axes.Axes) – matplotlib axes object used to plot decay chain.

Raises:

ValueError – If the order parameter is invalid.

progeny() → Dict[str, List[str]]

Returns dictionary with the direct progeny of the nuclides in the inventory.

Returns:: Dictionary with nuclide strings as keys and lists of the direct progeny of each nuclide, ordered by decreasing branching fraction, as values.
Return type:: dict

Examples

>>> inv = rd.Inventory({'C-14': 1.0, 'K-40': 2.0}, 'Bq')
>>> inv.progeny()
{'C-14': ['N-14'], 'K-40': ['Ca-40', 'Ar-40'])

Removes nuclide(s) from the inventory.

Parameters:: delete (str or int or Nuclide or list) – Nuclide string, canonical id, Nuclide object or list of nuclide strings, canonical ids or Nuclide objects to delete from the Inventory object.

Examples

>>> inv = rd.Inventory({'Be-10': 2.0, 'C-14': 3.0, 'H-3': 1.0, 'K-40': 4.0}, 'Bq')
>>> inv.remove('H-3')
>>> inv.activities()
{'Be-10': 2.0, 'C-14': 3.0, 'K-40': 4.0}
>>> inv.remove(['Be-10', 'K-40'])
>>> inv.activities()
{'C-14': 3.0}

subtract(sub_contents: Dict[str | int | Nuclide, float], units: str = 'Bq') → None

Subtracts a dictionary of nuclides and associated numbers/activities/masses from the inventory.

Parameters:

sub_contents (dict) – Dictionary containing nuclide strings or Nuclide objects as keys and the amount of each nuclide (with specified units) as values which are subtracted from the Inventory.
units (str, optional) – Units of the values in the dictionary (e.g. ‘Bq’, ‘Ci’, ‘g’, ‘mol’, ‘num’; ‘Bq’ is the default).

Examples

>>> inv = rd.Inventory({'K-40': 20.0, 'C-14': 2.0, 'H-3': 1.0}, 'Bq')
>>> inv.subtract({'H-3': 1.0})
>>> inv.subtract({190400000: 20.0})
>>> inv.activities()
{'C-14': 2.0, 'H-3': 0.0}

to_csv(filename: str | Path, units: str = 'Bq', delimiter: str = ',', write_units: bool = False, header: List[str] | None = None, encoding: str = 'utf-8') → None

Write the contents of the inventory to a CSV file.

The first column written is the nuclide, the second is the quantity of each nuclide in the chosen units (activity, mass, moles etc.), and optionally (if write_units=True) the third column is the unit.

Parameters:

filename (str or pathlib.Path) – The name or path of the file to write.
units (str, optional) – The units to output each nuclide quantity in. Default is ‘Bq’. Specify ‘num’ if you require the number of atoms of each nuclide.
delimiter (str, optional) – The delimiter to separate entries in the CSV file. Default is a comma. Specify ‘ ‘ for a tab-separated (i.e. TSV) file.
write_units (bool, optional) – Write a third column with the units of each nuclide quantity. Default is False.
header (None or str, optional) – Header row to write on first line of file. Default is None (i.e. no header row). If you want to include a header, pass a list of strings with the name for each column, e.g. ['nuclide', 'quantity', 'units'] if writing a units column.
encoding (str, optional) – Encoding of the file. Default is ‘utf-8’.

Raises:

ValueError – If the specified units are invalid.