Qubit design: API and CLI

Every qubit-design route has a fluxus qubit <command>, and the command calls the route function itself (fluxus.qubit_surface.call), so --json prints exactly the body the route returns, error bodies included. Text output is a readable summary of the same answer. The Fluxus test suite checks the API, the in-process call and the CLI against each other for every command, and runs the walkthrough below and checks the numbers it quotes.

Nothing here is silicon. The TransmonCross chain is trained on SQuADDS HFSS (capacitance, fr) and exact elsewhere (EC/EJ to f01 and anharmonicity, chi); its intervals describe agreement with HFSS. The parallel-pad family is a surrogate of an analytic oracle. The coupling tools solve a lumped circuit whose capacitances are yours.

Exit codes: 0 answered (an abstained or flagged answer included), 2 bad input, 3 refused (outside the data, or the engine is not available on this host). A script can tell a refusal from a crash.

Two geometry families, not interchangeable. cross is the qiskit-metal / SQuADDS TransmonCross + claw: use it for Metal designs. pad is Fluxus's parallel-pad cell. Their field names do not overlap.

The curl lines below use F=http://127.0.0.1:8787, a local engine, and E=docs/qubit/examples (request bodies kept in the repo and published with this guide). On the hosted API, replace $F/api/ with https://api.cogitan.ai/v1/fluxus/ and add your Authorization header. The CLI needs no server.

Quickstart: one lab design task, step by step

This works one design task on WM1 Q1 (the public SQuADDS chip). Steps keep their labels, s01 to s23. Every step that gives a number is below with the command and the curl that give it. The numbers in brackets are the engine's answers, checked by the Fluxus test suite.

s01 to s03, s20, s23: cards and studio projects. No engine numbers. Projects (create, save, export every project) are a studio feature, not part of this API. To see what the engine accepts before anything else:

fluxus qubit schema
fluxus qubit status
curl -s $F/api/qem/schema
curl -s $F/api/qem/status

s04 to s07: Q1 from the design notebook, with 90% intervals against HFSS. [f01 4.436 GHz [4.425, 4.448], anharmonicity -171.0 MHz [-172.0, -170.0], fr 6.415 GHz [6.350, 6.480], g 65.55 MHz [63.70, 67.44], chi -0.178 MHz [-0.196, -0.163], EC 156.7 MHz [155.8, 157.5], kappa / 2 pi 125 kHz [108, 145]]

fluxus qubit cross --cross-length-um 240 --claw-length-um 215 \
  --ground-spacing-um 10 --junction-lj-nh 9.686 --length-um 3900 \
  --coupling-length-um 225 --intervals
fluxus qubit cross --body $E/wm1_q1.json --intervals        # the same
curl -s $F/api/qem/cross -H 'content-type: application/json' \
  -d '{"cross_length_um": 240, "claw_length_um": 215, "ground_spacing_um": 10,
       "junction_lj_nh": 9.686, "length_um": 3900, "coupling_length_um": 225,
       "intervals": true}'

The answer also carries chi's regime (dispersive_regime, n_crit, n_crit_eff), EJ, purcell_t1_us and in_envelope / abstained. g uses the admittance-slope resonator capacitance (two-node capacitance matrix); its interval is a bound, not measured coverage. Add --purcell-filter-suppression X for a filter you measured.

The design notebook's Q1 has claw_cpw_length 0 (every HFSS capacitance row has 40 um). Send it and the numbers are the same, flagged: in_envelope false and outside_trained_configuration names the field (s09 shows this flag from Python).

fluxus qubit cross --body $E/wm1_q1.json --claw-cpw-length-um 0

s08: Q6's ground spacing, 10.9 um, refused by name (exit 3, HTTP 422). [Refused: 10.9 um is outside the HFSS range (4.1 to 10 um)]

fluxus qubit cross --body $E/wm1_q1.json --ground-spacing-um 10.9 --json
# {"error": {"code": "outside_envelope", "field": "ground_spacing_um",
#   "value": 10.9, "allowed": {"min": 4.1, "max": 10.0},
#   "reason": "swept_axis_out_of_range", "message": "..."}}
curl -s $F/api/qem/cross -H 'content-type: application/json' \
  -d '{"cross_length_um": 240, "claw_length_um": 215, "ground_spacing_um": 10.9,
       "junction_lj_nh": 9.686, "length_um": 3900, "coupling_length_um": 225}'

