nuclide

The nuclide module defines the Nuclide class. Each Nuclide instance represents one nuclide, and can be contructed from a nuclide string or zzzaaassss canonical id. The class properties provide an easy way of extracting atomic number and mass information, as well as a clean name string. Furthermore, additional methods provide an access point for mass data of nuclides, and the decay data of radionuclides, if present in a specified dataset. The default decay dataset used if none is supplied to the constructor is rd.DEFAULTDATA.

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

>>> import radioactivedecay as rd

Nuclide

class radioactivedecay.nuclide.Nuclide(nuclide: str | int, decay_data: ~radioactivedecay.decaydata.DecayData = Decay dataset: icrp107_ame2020_nubase2020, contains SymPy data: True)

Nuclide instances serve as name and atomic number/mass parsing objects for any nuclide or element.

Parameters:

nuclide (str or int) – Specify the nuclide with either a name string (e.g. ‘H-3’, ‘H3’ or ‘3H’) or a canonical id (zzzaaassss format).
decay_data (DecayData, optional) – Decay dataset (default is the ICRP-107 dataset).

nuclide

Nuclide name string.

Type:: str

decay_data

Decay dataset.

Type:: DecayData

Examples

>>> rd.Nuclide('K-40')
Nuclide: K-40, decay dataset: icrp107_ame2020_nubase2020
>>> rd.Nuclide('K40')
Nuclide: K-40, decay dataset: icrp107_ame2020_nubase2020
>>> rd.Nuclide(190400000)
Nuclide: K-40, decay dataset: icrp107_ame2020_nubase2020
>>> rd.Nuclide(280560001)
Nuclide: Ni-56m, decay dataset: icrp107_ame2020_nubase2020

property A: int

Returns the mass number of the nuclide.

Returns:: Mass number of the nuclide.
Return type:: int

Examples

>>> H3 = rd.Nuclide('H-3')
>>> H3.A
3

property Z: int

Returns the atomic number of the nuclide.

Returns:: Atomic number of the nuclide.
Return type:: int

Examples

>>> H3 = rd.Nuclide('H-3')
>>> H3.Z
1

property atomic_mass: float

Returns the atomic mass of the nuclide, in g/mol.

Returns:: Atomic mass of the nuclide in g/mol.
Return type:: float

Examples

>>> H3 = rd.Nuclide('H-3')
>>> H3.atomic_mass
3.01604928132
>>> Ba137m = rd.Nuclide('Ba-137m')
>>> Ba137m.atomic_mass
136.9065375271172

branching_fractions() → List[float]

Returns the branching fractions to the direct progeny of a radionuclide.

Returns:: List of branching fractions.
Return type:: list

Examples

>>> K40 = rd.Nuclide('K-40')
>>> K40.branching_fractions()
[0.8914, 0.1086]

decay_modes() → List[str]

Returns the decay modes for a radionuclide, as defined in the decay dataset. 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 parent to progeny decay type (e.g. ‘α’, ‘β-’ or ‘IT’).

Returns:: List of decay modes.
Return type:: list

Examples

>>> K40 = rd.Nuclide('K-40')
>>> K40.decay_modes()
['β-', 'β+ & EC']

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

Returns the half-life of a nuclide as a float in your chosen 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 a string of the half-life in human-readable units.
Returns:: Half-life of the nuclide.
Return type:: float or str

Examples

>>> K40 = rd.Nuclide('K-40')
>>> K40.half_life('y')
1251000000.0
>>> K40.half_life('readable')
'1.251 By'
>>> Fe56 = rd.Nuclide('Fe-56')
>>> Fe56.half_life('readable')
'stable'

property id: int

Returns the canonical nuclide id, in zzzaaassss form. Ground state is 0000, first excited state (“m”) is 0001, second (“n”) is 0002, etc.

Returns:: Canonical id of the nuclide.
Return type:: int

Examples

>>> H3 = rd.Nuclide('H-3')
>>> H3.id
10030000
>>> Ba137m = rd.Nuclide('Ba-137m')
>>> Ba137m.id
561370001

plot(label_pos: float = 0.5, fig: Figure | None = None, axes: Axes | None = None, kwargs_draw: Dict[str, Any] | None = None, kwargs_edge_labels: Dict[str, Any] | None = None) → Tuple[Figure, Axes]

Plots a diagram of the decay chain of a radionuclide. Then creates a NetworkX DiGraph and plot of it using NetworkX’s Matplotlib-based plotting functionality.

Some of the NetworkX default plotting parameters are changed to produce nice decay chain diagrams. However, users retain control over these parameters via kwargs_draw and kwargs_edge_labels. For more information on the various NetworkX plotting parameters, refer to its documentation.

Parameters:

label_pos (float, optional) – Position of labels along edges. Default is 0.5. If you find that edge labels are overlapping in the decay chain diagram, try increasing this parameter to e.g. 0.66.
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_draw – Keyword arguments for networkx.draw().
optional – Keyword arguments for networkx.draw().
**kwargs_edge_labels – Keyword arguments for networkx.draw_networkx_edge_labels().
optional – Keyword arguments for networkx.draw_networkx_edge_labels().

Returns:

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

progeny() → List[str]

Returns list of the direct progeny of the nuclide.

Returns:: List of the direct progeny of the nuclide, ordered by decreasing branching fraction.
Return type:: list

Examples

>>> K40 = rd.Nuclide('K-40')
>>> K40.progeny()
['Ca-40', 'Ar-40']

property state: str

Returns the metastable state character, i.e. ‘’ for ground state, ‘m’ for first metastable state, ‘n’ for second metastable state, etc..

Returns:: Metastable state character.
Return type:: str

Examples

>>> H3 = rd.Nuclide('H-3')
>>> H3.state
''
>>> Ba137m = rd.Nuclide('Ba-137m')
>>> Ba137m.state
'm'