axiom-ext-openmc 0.1.0

OpenMC physics-code extension for the Axiom platform

axiom-ext-openmc

OpenMC physics-code extension for the Axiom platform. Apache-2.0 · AEOS-conformant · works with or without Axiom present.

Per ADR-018 ("each physics code is its own AEOS-conformant Axiom extension; physics = native") and ADR-044 ("standalone-or-builtin extension distribution"), this package is the standalone wrapper that lets OpenMC participate in Axiom's federated compute primitives — without changing how OpenMC is normally used.

Why this exists

OpenMC by itself is a physics code — a CLI, a Python API, a binary, a set of input decks. Excellent at what it does. But on its own it's a lifeless digital organism: no error recovery beyond crash messages, no provenance beyond a statepoint.h5, no observability beyond stdout, no way to coordinate runs across federation peers, no signed receipt for the result.

Axiom changes what OpenMC is in four concrete ways once this package is installed:

1. Way easier to install. pip install axiom-ext-openmc is the integration step; entry-point discovery handles the rest. No manifest hand-editing, no manual import dance.
2. Way more flexible in form. Bare-metal, Docker container, SSH-to-peer, or federation-dispatched — all from the same wrapper without code changes.
3. More integrated. OpenMC composes with provenance, federation routing, classification gates, live observability, signed receipts, and RACI-managed automation — all of Axiom's nervous system.
4. More useful as a standalone entity. Even with no Axiom-aware consumer present, the wrapper acquires compositional value the moment any Axiom env exists on the host. Default-installed Axiom agents (M-O hygiene, AXI chat, PR-T publishing, D-FIB diagnostics) auto-engage with OpenMC runs — error recovery, output lifecycle, failure diagnosis — for free.

Axiom 'breathes life' into an otherwise lifeless digital organism. Axiom is the neural spark, nervous system, and heartbeat to the host it inhabits. (ADR-044 D6)

If you're already running OpenMC traditionally and have no Axiom env on your host, this package is invisible — your existing OpenMC workflows keep working unchanged. If you have any Axiom env, this package wires OpenMC into it without you needing to do anything more than installing the package.

What this package is, and is not

It IS	It IS NOT
A thin Python wrapper that exposes OpenMC as an Axiom CodeAdapter	A redistribution of OpenMC (you install OpenMC separately)
Discoverable by axiom.compute.adapters.get_adapter("openmc") after pip install (no manual import)	A replacement for OpenMC's CLI or Python API
A bridge for axi model run / federated dispatch + signed-receipt provenance	A required dependency for traditional OpenMC use
Apache-2.0 (this wrapper); MIT (OpenMC itself, separately installed)	A change to OpenMC's behavior — the wrapper does not shadow openmc.*

If you've never used Axiom and only want OpenMC, you don't need this package. If you have OpenMC installed and want it to compose with Axiom's federation, dispatch, and signed-receipt primitives, install this package and the rest is automatic.

Install

pip install axiom-ext-openmc

This installs the adapter Python code only. The OpenMC engine itself is a separate install — pick one of:

Form	Install	Notes
Native (recommended for daily use)	conda install -c conda-forge openmc	Fastest; full Python API + CLI
Docker (no native install required)	docker pull openmc/openmc:latest	Adapter pulls automatically when no native binary is found
SSH peer (Axiom federation)	install OpenMC on a peer; the adapter dispatches via SSH	Laptop-orchestrated, peer-executed

The adapter auto-detects what's available; force a runner with kernel_options["runner"] = "subprocess" | "docker" | "ssh:<peer>".

Use

Traditional OpenMC — completely unchanged

The wrapper is non-shadowing. If you have OpenMC installed natively, this is unaffected:

import openmc
openmc.run()  # works exactly as it always did

openmc -i geometry.xml -i materials.xml -i settings.xml

Axiom-routed dispatch — the bonus path

After pip install axiom-ext-openmc, the OpenMC adapter is discoverable from Axiom without any manual import:

from axiom.compute import dispatch, DispatchSpec

result = dispatch(DispatchSpec(
    model_id="my-model",
    composition_hash="sha256:...",
    kernel="openmc",          # discovered via importlib.metadata entry points
    peer_id="laptop",
    determinism_class="D-bit",
    determinism_state={
        "input_dir": "/path/to/openmc-input/",
        "n_particles": 100_000,
        "n_active_cycles": 50,
        "n_inactive_cycles": 20,
        "rng_seed": 42,
        "xs_library": "ENDF/B-VIII.0",
    },
    kernel_options={"runner": "docker"},  # or "subprocess" / "ssh:<peer>"
))
print(result.value_summary["k_eff"])

CLI surface (via Axiom or NeutronOS):

# From any Axiom-enabled CLI:
axi model run my-model --on local:openmc --tail

# Or NeutronOS:
neut model run my-model --on local:openmc --tail

What's in the box

• axiom_ext_openmc.adapter:OpenMCKernelAdapter — the CodeAdapter implementation, registered via [project.entry-points."axiom.compute.adapters"]
• axiom_ext_openmc.references — published reference k-eff/tally values (initially: ORNL TM-728 MSR references, Phase 5)
• axiom_ext_openmc.facility_packs/ — facility-specific OpenMC templates (Phase 2c+)
• axiom_ext_openmc.skills/ — MCP-callable tools for LLM-mediated input authoring + output parsing (Phase 2c+)
• axiom_ext_openmc._docker_runner_script — self-contained script bind-mounted into the openmc/openmc container

Versioning + compatibility

• Python: 3.11+
• axiom-os-lm >= 0.15.0 (entry-point discovery for adapters lands in this version)
• OpenMC: any version compatible with the conda-forge build OR openmc/openmc:latest Docker image

This package follows semver. Minor-version bumps may add new runners, references, or facility packs. Major-version bumps would change the OpenMCKernelAdapter interface.

Development

git clone https://github.com/UT-Computational-NE/axiom-ext-openmc.git
cd axiom-ext-openmc
pip install -e ".[test]"
pytest -q                    # unit tests
pytest -m docker -v          # opt-in Phase 2c smoke (requires Docker + openmc/openmc image)

License

Apache-2.0. See LICENSE and NOTICE.

This package is jointly copyrighted by The University of Texas at Austin and B-Tree Labs.

Architecture references

• ADR-018 — Each physics code is its own AEOS-conformant extension; physics = native.
• ADR-040 — Compute decomposition primitive (this adapter is one consumer).
• ADR-044 — Standalone-or-builtin extension distribution rule (this package is a standalone case).

Related projects

• Axiom — the platform this package extends
• NeutronOS — nuclear-domain consumer that includes this package as an optional dependency
• OpenMC — the physics code wrapped here (separately installed)