s09: WM1 from Qiskit Metal, all six qubits. The import runs in the Python client (cogitan.fluxus_metal.from_qiskit_metal), which is outside this API and CLI. What it reports is the same refusal set the route gives one qubit at a time: send each imported request to fluxus qubit cross --body.

s10: the lambda/2 readouts of Q3, Q5, Q6, each with its own NCap coupler. The qubits are refused, the readouts are not: /api/resonator with the NCap fields asks the half-wave NCap engine for fr and kappa. [Q3 fr 6.696 GHz, kappa 6366 kHz; Q5 6.855, 3133; Q6 6.912, 862; Q5 and Q6 flagged for ground spacing (every half-wave row: 4.1)]

fluxus qubit resonator --length-um 8150 --kind lambda2 --claw-length-um 185.9 \
  --finger-count 10 --finger-length-um 30.9 --cap-gap-um 4.1 \
  --cap-width-um 10.9 --ground-spacing-um 4.1
fluxus qubit resonator --body $E/wm1_q5_readout.json
fluxus qubit resonator --body $E/wm1_q6_readout.json
curl -s $F/api/resonator -H 'content-type: application/json' -d @$E/wm1_q3_readout.json

s11: make Q1 flux-tunable. A DC SQUID whose two junctions (14.53 nH and 29.06 nH) give 9.69 nH in parallel, and its tuning curve on 61 points. [f01 at bias 4.436 GHz [4.424, 4.448]; anharmonicity, fr, g, chi, EC as s05; tuning range 1.949 GHz]

fluxus qubit cross --body $E/wm1_q1_squid.json --intervals
fluxus qubit flux-sweep --body $E/wm1_q1_squid.json --n-points 61
curl -s $F/api/qem/cross/flux-sweep -H 'content-type: application/json' \
  -d '{"cross_length_um": 240, "claw_length_um": 215, "ground_spacing_um": 10,
       "length_um": 3900, "coupling_length_um": 225, "n_points": 61,
       "squid": {"lj1_nh": 14.53, "lj2_nh": 29.06}}'

The flags form is --squid-lj1-nh 14.53 --squid-lj2-nh 29.06 (with the geometry flags, and without --junction-lj-nh). Flux moves EJ only: EC, fr and kappa are one value for the whole curve. Loop inductance and flux crosstalk are not modelled.

s12: move the bias off the sweet spot. [f01 at bias 3.807 GHz [3.797, 3.817], anharmonicity -173.8 MHz [-174.8, -172.8], g 60.72 MHz [59.00, 62.47], chi -0.0944 MHz [-0.1016, -0.0877]]

fluxus qubit cross --body $E/wm1_q1_squid.json --flux-bias-phi0 0.25 --intervals
# with a flux-noise amplitude, a first-order 1/f dephasing estimate is added;
# without one, none is (it does not guess)
fluxus qubit cross --body $E/wm1_q1_squid.json --flux-bias-phi0 0.25 \
  --flux-noise-uphi0 2
curl -s $F/api/qem/cross -H 'content-type: application/json' \
  -d '{"cross_length_um": 240, "claw_length_um": 215, "ground_spacing_um": 10,
       "length_um": 3900, "coupling_length_um": 225, "intervals": true,
       "squid": {"lj1_nh": 14.53, "lj2_nh": 29.06, "flux_bias_phi0": 0.25}}'

tunable in the answer holds EJ at the bias, f01 at both sweet spots, the tuning range, df01/dPhi (GHz per flux quantum; zero at a sweet spot) and, with flux_noise_uphi0, dephasing (t_phi_us; flux_noise_f_ir_hz and flux_noise_t_us set its cut-off and time scale, defaults 1 Hz and 10 us).

s13: couple two Q1-like qubits. The studio's prefill: both qubits get C = e^2/(2h EC) of Q1's answer (the total capacitance, so it holds the readout claw; 123.65 fF to 0.01 fF) and Q1's junction; the second is detuned to 10.6 nH; 1 fF between them. [J exact 17.313 MHz]

fluxus qubit couple --from-cross $E/wm1_q1.json --q2-lj-nh 10.6 --cc-ff 1
fluxus qubit couple --c1-ff 123.65 --c2-ff 123.65 --cc-ff 1 \
  --q1-lj-nh 9.686 --q2-lj-nh 10.6                          # the same body
