Qubit design

qem

Hamiltonian for one PARALLEL-PAD transmon cell (f01, anharmonicity, fr, g, chi).

Fidelity

surrogate_of_analytic_oracle

Validation

reference

fluxus.physics.solve_cell -- an ANALYTIC capacitance/resonator model. Its geometry->Hamiltonian error against a field solve is tens of percent and is NOT included in the numbers below.

note

chi is composed from the exact diagonalisation, not regressed; see checkpoints/metrics.json

Refuses when

• geometry outside SPEC_RANGES -> abstained=true, oracle value
• kind other than lambda4, or center_width_um=10.0, gap_um=6.0, eps_r=11.45 changed (the surrogate has no input for them) -> abstained=true, oracle value
• eps_r < 1 -> HTTP 400 from the oracle
• the worst dressed overlap of the four levels chi reads is below 0.7236 (n_crit_eff < 0.25, |Delta| = g for a two-level pair) -> chi NaN, chi_method='unresolved', dispersive_regime='unresolved'
• NOT a refusal: between 0.7236 and 0.8536 (n_crit_eff 0.25 to 1.00) chi IS answered, with dispersive_regime='weak' and a chi_caveat; it holds only well below n_crit photons, so read n_crit_eff before using it at readout power
• dispersive_regime='weak' answers carry NO chi_mhz interval: the calibrated chi interval covers 49.3% of weak-tier answers against a 90% target (98.3% of dispersive ones; fresh 10,000-cell sample, seed 20260710); the chi value and the other four intervals are still served

qem_cross

Hamiltonian for one TransmonCross + claw cell, the SQuADDS / qiskit-metal geometry family.

Fidelity

surrogate_of_em_solve+exact_hamiltonian

Validation

reference

SQuADDS qubit-TransmonCross-cap_matrix, Ansys HFSS simulated Maxwell capacitance matrix -- NOT silicon

citation

Shanto et al., SQuADDS, Quantum 8, 1465 (2024), arXiv:2312.13483

config

qubit-TransmonCross-cap_matrix

n

1934

method

5-fold GroupKFold holding out whole cross_length values, degree-4 ridge on log(cross_length), log(claw_length), ground_spacing, fitted to log C

split_note

GROUPED, not random. Random KFold on this dense 3-D grid reports 0.12% median for C_cross_cross and is measuring interpolation between adjacent grid points.

c_cross_cross_ff

median

0.003

p95

0.0166

c_cross_claw_ff

median

0.0056

p95

0.0175

ec_mhz

median

0.003

p95

0.0168

Refuses when

• a swept axis outside its range -> HTTP 422 outside_envelope with {field, value, allowed:{min,max}}
• a single-valued axis changed -> HTTP 422 outside_envelope with {field, value, allowed:{const}}
• eps_r other than 11.45 (the HFSS-trained capacitance and fr models have no permittivity input) -> HTTP 422 outside_envelope with {field: eps_r, allowed:{const}}
• the capacitance engine has not been trained -> HTTP 503 engine_unavailable with a remedy string
• the worst dressed overlap of the four levels chi reads is below 0.7236 (n_crit_eff < 0.25, |Delta| = g for a two-level pair) -> chi NaN, chi_method='unresolved', dispersive_regime='unresolved'
• NOT a refusal: between 0.7236 and 0.8536 (n_crit_eff 0.25 to 1.00) chi IS answered, with dispersive_regime='weak' and a chi_caveat; it holds only well below n_crit photons, so read n_crit_eff before using it at readout power

qem_cross_flux_sweep

Tuning curve of a flux-tunable TransmonCross: f01, anharmonicity, g, chi and the Purcell T1 limit on a grid of flux points.

Fidelity

surrogate_of_em_solve+exact_hamiltonian

Validation

Refuses when

• no squid block -> HTTP 400
• intervals true -> HTTP 400 (the sweep has none)
• n_points above 101 or below 2 -> HTTP 422
• flux_max_phi0 not above flux_min_phi0 -> HTTP 400
• off-envelope geometry -> HTTP 422 outside_envelope, as qem_cross
• a point where EJ = 0 is null, with the reason in refused

junction

Josephson junction calculator: one of Lj, Ic, EJ or room-temperature Rn -> all the others, plus area from Jc.

Fidelity

analytic_closed_form

Validation

Refuses when

• not exactly one of lj_nh, ic_na, ej_ghz, rn_ohm_room -> HTTP 400 invalid_junction_input
• rn_ohm_room given without room_over_cold_ratio (process-dependent, never defaulted) -> HTTP 400
• jc in both units, or any value <= 0 -> HTTP 400

