simjecture 0.1.0__py3-none-any.whl

conjecture_solver/builtin_skills/warpx/references/picmi-interface.md

@@ -0,0 +1,118 @@
+# PICMI construction map
+
+WarpX exposes the PICMI interface through `from pywarpx import picmi`. A usual
+program constructs objects in this order:
+
+1. A geometry-specific grid such as `Cartesian1DGrid`, `Cartesian2DGrid`,
+   `Cartesian3DGrid`, or `CylindricalGrid`, with field and particle boundary
+   conditions stated explicitly.
+2. An electromagnetic or electrostatic solver compatible with that grid and
+   the intended model.
+3. One or more `Species` objects with explicit charge/mass or a recognized
+   particle type, each connected to an initial distribution.
+4. A particle layout for each species, such as `GriddedLayout` or
+   `PseudoRandomLayout`.
+5. A `Simulation` carrying timestep or CFL choice, maximum steps, particle
+   shape, random-seed policy, and any WarpX-specific controls.
+6. Applied fields, collisions, lasers, or other supported components only when
+   demanded by the proposed experiment.
+7. Diagnostics added to the simulation before `simulation.step()`.
+
+`simulation.write_input_file(file_name=...)` is useful for inspecting the
+compiled native input without running the calculation. When representation is
+scientifically important, also request `warpx_used_inputs_file` and inspect the
+realized native controls rather than trusting the frontend program alone.
+
+PICMI uses physical units for dimensional inputs. Check dimensional
+conversions explicitly. Parser expressions, velocity/momentum conventions,
+thermal spreads, boundary names, and dimension-dependent component ordering
+are common sources of plausible but incorrect initial states.
+
+Despite their names, `AnalyticDistribution(momentum_expressions=...)` and
+`momentum_spread_expressions=...` take proper velocity, `gamma*v`, in metres
+per second in this runtime. They do **not** take mechanical momentum `m*gamma*v`.
+For a nonrelativistic drift, supply the drift velocity itself; never multiply it
+by particle mass. Thermal spread expressions likewise use a velocity spread.
+Confirm the generated `*_u*_mean_function` and `*_u*_std_function` entries in
+the used-inputs record. Parser keyword arguments must actually occur in at
+least one expression consumed by that object; unused keywords are rejected by
+PICMI, so pass only the constants used by each distribution or field.
+
+For the pinned 26.07 runtime, use the concrete names implemented by the
+installed interface. Important multidimensional entries include
+`Cartesian2DGrid`, `AnalyticDistribution`, `AnalyticInitialField`,
+`ConstantAppliedField`, `AnalyticAppliedField`, and `CoulombCollisions`. Do not
+invent generic aliases such as `Grid` or `BinaryCollision`. Wire the objects
+with the exact methods `simulation.add_species(species, layout=layout)`,
+`simulation.add_applied_field(field)`, and
+`simulation.add_diagnostic(diagnostic)`. In WarpX 26.07,
+`CoulombCollisions` is not a standard PICMI interaction: pass a list through
+`picmi.Simulation(..., warpx_collisions=[collision])`; do not use
+`simulation.add_interaction(collision)`, which routes through the standard
+interaction path. Construct it as
+`picmi.CoulombCollisions(name="...", species=[species_a, species_b], ...)` in
+this runtime. Its constructor requires the single `species` collection;
+`species1=...` and `species2=...` without that collection are rejected. Use
+`CoulombLog`, `ndt_supercycle`, or `ndt_subcycle` with the exact capitalization
+shown by the runtime. If `CoulombLog` is omitted, WarpX calculates it locally;
+if it is prescribed, justify its physical range and measure the realized
+collision effect.
+
+For `AnalyticInitialField`, provide explicit expressions for all three magnetic
+components and all three electric components, using `"0.0"` for intended
+zeros. The installed constructor keyword names are exactly
+`Ex_expression`, `Ey_expression`, `Ez_expression`, `Bx_expression`,
+`By_expression`, and `Bz_expression`. Do not pass `Ex`/`Ey`/`Ez`/`Bx`/`By`/`Bz`
+or `E_x`/`B_x`-style aliases; those are rejected as unexpected keywords before
+WarpX initializes. `ConstantAppliedField` is different: it takes numeric
+`Ex`/`Ey`/`Ez`/`Bx`/`By`/`Bz` (not `E1`/`E2`/`E3` and not `*_expression`).
+Supplying only one analytic component can reach WarpX initialization and then
+abort when another external-grid parser entry is absent. Inspect the native
+input for `B_ext_grid_init_style = parse_b_ext_grid_function` (and the analogous
+electric entry when used); particle-applied external fields are a different
+mechanism.
+
+For a spatially varying thermal spread in `AnalyticDistribution`, the pinned
+WarpX subclass consumes `warpx_momentum_spread_expressions`, not the generic
+`momentum_spread_expressions` argument inherited from `picmistandard`. The
+generic argument can be accepted while disappearing from the realized native
+input, leaving only the directed momentum parser. Use numeric-literal strings
+for constant spreads, or make every parser symbol part of an expression path
+that the installed constructor actually registers. Verify native
+`momentum_distribution_type = "maxwellian"`, all three
+`u*_std_function(x,y,z)` expressions, and their `/c` normalization. A custom
+keyword used only by the generic spread expressions can be rejected as an
+unexpected keyword. For a spatially uniform Gaussian, `rms_velocity` is a
+simpler standard interface; still inspect `ux_th`, `uy_th`, and `uz_th`.
+
+The pinned Cartesian PICMI grid accepts field boundary strings `periodic`,
+`open`, `dirichlet`, `neumann`, and `absorbing_silver_mueller`, subject to
+solver compatibility. Particle boundary strings are `periodic`, `absorbing`,
+`reflect`, and `thermal`. These are numerical boundary behaviors, not sources.
+If the physics needs continuing material or flux injection, author and
+commission an explicit supported injection/source mechanism; do not relabel an
+open or absorbing boundary as inflow.
+
+Call `simulation.write_input_file(file_name="inputs")` before stepping and set
+`warpx_used_inputs_file` on `Simulation` when the realized controls matter.
+Inspect both records. Do not repeatedly introspect the runtime for the wiring
+listed here.
+
+`PseudoRandomLayout(seed=...)` prints a warning because WarpX 26.07 does not
+honor a layout-local seed. Use the simulation/runtime seed controls, retain the
+warning, and verify stochastic reproducibility rather than assuming the
+requested layout seed took effect.
+
+Before a 2D Cartesian calculation, read `2d-xz-commissioning.md` in full.
+
+## WarpX 1D coordinate mapping
+
+`Cartesian1DGrid` uses `z` as its sole physical spatial axis. When using
+`ParticleListDistribution`, supply longitudinal positions through `z` and
+longitudinal proper velocities through `uz`; `x`, `y`, `ux`, and `uy` remain
+transverse components. The longitudinal electric-field diagnostic is the `z`
+component of the `E` mesh. Verify the mapping in `warpx_used_inputs_file` and
+particle diagnostics when commissioning a new loading method.
+
+Use `read_skill` on the smoke example only to learn object wiring. Select all
+scientific values from the active hypothesis and commissioning reasoning.

