Trainability Lab

The Trainability Lab is Research mode’s microscope for parameterized circuits. Point it at the circuit in your editor and it answers one question with evidence: will gradient-based training of this ansatz get stuck on a barren plateau, and could a classical method simulate it anyway? Open it from the Trainability Lab item in the Research rail. It needs the desktop kernel; the web build shows a notice instead.

What you point it at

The Lab runs the code in your editor once (the same trust as ⌘↵: it is your own code), finds the parameterized Qiskit or Cirq circuit, and converts it to an internal parameterized circuit IR. Unbound symbols must be parameters of the circuit, not free variables. If the code reads params.get("n_qubits"), the Lab offers that name for the scaling study.

The observable is resolved in this order: the field in the target bar, a module-level nuclei_observable in your code (a string, a Qiskit SparsePauliOp or a Cirq PauliSum), then preset:local_z. Presets are preset:local_z (mean of Z on each qubit), preset:global_z (Z on every qubit), preset:zz_chain and preset:tfim. A malformed observable is reported with the column of the problem.

The analyses

Analysis	What it measures	Main assumptions
Gradients	The variance of each parameter’s partial derivative of the cost, over random parameter draws, plus the mean over parameters	Parameters drawn uniformly on [0, 2π) (`uniform`) or from a narrow Gaussian near zero (`small`); initial state \|0…0⟩
Scaling	How that variance changes with qubit count n (and optionally layer count): a fit of Var ∝ 2^(−βn) against a power law in n	Your code builds a comparable circuit for each n through `params`; at least 4 distinct n for a verdict
Lie algebra	The dimension of the dynamical Lie algebra 𝔤 generated by the circuit’s gates, its classification, and the Lie-algebraic variance prediction	Deep-circuit regime (the circuit approximates a 2-design over e^𝔤); 𝔤 treated as simple
Expressibility	KL divergence between the circuit’s distribution of state overlaps and the Haar distribution	Random draws of parameter pairs; limited by pair count and bin count
Entanglement	Meyer-Wallach entangling capability averaged over random parameters	Statevector simulation, so at most 20 qubits
Landscape	A 2-D slice of the cost along two random orthonormal directions through a random center	A slice shows local structure only

Statevector-based analyses (sampling gradients, expressibility, entanglement, landscape) are capped at 20 qubits by the kernel, and at 14 by the default UI settings. The exact engine below goes to 128.

Gradient variance: three kinds of interval

Every variance in the Lab is shown with its method and an interval. They are not interchangeable:

Bootstrap interval (sampling). The kernel draws samples parameter vectors (16 to 4096, default 200), computes exact gradients for each with a compiled batched simulator, and reports the sample variance with a 95% percentile bootstrap interval (1000 seeded resamples). It says how well this finite sample pins down the variance. It is statistical, and it shrinks as you add samples.
PPE exact. The Pauli Propagation Engine walks the observable backwards through the circuit as a sum of Pauli strings and computes the variance analytically. When no term had to be discarded, the answer is exact: the interval has zero width, there is no sampling noise, and it works up to 128 qubits. It is labelled pauli_propagation_exact.
PPE bounded. When the frontier of Pauli strings outgrows the budget (max_frontier, or a time budget), the engine discards the smallest terms and tracks the total weight it threw away. The result is still rigorous: the interval is a truncation bound that provably contains the true value, but it can be loose. It is labelled pauli_propagation_bounded and the UI calls the interval a truncation interval, not a confidence interval. Revised after review: when the bound is too loose to mean anything (the sweep timed out, the lower end is 0, or the upper end is more than twice the lower), the Lab shows no number: the variance is null and only the interval is shown. It never reports the middle of the interval.

method: auto (the default) uses the engine when it applies and its bound is tight, and falls back to sampling otherwise. You can force sampling or ppe. The engine applies when every rotation is a single-Pauli rotation with its own independent parameter (no shared parameters, no nonzero offset on a parameter) and every fixed gate is Clifford. Circuits outside that class use sampling, and the Lab tells you why.

