You provide two things each round: a measured statistic vector and a scalar score. The runtime returns the next configuration. Everything else is shape.
Your measure(x) runs your device or simulator at configuration x and returns a statistic vector (for example, bit marginals from a batch of shots). You also compute a scalar score (your objective). The runtime never sees your hardware — only those numbers.
Pass score= each round; the runtime forms its own internal target and drives the configuration to improve the score.
copyopt = SWCOptimizer(license_key="EVAL-...", n=N)
x = opt.start(x0)
for _ in range(rounds):
marginals, score = measure(x)
x = opt.step(marginals, score=score)
opt.end()Two target estimators are available via config={"estimator": "elite"|"smart"} — "elite" is the default; "smart" trades to sub-quadratic measurement scaling at larger dimension. See choosing the estimator.
For setpoint or tracking problems — drive a measured output to a target while the system drifts. Use mode="regulation" and pass target=, or the convenience helper:
copyfrom swc import swc_regulate
x_final, history = swc_regulate(measure, x0, target, key, rounds=120)The runtime treats axes as separable. On strongly coupled (non-separable) plants its efficiency falls off as cross-channel coupling grows — tracking holds to roughly 10–15% normalized coupling, then degrades smoothly (no cliff). For coupled plants beyond that range, pre-conditioning the loop with a one-time calibration is on the roadmap; contact us if this is your regime. See the envelope for where coupling makes the runtime the wrong fit.
The default update assumes your decoded statistic responds to each control like a single-axis rotation marginal — monotone, with the conventional sign, over your operating range. Many parametric readouts satisfy this (rotation-angle and amplitude calibration of a single channel). Some do not: if your control→observable map has the opposite slope sign (for example a sin² Rabi-population readout rather than a rotation marginal), the default step can move the wrong way.
You do not need to calibrate. In regulation mode the runtime measures each channel’s drive direction at the start of the session — it probes each control, reads which way the observable moves, and drives using the measured sign. Plants with reversed polarity, negative gain, or per-channel sign differences all work with no extra code; the only requirement is local monotonicity over your operating range. The compatibility page lists every plant type this covers.
Call opt.end() when done, or use the context manager so it closes for you:
copywith SWCOptimizer(key, n=N) as opt:
x = opt.start(x0)
for _ in range(rounds):
x = opt.step(measure(x), score=objective(x))