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. When the user explicitly asks to test GEMC source, use the first-class source-test command instead of hand-assembling clone, build, install, and smoke commands.

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 operational smoke/source-build validation only; do not treat passing tests as physics validation.

Workflow

1. Run first-use project documentation setup from the user's project directory:

scripts/setup_project_docs.sh

2. Read the local agent rules if present: AGENTS.md, CLAUDE.md, and docs/smoke_tests.md.
3. 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.
   • before running scripts/gemc3_apptainer.sh --pull-latest, report the current cached image path, mtime, size, provenance if known, and proposed image URI, then ask the user for permission.
4. Run:

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

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

Source-Test Workflow

Use this only when the user explicitly asks to test GEMC source. If the user says "test latest GEMC3 source" or similar, interpret "latest source" as the current GitHub HEAD of https://github.com/gemc/src, not the GEMC binary already installed in the container image. The source workflow must compile that checkout, then run every *.yaml example under the checkout's examples/ directory with the freshly built binary.

1. Read docs/source_tests.md.
2. Run:

scripts/run_source_tests.sh

3. Inspect results/gemc3_source/<timestamp>/summary.md and status.env.
4. Report:
   • source repo URL
   • commit hash
   • container image path
   • image refresh status
   • SIF mtime and size
   • Apptainer version
   • Geant4 version
   • Geant4 pkg-config versions
   • Python version
   • ROOT version
   • Meson version
   • PKG_CONFIG_PATH
   • binary kind
   • GEMC binary path
   • source example counts
   • first failed example
   • failure reason
   • setup phase status
   • pass/fail status
   • first useful error from the failed phase logs

Runtime Defaults

• Default image source: ghcr.io/gemc/src:dev-almalinux-10.
• Cached SIF: <current-project-dir>/src_dev-almalinux-10.sif.
• Work directory: invocation directory.
• Smoke-test parameters: one event and one thread.
• Runtime scripts do not read environment variables for configuration.
• The Apptainer wrapper canonicalizes the invocation directory with pwd -P, binds that physical path, and prints it as the canonical work directory.

Output Rules

• Generated outputs belong under results/gemc3_smoke/.
• Source-build outputs belong under results/gemc3_source/.
• 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.
• Source provenance failure: inspect provenance.stderr.log; do not treat a run with unknown commit hash as a valid source validation.
• Source preflight failure: inspect preflight.stderr.log and report failure_reason before reading Meson logs.
• Missing Geant4 pkg-config: report any candidate geant4.pc or candidate geant4_core.pc path shown in preflight.stderr.log.
• Source build failure: inspect the first failed phase in status.env, then read the matching *.stderr.log and *.stdout.log.
• Source setup failure: inspect setup.stderr.log and setup.stdout.log; this is example preparation, not a source build failure.
• Source example failure: confirm summary.md points to src_<timestamp>_<shortsha>/install/bin/gemc, inspect source_examples.md, then inspect the first failed example's logs under examples/; do not report source validation against the container $GEMC binary.