Add Convergence Diagnostics user guide#34
Open
kochjens wants to merge 27 commits into
Open
Conversation
Accompanies the scqubits PR-1 convergence-detection feature (ConvergenceCheckable mixin + estimate_convergence). The guide walks a user through the verified-refinement workflow for reaching a converged result on the Transmon energy spectrum: - the estimate / read-verdict / increase-cutoff loop - setting an accuracy target (absolute vs observed-gap scope) - choosing a mode (quick / verify / strict) and the cost/confidence tradeoff - reading the ConvergenceReport (status, per-level verdicts, recommendations, clusters, implementation audit) - the evidence ladder (certified > verified_empirical > calibrated > perturbative > diagnostic > unverified) - a complete worked example - current scope (energies, Transmon) and planned extensions (wavefunctions/matrix elements, coherence, more qubits, Circuit) New file: docs/source/guide/convergence/guide-convergence.rst Wired into the COMMON QUBITS, CIRCUITS toctree in index.rst after the coherence-times guide. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…gs label Resolve two Sphinx warnings in the convergence guide: qualify the estimate_convergence cross-reference (ambiguous across the mixin, Transmon, and inherited TunableTransmon) to .Transmon.estimate_convergence, and correct the settings :ref: label from guide_settings to guide-settings. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Describe the wavefunction, matrix-element, and coherence derived channels and the include_derived / derived_quantities usage, add the report.derived field, and state the supported scope (Transmon) factually. Drop development-roadmap framing in favor of end-user product documentation. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The truncation_channel example referenced the old `charge` label; update it to the renamed vocabulary (`charge_tail`, `FD_stencil`). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Document the equation behind every convergence check now implemented: one-step S*d0, two-step geometric tail d0/(1-R), Richardson d0/(1-g1/g0) with the asymptoticity ratio, cluster subspace angle, the charge finite-tail Green-function estimate (with d=1 boundary denominators), the HO finite-window block-resolvent estimate, the FD box/stencil split (edge-band P_edge, expanded-box-at-fixed-h), composite triangle inequality, transition errors, and the observed-gap normalization. Also documents the quick-mode perturbative estimators (replacing the old boundary-amplitude-only description), the 4-rung evidence ladder (certified/calibrated removed), report.summary()/level(), and the estimate_convergence_vs_paramvals sweep helper. All equations were cross-checked against the implementation; the page builds cleanly (0 warnings). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- add real print(report) / print(sweep) output throughout: a converged report, an underconverged report with recommendations, and a parameter sweep whose verdict varies across the range -- not just the generating code - replace pseudo-output code comments in the complete example with the actual printed values - drop the recommendations for-loop; recommendations already appear in print(report), and report.recommendations is noted as the list accessor - rename "movement" -> "refinement difference"; correct the sweep prose to match measured behavior and remove the misleading safety-factor "calibrated" wording Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Document the two-layer composite check: layer-1 subsystem-internal convergence (attached under derived) and layer-2 composite truncated_dim refinement on the composite_coupling channel, with real two-layer print(report) output, the hybridization (eta) screen and its formula, the assume_subsystems_converged flag, and verify-recommended quick mode. Note HilbertSpace support in the intro. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add FullZeroPi to the supported-classes note and a paragraph in the composite section: layer-1 delegation to the interior ZeroPi (attached under derived["interior_zeropi"]) and layer-2 refinement of the coupling cutoffs zeropi_cutoff (composite_coupling) and zeta_cutoff (HO_tail), plus the assume_inner_converged flag. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Completes the hard-coded qubit coverage in the availability note. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add non-HD Circuit to the supported-classes note and a "Custom circuits" section: refinement axes are the per-variable cutoffs (cutoff_n_<i> -> charge_tail; cutoff_ext_<i> -> FD_stencil discretized / HO_tail harmonic), dominant channel drives the recommendation, quick is verify-recommended. Notes that hierarchically diagonalized circuits are not yet supported (raise NotImplementedError). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…e 3b) HD circuits are now supported: replace the "not yet supported" note with the two-layer description (layer-2 truncated_dim refinement on composite_coupling + layer-1 subsystem delegation under derived; assume_subsystems_converged; nested-HD recorded as unchecked) and note the n_levels <= truncated_dim constraint. Drop the "not hierarchically diagonalized" qualifier in the availability note. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add a ParameterSweep paragraph + real-output example to the parameter-sweep section: applies update_hilbertspace at sampled grid points (corners first, then interior; sample=None checks all), runs the composite check at each, returns a ParameterSweepConvergence with per-point name->value coordinates and the worst point. Distinguishes it from the single-object estimate_convergence_vs_paramvals (N-D grids + coupled-parameter callback). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
A convergence test can only ever dismiss convergence; a pass is "we failed to dismiss this", never a guarantee. Replaces the two-axis status+evidence scheme with the single verdict ladder (likely_converged > maybe_converged > marginal > unverified > distrust), renames the modes cheap/moderate/strict with the per-mode verdict ceiling, drops the evidence field/section, and refreshes every embedded report output to the real current format (no evidence column; new verdict words). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Two runnable notebooks for the convergence-diagnostics feature: convergence-basics (single-qubit workflow -- verdict ladder, targets, modes, reading the report) and convergence-advanced (truncation channels, finite-difference qubits, the variational monotonicity check, derived quantities, coupled HilbertSpace, and parameter sweeps). Executed in the scq env. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…city Add a 'Worked examples' toctree linking the two notebooks, and bring the guide up to shipped behavior with the variational-monotonicity dismissal (a new distrust case in the verdict ladder plus a short subsection). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Document the structured per-check record (LevelVerdict.checks): a new subsection explaining the asymptoticity/boundary/monotonicity/perturbative_tail tests and that they are distinct from the estimate-vs-target grading (a level can be distrust with every check passing). Reword the evidence-field sentences to point at checks / estimator_method / warnings. Replace the two earlier example notebooks with a single concise companion, convergence-workflow.ipynb (the runnable core workflow, leaning on the guide); the comprehensive standalone tour lives in scqubits-examples/demo_convergence. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Independent review pass. Fix the object-vs-representation framing (a qubit is modeled by a Hamiltonian represented in a truncated basis, not 'a truncation'); the TypeError is raised by the top-level shim; state the nearest-neighbor (tridiagonal) premise for the charge finite-tail; disclose that fluxonium's dismissal uses a separate top-Fock boundary band; correct 'near-resonant' to 'at or below E_k'; show the safety factor in the geometric-tail formula; describe the buffer as one extra eigenvalue in the same diagonalization; tighten the Davis-Kahan/Kato-Temple statement; reword the motivating question to the falsification framing; note the per-check line is elided from the guide transcripts. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Update the three print(report) transcripts in the guide and re-execute the companion notebook to the new aligned-table format (no eps_gap placeholder; per-check line only under dismissed/borderline levels). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…adder') Rename the verdict section, show the best>worst ordering as a displayed one-line inequality set apart from the text, and reword the remaining 'ladder' mentions. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…(GHz)') Update the guide transcripts and re-execute the companion notebook. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…C_* settings - guide-convergence.rst: new "Quick start" section right after the intro, before "The verdicts" -- features scq.csc(qubit) as the headline, documents the moderate->strict escalation on repeated calls, links to the new CSC_DEFAULT_TARGET_ABS_GHZ / CSC_DEFAULT_NLEVELS_CAP settings via :ref:`settings-params`. - guide-settings.rst: converted the grid table to a list-table (the longer setting names no longer fit a 30-char column, and list-table is easier to extend in future) and added the two new CSC_* rows. - Also removes one stale auto-generated _autosummary file (nested_basis_monotonicity_violation.rst) for a function renamed to galerkin_monotonicity_violation earlier on this branch -- sphinx adds new autosummary files on rename but doesn't clean up the obsolete one, so the build warned on every run. Sphinx build: 0 warnings/errors from our changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…uide) Updates the convergence guide narrative and the companion notebook for the API rename of ``estimate_convergence`` -> ``check_convergence`` (and ``estimate_convergence_vs_paramvals`` -> ``check_convergence_vs_paramvals``). Re-executed the companion notebook to refresh cached outputs. Also removes three stale auto-generated ``_autosummary/`` files (``estimate_convergence``, ``estimate_convergence_vs_paramvals``, ``ParamSweepConvergence``) that sphinx left behind from the previous names; sphinx now emits zero warnings for our changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Two real issues while checking ParameterSweep coverage: 1. The intro note listed supported types but omitted ``ParameterSweep``, and the trailing sentence implied the top-level shim would reject it. Updated to list ``ParameterSweep`` with a cross-ref to the existing "Convergence across a parameter sweep" section (newly anchored at ``_guide_convergence_paramvals``), and reworded the ``TypeError`` sentence to reflect the shim's widened acceptance (the companion scqubits change makes ``scq.check_convergence(sweep)`` work). 2. Line 685 still referenced ``:class:`.ParamSweepConvergence```, the 1-D class that was removed during the P1 unification into ``ParameterSweepConvergence``. Fixed. Also: the "Estimate convergence" subsection header in the companion notebook becomes "Check convergence" (notebook re-executed for fresh cached outputs). Sphinx: 0 warnings/errors from our changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Grammar/spelling/American-English fixes and several substantive corrections across the narrative RST pages and notebook markdown cells (code cells and outputs untouched). Correctness highlights: - depolarization: fix copy-pasted quasiparticle paragraph (define Y_qp, add R_k/Delta/x_qp/K_0); admittance unit Ohm -> Ohm^-1 (siemens); transition frequency convention omega_ij = omega_i - omega_j (matches noise.py); relabel method-name table rows "Noise operator" -> "Method name"; exp() delimiters. - fullzeropi: example sets disorder params nonzero; text corrected accordingly. - convergence guide: sweep transcript now matches ParameterSweepConvergence.summary(). - circuit: external flux in units of Phi_0 (not 2*pi); temperature 0.1 K (was 0.1 mK); supported_noise_channels identifier; cross-ref to extra.ipynb; define_more symbolic_param_dict; bases/hd/visualization typos. - dispersive: drop spurious (s!=s') on the anharmonic-"Kerr" coefficient line. - for_developer: wrap stray autosummary entries in toctree directives. - plot-options: markersize type float; bibliography volume/punctuation fixes; acknowledgments grant number; assorted notebook prose fixes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…306]
Issue #306 (point 3) asked how the U_N in this section are defined; the
"Cluster-safe matching" guide used U_{N_0}, U_{N_1} without saying what
they are. Add the definition: they are the eigenvector blocks spanning a
cluster at two cutoffs (the relevant columns of the diagonalizing
unitary); explain why spans rather than individual eigenvectors are
compared (degenerate eigenvectors rotate arbitrarily); state the
sin(Theta) 0..1 meaning; and note it is dimensionless and independent of
set_units (not one of the GHz error estimates).
docs(convergence): define U_N in the cluster-safe-matching section [#306]
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Companion documentation for the convergence-diagnostics framework
(scqubits/scqubits#295). Adds
guide/convergence/guide-convergence.rstand linksit into the "Common Qubits, Circuits" toctree.
The guide walks through the workflow for reaching a trustworthy result:
quick/verify/strict) and the cost/confidencetrade-off;
ConvergenceReport(per-level verdicts, clusters, recommendations,implementation audit);
convergedrequires at leastverified_empiricalevidence.Test plan
make clean && make htmlbuilds the guide with no new warnings🤖 Generated with Claude Code