NeutronOS

Nuclear Energy Unified Technology for Research, Operations & Networks

A modular digital platform for nuclear facilities that unifies model management, operations tracking, signal analysis, and knowledge retrieval — replacing fragmented workflows (paper logs, spreadsheets, phone calls) with integrated digital tools.

Built on top of Axiom (domain-agnostic platform framework). NeutronOS adds nuclear-specific knowledge, agents, facility packs, and tools.

Install

pip install neutron-os

That installs the whole platform: the neut CLI, the Model Corral, Materials Database, Facility Packs, the Experiment Manager, and the Axiom-provided chat / knowledge-retrieval / signal / publishing surfaces. No physics code required — operations tracking, experiment scheduling, the model registry, and knowledge retrieval all work on their own.

Verify:

neut --help                  # NeutronOS CLI
axi doctor                   # environment + dependency check (Axiom-provided)

NeutronOS bundles axiom-os-lm (the Axiom platform) and adds the nuclear-domain layer on top.

Physics codes (optional)

NeutronOS runs transport/physics codes through optional, pluggable adapters — per ADR-018 and ADR-044, each code is its own AEOS-conformant extension, shipped as a pip extra you install only when you run that code. NeutronOS is not tied to any one code; MCNP, MPACT, Serpent and others install the same way (neutron-os[mcnp], …) as their adapters ship.

OpenMC is the reference adapter. Install its extra (the wrapper) plus the native code:

pip install "neutron-os[openmc]"      # the Axiom OpenMC adapter (the extra)
conda install -c conda-forge openmc   # the native physics code; full Python API

Then both surfaces work — and the wrapper is non-shadowing, so plain OpenMC is untouched:

Prefer Docker to a local OpenMC build? The adapter has a Docker runner (kernel_options={"runner": "docker"} pulls openmc/openmc:latest) — skip the conda step entirely.

From source (developer install):

git clone https://rsicc-gitlab.tacc.utexas.edu/ut-computational-ne/neutron-os-core.git
cd neutron-os-core
pip install -e ".[all]"

# Or use the bootstrap script (creates venv, installs, sets up direnv)
./scripts/bootstrap.sh

See CONTRIBUTING.md for detailed setup. The first-day install walkthrough with troubleshooting lives at docs/guides/first-day-openmc-install.md.

What NeutronOS Does

NeutronOS ships nuclear-domain builtins; the AXI orchestrator, chat, signal, and publishing surfaces are provided by the underlying Axiom platform.

Researcher / Operator
    |
    v
neut model ──> Physics model registry (Model Corral)
    |             init, validate, add, search, generate, review, share...
    |
neut facility ──> Facility packs (NETL-TRIGA, MSRE, PWR-generic)
    |               Materials database, configurations, procedures
    |
neut experiment ──> Experiment Manager (neut exp) — sample lifecycle
    |
neut demo ──> Guided walkthroughs

  + Axiom-provided surfaces (chat assistant, signal pipeline, document
    publishing) layered on top via the Axiom platform.

Key Capabilities

Model Corral (24 CLI commands)

Physics model registry with auto-detection, validation, material generation, and collaboration:

neut model add ./input.i               # Auto-detect code type (MCNP, MPACT, etc.)
neut model validate ./input.i           # Validate model file
neut model search --code mcnp           # Search by code type
neut model list                         # Browse registered models
neut model materials --card UO2         # Generate MCNP/MPACT material cards
neut model materials                    # List verified materials (11 compositions)
neut model review <id>                  # Start collaborative review
neut model share <id>                   # Share via federation

All commands support --json. Full list: init, validate, add, clone, search, list, show, pull, lineage, diff, export, audit, generate, lint, sweep, materials, share, receive, review, reviews, resolve, invite, contributors, status.

Materials Database

11 verified compositions from authoritative references (PNNL-15870, NUREG/CR-6698, and facility-measured characterizations cited by page):

neut model materials                    # List all materials
neut model materials --card UO2         # Generate MCNP cards
neut model materials --card Zircaloy-4 --format mpact  # MPACT format

MaterialSource protocol with 5 sources and priority merging. Deterministic MCNP/MPACT card generation.

Facility Packs

Pre-built knowledge bundles for specific reactor types:

neut facility list                      # Available packs
neut facility install NETL-TRIGA        # Install a facility pack
neut facility show NETL-TRIGA           # Pack details
neut facility materials NETL-TRIGA      # Facility-specific materials
neut facility sync                      # Sync with upstream