curl -s $F/api/coupling/pair -H 'content-type: application/json' \
  -d '{"capacitive": {"c1_ff": 123.65, "c2_ff": 123.65, "cc_ff": 1,
       "qubit1": {"lj_nh": 9.686}, "qubit2": {"lj_nh": 10.6}}}'

The answer has J (exact, first order with the charge elements, harmonic), the static ZZ exact and to second order (read perturbative_valid first) and the dressed levels. --bus (or any of --f1-ghz ... --g2-mhz) is the shared-resonator model instead. A SQUID cell given to --from-cross hands over EJ at its bias.

s14: the tunable coupler sweep, Yan et al. 2018, Fig. 2(a) circuit (the studio's defaults). [ZZ axis from -0.0046 to 0.0026 MHz; dashed idle points]

fluxus qubit coupler-sweep --body $E/yan2018_coupler.json
fluxus qubit coupler-sweep --c1-ff 70 --c2-ff 72 --cc-ff 200 --c1c-ff 4 \
  --c2c-ff 4.2 --c12-ff 0.1 --q1-f01-ghz 4 --q2-f01-ghz 4 \
  --fc-min-ghz 4.5 --fc-max-ghz 7 --n-points 41
curl -s $F/api/coupling/coupler-sweep -H 'content-type: application/json' \
  -d @$E/yan2018_coupler.json

The idle points: ZZ = 0 at 5.411 GHz and the exact coupling zero at 5.376 GHz (Yan's analytic g~ zero, 5.426 GHz, beside them). ZZ is null where the levels hybridise (36 of the 41 points here, resonant qubits), with the reason in refused.

s15: any lumped circuit, here the trimon of Maurya et al. (arXiv:2603.04566, Appendix B design values). [mode 0: 4.6931 GHz, -142.5 MHz, harmonic 5.0439 GHz]

fluxus qubit modes --body $E/trimon_maurya.json
fluxus qubit modes --matrix "46,21,4,21;21,30,21,3;4,21,53,21;21,3,21,36" \
  --junction 0,1,ej=8.16 --junction 1,2,ej=8.16 --junction 2,3,ej=8.16 \
  --junction 3,0,ej=8.16
curl -s $F/api/coupling/modes -H 'content-type: application/json' \
  -d @$E/trimon_maurya.json

--junction A,B,ej=GHz or A,gnd,lj=nH; --convention maxwell for a node capacitance matrix; --labels local for one mode per node. The answer holds every mode's frequency and anharmonicity and the chi matrix.

s16: next qubit from targets. Ranked TransmonCross designs, each re-solved with the full chain, each with request: the exact /api/qem/cross body that reproduces it. About 18 s. [#1 distance 0.000: cross 202, claw 175.1, ground 5 um, Lj 10.76 nH, lambda/4 3790.9 um, coupling 350 um; achieved g 80.10 MHz, chi -0.301 MHz]

fluxus qubit inverse --f01-ghz 4.5 --anharmonicity-mhz -200 --fr-ghz 6.5 --json > inv.json
python -c "import json; print(json.dumps(json.load(open('inv.json'))['candidates'][0]['request']))" > best.json
fluxus qubit cross --body best.json --intervals
curl -s $F/api/inv/cross -H 'content-type: application/json' \
  -d '{"f01_ghz": 4.5, "anharmonicity_mhz": -200, "fr_ghz": 6.5}'

s17: the junction for that Lj at your process's Jc (0.5 uA/um^2 is an example, not a process number). Use the full Lj from best.json (10.755042... nH); the studio does. [Ic 30.6 nA, EJ 15.20 GHz, Rn 9364 ohm cold, area 0.0612 um^2]

fluxus qubit junction --lj-nh 10.755042613636363 --jc-ua-per-um2 0.5
curl -s $F/api/junction -H 'content-type: application/json' \
  -d '{"lj_nh": 10.755042613636363, "jc_ua_per_um2": 0.5}'

Rounded to 10.76 nH the cold Rn reads 9368 ohm, not 9364.

s18: GDS of the qubit cell (TransmonCross geometry: cross, claw, junction marker; the resonator is not drawn; not a tape-out reticle). The route returns the file; X-Fluxus-Envelope says whether the predictions for it are trained ones. [1528 bytes, 22 polygons]

fluxus qubit gds --body best.json -o next_qubit.gds
curl -s $F/api/gds/cross -H 'content-type: application/json' \
  -d @best.json -o next_qubit.gds -D -

s19: frequency-collision yield for a 127-qubit heavy-hex chip at a 12 MHz spread (your fab's number). [4.29%, 95% CI 4.0 to 4.6, n = 20,000] The studio draws a fresh seed, so 4.29% is one draw; with --seed 1 the answer is 4.18% (CI 3.91 to 4.47) and replays exactly.

fluxus qubit yield --n-qubits 127 --sigma-f-mhz 12 --n-trials 20000 --seed 1
curl -s $F/api/yld -H 'content-type: application/json' \
  -d '{"n_qubits": 127, "sigma_f_mhz": 12, "n_trials": 20000, "seed": 1}'

s21: back to Qiskit Metal. The Python client's round trip (import Q1, search, write a TransmonCross options patch) runs on the same two routes: fluxus qubit cross --body $E/wm1_q1.json (s04) and fluxus qubit inverse (s16). The options patch itself is a client feature.

s22: Q3 on the command line (its cross gap is 29.1 um; the data holds 30). Exit 3. The legacy name fluxus qem-cross is the same command.

python -m fluxus.cli qem-cross --cross-length-um 200.9 --claw-length-um 185.9 \
  --ground-spacing-um 4.1 --junction-lj-nh 10.471 --cross-gap-um 29.1 \
  --cross-width-um 30.9 --claw-width-um 15.9      # exit 3
fluxus qubit cross --body $E/wm1_q3.json --json   # field cross_gap_um, allowed {const: 30.0}

Many designs at once. A sweep for one or two fields, a batch for a file of designs (a .jsonl or .json item may carry a squid object and the NCap fields; a .csv row is flat, so no squid), triage to see which still need your solver.

fluxus qubit sweep --body best.json --field junction_lj_nh --start 8 --stop 14 --n 13
fluxus qubit batch designs.csv -o results.csv
fluxus qubit triage designs.jsonl --require f01_ghz=4.3:4.7 --require anharmonicity_mhz=:-150

The studio features (projects, export) and the Python client (cogitan.fluxus, the Qiskit Metal import and options patch) are outside this API and CLI.

Reference

Every route is also in GET /api/capabilities with its schema and CLI command.

Common flags

• --json: the exact API body (for gds, a metadata object: path, size, polygons, envelope and its detail, scope).
• --body JSON|PATH: a base request (inline JSON or a .json file); flags on the command line override its fields (the SQUID flags override fields of the body's squid object one by one). Works on every request command.
• Numbers must be finite: nan and inf are refused at the flag (exit 2), and on the wire every route answers 422 non_finite_number.

TransmonCross fields (cross, flux-sweep, sweep, gds, batch items)

CLI flags are the field names with dashes (--claw-cpw-length-um, --finger-count); the squid block is --squid-lj1-nh, --squid-lj2-nh, --flux-bias-phi0, --flux-noise-uphi0, --flux-noise-f-ir-hz, --flux-noise-t-us. fluxus qubit schema --json is the authority; it is read from the constants the engines refuse by.

Refusals (HTTP 422, code: outside_envelope, exit 3), each naming field, value, allowed and reason: swept_axis_out_of_range (allowed {min, max}), unsampled_gap (allowed {ranges}), outside_support_triangle (the claw does not fit the cross), single_valued_axis_changed (a pinned field or eps_r; allowed {const}). Malformed input (a negative junction or coupler, an unknown field, a bad kind, a squid with junction_lj_nh, NCap fields with lambda4) is 400 or 422 invalid_request, exit 2. A missing checkpoint is 503 engine_unavailable with a remedy, exit 3.

Abstention, not refusal: a resonator outside the fr engine's box is still answered, with fr from the analytic CPW form (about 20% off HFSS): abstained: true, in_envelope: false, and out_of_envelope names the fr refusal. Exit 0.

Intervals: 90% by default, against HFSS. Coverage is measured for EC, f01 and anharmonicity (98.4% at the 95% capacitance level); g and chi rest on a union bound; kappa has its own band; Purcell T1 has none.

Flux sweep (flux-sweep)

The /api/qem/cross fields with squid required, plus n_points (2 to 101, default 41), flux_min_phi0 and flux_max_phi0 (default -0.5 and 0.5; each -1 to 1). Columns are lists aligned with flux_phi0; a point that cannot be solved (EJ = 0 for a symmetric SQUID at half a flux quantum) is null with the reason in refused; transmon_regime is false where EJ/EC < 20. No intervals (intervals: true is a 400). Off-envelope geometry is refused as on /api/qem/cross.

lambda/2 NCap readout (resonator, cross --kind lambda2)

Naming any of finger_count, finger_length_um, cap_gap_um, cap_width_um asks for the half-wave NCap engine (fr and kappa), which needs kind lambda2 and claw_length_um; omitted ones take the coupler the half-wave rows were solved with (5 fingers, 30 um, gap 5 um, width 10 um). Outside its envelope it refuses by name. On /api/resonator, ground_spacing_um only flags (the rows hold it at 4.1 um). This is the readout-only path: a qubit outside the HFSS data does not block its resonator's answer.

Coupling (couple, coupler-sweep, modes)

Lumped circuits: every capacitance is your input; Fluxus has no layout-to-capacitance model for multi-qubit chips. Each qubit junction is exactly one of lj_nh, ej_ghz or f01_ghz (a bare frequency; EJ is solved from the exact spectrum): --q1-lj-nh, --q1-ej-ghz, --q1-f01-ghz, and the same for --q2-.... A quantity whose dressed levels are hybridised is null, with the reason in refused. Limits (6 nodes, 4 modes, 8 junctions, 81 coupler-sweep points, levels) are in fluxus qubit schema under coupling. A non-symmetric or non-positive matrix is 400 invalid_circuit with problems, exit 2. The modes solver uses an iterative eigensolver above 1,200 basis states, so repeated calls can differ in the last few bits (about 1e-13 relative); compare its answers to a tolerance.

Parallel-pad fields (pad, verify, gds-pad)

--pad-width-um, --pad-height-um, --pad-gap-um, --ground-gap-um, --junction-lj-nh (alias --lj-nh), --length-um, --coupling-cap-ff are swept; --center-width-um, --gap-um, --eps-r and --kind lambda2 are pinned, and moving one makes the surrogate abstain (the oracle answers, abstained: true, exit 0). --engine surrogate|oracle forces one; --alpha sets the interval level (0.1 is the backend's own wrapper). A weak-dispersive answer (dispersive_regime: weak) has no chi_mhz interval: its calibrated coverage there is 49.3%, against a 90% target.

Batch, sweep, triage

• batch: .jsonl (one /api/qem/cross object a line), .json (an array, or {"items": [...]}) or .csv (header = field names; an empty cell is unset). Output jsonl is the exact slot per design; csv is a summary row (status, code, field, f01, anharmonicity, fr, g, chi, EC, kappa, Purcell, regime, source, message). --intervals and --alpha apply to items that do not set them. One call takes 500 items (the CLI sends longer files in chunks); past the 60 s request budget the rest come back budget_exhausted.
• sweep: --field (and --field2) from cross_length_um, claw_length_um, ground_spacing_um, junction_lj_nh, length_um, coupling_length_um; --start, --stop, --n (default 21, at most 201; 41 per axis for two). Over the cap the grid is clamped and says so. Points outside the data come back refused with field and reason. No intervals in a sweep.
• triage: --require TARGET=LO:HI (either bound may be empty) on f01_ghz, anharmonicity_mhz, fr_ghz, g_mhz, chi_mhz, ec_mhz or kappa_khz. Decisions read the intervals only: accept when every interval sits inside its window, reject when one sits wholly outside, simulate otherwise and for any refused or abstained design. The risk figures are bounds (k x alpha to accept, alpha to reject), not measured error. Up to 200 candidates a call.

Yield

yield, yield --detail and yield-curve take --n-qubits (required), --lattice heavy_hex|square, --target-f-ghz F1,F2,..., --sigma-f-mhz (default 12), --anharm-mhz (default -300), --n-trials (default 20000) and --seed. yield-graph FILE takes a .json with frequencies_ghz and edges (0-based pairs). Every answer echoes seed; omitted, a fresh one is drawn (for yield-graph, the route's fixed seed, so its unseeded answer is unchanged). A run over the 60 s budget is refused with the n_trials that fits (exit 2).