Skip to content

Document noise learning with CUDA-Q QEC for pre-decoder training - #103

Merged
ivanbasov merged 3 commits into
mainfrom
noise-learning-docs
Nov 19, 2026
Merged

ivanbasov merged 3 commits into
mainfrom
noise-learning-docs

Conversation

@ivanbasov

@ivanbasov ivanbasov commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

What

Documentation only.

  • New NOISE_LEARNING.md: how to estimate the 25-parameter circuit-level noise model from detector data with CUDA-Q QEC noise learning (cudaq_qec.plugins.nv_qldpc.learn_noise, mode="parametric", released in cudaq-qec 0.9.0) and write the result as a data.noise_model block for pre-decoder training.
  • One line in the "Noise model" section of README.md that links to it.

Why

data.noise_model is the input of training-data generation. When the device rates are unknown, they can be learned from recorded detector data without logical labels. The feature lives in CUDA-Q QEC; this page shows how to use it with the circuits and the config of this repository, and links to the CUDA-Q QEC documentation for the method itself.

For reviewers

  • Parameter naming. The surface-code circuits of this repository name a preparation/measurement parameter by the basis that fails (X_ERROR(p_prep_Z) after a Z-basis reset). The p25 helpers in cudaq-qec 0.9.0 name it by the applied Pauli and accept X_ERROR only for p_prep_X / p_meas_X. Without a conversion, p25.design_map rejects a tag circuit built by MemoryCircuit:
    ValueError: X_ERROR component X tagged as p_prep_Z: inconsistent with the circuit builder's conventions.
    The example exchanges the four keys when it builds the tag circuit and again on export, and the Notes section explains this. If the convention is aligned later on either side, the swap step can be removed. The color-code circuits follow the same naming since Read prep/meas noise keys by failing basis in the color-code circuits #104; the guide does not cover them.
  • Identifiability. One memory basis gives rank 23 of 25: in a Z-basis experiment p_prep_Z and p_meas_Z are fixed only together with p_cnot_XI and p_cnot_XX, and p_prep_X and p_meas_X only as a sum; the X basis mirrors this with p_cnot_IZ and p_cnot_ZZ. The two bases together give rank 25.
  • One noise model for both bases. Public training always generates data in both bases from one data.noise_model (config_validator.py sets meas_basis = "both" and rejects an override), so one block per basis cannot be used. The example fits the one set of 25 parameters that reproduces the mechanism rates learned in both bases (bounded least squares on the relative error, about ten lines with SciPy, which the inference requirements already include).

Changes after review

The first version combined the two single-basis results parameter by parameter (preparation and measurement from the run in their own basis, CNOT from the run that identifies them). That mixes values that are consistent only as a set, and the reported accuracy held only because the example's true p_cnot_XI and p_cnot_XX are nearly equal. With p_cnot_XI = 1.5e-3 and p_cnot_XX = 1e-4 that merge gave p_prep_Z at 0.80x and p_meas_Z at 1.42x of the truth, and mechanism rates off by up to about 20% in the Z basis. It is replaced by the joint fit above. Also changed: a sentence that the device must run the MemoryCircuit schedule, the parameter-name note scoped to the surface-code circuits, what a single-basis result can be used for, and the description of the learn_physical_params command-line tool. After #104 merged (0801290): the guide no longer says that the color-code circuits read the four keys the other way, and the parameter-name note is no longer scoped to the surface-code circuits.

Verification