inv_cross

Inverse design: target Hamiltonian -> ranked TransmonCross geometries.

Fidelity

surrogate_of_em_solve+exact_hamiltonian

Validation

reference

SQuADDS qubit-TransmonCross-cap_matrix, Ansys HFSS simulated Maxwell capacitance matrix -- NOT silicon

citation

Shanto et al., SQuADDS, Quantum 8, 1465 (2024), arXiv:2312.13483

config

qubit-TransmonCross-cap_matrix

n

1934

method

5-fold GroupKFold holding out whole cross_length values, degree-4 ridge on log(cross_length), log(claw_length), ground_spacing, fitted to log C

split_note

GROUPED, not random. Random KFold on this dense 3-D grid reports 0.12% median for C_cross_cross and is measuring interpolation between adjacent grid points.

c_cross_cross_ff

median

0.003

p95

0.0166

c_cross_claw_ff

median

0.0056

p95

0.0175

ec_mhz

median

0.003

p95

0.0168

Refuses when

• no target named -> HTTP 400 no_targets
• unknown target name -> HTTP 400 (never silently ignored)
• an unreachable target still returns the closest design; read residuals to tell 'best available' from 'hit'

resonator_fr

Resonator frequency from geometry. With the lambda/2 NCap coupler fields (finger_count, finger_length_um, cap_gap_um, cap_width_um) and claw_length_um it also returns kappa, from the half-wave NCap engine, with no qubit needed.

Fidelity

surrogate_of_em_solve

Validation

median

0.0273

p95

0.1052

n

1160

n_unique_lengths

19

quantity

resonator fr

reference

SQuADDS HFSS eigenmode (EM-simulated, not silicon)

method

GroupKFold(5) holding out whole resonator lengths, degree-2 polynomial ridge in log-log space; NESTED model selection (degree chosen by an inner GroupKFold on training lengths only, so the reported number never participated in the choice)

superseded_trees

median

0.0666

p95

0.1553

note

HistGradientBoosting, the family shipped until 2026-08-10. Trees cannot represent fr ~ 1/L, so they lose more than half their accuracy as soon as the split stops handing them neighbouring lengths

random_kfold_contrast

median

0.0275

p95

0.0891

note

the flattering split. For THIS family grouped ~ random (2.73% vs 2.75%), which is the signature of a model that learned the physics rather than the grid; the tree family split 6.66% vs 2.84%

claw_aware

median

0.0048

p95

0.0109

n

1160

method

GroupKFold(5) over whole resonator lengths, nested degree selection, degree-2/3 polynomial ridge in log-log space with log1p(claw_length) as an 8th feature

improvement_over_claw_blind

5.70x on the median, 9.7x on p95

note

selected by predict_fr(..., claw_length_um=...). A bare ResonatorSpec carries no claw, so the claw-blind numbers above remain the honest answer for those callers

per_point_rejected

constant

coverage

0.983

mean_rel_width

0.0124

per_point

coverage

0.893

mean_rel_width

0.0215

width_vs_error_corr

-0.034

verdict

rejected: lower coverage, wider band, and no correlation between predicted difficulty and realised error

design_readiness

a designer targeting a readout frequency needs ~1%. Claw-aware: 0.48% median / 1.09% p95 -- at the threshold. Claw-blind: 2.73% / 10.52%, still a scoping tool. Analytic CPW model: 20.03%

config

cavity_claw-RouteMeander-eigenmode

n_trained

1160

n_trained_claw

1160

Refuses when

• checkpoint absent -> HTTP 503
• center_width_um or gap_um differs from the single trained value -> HTTP 422 resonator_outside_envelope
• length_um or coupling_length_um outside the trained range for its kind -> HTTP 422 resonator_outside_envelope
• NCap fields with kind lambda4, with a coupling_length_um, or without claw_length_um -> HTTP 400
• NCap request outside the half-wave envelope (see qem_cross envelope._halfwave_ncap) -> HTTP 422 naming the field

coupling_pair

Two transmons, direct capacitor or shared bus: J, static ZZ exact and perturbative, dressed frequencies.

Fidelity

exact_diagonalisation_of_lumped_circuit

Validation

reference

limits and second-order perturbation theory of the same circuit Hamiltonian; no measured ZZ

checks

