solid-gemc-claude

solid-gemc-claude

A plugin for running solid_gemc (the SoLID experiment's GEMC-based simulation) from Claude Code or OpenAI Codex CLI. solid_gemc, GEMC, Geant4, and ROOT all live in a pinned JLabCE 2.5 apptainer image; analysis runs on the host with uproot.

The name keeps its -claude suffix for historical/repo-stability reasons; the plugin is not Claude-specific. The whole workflow runs through one platform-neutral wrapper (bin/solid-gemc-run), with thin per-harness adapters on top.

Docs site: zhaozhiwen.github.io/solid_gemc_claude (install + quickstart + two demo run reports).

Status: v0.0.6. Dual-platform (Claude Code + Codex CLI). The orchestrator skill drives the full simulation loop through the wrapper. See docs/DESIGN.md for design intent and the cross-platform architecture.

Requirements

• apptainer ≥ 1.4 on Linux.
• wget, git on the host. (No host-side tcsh needed — the wrapper invokes tcsh inside the container.)
• Python 3.9+ with uproot numpy matplotlib (only for the analyze step).
• ~1.7 GB of disk for the cached JLabCE 2.5 image plus ~1 GB for the cloned + built solid_gemc tree, both per workspace (the cache lives in the workspace so it survives plugin updates; set $SOLID_GEMC_CLAUDE_CACHE to share one .sif across workspaces).
• Claude Code (plugin support) or OpenAI Codex CLI (Agent Skills).

The plugin downloads jeffersonlab_jlabce_tag2.5_digest:sha256:9b9a9ec8c793...sif on first use; URL is pinned in bin/solid-gemc-run.

Install

The repo is one source of truth for both harnesses — shared bin/solid-gemc-run + skills/solid-gemc/, with .claude-plugin/ and .codex-plugin/ manifests side by side (plus the per-harness marketplace descriptors .claude-plugin/marketplace.json and .agents/plugins/marketplace.json) and CLAUDE.md / AGENTS.md (same content) at the root. The analysis venv installs lazily on the first analyze on every platform (idempotent; run bin/solid-gemc-run setup-python to pre-install).

Claude Code

/plugin marketplace add zhaozhiwen/solid_gemc_claude
/plugin install solid-gemc-claude@solid-gemc-claude

Codex CLI

codex plugin marketplace add zhaozhiwen/solid_gemc_claude
codex plugin add solid-gemc-claude@solid-gemc-claude

Codex reads AGENTS.md — the canonical project-rules file. CLAUDE.md is a symlink to it and Claude Code reads it. codex plugin add drops the symlink but keeps the real AGENTS.md.

Try this after install

You can ask your agent harness to

Learn the examples at solid_gemc repo "solid_gemc/analysis/hgc_study/" and "solid_gemc/geometry/hgc_moved/",
Do the heavy gas Cherenkov simulation on SIDIS He3 moved configuration with 1000 events of 5 GeV pi- at 10 degree theta angle and full phi angle,
then plot number of photoelectron yield in various illustrative ways,
verify the sim result with physics analytic calculation,
finally show me the results in an html file

How you drive it

The solid-gemc orchestrator skill auto-loads on SoLID-flavored natural language, gap-checks a seven-field spec, presents a plan, gates on your approval, then drives the whole run through bin/solid-gemc-run (bootstrap the workspace, pick + edit a GCard, run solid_gemc, convert EVIO → ROOT, record provenance, plot). Works the same on Claude Code and Codex CLI.

You can ask your agent harness to init solid-gemc-claude, which will run bin/solid-gemc-run init to pull .sif, clone solid_gemc, run both scons builds, scaffold workspace as a one-shot bootstrap. Or it will run at the first time you use it.

Two upstream worked examples live in your workspace after init, both fully self-contained:

Example	What it teaches
solid_gemc/analysis/hgc_study/	the config + run + analyze pipeline — GCards (cherenkov.gcard, solid_SIDIS_He3_hgc.gcard, …), batch run scripts (load.sh / run.sh), ROOT analysis (analysis.C and the compare_*.C scripts)
solid_gemc/geometry/hgc_moved/	custom detector authoring — Perl generators (solid_SIDIS_hgc_*.pl), the resulting factory text files (*__geometry_Original.txt etc.) referenced by <detector name="..." factory="TEXT" ...>, plus a readme.md

bin/solid-gemc-run analyze runs/<id> would produce uproot-based default plots from out.root (the post-converted file).