Validate generated outputs with deterministic comparison workflows.

CLI verification

Use pystamps verify once a run copy exists.

Copyuv run pystamps verify --run /path/to/run_copy --golden /path/to/reference_dataset

• Returns 0 when all comparisons pass and non-zero when mismatches are found.
• Compares numeric MATLAB payloads with tolerance settings and classifies failure families by artifact.
• Use repository shortcuts only for fixed in-repo references.

Native full-chain verification

Use this gate for the Rust native execution path. It prepares a clean run copy, executes native stages, checks performance budgets, and compares outputs against the golden dataset.

Copymake native-full-chain-verify

Copymake native-full-chain-verify \
  DATASET=/path/to/source_dataset \
  GOLDEN=/path/to/reference_dataset \
  RUN=/path/to/clean_run_dataset \
  THREADS=8

Read RUN/_native_gate_reports/ for coverage, run output, timings, and verification details.

Repository shortcut caveat

make verify is a convenience for fixed reference paths in this repository. For arbitrary runs, use the CLI command above so the path pair is explicit.

Parity audit workflow

Parity audits prepare and track fresh run copies, then report the copy path for explicit verification.

make audit is the repo-local convenience wrapper. The authoritative driver is scripts/validate_audit.py, and omitting --datasets makes it use the manifest-backed required dataset set from pystamps/data/audited_workflow_manifest.json.

Copymake audit

CopyOPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 PYTHONPATH=. \
  uv run python scripts/validate_audit.py \
    --output /path/to/latest_audit.json

CopyRUN_COPY="$(uv run python - <<'PY'
import json
from pathlib import Path

payload = json.loads(Path('/path/to/latest_audit.json').read_text(encoding='utf-8'))
print(payload['audits'][0]['run_root'])
PY
)"
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 PYTHONPATH=. \
  uv run pystamps verify --run "$RUN_COPY" --golden /path/to/reference_dataset

• Fresh audit output should be treated as active input for subsequent checks.
• The required done-gate datasets are owned by pystamps/data/audited_workflow_manifest.json, including the small-baseline stage-7 audit targets.
• Do not rerun against stale copies; interrupted audits or manual restart paths invalidate prior results.

Parity loop and oracle precedence

make parity-loop wraps scripts/parity_bug_loop.py. The loop consumes a matching latest_audit.json when one already exists, then ranks the next target from the saved first-divergent-boundary trace instead of guessing from downstream symptoms.

Oracle precedence comes from pystamps/data/oracle_contract.json: cpp_wrapper, then matlab_source, then manual_references. When the pinned StaMPS wrapper intentionally differs from the MATLAB scripts, the wrapper-backed path is the practical parity oracle and should be recorded in the emitted audit trace.

Release flow references

For release gate ordering, use the same parity-audit and verify steps from the verification flow. The release page now links here for full command context.

See the full API contract fields for parity in api/parity_contract and the command-level verification API in api/verify.