Verdict rules

Scaling verdict. The fit is weighted least squares on log₂(variance), with weights from the interval widths. The exponential model has rate β. Models are compared by AIC.

Verdict	When
Barren plateau	The exponential model is preferred by ΔAIC ≥ 2 and the lower end of β’s 95% interval is above 0.1
Polynomial	β’s 95% interval lies entirely at or below 0.1 (its upper end is ≤ 0.1), or the power-law model is preferred by ΔAIC ≥ 2
Inconclusive	Anything else. Always when fewer than 4 distinct qubit counts were fitted, when the largest n is less than twice the smallest, and when any point has a zero or null variance or an uninformative interval (lower end 0, or upper end more than twice the lower)

Revised after review. The earlier rule called a fit polynomial whenever β’s interval merely included values at or below 0.1, so a wide interval became a positive verdict. On synthetic data over n = 4 to 7 that called n⁻¹ a barren plateau 22% of the time and 2^(−0.25n) polynomial 22.5% of the time. Now a narrow range is inconclusive, and polynomial needs either a small upper bound or a model-selection win.

Inconclusive is a real answer. The Lab never rounds an unclear fit up to a verdict. β’s interval is a parametric bootstrap: each point’s log-variance is redrawn from its own interval and the slope refitted, so the point intervals (sampling or Pauli-propagation truncation) carry into β.

Barren-plateau risk (the verdict rail). The rail combines the evidence, and lists every item so you can see why. Measured scaling outranks theory:

A barren_plateau scaling verdict gives high; polynomial gives low (raised to medium if a lint warning about a global cost or an exponentially large algebra also fired).
With no usable scaling verdict, an exponentially large Lie algebra gives high when the closure completed and medium when it was truncated; a small algebra gives low.
With neither, a TRN001 or TRN002 lint warning gives medium.
Otherwise the risk is unknown. The Lab does not guess.

Simulability. If the algebra’s dimension is polynomial (at most 4n²), the Lab notes that expectations may be classically simulable with 𝔤-sim (Goh et al. 2023) when the observable or the state lies in 𝔤. Whether a circuit resists the Pauli-propagation estimator is not a statement about classical hardness: estimability is resistance to this estimator under this budget; it is not a proof of classical simulability.

Lie algebra and the variance prediction

The closure is computed on the effective generators: fixed gates are pushed to the end of the circuit, so each rotation generator is conjugated by the fixed gates before it. With only Clifford fixed gates this is exact Pauli conjugation and scales to about 20 qubits; non-Clifford fixed gates use a dense fallback for at most 6 qubits and are otherwise unsupported. If the closure hits the dimension cap (4096 by default) or the time budget (10 s) the status is truncated and only a lower bound on the dimension is shown.

Classification is by exact dimension match to su(2ⁿ), so(2ⁿ), sp(2ⁿ⁻¹) and the free-fermion algebra so(2n). A match is not an isomorphism proof, and the note says so. Anything else is reported as other.

The prediction Var = P_𝔤(ρ) P_𝔤(O) / dim 𝔤 (Ragone et al., 2024) is shown next to the empirical measurement, with its stated assumptions, and is marked applicable only when the observable or the initial state lies in 𝔤. When it does not apply, the Lab says so rather than printing a number.

Revised after review. The formula is the sum over the simple ideals of the algebra, Var = Σⱼ P_𝔤ⱼ(ρ) P_𝔤ⱼ(O) / dim 𝔤ⱼ, after removing the centre (generators that commute with everything). The single-ideal version is wrong for an algebra such as su(2) ⊕ su(16) (0.062 predicted, 0.336 measured). It is computed only where the ideals can be found exactly (Pauli-string generators) and for the provably simple su(2ⁿ); for other shared-parameter or multi-Pauli circuits the Lab reports “not applicable”. The prediction is for the variance of the cost over parameter space, so it is compared with the measured cost variance, never with the gradient variance.

