parameter-scan

name: parameter-scan user-invocable: false description: Use when the user wants to vary one or more parameters and see how a quantity responds — phrases like "how does X depend on Y", "sweep U/t from 0 to 10", "scan J2/J1 across the transition", "finite-size series at L = 12, 16, 20, 24", "bond-dimension sweep chi=50 to 400", a single-axis scan, or a multi-axis grid.

parameter-scan

Sweep a Cartesian product of declared axes while holding other payload fields fixed. Produces a grid-indexed table, plot, shape labels, and a short report. This primitive is generic over axis names, physical meaning, payload schema, and per-cell implementation.

Binding Scope

Activation

• User asks how a quantity depends on a parameter.
• User asks for a finite-size, bond-dimension, coupling, or multi-axis grid.
• A calling workflow needs a sweep to characterize a response, locate a feature, or support an extrapolation.
• A single-point calculation naturally offers a scan follow-up.

Inputs

• Fixed payload from caller.
• Axes: named value lists, treated as opaque payload.
• Quantity: manifest field or artifact selected by caller.
• Optional per-cell settings overrides.
• Optional retry policy declared by caller.

Workflow

The mechanical stages — enumeration, manifest collection + validation, shape labelling, and arity-based plotting — are implemented by scripts/parameter_scan.py; run its subcommands rather than doing them by hand. Axis ranges, the per-cell compute, retry decisions, and interpretation stay with the caller.

python3 scripts/parameter_scan.py plan    --axes axes.json --run-id <run> [--settings s.json] [--provenance p.json]
python3 scripts/parameter_scan.py collect --run-spec results/<run>/run_spec.json [--success-field FIELD] [--success-value true] [--value-field FIELD ...]
python3 scripts/parameter_scan.py shape   --csv results/<run>/parameter-scan.csv --x-axis AXIS --value-col COL [--series-axis AXIS]
python3 scripts/parameter_scan.py plot    --csv results/<run>/parameter-scan.csv --axes axes.json --value-col COL [--err-col COL]

1. Plan. plan enumerates the Cartesian product and writes parameter-scan.plan.json + run_spec.json (generic contract below).
2. Build run spec. plan emits run_spec.json for resumable/cluster execution.
3. Resume detect. collect (and /using-slurm pending-cells) classify cells: success / failed / missing manifest / no cell directory.
4. Execute. Run locally for small scans; compose with /using-slurm for cluster scans.
5. Retry only by policy. Auto-bump controlling settings only for cells whose manifest reports non-convergence and whose caller declared a retry policy.
6. Collect. collect assembles every manifest into parameter-scan.csv; failed/missing cells appear with status and the validation report flags consensus violations.
7. Plot. plot emits parameter-scan.png, choosing line/errorbar, family curves, or heatmap by axis arity.
8. Shape labels. shape applies the generic shape labels from the table below; no physical interpretation.
9. Hand back. Return table, plot, shape labels, and recommended next step to caller.

Assemble Invariants

Observed cell manifests must exactly match declared run-spec cells. Trial artifacts belong outside the covered path unless declared.

Run Spec Contract

For cluster or resumable execution, write:

{
  "run_id": "example-run",
  "run_dir": "results/example-run",
  "settings": { "control_knob": 30, "budget": 1000000 },
  "provenance": { "protocol_hash": "...", "sources": ["..."], "claims": ["..."] },
  "cells": [
    { "cell_id": "cell-0001", "params": { "axis_1": 16, "axis_2": 0.8 } }
  ]
}

Reusable fields:

• cell_id
• params
• optional per-cell settings
• shared settings
• shared provenance

The primitive treats params, settings, and provenance as data, not schema. Domain-shaped names are allowed only as payload consumed by the entrypoint. Correctness- or uncertainty-affecting setup belongs in settings. The entrypoint echoes the payload it actually used into each manifest and emits machine-readable evidence for declared constraints.

Optional strict assemble fields:

• assemble.manifest_contract
• assemble.consensus_fields
• assemble.provenance_fields

These are generic field-path checks: required/nonempty, equality, list membership, numeric bounds, optional numeric fields, and evidence-set bindings.

Shape Labels

Labels describe data shape only. The caller decides interpretation.

Bad:

bond_dim_axis = [16, 32, 64, 128]

Good:

axes = caller.axes

Bad: silently omit failed cells from parameter-scan.csv.

Good: include every planned cell with status = success | failed | missing | pending.

Output

• results/<run>/parameter-scan.plan.json
• results/<run>/run_spec.json for resumable/cluster scans
• results/<run>/cells/<cell_id>/manifest.json
• results/<run>/parameter-scan.csv
• results/<run>/parameter-scan.png
• scripts/<run>/parameter-scan.jl or .py
• 2-3-line report: shape labels and next step

Resume

• Reuse cells with success-tagged manifests.
• Do not auto-retry failed cells without user ratification unless the caller declared a retry policy.
• If axes or values change, start a new run id.

Composition

• /using-slurm handles cluster array submission, monitoring, and fetch.
• /scaling-fit consumes power-law-like, extremum, or crossing scans when the caller needs exponents/collapse.
• /cross-method-check verifies one selected point independently.
• Literature-dependent interpretation belongs to the caller's source-search/source-audit path.

Anti-patterns