conjecture_solver/builtin_skills/warpx/references/resource-scaling.md

@@ -0,0 +1,24 @@
+# Resource scaling
+
+Estimate cost before launching a calculation. For explicit PIC, particle work
+typically grows with cells times macroparticles per cell times species times
+steps. Field work grows with cells, components, solver iterations, and steps.
+Diagnostics can dominate storage when full particles or frequent mesh dumps
+are requested.
+
+Start commissioning with the smallest case that exercises the intended
+geometry, species, solver, boundaries, and diagnostic path. Increase one
+relevant fidelity axis at a time. Keep heavy raw output sparse unless the
+observable requires it; use reduced diagnostics for inexpensive monitoring,
+but retain enough raw information to challenge the estimator.
+
+The sandbox exposes two distinct instruments: `warpx-cpu-26.07` is a bounded
+eight-thread OpenMP CPU profile, while `warpx-cuda-openpmd-26.07` is a
+non-MPI, 2D CUDA profile with HDF5 openPMD output. Read `cpu-launch-tuning.md`
+or `gpu-launch-tuning.md` before a long campaign. Do not assume the GPU is
+faster: run a bounded commissioning case with the actual workload, then spend
+its measured throughput on the fidelity axis that most limits the intended
+inference. Large multidimensional, high-particle, or long-duration proposals
+may still be unreachable even though WarpX supports them on other machines.
+An honest instrument-unreachable result is preferable to silently weakening
+the physical question.

