[logan-nc]

Release note

• Audience: users
• Numerical impact: none
• Migration: none

A new page, docs/development/running-scans.md, measures where a GPEC run's wall time goes (package load, first-case compilation, image rebuilds) and shows how to structure cases, scans, job arrays and edit-test loops so that cost is paid once. CLAUDE.md and the developer notes point to it.

Regression report

Not run: documentation only, src/ untouched.

Notes for reviewers

Why. People and agents running scans on clusters lose much of their wall time to Julia load and compilation: a fresh julia per case, resubmitting after a src/ edit, or an array of tasks all starting on a stale image. #634 fixed this for the regression harness by running every case at a ref in one warm worker. Nothing told users how to do the same for their own runs.

Measured at develop a1149c5c2, Julia 1.11.7, pinned ci/manifests manifest, Slurm jobs on a two-socket Ice Lake node, 4 CPUs unless noted, default build (precompile_workload on). Ranges are over two runs.

Cost	Time
julia -e 1	0.16 s
using GeneralizedPerturbedEquilibrium, valid image	12.0–13.7 s
Rebuild after a one-line src/ edit: workload on / off	191–195 s / 37 s
Fresh depot, all deps + GPEC, 8 CPUs	533 s
Solovev example: first case / later cases, 4 threads	19.5–21.7 s / 9.2–10.1 s
Solovev example, first case with workload off	100–103 s
DIII-D-like example: first case / later cases	70–74 s / 22.8–24.8 s
DIII-D-like example, first case with workload off	236–238 s
DIII-D-like peak RSS	3.1 GB
Revise after the same edit: revise() / next Solovev case	2.8–2.9 s / 10.2–10.4 s

A 10-point Solovev elongation scan in one 4-CPU allocation:

Structure	Wall time
One julia per case, valid image	327–332 s
One julia per case, after a src/ edit	521–545 s
One process, loop, 4 threads	117–120 s
Distributed, 4 workers × 1 thread	72–73 s
Job array, 4 tasks × 1 CPU, chunks	60–61 s
Same array on a stale image (tasks wait on one build)	247–256 s

Cross-CPU check: one depot on a shared filesystem, Ice Lake build host, Cascade Lake load host. A native image was rejected ("Unable to find compatible target in cached code image") and rebuilt in 482 s. With JULIA_CPU_TARGET="generic;cascadelake,clone_all;icelake-server,clone_all" the build took about as long (523 s against 533 s) and loaded with no rejection, even from a job that did not set the variable.

Checked.

• The page's scan script ran as task 2 of a 4-task array: load 12.6 s, cases 20.6, 10.4, 9.9 s. A rerun skipped all three finished cases.
• The warm-worker snippet ran an edit-rerun loop against a live src/ edit.
• julia --project=docs docs/make.jl passes.

Not measured. Lock-file behaviour of tasks on different nodes sharing one depot. The page says so.

What changed. AGENTS.md, GEMINI.md and .github/copilot-instructions.md are symlinks to CLAUDE.md, so they pick up its new section automatically. docs/development/ is not built by Documenter, so the page is linked from CLAUDE.md (like benchmarking.md) and from the built developer notes.

Proposed follow-up, not in this PR: a small run_variants(base_dir, overrides; outroot) helper that runs a vector of deck overrides in one process with per-case directories, logs and DONE markers. The harness's _materialize_rundir and warm worker already do most of this internally. Exporting a user-facing version would make the right pattern a one-liner, but it is an API decision for maintainers.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01VdRsGGg4YRG6E9fgLGbpdF