• J = 0 at cc = 0, J linear and ZZ quadratic in small cc
• resonant qubits (80 fF, 2 fF, 5.0 GHz): the exact splitting 121.92 MHz is 2 J_charge to 0.008%
• exact ZZ vs second order with CPB charge elements and counter-rotating terms: agree to 0.03-0.04% at cc = 0.02-0.2 fF (80/85 fF, 5.0/5.6 GHz)
• the textbook formula 2J^2(a1+a2)/((D+a1)(D-a2)) has the exact sign and reads 4.3% high there: its harmonic sqrt(2) 1-2 element overstates the transmon's ((n12/n01)^2/2 = 0.944 at EJ/EC ~ 30)
• bus: exact J agrees with g1 g2 (1/D1 + 1/D2 - 1/S1 - 1/S2)/2 to 0.02-0.4% at g = 20-100 MHz (f 5.0/5.2, fr 7.0 GHz); the RWA form without the 1/S terms is 13-14% low

test

tests/test_multiqubit.py

Refuses when

• non-symmetric, negative (branch) or non-positive-definite capacitance matrix -> HTTP 400 invalid_circuit with problems[]
• more than the size caps in envelope -> HTTP 400 invalid_circuit
• a quantity whose dressed levels are hybridised (overlap below 0.7236) -> null, with the reason in refused
• out-of-range number (capacitance outside [0, 10000] fF, frequency outside (0, 50] GHz, EJ outside (0, 500] GHz) -> HTTP 422
• both or neither of capacitive and bus -> HTTP 400
• a qubit with not exactly one of lj_nh, ej_ghz, f01_ghz -> HTTP 400
• a target f01 below the EJ/EC = 1 value -> HTTP 400

coupling_coupler_sweep

Transmon - tunable coupler - transmon: ZZ and effective coupling vs coupler frequency, and the idle points.

Fidelity

exact_diagonalisation_of_lumped_circuit

Validation

reference

Yan et al., Phys. Rev. Applied 10, 054062 (2018): Eq. (5) worked example and the Fig. 2 circuit

checks

• Eq. (5) terms for the printed example: -1.25, -0.139, 0.5, 1.0 (paper: -1.25, -0.14, 0.5, 1.0)
• Fig. 2 circuit (C1 70, C2 72, Cc 200, C1c 4, C2c 4.2, C12 0.1 fF, qubits 4 GHz): exact coupling zero 5.376 GHz, ZZ zero 5.411 GHz, Eq. (5) zero 5.426 GHz; the paper's Fig. 2(b) dot, read by eye, is at about 5.41 GHz. Their qubits are not identical, so the dressed qubits stay 0.33 MHz apart at the zero and a gap-based 2g~ cannot place it closer than about +-0.07 GHz
• 2g~ at 4.3 GHz: exact -20.07 MHz; Fig. 2(b) crosses -20 MHz near 4.3 GHz
• the paper does not state the transmons' EJ or anharmonicity; here each is a transmon with the stated C and its bare f01 at 4 GHz

test

tests/test_multiqubit.py

Refuses when

• non-symmetric, negative (branch) or non-positive-definite capacitance matrix -> HTTP 400 invalid_circuit with problems[]
• more than the size caps in envelope -> HTTP 400 invalid_circuit
• a quantity whose dressed levels are hybridised (overlap below 0.7236) -> null, with the reason in refused
• out-of-range number (capacitance outside [0, 10000] fF, frequency outside (0, 50] GHz, EJ outside (0, 500] GHz) -> HTTP 422
• fc_max_ghz not above fc_min_ghz -> HTTP 400
• a coupler frequency the coupler EC cannot reach as a transmon -> HTTP 400

coupling_modes

Any small lumped circuit (e.g. a trimon): dressed frequencies, anharmonicities and the chi matrix.

Fidelity

exact_diagonalisation_of_lumped_circuit

Validation

reference

Maurya et al., arXiv:2603.04566 (trimon), Appendix B design capacitance matrix and EJ = 8.16 GHz; Table AI measured values

checks

• mode frequencies 4.6931 / 5.1970 / 5.9597 GHz vs the paper's design 4.691 / 5.195 / 5.957 GHz (+0.04 to +0.05%) and measured 4.709 / 5.174 / 5.940 GHz (-0.34 to +0.44%)
• anharmonicity -142.5 / -146.4 / -171.6 MHz vs measured -118 / -129 / -164 MHz (4.6-20.8% larger in magnitude)
• chi AB / BC / CA -249.1 / -311.1 / -286.3 MHz vs measured -211 / -270 / -243 MHz (15-18% larger in magnitude, same ordering)
• the paper gives no design-stage anharmonicity or chi, so the nonlinear gap cannot be split between this lumped model and the fabricated device
• a floating transmon equals its grounded equivalent C = Cp + C1 C2 / (C1 + C2) to 1e-7; a junction-less island equals its Kron-reduced series capacitance to 1e-6

