ParameterScan¶
from cascaqit import ParameterScan
ParameterScan ¶
ParameterScan(
scan_id: str,
mode: ParameterScanMode,
points: tuple[dict[str, ParameterScalar], ...],
metadata: dict[str, Any] = dict(),
schema_version: str = CANONICAL_PARAMETER_SCHEMA_VERSION,
)
Declare an ordered collection of parameter points. Prefer explicit() or cartesian(); direct construction requires scan_id, mode and points. Mode is explicit or cartesian. Scan values are finite bool, int or float scalars; the parameter manager checks declared types and bounds. Metadata and schema version are stored with the declaration.
expand() binds parameters without invoking a backend. Execute with LocalBackend.run(program, sweep=scan, shots=...); see Parameter scans.
from cascaqit import Parameter, ParameterManager, ParameterScan
manager = ParameterManager().declare(Parameter("theta"))
scan = ParameterScan.explicit(scan_id="scan.theta", points=[{"theta": 0.0}, {"theta": 0.5}])
expanded = scan.expand(manager)
assert not expanded.has_errors
assert len(expanded.bind_sets) == 2
assert expanded.metadata["execution_performed"] is False
explicit ¶
explicit(
*,
scan_id: str,
points: tuple[dict[str, ParameterScalar], ...]
| list[dict[str, ParameterScalar]],
metadata: dict[str, Any] | None = None,
) -> ParameterScan
Preserve point order, copying and normalizing each name-to-scalar dictionary into a scan declaration. Invalid scalars or non-dictionary points raise. An empty list can be constructed, but expand reports an empty-scan diagnostic.
cartesian ¶
cartesian(
*,
scan_id: str,
grid: dict[
str,
tuple[ParameterScalar, ...] | list[ParameterScalar],
],
metadata: dict[str, Any] | None = None,
) -> ParameterScan
Sort axes by parameter name, then form the Cartesian product in each axis’s supplied value order; the last axis varies fastest. An empty grid or any empty axis produces no points. All points are materialized immediately, so estimate the product of axis lengths for large grids.
Bind each point through manager and return ParameterScanResult. bind_sets retains valid unique points; diagnostics identifies failures and their scan_index. Duplicate detection uses fully resolved parameter values and drops repeated points. A result may contain valid bindings and errors together; check has_errors before execution rather than treating a nonempty bind_sets as complete success.
Restore ParameterScan from a dictionary. Preserve point order and recheck mode and scalar input format. Missing required fields or invalid values can raise KeyError, TypeError or ValueError.
Parse a JSON object and call from_dict(), returning ParameterScan. Invalid JSON raises a parsing error; a non-object root raises TypeError.
Return a JSON-compatible dictionary, serializing nested objects and converting tuples to arrays. This stores the declaration, not an execution result.
Return a JSON string without writing a file. indent=None uses compact formatting; supply an indentation width for readable output.
Return the SHA-256 hex digest of canonical JSON. Fields, identifiers and metadata can affect it. Use it to compare saved content, not to decide physical equivalence.