nuclide 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- nuclide-0.1.0/CONTRIBUTING.md +55 -0
- nuclide-0.1.0/LICENSE +21 -0
- nuclide-0.1.0/MANIFEST.in +5 -0
- nuclide-0.1.0/PKG-INFO +180 -0
- nuclide-0.1.0/README.md +149 -0
- nuclide-0.1.0/docs/data.md +107 -0
- nuclide-0.1.0/docs/unitx-feedback.md +99 -0
- nuclide-0.1.0/pyproject.toml +55 -0
- nuclide-0.1.0/setup.cfg +4 -0
- nuclide-0.1.0/src/nuclide/__init__.py +6 -0
- nuclide-0.1.0/src/nuclide/_data.py +36 -0
- nuclide-0.1.0/src/nuclide/_nuclide.py +300 -0
- nuclide-0.1.0/src/nuclide/data/NOTICE.md +33 -0
- nuclide-0.1.0/src/nuclide/data/nubase2020.json +93281 -0
- nuclide-0.1.0/src/nuclide/data/nubase_4.mas20.txt.gz +0 -0
- nuclide-0.1.0/src/nuclide/py.typed +0 -0
- nuclide-0.1.0/src/nuclide.egg-info/PKG-INFO +180 -0
- nuclide-0.1.0/src/nuclide.egg-info/SOURCES.txt +23 -0
- nuclide-0.1.0/src/nuclide.egg-info/dependency_links.txt +1 -0
- nuclide-0.1.0/src/nuclide.egg-info/requires.txt +8 -0
- nuclide-0.1.0/src/nuclide.egg-info/top_level.txt +1 -0
- nuclide-0.1.0/tests/test_data.py +104 -0
- nuclide-0.1.0/tests/test_identity.py +113 -0
- nuclide-0.1.0/tests/test_quantities.py +203 -0
- nuclide-0.1.0/tools/import_nubase.py +200 -0
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Use Python 3.12 or newer. From the repository root:
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
python -m venv .venv
|
|
7
|
+
source .venv/bin/activate
|
|
8
|
+
python -m pip install -e ".[test]"
|
|
9
|
+
python -m pytest
|
|
10
|
+
python -m ruff check .
|
|
11
|
+
python -m ruff format --check .
|
|
12
|
+
pyright
|
|
13
|
+
python -m build
|
|
14
|
+
python -m twine check --strict dist/*
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
On Windows, activate the environment with `.venv\Scripts\activate`.
|
|
18
|
+
|
|
19
|
+
Keep physical quantities explicit at public boundaries and make missing nuclear
|
|
20
|
+
data distinguishable from stability. New data must include a traceable source,
|
|
21
|
+
its version or retrieval date, and the meaning of any uncertainties or omitted
|
|
22
|
+
decay channels. Changes to decay calculations should include tests against
|
|
23
|
+
analytic results and physical conservation laws within the model's stated scope.
|
|
24
|
+
|
|
25
|
+
CI runs the test suite on Python 3.12–3.14, checks formatting and typing, and
|
|
26
|
+
builds both source and wheel distributions. It also imports the installed wheel
|
|
27
|
+
outside the source checkout to check that its nuclear data are included.
|
|
28
|
+
|
|
29
|
+
The Python implementation is MIT-licensed. The bundled NUBASE2020 evaluation
|
|
30
|
+
is distributed under CC BY 3.0; keep its attribution in
|
|
31
|
+
[`src/nuclide/data/NOTICE.md`](src/nuclide/data/NOTICE.md) with any redistributed
|
|
32
|
+
data. Source distributions include the original compressed evaluation and
|
|
33
|
+
`tools/import_nubase.py` so that the packaged JSON can be reproduced.
|
|
34
|
+
|
|
35
|
+
## Publishing
|
|
36
|
+
|
|
37
|
+
The repository uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
|
|
38
|
+
Before the first release, configure a pending publisher for project `nuclide` in
|
|
39
|
+
your PyPI account with these exact values:
|
|
40
|
+
|
|
41
|
+
| Setting | Value |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| GitHub owner | `DaitTHU` |
|
|
44
|
+
| Repository | `nuclide` |
|
|
45
|
+
| Workflow filename | `release.yml` |
|
|
46
|
+
| Environment | `pypi` |
|
|
47
|
+
|
|
48
|
+
Create the GitHub environment `pypi` to match that publisher. No PyPI API token
|
|
49
|
+
is needed in the repository.
|
|
50
|
+
|
|
51
|
+
For a release, update the version in `pyproject.toml`, run the checks above,
|
|
52
|
+
and commit the release. Push a tag matching that version, such as `v0.1.0`.
|
|
53
|
+
The release workflow checks the tag, runs the full CI workflow, and publishes
|
|
54
|
+
the distributions built by that run. Verify the resulting PyPI project and
|
|
55
|
+
install the released version in a fresh environment before announcing it.
|
nuclide-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Dait
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
nuclide-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: nuclide
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Natural, unit-aware operations on nuclides and radioactive decay
|
|
5
|
+
Author: Dait
|
|
6
|
+
License-Expression: MIT AND CC-BY-3.0
|
|
7
|
+
Project-URL: Source, https://github.com/DaitTHU/nuclide
|
|
8
|
+
Project-URL: Issues, https://github.com/DaitTHU/nuclide/issues
|
|
9
|
+
Keywords: nuclide,isotope,radioactivity,nuclear-physics,units
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Python: >=3.12
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
License-File: src/nuclide/data/NOTICE.md
|
|
23
|
+
Requires-Dist: unitx>=0.17.13
|
|
24
|
+
Provides-Extra: test
|
|
25
|
+
Requires-Dist: pytest; extra == "test"
|
|
26
|
+
Requires-Dist: ruff; extra == "test"
|
|
27
|
+
Requires-Dist: pyright; extra == "test"
|
|
28
|
+
Requires-Dist: build; extra == "test"
|
|
29
|
+
Requires-Dist: twine; extra == "test"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# nuclide
|
|
33
|
+
|
|
34
|
+
Nuclear data and radioactive decay calculations that read like physics.
|
|
35
|
+
|
|
36
|
+
```python
|
|
37
|
+
from nuclide import Nuclide
|
|
38
|
+
from unitx.si import si
|
|
39
|
+
|
|
40
|
+
rn = Nuclide("Rn222")
|
|
41
|
+
rn.Z, rn.N, rn.A # (86, 136, 222)
|
|
42
|
+
rn.half_life.to(si.d) # 3.8215 d (NUBASE2020)
|
|
43
|
+
rn.survival_fraction(rn.half_life) # 0.5
|
|
44
|
+
rn.activity(mass=1 * si.ug).to(si.Bq) # activity of pure Rn-222
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Install
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
pip install nuclide
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Python 3.12 or newer. The only runtime dependency is
|
|
54
|
+
[unitx](https://github.com/DaitTHU/unitx). Nuclear data are bundled: queries and
|
|
55
|
+
calculations work offline, with no NumPy or SciPy required.
|
|
56
|
+
|
|
57
|
+
For a local checkout before publication: `python -m pip install -e .`.
|
|
58
|
+
|
|
59
|
+
## A nuclide is an identity
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
assert Nuclide("Rn222") == Nuclide("Rn-222") == Nuclide("222Rn")
|
|
63
|
+
assert Nuclide("Tc99m") != Nuclide("Tc99")
|
|
64
|
+
|
|
65
|
+
rn = Nuclide("Rn222")
|
|
66
|
+
print(rn) # Rn-222
|
|
67
|
+
repr(rn) # "Nuclide('Rn-222')"
|
|
68
|
+
rn.element # 'Rn'
|
|
69
|
+
rn.state # '' (ground state); 'm' or 'n' for the first two isomers
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Objects are immutable and hashable, so they work as dictionary keys. The spellings
|
|
73
|
+
`Tc-99m`, `Tc99m1`, and `99mTc` identify the same first isomer; `m2` is an alias for
|
|
74
|
+
the source's second-isomer suffix `n`. Element symbols are case insensitive.
|
|
75
|
+
`Nuclide("n1")` denotes the free neutron.
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
from nuclide import nuclides
|
|
79
|
+
|
|
80
|
+
radon_states = nuclides("Rn")
|
|
81
|
+
stable_carbon = [n for n in nuclides("C") if n.is_stable]
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Unknown names and states outside the bundled evaluation raise `ValueError`.
|
|
85
|
+
|
|
86
|
+
## Physical properties carry units
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
rn.half_life.to(si.h)
|
|
90
|
+
rn.decay_constant.to("1/s")
|
|
91
|
+
rn.mean_lifetime.to(si.d)
|
|
92
|
+
rn.atomic_mass.to(si.u)
|
|
93
|
+
rn.mass_excess.to(si.keV)
|
|
94
|
+
rn.molar_mass.to(si.g / si.mol)
|
|
95
|
+
rn.specific_activity.to(si.Bq / si.g)
|
|
96
|
+
|
|
97
|
+
tc = Nuclide("Tc99m")
|
|
98
|
+
tc.excitation_energy.to(si.keV)
|
|
99
|
+
tc.spin_parity
|
|
100
|
+
tc.decay_modes # source descriptions, in percent
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Use `.to(unit)` to keep a quantity, or `.value_in(unit)` to get a scalar for
|
|
104
|
+
numerical code. `atomic_mass` is the **neutral atomic mass**, including electrons,
|
|
105
|
+
computed as `A * u + mass_excess / c**2`. It is not the bare nuclear mass.
|
|
106
|
+
|
|
107
|
+
## Count, mass, activity, and time
|
|
108
|
+
|
|
109
|
+
Each conversion takes exactly one named input. A nuclide carries no mutable
|
|
110
|
+
sample amount; you specify the amount for each calculation.
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
rn = Nuclide("Rn222")
|
|
114
|
+
|
|
115
|
+
count = rn.atoms(mass=1 * si.ug)
|
|
116
|
+
activity = rn.activity(atoms=count)
|
|
117
|
+
mass = rn.mass(activity=activity).to(si.ug)
|
|
118
|
+
|
|
119
|
+
remaining = count * rn.survival_fraction(7 * si.d)
|
|
120
|
+
remaining_activity = rn.activity(atoms=remaining)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
These are **single-parent, pure-isotope** calculations. Survival follows
|
|
124
|
+
`N(t) / N(0) = exp(-ln(2) * t / half_life)`, with no production, transport, or
|
|
125
|
+
daughter growth. Inputs must be finite, nonnegative scalars; times, masses and
|
|
126
|
+
activities must carry compatible units. Counts may be nonintegral expected
|
|
127
|
+
populations.
|
|
128
|
+
|
|
129
|
+
For stable nuclides the half-life is infinite, the decay constant and activity
|
|
130
|
+
are zero, and the survival fraction is one. Activity cannot determine a stable
|
|
131
|
+
nuclide's mass or atom count, so those inverse operations raise `ValueError`.
|
|
132
|
+
|
|
133
|
+
## Know what the evaluation says
|
|
134
|
+
|
|
135
|
+
The data are a fixed, attributed **NUBASE2020** snapshot, including ground states
|
|
136
|
+
and the first two isomers. Evaluated values, estimates, bounds, and missing values
|
|
137
|
+
remain distinct:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
rn.half_life_status # 'measured'
|
|
141
|
+
rn.half_life_text # source value and unit
|
|
142
|
+
rn.half_life_uncertainty_text # original uncertainty notation
|
|
143
|
+
rn.mass_is_estimated # source '#' flag
|
|
144
|
+
rn.mass_excess_uncertainty # tabulated energy uncertainty
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Estimated or approximate central values can be used in calculations; check
|
|
148
|
+
`half_life_status` and `mass_is_estimated` when that distinction matters. A
|
|
149
|
+
half-life given only as a limit, unknown, or particle-unstable without a lifetime
|
|
150
|
+
raises `DataUnavailableError` on numerical access. Uncertainties are not
|
|
151
|
+
propagated. Ground/isomer ordering qualifications remain in the bundled source
|
|
152
|
+
records; the package follows NUBASE labels.
|
|
153
|
+
|
|
154
|
+
`decay_modes` preserves source descriptions such as `A=100`. These descriptions
|
|
155
|
+
may overlap: beta-delayed particle emission can be part of a reported total beta
|
|
156
|
+
rate. They are **not** mutually exclusive, daughter-state-resolved branching
|
|
157
|
+
fractions. Version 0.1 does not compute full decay chains, daughter populations,
|
|
158
|
+
emission spectra, or dose/shielding quantities.
|
|
159
|
+
|
|
160
|
+
See [data provenance and conversion rules](docs/data.md). In particular, NUBASE
|
|
161
|
+
uses a tropical year of 31,556,926 seconds; input `si.yr` follows unitx's 365-day
|
|
162
|
+
definition. The package converts source lifetimes to seconds before calculation.
|
|
163
|
+
|
|
164
|
+
## Origin and license
|
|
165
|
+
|
|
166
|
+
This is a new Python implementation inspired by
|
|
167
|
+
[DaitTHU/Radiation](https://github.com/DaitTHU/Radiation), an undergraduate MATLAB
|
|
168
|
+
project. It keeps the idea of a natural nuclear-physics interface while using
|
|
169
|
+
evaluated data with explicit nuclear-state identities.
|
|
170
|
+
|
|
171
|
+
Python code: [MIT](LICENSE). NUBASE2020 data: separately attributed under
|
|
172
|
+
[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/), with the full source and
|
|
173
|
+
transformation notice in [NOTICE.md](src/nuclide/data/NOTICE.md).
|
|
174
|
+
|
|
175
|
+
F. G. Kondev, M. Wang, W. J. Huang, S. Naimi and G. Audi,
|
|
176
|
+
*The NUBASE2020 evaluation of nuclear physics properties*, Chinese Physics C
|
|
177
|
+
**45**, 030001 (2021), [doi:10.1088/1674-1137/abddae](https://doi.org/10.1088/1674-1137/abddae).
|
|
178
|
+
|
|
179
|
+
Development commands and publishing setup are in [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
180
|
+
Notes from using unitx for these workflows are in [unitx feedback](docs/unitx-feedback.md).
|
nuclide-0.1.0/README.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# nuclide
|
|
2
|
+
|
|
3
|
+
Nuclear data and radioactive decay calculations that read like physics.
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
from nuclide import Nuclide
|
|
7
|
+
from unitx.si import si
|
|
8
|
+
|
|
9
|
+
rn = Nuclide("Rn222")
|
|
10
|
+
rn.Z, rn.N, rn.A # (86, 136, 222)
|
|
11
|
+
rn.half_life.to(si.d) # 3.8215 d (NUBASE2020)
|
|
12
|
+
rn.survival_fraction(rn.half_life) # 0.5
|
|
13
|
+
rn.activity(mass=1 * si.ug).to(si.Bq) # activity of pure Rn-222
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
pip install nuclide
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Python 3.12 or newer. The only runtime dependency is
|
|
23
|
+
[unitx](https://github.com/DaitTHU/unitx). Nuclear data are bundled: queries and
|
|
24
|
+
calculations work offline, with no NumPy or SciPy required.
|
|
25
|
+
|
|
26
|
+
For a local checkout before publication: `python -m pip install -e .`.
|
|
27
|
+
|
|
28
|
+
## A nuclide is an identity
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
assert Nuclide("Rn222") == Nuclide("Rn-222") == Nuclide("222Rn")
|
|
32
|
+
assert Nuclide("Tc99m") != Nuclide("Tc99")
|
|
33
|
+
|
|
34
|
+
rn = Nuclide("Rn222")
|
|
35
|
+
print(rn) # Rn-222
|
|
36
|
+
repr(rn) # "Nuclide('Rn-222')"
|
|
37
|
+
rn.element # 'Rn'
|
|
38
|
+
rn.state # '' (ground state); 'm' or 'n' for the first two isomers
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Objects are immutable and hashable, so they work as dictionary keys. The spellings
|
|
42
|
+
`Tc-99m`, `Tc99m1`, and `99mTc` identify the same first isomer; `m2` is an alias for
|
|
43
|
+
the source's second-isomer suffix `n`. Element symbols are case insensitive.
|
|
44
|
+
`Nuclide("n1")` denotes the free neutron.
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
from nuclide import nuclides
|
|
48
|
+
|
|
49
|
+
radon_states = nuclides("Rn")
|
|
50
|
+
stable_carbon = [n for n in nuclides("C") if n.is_stable]
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Unknown names and states outside the bundled evaluation raise `ValueError`.
|
|
54
|
+
|
|
55
|
+
## Physical properties carry units
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
rn.half_life.to(si.h)
|
|
59
|
+
rn.decay_constant.to("1/s")
|
|
60
|
+
rn.mean_lifetime.to(si.d)
|
|
61
|
+
rn.atomic_mass.to(si.u)
|
|
62
|
+
rn.mass_excess.to(si.keV)
|
|
63
|
+
rn.molar_mass.to(si.g / si.mol)
|
|
64
|
+
rn.specific_activity.to(si.Bq / si.g)
|
|
65
|
+
|
|
66
|
+
tc = Nuclide("Tc99m")
|
|
67
|
+
tc.excitation_energy.to(si.keV)
|
|
68
|
+
tc.spin_parity
|
|
69
|
+
tc.decay_modes # source descriptions, in percent
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Use `.to(unit)` to keep a quantity, or `.value_in(unit)` to get a scalar for
|
|
73
|
+
numerical code. `atomic_mass` is the **neutral atomic mass**, including electrons,
|
|
74
|
+
computed as `A * u + mass_excess / c**2`. It is not the bare nuclear mass.
|
|
75
|
+
|
|
76
|
+
## Count, mass, activity, and time
|
|
77
|
+
|
|
78
|
+
Each conversion takes exactly one named input. A nuclide carries no mutable
|
|
79
|
+
sample amount; you specify the amount for each calculation.
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
rn = Nuclide("Rn222")
|
|
83
|
+
|
|
84
|
+
count = rn.atoms(mass=1 * si.ug)
|
|
85
|
+
activity = rn.activity(atoms=count)
|
|
86
|
+
mass = rn.mass(activity=activity).to(si.ug)
|
|
87
|
+
|
|
88
|
+
remaining = count * rn.survival_fraction(7 * si.d)
|
|
89
|
+
remaining_activity = rn.activity(atoms=remaining)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
These are **single-parent, pure-isotope** calculations. Survival follows
|
|
93
|
+
`N(t) / N(0) = exp(-ln(2) * t / half_life)`, with no production, transport, or
|
|
94
|
+
daughter growth. Inputs must be finite, nonnegative scalars; times, masses and
|
|
95
|
+
activities must carry compatible units. Counts may be nonintegral expected
|
|
96
|
+
populations.
|
|
97
|
+
|
|
98
|
+
For stable nuclides the half-life is infinite, the decay constant and activity
|
|
99
|
+
are zero, and the survival fraction is one. Activity cannot determine a stable
|
|
100
|
+
nuclide's mass or atom count, so those inverse operations raise `ValueError`.
|
|
101
|
+
|
|
102
|
+
## Know what the evaluation says
|
|
103
|
+
|
|
104
|
+
The data are a fixed, attributed **NUBASE2020** snapshot, including ground states
|
|
105
|
+
and the first two isomers. Evaluated values, estimates, bounds, and missing values
|
|
106
|
+
remain distinct:
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
rn.half_life_status # 'measured'
|
|
110
|
+
rn.half_life_text # source value and unit
|
|
111
|
+
rn.half_life_uncertainty_text # original uncertainty notation
|
|
112
|
+
rn.mass_is_estimated # source '#' flag
|
|
113
|
+
rn.mass_excess_uncertainty # tabulated energy uncertainty
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Estimated or approximate central values can be used in calculations; check
|
|
117
|
+
`half_life_status` and `mass_is_estimated` when that distinction matters. A
|
|
118
|
+
half-life given only as a limit, unknown, or particle-unstable without a lifetime
|
|
119
|
+
raises `DataUnavailableError` on numerical access. Uncertainties are not
|
|
120
|
+
propagated. Ground/isomer ordering qualifications remain in the bundled source
|
|
121
|
+
records; the package follows NUBASE labels.
|
|
122
|
+
|
|
123
|
+
`decay_modes` preserves source descriptions such as `A=100`. These descriptions
|
|
124
|
+
may overlap: beta-delayed particle emission can be part of a reported total beta
|
|
125
|
+
rate. They are **not** mutually exclusive, daughter-state-resolved branching
|
|
126
|
+
fractions. Version 0.1 does not compute full decay chains, daughter populations,
|
|
127
|
+
emission spectra, or dose/shielding quantities.
|
|
128
|
+
|
|
129
|
+
See [data provenance and conversion rules](docs/data.md). In particular, NUBASE
|
|
130
|
+
uses a tropical year of 31,556,926 seconds; input `si.yr` follows unitx's 365-day
|
|
131
|
+
definition. The package converts source lifetimes to seconds before calculation.
|
|
132
|
+
|
|
133
|
+
## Origin and license
|
|
134
|
+
|
|
135
|
+
This is a new Python implementation inspired by
|
|
136
|
+
[DaitTHU/Radiation](https://github.com/DaitTHU/Radiation), an undergraduate MATLAB
|
|
137
|
+
project. It keeps the idea of a natural nuclear-physics interface while using
|
|
138
|
+
evaluated data with explicit nuclear-state identities.
|
|
139
|
+
|
|
140
|
+
Python code: [MIT](LICENSE). NUBASE2020 data: separately attributed under
|
|
141
|
+
[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/), with the full source and
|
|
142
|
+
transformation notice in [NOTICE.md](src/nuclide/data/NOTICE.md).
|
|
143
|
+
|
|
144
|
+
F. G. Kondev, M. Wang, W. J. Huang, S. Naimi and G. Audi,
|
|
145
|
+
*The NUBASE2020 evaluation of nuclear physics properties*, Chinese Physics C
|
|
146
|
+
**45**, 030001 (2021), [doi:10.1088/1674-1137/abddae](https://doi.org/10.1088/1674-1137/abddae).
|
|
147
|
+
|
|
148
|
+
Development commands and publishing setup are in [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
149
|
+
Notes from using unitx for these workflows are in [unitx feedback](docs/unitx-feedback.md).
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Nuclear data
|
|
2
|
+
|
|
3
|
+
nuclide bundles a fixed **NUBASE2020** snapshot. Queries work offline and return
|
|
4
|
+
the same values across installations of a package version. The snapshot was
|
|
5
|
+
downloaded on 2026-11-16; this date does not make it a 2026 evaluation. NUBASE2020
|
|
6
|
+
considers experimental literature available through 2020-10-30.
|
|
7
|
+
|
|
8
|
+
The source is the [AMDC machine-readable NUBASE2020 table](https://nds.iaea.org/amdc/ame2020/nubase_4.mas20.txt).
|
|
9
|
+
The evaluation, its policies, and its state conventions are described in
|
|
10
|
+
[Kondev et al., Chinese Physics C 45, 030001 (2021)](https://doi.org/10.1088/1674-1137/abddae).
|
|
11
|
+
The [data attribution notice](../src/nuclide/data/NOTICE.md) contains the license,
|
|
12
|
+
source hash, and transformation summary. Code and data have separate licenses:
|
|
13
|
+
the Python implementation is MIT, and the NUBASE2020 content is CC BY 3.0.
|
|
14
|
+
|
|
15
|
+
## Coverage
|
|
16
|
+
|
|
17
|
+
The source contains 5,843 rows. This release includes **5,375 states**:
|
|
18
|
+
|
|
19
|
+
| State | Records |
|
|
20
|
+
| --- | ---: |
|
|
21
|
+
| Ground state | 3,555 |
|
|
22
|
+
| First isomer, `m` | 1,366 |
|
|
23
|
+
| Second isomer, `n` | 454 |
|
|
24
|
+
|
|
25
|
+
These are records in the evaluation, including estimated properties; the count
|
|
26
|
+
does not mean that every included nuclide has been experimentally observed.
|
|
27
|
+
The neutron is included as `n-1`. Higher isomers, other excited levels,
|
|
28
|
+
resonances, and isobaric analogue states are outside this release's scope.
|
|
29
|
+
The source uses some of the same labels for higher isomers and other levels,
|
|
30
|
+
so they are not automatically mapped to extra isomer numbers.
|
|
31
|
+
|
|
32
|
+
Among the ground/`m`/`n` candidates, 11 entries explicitly marked `RN`
|
|
33
|
+
(reported nonexistent) and 13 marked `EU` (existence uncertain) are omitted.
|
|
34
|
+
All 468 excluded rows, including unsupported states, are listed by name and
|
|
35
|
+
reason in the generated metadata. The unmodified compressed source retains
|
|
36
|
+
their complete information.
|
|
37
|
+
|
|
38
|
+
## Half-lives and qualifiers
|
|
39
|
+
|
|
40
|
+
`half_life_status` distinguishes the meaning of a value:
|
|
41
|
+
|
|
42
|
+
| Status | Meaning | Records |
|
|
43
|
+
| --- | --- | ---: |
|
|
44
|
+
| `measured` | Evaluated central value without a special qualifier | 4,507 |
|
|
45
|
+
| `estimated` | Value marked `#`, estimated from systematic trends | 413 |
|
|
46
|
+
| `approximate` | Value marked `~` | 28 |
|
|
47
|
+
| `stable` | Source reports `stbl` | 254 |
|
|
48
|
+
| `lower_limit` | Only a lower limit is given | 58 |
|
|
49
|
+
| `upper_limit` | Only an upper limit is given | 52 |
|
|
50
|
+
| `unknown` | No numerical half-life or recognized limit is given | 60 |
|
|
51
|
+
| `unstable` | Particle-unstable, with no numerical half-life | 3 |
|
|
52
|
+
|
|
53
|
+
Here `measured` describes the absence of a source qualifier; it does not imply
|
|
54
|
+
an exact value. Evaluated central values still have measurement uncertainties.
|
|
55
|
+
In NUBASE, `stbl` also covers a nuclide for which no finite half-life has been
|
|
56
|
+
established. It is not a proof of infinite physical lifetime.
|
|
57
|
+
|
|
58
|
+
For example, Rn-222 has `3.8215 d`, Tc-99m has `6.0066 h`, and B-18 has only
|
|
59
|
+
`<26 ns`. The importer preserves the last value as an upper limit, including
|
|
60
|
+
when the source places it in the uncertainty column. A bound is never promoted
|
|
61
|
+
to a measured half-life. Numerical decay calculations require a central value
|
|
62
|
+
or a source-stable state; missing values and bounds cannot determine a unique
|
|
63
|
+
decay constant.
|
|
64
|
+
|
|
65
|
+
The evaluation uses a **tropical year of 31,556,926 seconds**, as specified in
|
|
66
|
+
section 2.5 of the paper. This differs from a Julian year of 365.25 days.
|
|
67
|
+
The imported second values use the NUBASE convention. Converting a resulting
|
|
68
|
+
quantity into another library's year unit uses that unit's own definition.
|
|
69
|
+
|
|
70
|
+
`half_life_uncertainty_raw` preserves the source's uncertainty field, including
|
|
71
|
+
asymmetric errors and supplementary limits. `raw_line` preserves every original
|
|
72
|
+
fixed-width row. The current numerical API uses central values and does not
|
|
73
|
+
propagate uncertainties. Mass-excess estimates retain their `#` flag via
|
|
74
|
+
`mass_excess_estimated`; mass-excess uncertainty and excitation energy are also
|
|
75
|
+
stored in the data.
|
|
76
|
+
|
|
77
|
+
## Decay modes are descriptive data
|
|
78
|
+
|
|
79
|
+
The source's decay-mode strings are preserved. They are **not a complete set
|
|
80
|
+
of mutually exclusive transitions between specific nuclear states**.
|
|
81
|
+
For example, `B-=100;B-n=16` includes a delayed-neutron channel within the beta
|
|
82
|
+
decay total. Adding these values would double-count part of the decay.
|
|
83
|
+
An internal transition can also feed another isomer. Therefore this release
|
|
84
|
+
does not infer daughter nuclides, complete decay chains, or daughter buildup
|
|
85
|
+
from these strings. Parent survival calculations describe disappearance of
|
|
86
|
+
the initial nuclide only.
|
|
87
|
+
|
|
88
|
+
## Reproducing the bundle
|
|
89
|
+
|
|
90
|
+
The original text is included as a deterministic gzip file. From the repository
|
|
91
|
+
root, run:
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
python tools/import_nubase.py
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Or provide the uncompressed snapshot explicitly:
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
python tools/import_nubase.py /path/to/nubase_4.mas20.txt
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
The importer checks the source SHA-256 before conversion and generates
|
|
104
|
+
`src/nuclide/data/nubase2020.json` deterministically. It rejects unreviewed source
|
|
105
|
+
changes rather than silently replacing the data. Importing a different
|
|
106
|
+
evaluation requires reviewing its format and scientific changes, updating the
|
|
107
|
+
importer and provenance, and rerunning the data tests.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# unitx feedback from nuclear calculations
|
|
2
|
+
|
|
3
|
+
The initial nuclide implementation uses the published `unitx` 0.17.13 API.
|
|
4
|
+
Scalar calculations work without NumPy. The observations below come from
|
|
5
|
+
running a consumer against the installed wheel and checking its annotations
|
|
6
|
+
with Pyright; they distinguish useful existing behavior from possible
|
|
7
|
+
improvements. No changes to unitx are required for these calculations.
|
|
8
|
+
|
|
9
|
+
## Quantities compose naturally
|
|
10
|
+
|
|
11
|
+
Multiplication by a unit, ordinary arithmetic, and `.to()` cover the basic
|
|
12
|
+
nuclear calculations. `si` contains units; `SI` contains physical constants.
|
|
13
|
+
For example, with an illustrative half-life and atomic mass:
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
from math import log
|
|
17
|
+
|
|
18
|
+
from unitx import math as umath
|
|
19
|
+
from unitx.si import SI, si
|
|
20
|
+
|
|
21
|
+
half_life = 4.0 * si.d
|
|
22
|
+
atomic_mass = 222.0 * si.Da
|
|
23
|
+
decay_constant = log(2) / half_life
|
|
24
|
+
specific_activity = (decay_constant / atomic_mass).to(si.Bq / si.g)
|
|
25
|
+
molar_mass = (atomic_mass * SI.NA).to(si.g / si.mol)
|
|
26
|
+
|
|
27
|
+
atoms = ((1 * si.ug) / atomic_mass).n
|
|
28
|
+
activity = (atoms * decay_constant).to(si.Bq)
|
|
29
|
+
mass = (activity / decay_constant * atomic_mass).to(si.ug)
|
|
30
|
+
remaining_fraction = umath.exp(-decay_constant * half_life).n
|
|
31
|
+
assert remaining_fraction == 0.5
|
|
32
|
+
assert mass.isclose(1 * si.ug)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The numerical values here demonstrate the interface; they are not nuclear
|
|
36
|
+
reference data. In nuclide, the properties come from the bundled dataset.
|
|
37
|
+
|
|
38
|
+
`.n` explicitly extracts a coherent dimensionless number. It fits both a
|
|
39
|
+
number of atoms and a survival fraction. `.value_in(unit)` is the corresponding
|
|
40
|
+
boundary when passing a physical quantity to a numerical routine.
|
|
41
|
+
|
|
42
|
+
The example retains `Quantity[float]` for physical results and `float` for the
|
|
43
|
+
dimensionless results, without casts or forced numerical conversions.
|
|
44
|
+
A parameter annotated as `Quantity[float]` also accepts the natural integer
|
|
45
|
+
construction `1 * si.d`.
|
|
46
|
+
|
|
47
|
+
## Inverse-unit conversion is easy to mistype
|
|
48
|
+
|
|
49
|
+
The natural-looking expression below raises `TypeError`:
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
decay_constant.to(1 / si.s)
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`1 / si.s` constructs a quantity under unitx's number–unit arithmetic rules,
|
|
56
|
+
whereas `.to()` takes a unit or unit spelling. The supported forms are:
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
decay_constant.to(si.s**-1)
|
|
60
|
+
decay_constant.to("1/s")
|
|
61
|
+
activity.to(si.Bq)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
This behavior is consistent with the existing object model. A targeted error
|
|
65
|
+
message suggesting `si.s**-1` or `'1/s'` would make this common mistake easier
|
|
66
|
+
to correct.
|
|
67
|
+
|
|
68
|
+
## Curie is missing from the standard catalogue
|
|
69
|
+
|
|
70
|
+
`si.Bq` and its common SI prefixes are available. `si.Ci` and `si.uCi` raise
|
|
71
|
+
`AttributeError` in 0.17.13. Curie and its prefixes would be useful additions
|
|
72
|
+
for nuclear calculations. nuclide uses becquerels and does not modify unitx's
|
|
73
|
+
global registry on import.
|
|
74
|
+
|
|
75
|
+
## A year needs an explicit convention
|
|
76
|
+
|
|
77
|
+
In unitx, `si.yr` is exactly 365 days, while `si.a_j` is the Julian year of
|
|
78
|
+
365.25 days. A nuclear dataset's stated year convention must determine the
|
|
79
|
+
conversion; its `y` label cannot automatically be mapped to `si.yr`.
|
|
80
|
+
Both units are documented, but the difference is easy to miss in data imports.
|
|
81
|
+
|
|
82
|
+
NUBASE2020 specifically adopts a tropical year, giving `1 y = 31,556,926 s`.
|
|
83
|
+
Neither `si.yr` nor `si.a_j` matches that convention. nuclide converts the
|
|
84
|
+
dataset's year-based values to seconds using its stated factor. See
|
|
85
|
+
[NUBASE2020, section 2.3](https://cpc.ihep.ac.cn/en/article/doi/10.1088/1674-1137/abddae).
|
|
86
|
+
|
|
87
|
+
## Atomic mass and constants already fit
|
|
88
|
+
|
|
89
|
+
`si.u` and `si.Da` refer to the same atomic mass unit and display as `Da`.
|
|
90
|
+
`SI.c` is the speed-of-light quantity; `SI.NA` is the Avogadro constant.
|
|
91
|
+
An atomic mass excess can therefore be used directly:
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
atomic_mass = (mass_number * si.u + mass_excess / SI.c**2).to(si.u)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Multiplying an atomic mass by `SI.NA` derives its molar mass while retaining
|
|
98
|
+
the current constants. These are atomic masses, including the atomic
|
|
99
|
+
electrons; a nuclear mass requires a separate physical model.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "nuclide"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Natural, unit-aware operations on nuclides and radioactive decay"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
license = "MIT AND CC-BY-3.0"
|
|
12
|
+
license-files = ["LICENSE", "src/nuclide/data/NOTICE.md"]
|
|
13
|
+
authors = [{name = "Dait"}]
|
|
14
|
+
keywords = ["nuclide", "isotope", "radioactivity", "nuclear-physics", "units"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 3 - Alpha",
|
|
17
|
+
"Intended Audience :: Science/Research",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Programming Language :: Python :: 3.14",
|
|
23
|
+
"Topic :: Scientific/Engineering :: Physics",
|
|
24
|
+
"Typing :: Typed",
|
|
25
|
+
]
|
|
26
|
+
dependencies = ["unitx>=0.17.13"]
|
|
27
|
+
|
|
28
|
+
[project.optional-dependencies]
|
|
29
|
+
test = ["pytest", "ruff", "pyright", "build", "twine"]
|
|
30
|
+
|
|
31
|
+
[project.urls]
|
|
32
|
+
Source = "https://github.com/DaitTHU/nuclide"
|
|
33
|
+
Issues = "https://github.com/DaitTHU/nuclide/issues"
|
|
34
|
+
|
|
35
|
+
[tool.setuptools.packages.find]
|
|
36
|
+
where = ["src"]
|
|
37
|
+
|
|
38
|
+
[tool.setuptools.package-data]
|
|
39
|
+
nuclide = ["py.typed", "data/*.json", "data/NOTICE.md"]
|
|
40
|
+
|
|
41
|
+
[tool.pytest.ini_options]
|
|
42
|
+
testpaths = ["tests"]
|
|
43
|
+
addopts = "-ra"
|
|
44
|
+
|
|
45
|
+
[tool.ruff]
|
|
46
|
+
target-version = "py312"
|
|
47
|
+
line-length = 88
|
|
48
|
+
|
|
49
|
+
[tool.ruff.lint]
|
|
50
|
+
select = ["E4", "E7", "E9", "F", "I", "UP", "B"]
|
|
51
|
+
|
|
52
|
+
[tool.pyright]
|
|
53
|
+
include = ["src"]
|
|
54
|
+
pythonVersion = "3.12"
|
|
55
|
+
typeCheckingMode = "standard"
|
nuclide-0.1.0/setup.cfg
ADDED