test

tests/test_multiqubit.py

Refuses when

• non-symmetric, negative (branch) or non-positive-definite capacitance matrix -> HTTP 400 invalid_circuit with problems[]
• more than the size caps in envelope -> HTTP 400 invalid_circuit
• a quantity whose dressed levels are hybridised (overlap below 0.7236) -> null, with the reason in refused
• out-of-range number (capacitance outside [0, 10000] fF, frequency outside (0, 50] GHz, EJ outside (0, 500] GHz) -> HTTP 422
• a junction naming a node outside the matrix, or joining a node to itself -> HTTP 400
• no junction, or no dynamical mode -> HTTP 400

qem_schema

fields, units, defaults, envelopes, engines and refusal kinds

Fidelity

metadata

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• never refuses

qem_status

whether each qubit engine loads here, with versions

Fidelity

metadata

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• never refuses; an engine that does not load reports available false with the error

qem_cross_batch

many TransmonCross cells, one /api/qem/cross body per slot

Fidelity

surrogate_of_em_solve+exact_hamiltonian

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• each slot inherits /api/qem/cross: outside the data -> that slot holds the 422 outside_envelope body; a malformed item -> its 400 or 422 body
• more than the cap -> truncated with a clamped block
• past the request budget -> budget_exhausted slots and a budget block

qem_cross_sweep

one or two TransmonCross fields over a grid, point answers

Fidelity

surrogate_of_em_solve+exact_hamiltonian

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• a malformed base or axis -> HTTP 400 once
• base.intervals true -> HTTP 400 (point answers only)
• points outside the data -> status refused with field and reason
• n over the cap -> clamped with a clamped block

qem_triage

accept / reject / simulate candidates from their intervals

Fidelity

conformal_interval_decision

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• a requirement on an unknown target, or with lo > hi or a NaN bound -> HTTP 400
• a candidate outside the data -> simulate, refusal named; never accept or reject without an interval

qem_verify

parallel-pad prediction against the analytic oracle

Fidelity

surrogate_vs_analytic_oracle

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• the same refusals as /api/qem

inv

targets -> ranked parallel-pad cells, oracle-verified

Fidelity

analytic_oracle_verified_search

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• unknown target name -> HTTP 400
• an unreachable target returns the closest cells; read distance

gds_cross

TransmonCross qubit cell as GDSII bytes (resonator not drawn)

Fidelity

layout_geometry

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• a non-physical junction or resonator value -> HTTP 400
• outside the data: still drawn, X-Fluxus-Envelope says outside and names the field

gds

parallel-pad cell plus resonator as GDSII (base64 in JSON)

Fidelity

layout_geometry

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• the same physical-validity check as /api/qem -> HTTP 400
• length_um over 100,000 um -> HTTP 422

em_inductance

partial-inductance field solve over conductor segments

Fidelity

analytic_field_solve

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• more than 1,000 segments -> HTTP 422
• degenerate geometry -> HTTP 400

yld

frequency-collision yield Monte Carlo on a lattice

Fidelity

monte_carlo_of_collision_rules

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• over the request budget -> HTTP 422 naming the n_trials that fits

yld_detail

yield with per-qubit collision rates

Fidelity

monte_carlo_of_collision_rules

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• over the request budget -> HTTP 422

yld_curve

yield against frequency spread

Fidelity

monte_carlo_of_collision_rules

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• over the request budget (one run per sigma) -> HTTP 422

yld_graph

yield over your own qubit graph and frequencies

Fidelity

monte_carlo_of_collision_rules

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• edges out of range or self-loops -> HTTP 400
• n_trials over 50,000 -> clamped

chip_map

lattice map: coordinates, roles, edges, default frequencies

Fidelity

metadata

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• n_qubits outside [1, 2000] -> HTTP 400

cell_eval

one placed floorplan cell scored by its surrogate

Fidelity

surrogate_of_analytic_oracle

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• unknown cell -> HTTP 400

floorplan_eval

a placed floorplan: per-cell metrics and chip rollup

Fidelity

surrogate_of_analytic_oracle

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• duplicate cell ids or malformed wires -> HTTP 400

preflight

logical-qubit preflight from coherence and gate inputs

Fidelity

rules_corpus_bound

Validation

reference

see qem_cross for the TransmonCross chain and qem for the parallel-pad family; nothing here is silicon

Refuses when

• has_lru or code_family unstated -> refused with the reason
• this host does not carry Corpus -> HTTP 503 corpus_unavailable