conjecture_solver/builtin_skills/warpx/references/time-integration.md

@@ -0,0 +1,58 @@
+# Electromagnetic time integration
+
+Select the evolve scheme from the physical timescales and observable. Do not
+infer a timestep from a familiar dimensional value alone. Record `dt` in
+seconds and normalized to every potentially limiting plasma, cyclotron,
+collision, transit, growth, drive, and diagnostic timescale.
+
+## Explicit electromagnetic PIC
+
+Omitting `warpx_evolve_scheme` uses WarpX's explicit default. For an auditable
+choice, construct `picmi.ExplicitEvolveScheme()` and pass it to
+`picmi.Simulation(..., warpx_evolve_scheme=evolve_scheme)`.
+
+For an explicit Yee update, enforce the multidimensional electromagnetic CFL
+condition
+
+`c*dt*sqrt(sum_i(1/dx_i**2)) < 1`.
+
+For equal cells in two dimensions this gives `dt < dx/(c*sqrt(2))`. Also
+resolve any plasma, gyro, collision, particle-crossing, or source timescale
+that can affect the proposed observable. A CFL-passing step is not by itself
+an accurate kinetic step.
+
+## Implicit electromagnetic PIC
+
+The pinned 26.07 PICMI runtime exposes:
+
+- `picmi.ThetaImplicitEMEvolveScheme(nonlinear_solver=..., theta=...)`;
+- `picmi.SemiImplicitEMEvolveScheme(nonlinear_solver=...)`;
+- `picmi.NewtonNonlinearSolver(...)` and
+  `picmi.PicardNonlinearSolver(...)`; and
+- `picmi.GMRESLinearSolver(...)` for a Newton solve when appropriate.
+
+Pass the selected evolve object through
+`picmi.Simulation(..., warpx_evolve_scheme=evolve_scheme)`. Require nonlinear
+convergence and preserve the configured tolerance, iteration limit, iteration
+history, and failure state. Inspect `warpx_used_inputs_file` for
+`algo.evolve_scheme = theta_implicit_em` or `semi_implicit_em`, the intended
+`implicit_evolve.nonlinear_solver`, and the exact `warpx.const_dt`.
+
+Implicit advancement removes the explicit electromagnetic CFL condition as a
+stability restriction; it does not remove accuracy restrictions. The step
+must still resolve the dynamics used as evidence, particle motion relevant to
+the estimator, collisions or forcing as implemented, diagnostic sampling, and
+changes in the represented state. Qualify the chosen step against a smaller
+`dt` while holding the physical case, duration, seed policy, and estimator
+fixed. Reject a run whose nonlinear solve fails or whose result depends
+materially on solver tolerances.
+
+On the local 2D CUDA/openPMD 26.07 runtime, theta-implicit Picard has
+repeatedly aborted with CUDA error 700 inside current deposition when a
+loaded 2D electromagnetic plasma is advanced, even when the one-step implicit
+wiring smoke succeeds. That is a scheme-specific solver-path failure, not an
+openPMD/HDF5 failure. If the operator forbids implicit evolution or requires
+explicit electromagnetic PIC, do not spend the campaign commissioning implicit
+loaded-plasma cases. Use `ExplicitEvolveScheme` (or the
+explicit default), enforce the multidimensional CFL condition, and treat
+implicit only as a documented unavailable path.

