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.
@@ -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.
@@ -0,0 +1,5 @@
1
+ include CONTRIBUTING.md
2
+ include tools/import_nubase.py
3
+ include src/nuclide/data/*.gz
4
+ recursive-include tests *.py
5
+ recursive-include docs *.md
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).
@@ -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"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+