Nucleide is a modern Rust toolkit for nuclear-engineering workflow glue: legacy transport-code I/O, nuclide identification, materials, CRAM depletion, and enrichment analytics — exposed through a typed Python API.
The project is a fresh Rust implementation of capabilities pioneered by
PyNE, focused on memory safety, fast builds,
and pip install-able wheels. Scope is intentionally narrow today and will
expand as more parsers and workflow pieces land.
pip install nucleidePrebuilt wheels cover Linux, macOS, and Windows for Python >= 3.10 (abi3). To build from source instead, see the Development section below.
Nuclear-engineering workflows spend most of their time moving data between
codes rather than solving transport itself. The established tooling for that
glue layer carries a heavy build chain (CMake + Fortran + Cython) and
hand-written parsers that are hard to extend and harder to embed. Nucleide
rebuilds the high-value subset in memory-safe Rust with one-command
pip install wheels, keeping Python as the user-facing API.
| Area | Capabilities |
|---|---|
Nuclide core (nuclei) |
Canonical nucid representation, particle registry, reaction-name registry (labels, MT mapping, hashes), name-dialect conversions (ZZAAAMM, ZAID/MCNP, Serpent, FLUKA, NIST, CINDER, ALARA, SZA), AME2020 masses, natural abundances, half-lives |
Materials (material) |
Compositions, mixing arithmetic, unit conversions, DOE/PNNL Materials Compendium loading, materials XML export |
MCNP I/O (mcnp-io) |
xsdir, meshtal, SSW/SURFSRC, PTRAC, WWINP, MCTAL readers; material extraction from input decks; mesh-to-geometry deck generation |
Serpent I/O (serpent-io) |
_res.m, _dep.m, _det.m readers producing structured records |
FLUKA I/O (fluka-io) |
USRBIN tally reader, material/compound card generation |
Depletion (depletion) |
CRAM (orders 16/48) matrix exponential, depletion-chain XML parsing |
Enrichment (enrichment) |
Multicomponent cascade solver (numeric), SWU closed-form helpers |
Variance reduction (vr-tools) |
MAGIC weight-window generation, mesh source sampling with alias tables |
| Python bindings | PyO3 extension module behind a typed pure-Python facade (nucleide._internal, .pyi stubs, py.typed) |
Transport solvers, Fortran discrete-ordinates ports, ENSDF evaluators, MOAB-dependent
meshing, and GUIs. Nucleide complements transport codes; it does not replace them.
nucleide/
├── crates/
│ ├── nuclei/ # nuclide ids, naming conventions, physical data
│ ├── material/ # compositions, mixing, libraries, XML export
│ ├── mcnp-io/ # xsdir/meshtal/SSW/MCTAL/PTRAC/WWINP
│ ├── serpent-io/ # res/dep/det readers
│ ├── fluka-io/ # usrbin reader, material cards
│ ├── vr-tools/ # MAGIC weight windows, source sampling
│ ├── enrichment/ # cascades, SWU
│ ├── depletion/ # CRAM + chain files
│ └── linalg/ # isolation facade over the linear-algebra backend
├── bindings/python/ # PyO3 crate -> nucleide._internal
├── python/nucleide/ # typed pure-Python facade (maturin mixed layout)
├── fixtures/ # golden-byte test data
├── validation/ # cross-code validation harness vs PyNE/OpenMC
└── tests/ # Python-side tests
git clone https://github.com/nukehub-dev/nucleide.git
cd nucleide
# Rust side
cargo test # workspace unit tests
cargo clippy --all-targets -- -D warnings
# Python side (needs: rustup, pip install maturin)
pip install maturin pytest pytest-cov ruff mypy
maturin develop # build + install into current venv
pytest tests/
# Lint / type-check / format the Python surface
ruff format python tests
ruff check python tests
mypy # strict type-check against .pyi stubs
# Rust coverage (needs llvm-tools-preview component)
cargo llvm-cov --workspace # or --lcov for CI upload| Layer | Format | Lint | Types | Coverage |
|---|---|---|---|---|
| Rust | rustfmt (cargo fmt) |
clippy -D warnings |
— | cargo-llvm-cov (CI) |
| Python | ruff format | ruff check | mypy --strict via .pyi stubs |
pytest-cov |
Wheels are built with maturin (PyO3 mixed layout). One wheel serves all Python >= 3.10 via abi3 — the same stack used by pydantic-core, polars, and ruff.
- Parsers are validated against golden-byte fixtures in
fixtures/; parser output must match recorded snapshots before any release. - Numeric kernels (CRAM, cascade solving) are checked against published
analytic vectors and cross-code results on shared inputs; the runnable
cross-code harness in
validation/compares Nucleide against PyNE and OpenMC and commits its measured results. - Behavioral compatibility with legacy tool output is asserted wherever a fixture exists, so downstream workflows see identical data.
Criterion benchmarks (cargo bench) cover the numeric kernels and parsers.
If you use Nucleide in research, see CITATION.cff and the
JOSS paper draft in paper.md.
Pre-alpha. APIs may change without notice.
Additional tutorials, reference pages, and developer guides live in the
docs/ tree.
Nucleide is a fresh Rust implementation of workflow-glue capabilities pioneered
by PyNE ("Python for Nuclear Engineering",
BSD-3-Clause). Some reference data and golden test fixtures — notably the
DOE/PNNL Materials Compendium — are vendored directly from PyNE; see
fixtures/data/MaterialsCompendium.LICENSE for its terms.