conjecture_solver/builtin_skills/warpx/scripts/benchmark_cpu_threads.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Benchmark one exact operator-supplied program argv across OpenMP settings."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import re
+import statistics
+import subprocess
+import time
+from pathlib import Path
+
+EVOLVE_RE = re.compile(
+    r"Evolve time = ([0-9.eE+-]+) s;.*Avg\. per step = ([0-9.eE+-]+) s"
+)
+PROFILE_EVOLVE_RE = re.compile(
+    r"^WarpX::Evolve\(\)\s+1\s+([0-9.eE+-]+)", re.MULTILINE
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--python", type=Path, required=True)
+    parser.add_argument("--program", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--threads", required=True)
+    parser.add_argument("--repeats", type=int, default=2)
+    parser.add_argument(
+        "--affinity", choices=("none", "close", "spread"), default="close"
+    )
+    parser.add_argument("--places", choices=("cores", "threads"), default="cores")
+    parser.add_argument("--required-path", action="append", required=True)
+    parser.add_argument("program_argv", nargs=argparse.REMAINDER)
+    args = parser.parse_args()
+    if args.program_argv[:1] == ["--"]:
+        args.program_argv = args.program_argv[1:]
+    return args
+
+
+def contained_paths(values: list[str]) -> tuple[Path, ...]:
+    paths = tuple(Path(value) for value in values)
+    for path in paths:
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError("--required-path must be a contained relative path")
+    return paths
+
+
+def amrex_capabilities(python: Path) -> dict[str, object]:
+    probe = subprocess.run(
+        [
+            str(python),
+            "-c",
+            (
+                "import json, amrex.space2d as a; "
+                "print(json.dumps({'have_mpi': bool(a.Config.have_mpi), "
+                "'have_omp': bool(a.Config.have_omp)}))"
+            ),
+        ],
+        check=True,
+        text=True,
+        capture_output=True,
+    )
+    return json.loads(probe.stdout)
+
+
+def launch_environment(threads: int, affinity: str, places: str) -> dict[str, str]:
+    env = os.environ.copy()
+    env.update(
+        {
+            "OMP_NUM_THREADS": str(threads),
+            "OPENBLAS_NUM_THREADS": "1",
+            "MKL_NUM_THREADS": "1",
+            "NUMEXPR_NUM_THREADS": "1",
+        }
+    )
+    if affinity == "none":
+        env.pop("OMP_PROC_BIND", None)
+        env.pop("OMP_PLACES", None)
+    else:
+        env["OMP_PROC_BIND"] = affinity
+        env["OMP_PLACES"] = places
+    return env
+
+
+def require_outputs(run: Path, paths: tuple[Path, ...]) -> dict[str, int]:
+    observed: dict[str, int] = {}
+    for relative in paths:
+        target = run / relative
+        if not target.is_file() or target.stat().st_size == 0:
+            raise RuntimeError(f"required nonempty output is absent: {relative}")
+        observed[relative.as_posix()] = target.stat().st_size
+    return observed
+
+
+def timing_from_log(output: str) -> tuple[float | None, float | None]:
+    timings = EVOLVE_RE.findall(output)
+    if timings:
+        return tuple(float(value) for value in timings[-1])  # type: ignore[return-value]
+    profile = [float(value) for value in PROFILE_EVOLVE_RE.findall(output)]
+    return (max(profile), None) if profile else (None, None)
+
+
+def run_one(
+    args: argparse.Namespace,
+    required: tuple[Path, ...],
+    threads: int,
+    repeat: int,
+) -> dict[str, object]:
+    run = args.output / f"omp-{threads:03d}-{args.affinity}-{args.places}-r{repeat}"
+    run.mkdir(parents=True, exist_ok=False)
+    command = [str(args.python), str(args.program), *args.program_argv]
+    started = time.perf_counter()
+    completed = subprocess.run(
+        command,
+        cwd=run,
+        env=launch_environment(threads, args.affinity, args.places),
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    wall_s = time.perf_counter() - started
+    (run / "benchmark.log").write_text(completed.stdout)
+    if completed.returncode:
+        raise RuntimeError(
+            f"threads={threads} repeat={repeat} exited {completed.returncode}; "
+            f"see {run / 'benchmark.log'}"
+        )
+    outputs = require_outputs(run, required)
+    evolve_s, step_s = timing_from_log(completed.stdout)
+    return {
+        "threads": threads,
+        "affinity": args.affinity,
+        "places": args.places,
+        "repeat": repeat,
+        "wall_s": wall_s,
+        "warpx_evolve_s": evolve_s,
+        "warpx_step_s": step_s,
+        "required_outputs": json.dumps(outputs, sort_keys=True),
+        "run_dir": str(run),
+    }
+
+
+def main() -> int:
+    args = parse_args()
+    args.python = args.python.resolve()
+    args.program = args.program.resolve()
+    args.output = args.output.resolve()
+    required = contained_paths(args.required_path)
+    threads = [int(value) for value in args.threads.split(",")]
+    if not threads or any(value <= 0 for value in threads):
+        raise ValueError("--threads must contain positive integers")
+    if args.repeats <= 0:
+        raise ValueError("--repeats must be positive")
+    capabilities = amrex_capabilities(args.python)
+    mpi_world_size = int(
+        os.environ.get("OMPI_COMM_WORLD_SIZE")
+        or os.environ.get("PMI_SIZE")
+        or os.environ.get("MPI_LOCALNRANKS")
+        or "1"
+    )
+    if mpi_world_size > 1 and not capabilities["have_mpi"]:
+        raise RuntimeError(
+            "refusing MPI launch: loaded AMReX reports have_mpi=false"
+        )
+    args.output.mkdir(parents=True, exist_ok=False)
+    rows = [
+        run_one(args, required, count, repeat)
+        for count in threads
+        for repeat in range(1, args.repeats + 1)
+    ]
+    with (args.output / "runs.csv").open("w", newline="") as stream:
+        writer = csv.DictWriter(stream, fieldnames=list(rows[0]))
+        writer.writeheader()
+        writer.writerows(rows)
+    summaries = [
+        {
+            "threads": count,
+            "median_wall_s": statistics.median(
+                float(row["wall_s"]) for row in rows if row["threads"] == count
+            ),
+        }
+        for count in threads
+    ]
+    result = {
+        "capabilities": capabilities,
+        "observed_mpi_world_size": mpi_world_size,
+        "program": str(args.program),
+        "program_argv": args.program_argv,
+        "required_paths": [path.as_posix() for path in required],
+        "repeats": args.repeats,
+        "affinity": args.affinity,
+        "places": args.places,
+        "summaries": summaries,
+        "best": min(summaries, key=lambda value: value["median_wall_s"]),
+    }
+    (args.output / "summary.json").write_text(
+        json.dumps(result, indent=2, sort_keys=True) + "\n"
+    )
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

conjecture_solver/builtin_skills/warpx/scripts/benchmark_gpu.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Benchmark exact operator-supplied program argv cases on the CUDA runtime."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import re
+import statistics
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+EVOLVE_RE = re.compile(
+    r"Evolve time = ([0-9.eE+-]+) s;.*Avg\. per step = ([0-9.eE+-]+) s"
+)
+PROFILE_EVOLVE_RE = re.compile(
+    r"^WarpX::Evolve\(\)\s+1\s+([0-9.eE+-]+)", re.MULTILINE
+)
+LABEL_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--python", type=Path, required=True)
+    parser.add_argument("--program", type=Path, required=True)
+    parser.add_argument("--cases", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--repeats", type=int, default=2)
+    parser.add_argument("--required-path", action="append", required=True)
+    return parser.parse_args()
+
+
+def contained_paths(values: list[str]) -> tuple[Path, ...]:
+    paths = tuple(Path(value) for value in values)
+    for path in paths:
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError("--required-path must be a contained relative path")
+    return paths
+
+
+def read_cases(path: Path) -> tuple[dict[str, Any], ...]:
+    payload = json.loads(path.read_text())
+    cases = payload.get("cases") if isinstance(payload, dict) else None
+    if not isinstance(cases, list) or not cases:
+        raise ValueError("cases file must contain a nonempty 'cases' list")
+    result = []
+    labels = set()
+    for item in cases:
+        if not isinstance(item, dict) or set(item) != {"label", "argv"}:
+            raise ValueError("each case must contain exactly 'label' and 'argv'")
+        label = item["label"]
+        argv = item["argv"]
+        if not isinstance(label, str) or not LABEL_RE.fullmatch(label):
+            raise ValueError("case labels may contain only letters, digits, ._- ")
+        if label in labels:
+            raise ValueError(f"duplicate case label: {label}")
+        if not isinstance(argv, list) or not all(isinstance(v, str) for v in argv):
+            raise ValueError(f"case {label!r} argv must be a list of strings")
+        labels.add(label)
+        result.append({"label": label, "argv": argv})
+    return tuple(result)
+
+
+def amrex_capabilities(python: Path) -> dict[str, object]:
+    code = (
+        "import json, amrex.space2d as a; "
+        "print(json.dumps({'have_mpi': bool(a.Config.have_mpi), "
+        "'have_omp': bool(a.Config.have_omp), "
+        "'have_gpu': bool(a.Config.have_gpu), "
+        "'gpu_backend': str(a.Config.gpu_backend)}))"
+    )
+    probe = subprocess.run(
+        [str(python), "-c", code], check=True, text=True, capture_output=True
+    )
+    return json.loads(probe.stdout)
+
+
+def gpu_identity() -> dict[str, str]:
+    query = subprocess.run(
+        [
+            "nvidia-smi",
+            "--query-gpu=name,memory.total,compute_cap,driver_version",
+            "--format=csv,noheader,nounits",
+        ],
+        check=True,
+        text=True,
+        capture_output=True,
+    )
+    name, memory_mib, compute_cap, driver = (
+        value.strip() for value in query.stdout.splitlines()[0].split(",")
+    )
+    return {
+        "name": name,
+        "memory_mib": memory_mib,
+        "compute_capability": compute_cap,
+        "driver_version": driver,
+    }
+
+
+def capability_environment(python: Path) -> dict[str, str]:
+    env = os.environ.copy()
+    python_site = subprocess.run(
+        [str(python), "-c", "import sysconfig; print(sysconfig.get_paths()['purelib'])"],
+        check=True,
+        text=True,
+        capture_output=True,
+    ).stdout.strip()
+    bundled_site = str(Path(python_site) / "pywarpx" / "site-packages")
+    env["PYTHONPATH"] = os.pathsep.join(
+        value for value in (bundled_site, python_site, env.get("PYTHONPATH", "")) if value
+    )
+    env["WARPX_PYTHON_SITE"] = python_site
+    env.update(
+        {
+            "OMP_NUM_THREADS": "1",
+            "OPENBLAS_NUM_THREADS": "1",
+            "MKL_NUM_THREADS": "1",
+            "NUMEXPR_NUM_THREADS": "1",
+        }
+    )
+    return env
+
+
+def require_outputs(run: Path, paths: tuple[Path, ...]) -> dict[str, int]:
+    observed: dict[str, int] = {}
+    for relative in paths:
+        target = run / relative
+        if not target.is_file() or target.stat().st_size == 0:
+            raise RuntimeError(f"required nonempty output is absent: {relative}")
+        observed[relative.as_posix()] = target.stat().st_size
+    return observed
+
+
+def timing_from_log(output: str) -> tuple[float | None, float | None]:
+    timings = EVOLVE_RE.findall(output)
+    if timings:
+        return tuple(float(value) for value in timings[-1])  # type: ignore[return-value]
+    profile = [float(value) for value in PROFILE_EVOLVE_RE.findall(output)]
+    return (max(profile), None) if profile else (None, None)
+
+
+def run_one(
+    args: argparse.Namespace,
+    case: dict[str, Any],
+    required: tuple[Path, ...],
+    repeat: int,
+    env: dict[str, str],
+) -> dict[str, object]:
+    run = args.output / f"{case['label']}-r{repeat}"
+    run.mkdir(parents=True, exist_ok=False)
+    command = [str(args.python), str(args.program), *case["argv"]]
+    started = time.perf_counter()
+    completed = subprocess.run(
+        command,
+        cwd=run,
+        env=env,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    wall_s = time.perf_counter() - started
+    (run / "benchmark.log").write_text(completed.stdout)
+    if completed.returncode:
+        raise RuntimeError(
+            f"case={case['label']} repeat={repeat} exited {completed.returncode}; "
+            f"see {run / 'benchmark.log'}"
+        )
+    outputs = require_outputs(run, required)
+    evolve_s, step_s = timing_from_log(completed.stdout)
+    return {
+        "label": case["label"],
+        "repeat": repeat,
+        "wall_s": wall_s,
+        "warpx_evolve_s": evolve_s,
+        "warpx_step_s": step_s,
+        "argv": json.dumps(case["argv"]),
+        "required_outputs": json.dumps(outputs, sort_keys=True),
+        "run_dir": str(run),
+    }
+
+
+def main() -> int:
+    args = parse_args()
+    args.python = args.python.resolve()
+    args.program = args.program.resolve()
+    args.output = args.output.resolve()
+    cases = read_cases(args.cases.resolve())
+    required = contained_paths(args.required_path)
+    if args.repeats <= 0:
+        raise ValueError("--repeats must be positive")
+    capabilities = amrex_capabilities(args.python)
+    if not capabilities["have_gpu"]:
+        raise RuntimeError("refusing benchmark: loaded AMReX reports have_gpu=false")
+    if str(capabilities["gpu_backend"]).upper() != "CUDA":
+        raise RuntimeError(
+            f"this harness expects CUDA, got {capabilities['gpu_backend']}"
+        )
+    args.output.mkdir(parents=True, exist_ok=False)
+    env = capability_environment(args.python)
+    rows = [
+        run_one(args, case, required, repeat, env)
+        for case in cases
+        for repeat in range(1, args.repeats + 1)
+    ]
+    with (args.output / "runs.csv").open("w", newline="") as stream:
+        writer = csv.DictWriter(stream, fieldnames=list(rows[0]))
+        writer.writeheader()
+        writer.writerows(rows)
+    summaries = [
+        {
+            "label": case["label"],
+            "argv": case["argv"],
+            "median_wall_s": statistics.median(
+                float(row["wall_s"])
+                for row in rows
+                if row["label"] == case["label"]
+            ),
+        }
+        for case in cases
+    ]
+    result = {
+        "capabilities": capabilities,
+        "gpu": gpu_identity(),
+        "program": str(args.program),
+        "required_paths": [path.as_posix() for path in required],
+        "repeats": args.repeats,
+        "summaries": summaries,
+        "best": min(summaries, key=lambda value: value["median_wall_s"]),
+    }
+    (args.output / "summary.json").write_text(
+        json.dumps(result, indent=2, sort_keys=True) + "\n"
+    )
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())