Polynomial dimension is not trainability. A full su, so or sp of 2ⁿ is the exponential family even when its dimension is small (so(8) at n = 3): it is never reported as 𝔤-sim feasible. A genuinely polynomial dimension suggests 𝔤-sim simulability; it does not by itself bound the purities or guarantee trainability.

Lint rules

Lint runs as you type with a 0.35 s compute budget and draws markers in the editor. Rules that need a complete Lie-algebra closure (TRN002, TRN003, TRN006) are skipped, with a note, if the closure does not finish in time.

Code	Severity	Fires when	Reference
TRN001 Global cost function	warning	An observable term acts on at least max(3, ⌈n/2⌉+1) qubits, and n ≥ 4	Cerezo et al., Nat. Commun. 12, 1791 (2021)
TRN002 Exponentially large Lie algebra	warning	The closure is complete and its dimension matches su, so or sp of 2ⁿ, for n ≥ 4	Ragone et al., Nat. Commun. 15, 7172 (2024)
TRN003 Polynomial Lie algebra	info	The dimension is at most 4n² and is not a full su/so/sp family: the circuit is likely 𝔤-sim simulable (this does not by itself guarantee trainability)	Goh et al., arXiv:2308.01432 (2023)
TRN004 Dead parameter	info	A parameterized gate’s generator commutes with the observable after conjugation and nothing later changes that: it cannot affect the cost	n/a (a direct computation)
TRN005 Redundant consecutive rotations	info	Two consecutive rotations about the same axis on the same qubit with independent parameters	n/a
TRN006 Overparameterized circuit	info	The number of parameters is at least the algebra’s dimension	Larocca et al., Nat. Comput. Sci. 3, 542 (2023)
TRN007 No free parameters	info	The circuit has none; the Lab is inactive (reported once in the summary, never as a marker)	n/a

The Trainability Certificate

Export certificate in the verdict rail writes two files next to your experiments:

experiments/<file-stem>.trainability.json holds the full results, the verdicts and the provenance.
experiments/<file-stem>.trainability.md is a human-readable report: each verdict with its evidence chain, every number with its interval and method label, the stated assumptions, citations, and a Reproduce block.

The provenance records the SHA-256 of your code, the canonical observable, the settings as clamped by the kernel, the versions of Python, NumPy, Qiskit, Cirq and Stim, a fingerprint of the analysis source, the backend and a timestamp. Re-running with the same code, settings and seed on the same backend reproduces every number bit for bit; this is asserted by a kernel test for the gradient (sampling and exact) and Lie-algebra analyses.

Honest limits

A finite sample is a sample. A bootstrap interval does not cover model error, and variances near 2⁻⁶⁴ cannot be seen by sampling at all. Only the exact engine reaches them.
Bounded intervals can be loose. A bounded result is correct but may be too wide to decide anything. The Lab shows the width, and a verdict built on loose points degrades toward inconclusive.
The engine has a class. Shared parameters, parameter offsets and non-Clifford fixed gates push you back to sampling, capped at 20 qubits.
The prediction has assumptions. The Lie-algebraic formula describes deep circuits. A shallow circuit can sit far from it, which is why the measured scaling outranks the prediction in the verdict.
Dimension matching is not identification. Two different algebras can have the same dimension.
Scaling compares circuits you build. If the family you sweep changes structure with n, the verdict is about that family, not about your single circuit.
Fitting needs range. With fewer than four distinct qubit counts, or a window too narrow to separate an exponential from a high-degree polynomial, the honest answer is inconclusive.
Not a training guarantee. A low risk is not a promise that an optimizer will find a good minimum, and a high risk is not a promise it will not. The Lab measures gradient concentration, not local minima.

Where this connects

The Discovery Engine’s VQE evaluator rejects barren ansatzes at initialization with the same gradient statistics, and its Frontier evaluator scores ansatzes with the exact engine.
Dirac sees the Lab’s current verdicts, lint diagnostics and staleness in Research mode (never in Learn mode).
Protocol details are in the Quantum AI Lab messages.