The Python block was extracted verbatim from NOISE_LEARNING.md and run from the repository root on this branch:

  • cudaq-qec-cu12 0.9.0 from PyPI, stim 1.16.0, Python 3.11, one RTX PRO 6000.
  • Distance 7, 7 rounds, 262,144 simulated shots per basis, 16 passes: 56 s wall time in total.
  • Learned vs. true parameters: preparation and measurement within 2%, idle within 3%; 14 of 15 CNOT parameters within 20% (range 0.74x to 1.17x).
  • Mechanism rates of the learned model vs. the true model: median difference 0.4%, largest 1.2%, in each basis.
  • Same block with the true p_cnot_XI = p_cnot_ZZ = 1.5e-3 and p_cnot_XX = p_cnot_IZ = 1e-4: preparation and measurement within 3%, the two large CNOT parameters within 3%, the two small ones at 1.22x and 1.32x; 13 of 15 CNOT parameters within 20%; mechanism rates within 2.2% in each basis.
  • The written YAML loads through noise_model_from_config on top of conf/config_public.yaml.
  • learn_physical_params was run on these circuits: a tag circuit from unswapped tags is rejected with the error above; with swapped tags the --yaml output has the four prep/meas keys exchanged.

Not covered: a training run on the learned noise model, and detector data from a device (the example simulates the data).

No code, test or dependency changes.

🤖 Generated with Claude Code

Add NOISE_LEARNING.md: how to estimate the 25-parameter noise model from
detector data with cudaq-qec 0.9.0 (nv_qldpc.learn_noise, parametric mode)
and write it as a data.noise_model block for training. Link it from the
"Noise model" section of the README.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: Ivan Basov <ibasov@nvidia.com>
@ivanbasov
ivanbasov requested a review from bmhowe23 November 18, 2026 19:28

@bmhowe23 bmhowe23 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is a useful page. I ran the Python block verbatim against cudaq-qec-cu12==0.9.0 and it reproduces the numbers in the description (rank 23 of 25 per basis; prep/meas/idle within 3%; 14 of 15 CNOT parameters within 20%).

One issue with how the two bases are merged (first inline comment), plus a few smaller doc points. The comment on the "Parameter names" note points at a naming inconsistency in this repo that predates the PR.

Limits of my own checks:

  • The unidentified directions mentioned in the comments on the merge loop and the "Use both bases" note were checked at d=3 and d=5 for the XV orientation only.
  • I did not check whether training mixes bases under one data.noise_model. If it does, the "one block per basis" advice needs rethinking.
  • For the surface-code / color-code naming comment I read the two circuit builders only. I did not check which convention precompute_dem or the training-data generator follow, and I did not run the color-code path.

Comment thread NOISE_LEARNING.md Resolved
Comment thread NOISE_LEARNING.md Resolved
Comment thread NOISE_LEARNING.md Resolved
Comment thread NOISE_LEARNING.md Resolved
Comment thread NOISE_LEARNING.md Resolved
Address review comments on the noise learning guide.

The example combined the two single-basis results parameter by
parameter. One memory basis fixes the preparation and measurement
parameters only together with two CNOT parameters, so values taken from
different runs do not form a consistent set. The example now fits the
one set of 25 parameters that reproduces the mechanism rates learned in
both bases; the two experiments together fix all 25.

Also state that the device must run the MemoryCircuit schedule, scope
the parameter-name note and the swap step to the surface-code circuits,
say what a single-basis result can be used for, and correct the
description of the learn_physical_params command-line tool.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: Ivan Basov <ibasov@nvidia.com>
@ivanbasov

Copy link
Copy Markdown
Member Author

@bmhowe23 thanks for the review. All five comments are addressed in 21baead, with a reply in each thread; the PR description has the updated verification numbers. Could you take another look?

The main change is the example: the per-parameter merge of the two bases is replaced by one fit of the 25 parameters to the results of both bases. The answer to the open question in the review is that public training always uses both bases under one data.noise_model, which is why the guide keeps a single block instead of one per basis.

The change is documentation only. Unit tests and the style checks pass on 21baead; the GPU jobs are still running.

@ivanbasov
ivanbasov requested a review from bmhowe23 November 19, 2026 01:11

@bmhowe23 bmhowe23 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @ivanbasov!

With #104 merged, the color-code circuits read the prep/meas keys by the
failing basis, as the surface-code circuits do. Drop the sentence that
said they read them the other way and the surface-code scoping of the
parameter-name note. The example itself still covers the surface code only.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: Ivan Basov <ibasov@nvidia.com>
@ivanbasov
ivanbasov merged commit 0b2f5f8 into main Nov 19, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants