OpenMC is powerful but can be painful to use: you hand-write XML, manage batch runs, and read results out of HDF5. It would be great if we could safely use AI to reduce that friction.
PromptMC is infrastructure and tooling that lets AI LLM assistants and humans drive OpenMC through typed, schema-driven workflows. It works like a grammar checker between an assistant and OpenMC: your AI proposes a configuration, and PromptMC validates the XML structure and supported schema constraints before the simulator runs, catching malformed inputs early.
Because AI hallucination is a valid concern in reactor physics, the system is designed with deterministic blast walls. Every configuration (from a human, the deterministic local planner, or AI) is validated against the same typed Pydantic schemas before it reaches the simulator.
The goal is not autonomous reactor design; the goal is safer, faster OpenMC iteration.
Without OpenMC installed:
- Validate XML structure and PromptMC's supported OpenMC schemas
- Describe a simulation → a validated plan and
settings.xml(the default planner is keyword-based and uses no generative AI) - Drive planning and schema validation from an AI client via the MCP server
With OpenMC installed:
- Run simulations (subprocess or Python API)
- Run geometry-debug overlap checks and generate 2D slice plots inside your AI chat client
- Parse statepoint and tally outputs without touching HDF5
Prerequisites:
- Python 3.10 or higher (note: macOS's bundled Python is 3.9 —
uvbelow sidesteps this by fetching its own)
PromptMC — quickest as an isolated CLI install via uv or pipx:
uv tool install promptmc # or: pipx install promptmcOr with pip into an existing environment:
pip install promptmc # core: CLI, schema validation, local planner, MCP server
pip install 'promptmc[llm]' # + Gemini-backed `plan --llm`
pip install 'promptmc[yaml]' # + YAML batch specs (JSON works without it)
pip install 'promptmc[monitoring]'# + psutil-based resource/perf monitoring
pip install 'promptmc[telemetry]' # + OpenTelemetry tracing
pip install 'promptmc[all]' # everything above except telemetryThe core install — CLI, schema validation, the local planner, statepoint parsing, and the promptmc-mcp server — depends on typer, rich, pydantic, defusedxml, tenacity, mcp, and h5py; the remaining integrations live behind the extras above and degrade gracefully (or raise a clear "install promptmc[…]" error) when absent.
Plot rendering and geometry-debug import OpenMC's Python API, so for those install PromptMC with pip into the same environment as OpenMC (e.g. your conda env). Everything else — planning, validation, the MCP server, and simulation runs via the openmc executable — works from an isolated install.
OpenMC (required for simulation execution, geometry-debug checks, and plot rendering) installs via Conda, Spack, Docker, or from source per docs.openmc.org.
Cross-section data (for running simulations):
pip install openmc-data-downloader
openmc_data_downloader -l TENDL-2019 -i U235 U238 O16 H1 -d cross_sections
export OPENMC_CROSS_SECTIONS=$(pwd)/cross_sections/cross_sections.xmlSee installation for more details.
The validation gate is the core of PromptMC, and you can exercise it with no OpenMC install, no cross-section data, and no API key.
# 1. Turn a plain-English request into a complete input deck (deterministic local planner, no API key)
promptmc plan "pin cell criticality with 50k particles" --write # writes openmc_inputs/
# 2. Validate the deck against PromptMC's typed schemas
promptmc validate openmc_inputs --schema # passesThe gate's job is catching malformed inputs before a run consumes them. Hand it a value an AI assistant might plausibly invent, such as <run_mode>criticalize</run_mode>, and it rejects the input and reports what was allowed:
[ERROR] (settings.xml:run_mode)
Input should be 'eigenvalue', 'fixed source', 'plot', 'particle restart' or 'volume'
The error is structured, so an assistant can read it and self-correct.
plan --write and promptmc template emit a complete deck directory
(settings.xml, geometry.xml, materials.xml, plus an optional
tallies.xml). With OpenMC and cross-section data installed, run it directly:
promptmc run ./openmc_inputs # runs the simulation
promptmc analyze ./openmc_inputs # k-effective and tallies, parsed from the statepointThe built-in templates back their decks with validated reference geometries
(PWR pin, Godiva); swap in your own geometry.xml/materials.xml for a custom
model.
PromptMC exposes a Model Context Protocol server so AI assistants can run OpenMC workflows natively — validation, plotting, execution, and result parsing — from inside an LLM chat client such as Claude Desktop, Cursor, or Google Antigravity. The point of routing through MCP is that an assistant can validate its own generated geometry and inputs (schema checks, overlap detection) before you spend a run on them, catching malformed inputs that are easy for an LLM to produce and hard to spot by eye.
Tools: openmc_validate, openmc_schema_check, openmc_template, openmc_list_templates, openmc_run, openmc_analyze, openmc_plot (2D slice, returned to the chat client), openmc_geometry_debug, openmc_check_installation, openmc_check_cross_sections.
Resources expose the configured cross-sections path, the session's tool-call history, and the bundled examples.
Setup: see the MCP server configuration guide for per-client steps (Claude Desktop/Code, Cursor, Google Antigravity, VS Code).
By default, plan uses a deterministic local planner, needing no API key, no network, no generative AI. The optional --llm flag calls Google Gemini (set GEMINI_API_KEY) to interpret more open-ended requests.
promptmc plan "pin cell criticality with 50k particles" --write
promptmc validate settings.xml --schema # structure + schema, no OpenMC needed
promptmc template criticality --particles 10000 # generate a complete input deck
promptmc run ./model --threads 4 # needs OpenMC (geometry + materials + settings)
promptmc batch batch_spec.yaml --parallel threads --workers 4
promptmc analyze ./model --json > results.json # parse statepoint + tallies
promptmc plan --llm "concrete shielding calculation with 1 million particles"
promptmc info # OpenMC installation details
promptmc doctor # one-shot environment check with fix hintsFull options in the CLI reference.
PromptMC is an engineering-assist tool that keeps a human in the loop. It is not a substitute for professional engineering judgment, independent verification and validation, or regulatory review, and is not for safety, licensing, or other regulated decisions. Reproducing a published benchmark is not qualification for safety analysis. Provided as-is (see LICENSE).
- Installation · MCP server · CLI reference · Python API
- Templates · Telemetry · Examples · Design docs
- Roadmap · Changelog · Contributing
I studied nuclear engineering at MIT over 20 years ago, running MCNP 4 for my senior thesis. Though I left during my senior year, I eventually went back to university to get a degree in Computer Science, and I have spent the last 11 years working as a software engineer and site reliability engineer at a major FAANG cloud provider.
PromptMC bridges those two worlds. It is also, for me, an exploration of using agentic programming to build software for fun but still holding professional production principles and standards.
I welcome contributions! Please ensure all checks pass (pytest, ruff check, mypy src/) before opening a PR.
- License: MIT
- Documentation: GitHub Repository
- Issues and Discussions: GitHub Issues
- Roadmap: ROADMAP.md for planned features and scope.