HYRR

HYRR

Hierarchical Yield and Radionuclide Rates

A pure Python package for predicting radio-isotope production in stacked target assemblies, using TENDL cross-section data and NIST stopping power tables.

Web App | Desktop App | Documentation

Try it now — full simulation runs in the browser, no install, no data leaves your machine. Need offline access? Download the desktop app for Windows, macOS, or Linux.

What it does

• Stopping power via PSTAR/ASTAR table lookup (replaces Bethe-Bloch)
• Energy-integrated production rates for any projectile (p, d, t, ³He, α)
• Bateman equations for activity, yield, and decay chains
• Compound materials with natural or enriched isotopic composition
• Stacked layer geometries (windows, targets, degraders, backings)
• Depth-resolved heat and activity profiles

Performance

HYRR is designed for interactive use — simulations are fast enough for real-time parameter sweeps:

Operation	Time
Single isotope production rate	~56 µs
Full layer simulation (all isotopes)	~1.6 ms

Compared to tools like Isotopia, HYRR is significantly faster and lighter: pure NumPy/SciPy with Parquet-backed nuclear data (no heavy ORM, no database server). The browser frontend achieves similar performance with a pure TypeScript compute engine.

Installation

uv add git+https://github.com/exoma-ch/hyrr.git

Quick start

from hyrr import TargetStack, Layer, Beam

stack = TargetStack(
    beam=Beam(projectile="p", energy_MeV=30.0, current_mA=0.15),
    layers=[
        Layer(material=havar, thickness_cm=0.0025),
        Layer(material=enriched_mo100, energy_out_MeV=12.0),
        Layer(material=copper, thickness_cm=0.5),
    ],
)

result = stack.run(irradiation_time_s=86400, cooling_time_s=86400)
result.summary()

Frontend

exoma-ch.github.io/hyrr — hosted on GitHub Pages, zero backend.

The browser frontend (frontend/) is a standalone Svelte 5 + TypeScript app with a pure-TS physics engine (no Python/WASM). Nuclear data is lazy-loaded from Parquet files via hyparquet. All computation runs locally — no server, no data upload.

The physics engine is also published as @hyrr/compute (npm workspace under packages/compute/) for use in Node.js tools and the MCP server.

Key frontend features:

• Repeating layer groups — wrap layers into groups repeated N times or until beam energy drops below a threshold
• Undo/redo — Cmd+Z / Cmd+Shift+Z with 50-deep history
• Simulation mode — Auto (live) or Manual (run on demand) with status indicator
• URL sharing + sessions — full config (including groups) encoded in URL hash; session tabs persist across reloads
• Isotope filter — shared filter bar above activity plots and activity table

Install channels

HYRR ships through one channel per surface. Pick the one that matches what you actually want:

You want…	Use	Command
The desktop GUI	GitHub Releases	Download installer (.dmg / .msi / .deb / .AppImage)
The MCP server, no GUI	uvx (PyPI)	claude mcp add hyrr -- uvx hyrr-mcp
The MCP server, already have desktop	desktop binary	claude mcp add hyrr -- /Applications/HYRR.app/Contents/MacOS/hyrr --mcp
The Python library	pip / uv	pip install hyrr
The browser app	static GitHub Pages	hyrr.app
Build the MCP from source (devs)	cargo, from a checkout	cd hyrr-mcp && cargo build --release → ./target/release/hyrr-mcp

See docs/adr/0001-mcp-single-ssot-and-install-channels.md for the rationale behind the split.

MCP Server

Agent-driven irradiation analysis via the Model Context Protocol. Listed in the official MCP Registry as io.github.exoma-ch/hyrr, so registry-aware clients can find and install it without this README; each hyrr-mcp-v* release updates the listing. All entry points share the same Rust codepath (core/src/mcp/) — adding a tool means editing one file and every surface picks it up on next build.

Tools: simulate, list_materials, list_reaction_channels, get_decay_data, compare_simulations, get_stack_energy_budget, get_stopping_power, get_isotope_production_curve. Every response footer carries *Library: <id> · data release: <ver>* so agents see which nuclear data fed the calculation — a library id alone does not identify it, since the same library at two data releases is two different sets of numbers (#681). Referrals to nucl-parquet-mcp for deeper data carry the same pair: the two servers resolve their data independently and nothing compares them.

Desktop App

Download — available for Windows, macOS (Apple Silicon & Intel), and Linux.

The desktop app (desktop/) wraps the same frontend in a native window using Tauri v2. All nuclear data (~68 MB Parquet) is bundled, so it works fully offline on air-gapped machines. Built with the system webview — the installer is ~15 MB.

Platform	Artifact
Windows 10+	.msi installer + .exe (NSIS)
macOS 10.15+	.dmg (Apple Silicon) / .dmg (Intel)
Ubuntu 22.04+	.deb + .AppImage

Releases are built automatically via GitHub Actions on version tags (v*).

Development

git clone --recurse-submodules https://github.com/exoma-ch/hyrr.git
cd hyrr
uv sync --all-extras
uv run pytest

Frontend:

cd frontend
npm ci
npm run dev
npm test          # vitest
npm run check     # svelte-check (TypeScript)

Desktop (requires Tauri CLI and Rust):

npm install -g @tauri-apps/cli
cd desktop && npx tauri dev

Contributing

1. Fork and create a feature branch
2. Python: uv sync --all-extras, then uv run pytest and uv run ruff check src/
3. Frontend: cd frontend && npm ci, then npm test and npm run check
4. Commit format: type(scope): description
5. Open a PR against main

Dependencies

• numpy, scipy — numerics
• polars — data access (Parquet backend)
• matplotlib — plotting
• py-mat — material definitions
• nucl-parquet — evaluated nuclear data (TENDL, ENDF/B, JENDL, JEFF, EXFOR)

About eXoma

eXoma — Exotic Matter Applications — is a research group at ETH Zürich focused on novel radioisotope production methods and targetry.

License & legal

• Code: MIT.
• Bundled nuclear data (via the nucl-parquet submodule): third-party — each library keeps its own terms and required citation. See nucl-parquet/ATTRIBUTION.md; HYRR does not relicense the data.
• Disclaimer: results carry evaluated-data uncertainties and are not validated for clinical, safety, or regulatory use — see DISCLAIMER.
• Privacy · Terms · How to cite · Compliance · Contributing