Parameter Sweeps

A ParameterSweep builds a deterministic grid of parameter combinations and expands it as an ordered Cartesian product.

Definitions

Each parameter maps to one of:

  • a list/tuple of explicit numeric values — [0.0, 0.5, 1.0];

  • {"values": [...]} — explicit values;

  • {"range": (start, stop, step)} — NumPy arange-style;

  • {"start": .., "stop": .., "num_points": n} — linspace;

  • {"start": .., "stop": .., "step": ..} — arange-style.

Usage

from microquantum import ParameterSweep

sweep = ParameterSweep({
    "theta": [0.0, 0.5, 1.0],              # explicit values
    "phi": {"range": (0.0, 1.0, 0.5)},     # arange-style (0.0, 0.5)
})

print(sweep.parameters)            # ("theta", "phi")
print(sweep.values)                # {"theta": [...], "phi": [0.0, 0.5]}
print(sweep.num_combinations)      # 3 * 2 == 6
print(len(sweep))                  # 6
print(sweep.combinations())        # 6 ordered dicts

# iterable too:
for combo in sweep:
    print(combo)

Verify against a base work item

verify/validate tie a sweep to the base work’s parameters before any execution:

from microquantum import Parameter, QuantumCircuit

theta = Parameter("theta")
phi = Parameter("phi")
qc = QuantumCircuit(1).ry(theta, 0).rz(phi, 0)

available = {p.name for p in qc.parameters}   # {"theta", "phi"}
print(sweep.validate(available))    # [] if compatible
sweep.verify(available)             # raises ValueError on mismatch

Use in experiments

Add a sweep to an Experiment with a base plan/circuit; each combination becomes one bound execution (see Experiments). Sweeps are JSON-safe (to_dict() / to_json()).