Plugin Gemc3

GEMC3 Tester

Codex and Claude plugin for smoke-testing a local GEMC3 Apptainer runtime and explicitly validating GEMC source builds.

The default smoke test runs installed GEMC examples to answer one practical question: can this user's configured GEMC3 container initialize and run basic and optical simulations successfully?

What It Tests

Installed-example smoke tests:

• Apptainer is available.
• A GEMC3 SIF is available in the current project directory.
• The container entrypoint initializes the GEMC environment.
• GEMC can run these installed examples with one event and one thread:
  • b1
  • b2
  • b3
  • simple_flux
  • optical_cherenkov

Source-build tests:

• https://github.com/gemc/src is checked out into a per-run directory named src_<timestamp>_<shortsha>.
• Preflight checks run before Meson configure for Geant4 command-line and pkg-config visibility plus Python compatibility.
• The checkout configures, builds, and installs inside the GEMC3 container.
• The install prefix is local to that checkout: src_<timestamp>_<shortsha>/install.
• Every *.yaml example under the checkout's examples/ directory runs with src_<timestamp>_<shortsha>/install/bin/gemc, not the container $GEMC binary.
• Matching setup scripts such as b1.py run before their YAML example with PYTHONPATH=src_<timestamp>_<shortsha>/install/api.
• The summary records source, commit, image freshness, container/tool versions, GEMC binary provenance, and a derived failure_reason.

Quick Start

From the project directory where you want GEMC3 smoke-test artifacts:

scripts/setup_project_docs.sh
scripts/gemc3_apptainer.sh gemc --help
scripts/run_smoke_tests.sh

scripts/setup_project_docs.sh is safe to rerun. It creates AGENTS.md, CLAUDE.md -> AGENTS.md, and log.md only when they are missing.

To validate the upstream GEMC source checkout:

scripts/run_source_tests.sh

To force-refresh the cached GEMC3 image before testing:

scripts/gemc3_apptainer.sh --pull-latest

Install From GitHub As A Codex Marketplace

On another computer, add this GitHub repository as a Codex plugin marketplace:

codex plugin marketplace add zhaozhiwen/plugin_gemc3

For a pinned branch, tag, or commit:

codex plugin marketplace add zhaozhiwen/plugin_gemc3@main

Codex fetches zhaozhiwen/plugin_gemc3 from GitHub and reads .agents/plugins/marketplace.json.

Install From GitHub As A Claude Marketplace

In Claude Code, add this GitHub repository as a plugin marketplace and install the plugin:

/plugin marketplace add zhaozhiwen/plugin_gemc3
/plugin install plugin-gemc3@plugin-gemc3

Claude Code fetches zhaozhiwen/plugin_gemc3 from GitHub and reads the repository-root .claude-plugin/marketplace.json, which points to this installable package at plugins/plugin-gemc3/.

On first run, the wrapper pulls:

ghcr.io/gemc/src:dev-almalinux-10

The cached SIF is stored at:

<current-project-dir>/src_dev-almalinux-10.sif

The wrapper only refreshes that cached SIF when it is missing or when explicitly run with --pull-latest. After a pull, it writes image provenance to:

<current-project-dir>/src_dev-almalinux-10.sif.provenance.env

The runtime scripts do not read environment variables for configuration. They always use the invocation directory as the work directory. Installed-example smoke tests run one event with one thread; source builds use Meson's default compile parallelism.

On first use in a project, run scripts/setup_project_docs.sh to seed project-local agent rules and an append-only log.md for GEMC3 runs and decisions.

Outputs

Smoke-test artifacts are written under:

<current-project-dir>/results/gemc3_smoke/<timestamp>/

Each example gets its own directory containing stdout.log, gemc.err, and any GEMC outputs generated by that example. The run root contains summary.md.

Source-test artifacts are written separately under:

<current-project-dir>/results/gemc3_source/<timestamp>/

The source-test run root contains phase logs, per-example logs under examples/, aggregate gemc.err, status.env, source_examples.md, and summary.md. status.env is rewritten as a complete key-value snapshot after each phase, so reruns do not produce duplicate contradictory status lines. Source-test summaries include image freshness, SIF size/mtime, Apptainer version, Geant4 pkg-config versions, Python version, source-example counts, first failed example, and a derived failure_reason.

Not In V1

• GUI launch testing.
• ROOT analysis.