Shipped packs: NETL-TRIGA, MSRE, PWR-generic. Each includes materials, configurations, and domain knowledge.

Interactive Chat (Axiom-provided)

Chat is provided by Axiom's AXI orchestrator, not a NeutronOS builtin. NeutronOS contributes the nuclear knowledge, materials database, and facility grounding.

Nuclear engineering assistant with tool calling and RAG grounding:

axi chat                               # Start interactive session
axi chat --resume                      # Continue last session
axi chat --simple                      # Read-only mode (no writes)

The assistant has access to the materials database, model registry, and facility knowledge. When asked about material compositions, it uses verified database values — never training data.

Signal Pipeline (Axiom-provided)

Signal ingestion is provided by Axiom's SCAN agent; there is no neut signal noun registered in NeutronOS today.

Proactive program awareness — ingest signals from multiple sources:

axi signal brief                       # Catch up on what happened
axi signal draft                       # Generate weekly changelog
axi signal status                      # Pipeline health
axi signal watch                       # Watch for new signals

Sources: voice memos, Microsoft Teams, GitLab, freetext. Extracts: decisions, action items, risks, blockers, deadlines, people mentions, technical concepts.

Document Publishing (Axiom-provided)

Document publishing is provided by Axiom's PRESS agent; there is no neut pub noun registered in NeutronOS today.

Markdown to DOCX lifecycle with review gates:

axi pub overview                       # Document ecosystem dashboard
axi pub publish report.md              # Generate + publish
axi pub review report.md               # Interactive review
axi pub status                         # Document status

CoreForge Bridge

Integration with CoreForge neutronics tools for MCNP model workflows.

Platform Features (via Axiom)

NeutronOS inherits all Axiom platform capabilities. These ship with the Axiom platform and are invoked as axi <noun> (not registered NeutronOS nouns):

Repository Structure

Neutron_OS/
├── src/neutron_os/           # Python package root
│   ├── cli.py                #   CLI entry point
│   └── extensions/builtins/  #   Builtin extensions
│       ├── model_corral/     #     Model Corral (neut model, neut facility)
│       ├── expman/           #     Experiment Manager (neut experiment / neut exp)
│       └── demo/             #     Guided walkthroughs (neut demo)
├── webapp/                   # Web experience
├── runtime/                  # Instance data (config, inbox, sessions)
├── tests/                    # Cross-cutting tests
├── docs/                     # Documentation — see docs/README.md
│   ├── prds/  specs/  adrs/  #   One folder per doc kind
│   └── guides/  runbooks/  reference/  strategy/  templates/
├── infra/                    # Deployment configs (K3D, Docker)
├── scripts/                  # Bootstrap and install scripts
└── pyproject.toml            # Package definition

The agent fleet (AXI/SCAN/TIDY/RIVET/TRIAGE/PRESS/CURIO/…), gateway/orchestrator, and shared infra helpers (axiom.infra.*) are provided by Axiom, not this repo.

Development

# Run all tests (1700+)
make test

# Run specific suites
pytest tests/ -v                                # Cross-cutting
pytest src/neutron_os/extensions/builtins/model_corral/tests/ -v  # Model Corral
pytest -m "not integration"                     # Unit only (runs as pre-push hook)

# Lint (must pass before push)
ruff check src/ tests/
ruff format src/ tests/

# Build
make build

Tech Stack

Design Principles

• Reactor-agnostic core with facility-specific configuration via packs
• Offline-first — queue locally, sync on restore
• Human-in-the-loop for all writes in safety-adjacent contexts
• No vendor lock-in — model-agnostic, cloud-agnostic, IDE-agnostic
• Provider pattern — swap implementations via config, not code changes
• Federation-native — every node is sovereign; invite = join as peer, not shared DB user

Documentation

docs/ holds one folder per document kind — start at the map in docs/README.md:

• Executive PRD — what we're building and why
• Master Tech Spec — how it's built
• ADR index — why it's this way (decision records)
• Glossary — what the words mean
• New PRD / spec / ADR? Start from docs/templates/; the portfolio-wide standard lives in the Axiom repo (docs/conventions/doc-standards.md) and is audited by axi hygiene stat docs

Releases

Releases ship from tags to PyPI; the version badge above tracks the latest. See CHANGELOG.md for full release notes.

Contributing

See CONTRIBUTING.md for development workflow, git practices, and conventions.

License

Apache 2.0 — see LICENSE.

Acknowledgments

Developed at The University of Texas at Austin, Department of Mechanical Engineering — Nuclear & Radiation Engineering Program.