Reference Guide

Isotope

Here we define an isotope, which is a more defined ZAID with physical attributes. Unlike ZAID, which should only be thought of as a fancy number that could, on a good day, represent an actual physical thing, Isotopes are a representation of the physical concept of an isotope. They are named appropriately, they can only be generated if they are known to exist, and they contain physical attributes.

Currently, these physical attributes are limited in scope, to limit the memory footprint of using these isotopes.

exception UnknownIsotopeError

Bases: ValueError

An error for when the required Isotope for creation isn’t in the database.

class Isotope(Z: int, A: int, m: int, /)

Bases: ZAID

An Isotope is a ZAID that has special information, because it is actually a physical isotope, like O16 or U235. It contains physical information about the physical isotope to assist in material generation. As a convention, an Isotope with Z>0 and A=m=0 represents the natural element with Z protons. While it is useful for material generation, and thus supported, users should use them with caution, since they do not actually represent objects that can be assigned nuclear properties, which is what most users of this package are expected to eventually want to do.

See also

isotopes.zaid.ZAID

For ZAID representation with Z, A and m

mass

Mass of a nucleus of this isotope, in unified atomic mass units (1u = 1g/mol). For elements, it is the abundance-weighted mass.

Type:

float

decay

Decay rate (1/s) of the isotope. That is ln(2)/half-life.

Type:

float

abundance

Fractional natural abundance of the isotope in nature. For elements, this is a dictionary for its naturally occuring isotopes.

Type:

float or dict[Isotope, float]

Examples

>>> from math import floor
>>> i1 = Isotope(6, 0, 0)
>>> floor(i1.mass)
12
>>> i1.abundance
{C12: 0.9894, C13: 0.0106}
>>> type(i1.mass)
<class 'float'>

classmethod from_int_with_fallback(num: int) → Isotope | ZAID

Tries to return an Isotope from an integer, and if fails reverts to ZAID.

Parameters:

num (int) – The number to try to transform

classmethod from_zaid(zaid: ZAID) → Isotope

Creates an Isotope from a ZAID.

Parameters:

zaid (ZAID) – The ZAID to transform.

classmethod from_zaid_with_fallback(zaid: ZAID) → Isotope | ZAID

Tries to return an Isotope from a ZAID, and if fails reverts to ZAID.

Parameters:

zaid (ZAID) – The ZAID to try and transform.

path = PosixPath('/home/runner/work/isotopes/isotopes/isotopes/nubase2020.csv')

ZAID

class ZAID(Z: int, A: int, m: int, /)

Bases: int

This is a numeric representation of a nuclear structure, i.e. the number of protons, nucleons and the isomeric state of the nucleus. Since this is only a representation, the value might not correspond to an actual physical isotope. A more rigid, and more memory-heavy implementation is given in Isotope.

Users should be aware that not all possible ZAIDs represent objects that can be used in all cases. Some programs/libraries do not include data even for real isotopes like C14, and some ZAIDs could be used by a user for their own purposes and be ill-suited when encountered by other programs. For example, if one’s library does not contain an isotope in a mixture you defined, you could have a problem when using a Monte Carlo program such as OpenMC, unless these isotopes are filtered out before use.

Parameters:

• Z (int) – The number of protons.

• A (int) – The total number of nucleons.

• m (int) – The isomeric state of the nucleus. 0 is the ground state, and up it goes. See the wikipedia page on the subject of isomers.

References

classmethod from_int(num: int) → T

Creates the object representation from its corresponding integer value.

classmethod from_name(s: str) → T

Creates the object representation from its corresponding symbol value or name.

property A: int

Number of nucleons in the nucleus.

property Z: int

Number of protons in the nucleus.

property m: int

Isomeric energy level. Isomers are two nuclei in different nuclear states, with the same number of each nucleon. They have different cross-sections and nuclear properties, like their decay modes. The 0 state is often the only stable isomer, though some materials have isomers that are more stable than their base state.

property name: str | None

The full name of this isotope, if it makes sense. Not all ZAIDs are actually representations of known isotopes.

property symbol: str | None

The symbolic representation of this isotope, if it makes sense. Not all ZAIDs are actually representations of known isotopes.

Returns:

Returns None iff this doesn’t represent a known isotope. For example, ZAID(15000,0,0) would not be recognized.

Return type:

str or None

Extreme Magic

To make importing isotopes easier, we have some extreme magic going on in our module’s __getattr__. It ensures that isotopes are created when imported by name. The auto-completion is possible because we also include a .pyi file with all of the possible isotope names. We test by regression that the list is up to date, so we can be quite sure that it represents all the possible Isotope values, too.

__getattr__(name)

This is somewhat a magic piece of code. Instead of having the entire landscape of possible isotopes in the namespace, this function only creates for you the isotopes you import directly. Using the __init__.pyi file, the user gets automatic completion from most static programs for all available isotopes.