gemc3-tester

GEMC3 Tester

Goal

Use the repository scripts to verify that GEMC3 can initialize and run installed basic and optical examples in the user's configured Apptainer container.

This procedure is agent-neutral Markdown. Codex can discover it through the plugin manifest, and other coding agents can use it by reading this file from the repo. It is for smoke testing only; do not treat passing smoke tests as physics validation.

Workflow

1. Read the local agent rules if present: AGENTS.md, CLAUDE.md, and docs/smoke_tests.md.
2. Check static prerequisites before running simulations:
   • command -v apptainer
   • network/cache access is available for the first-run apptainer pull, unless the cached SIF already exists.
3. Run:

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

4. Inspect results/gemc3_smoke/<timestamp>/summary.md.
5. Report:
   • container image path
   • work directory
   • examples run
   • pass/fail status
   • first useful error from any failed gemc.err, stderr.log, or stdout.log

Runtime Defaults

• Default image source: ghcr.io/gemc/src:dev-almalinux-9.4.
• Cached SIF: <current-project-dir>/src_dev-almalinux-9.4.sif.
• Work directory: invocation directory.
• Smoke-test parameters: one event and one thread.
• Runtime scripts do not read environment variables for configuration.

Output Rules

• Generated outputs belong under results/gemc3_smoke/.
• Do not delete old result directories unless the user explicitly asks.
• Do not add large generated data to source.
• Do not store secrets, credentials, or private data in logs or docs.

Failure Interpretation

• Pull failure: focus on network access, GHCR access, cache directory permissions, or Apptainer registry support.
• Missing Apptainer: report that the host cannot run the smoke tests.
• gemc --help fails: focus on container initialization and entrypoint setup.
• One example fails: inspect that example's logs first.
• Nonempty gemc.err: treat the example as failed even if the exit status is zero.