Nucleide Documentation

This directory contains durable documentation for Nucleide: a Rust toolkit for nuclear-engineering workflow glue, exposed through a typed Python API. The docs are organized by audience so you can find what you need without reading everything else.

Start with the project README for the feature list, status, and license.

How to use this index

New users → start with Getting started
Analysts parsing legacy code output → see the tutorials
Readers who want the physics/math → see the Theory pages
Developers contributing code → read Local development, then Contributing
Architects reviewing boundaries → start with Architecture overview
Release managers → see Roadmap and the changelog

Documentation structure

Tutorials

Document	Purpose
Tutorials	Tutorial index and suggested reading order
Getting started	Install Nucleide from PyPI and run your first Python snippet
Parse MCNP output	Read xsdir, meshtal, MCTAL, WWINP, PTRAC, and SSW files
Build materials	Build materials from formulae, mix compositions, and export XML
Run depletion	Load a depletion chain and run a short CRAM solve
Enrichment cascade	Set up and solve a multicomponent enrichment cascade
Interactive tutorials	Run Nucleide in the browser through the WASM build
Interactive — nuclides	Nuclide identifiers and nuclear data
Interactive — materials	Formulas, fractions, mixing, and XML export
Interactive — enrichment	Solve MARC cascades live
Interactive — depletion	One-step CRAM depletion
Interactive — MCNP I/O	Parse MCNP file snippets
Interactive — variance reduction	MAGIC bounds and alias-table sampling

Theory

Document	Purpose
Theory	Theory index and suggested reading order
Depletion	Burnup matrices, the Bateman equation, and CRAM
Enrichment cascades	MARC cascades, separation factors, and SWU
Variance reduction	MAGIC weight windows and alias-table source sampling
Nuclear data	Nuclide IDs, name dialects, masses, and half-lives

Reference

Document	Purpose
Reference	Reference index and quick links
Crate overview	One-line responsibilities for every workspace crate
Python API	Python facade overview and module map

Development

Document	Purpose
Local development	Toolchain, local build, test, and lint commands
Contributing	Branch workflow, commit style, and PR checklist
Cross-code validation	Reproduce the PyNE/OpenMC validation harness and measured tables

Architecture

Document	Purpose
Architecture overview	High-level system overview and layer boundaries
Crate responsibilities	Crate-level responsibilities and dependency rules

Plan

Document	Purpose
Roadmap	Current status and upcoming priorities
Decision log	Architecture and process decisions with rationale

Maintenance rules

Keep docs in sync with code. A PR that changes a public API, parser output, or crate boundary must update the matching tutorial or reference page.
Prefer deletion over stale historical notes. If a section no longer reflects current behavior, delete it or move it to an explicit “Historical” appendix with a removal date.
Do not duplicate details that live elsewhere. Link to the project README, API stubs, and fixture READMEs instead of copying them.
Use relative links. Internal links must be relative so documentation stays usable offline and in branches.
Use .mdx for component-heavy pages. Pages that use @nukehub/docs-kit shortcodes such as <Mermaid>, <Callout>, or <DataTable> must have an .mdx extension. Plain .md is fine for prose-only pages.
Every page sets title and sidebar.order in frontmatter. Without an explicit order the site sidebar falls back to alphabetical sorting. Keep the order values aligned with the reading order in the section index tables, and do not repeat the title as an in-body # heading (the site renders the frontmatter title as the page heading).

See the project AGENTS.md for ownership and contract details.