Skip to content

Commit 37bad32

Browse files
cketcham2333cketcham2333
committed
Merge down from main
2 parents d7dab65 + 9c80b97 commit 37bad32

File tree

8 files changed

+273
-14
lines changed

8 files changed

+273
-14
lines changed

‎docs/sphinx/api/qec/nv_qldpc_decoder_api.rst‎

Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -99,16 +99,51 @@
9999
- `clip_value` (float): Value to clip the BP messages to. Should be a
100100
non-negative value (defaults to 0.0, which disables clipping). Introduced in
101101
0.4.0.
102-
- `bp_method` (int): The BP method to use. 0 for sum-product, 1 for min-sum.
103-
Defaults to 0. Introduced in 0.4.0.
102+
- `bp_method` (int): Core BP algorithm to use (defaults to 0). Introduced in 0.4.0,
103+
expanded in 0.5.0:
104+
105+
- 0: sum-product
106+
- 1: min-sum (introduced in 0.4.0)
107+
- 2: min-sum+mem (uniform memory strength, introduced in 0.5.0)
108+
- 3: min-sum+dmem (disordered memory strength, introduced in 0.5.0)
109+
- `composition` (int): Iteration strategy (defaults to 0). Introduced in 0.5.0:
110+
111+
- 0: Standard (single run)
112+
- 1: Sequential relay (multiple gamma legs). Requires: `bp_method=3`, `srelay_config`
104113
- `scale_factor` (float): The scale factor to use for min-sum. Defaults to 1.0.
105114
When set to 0.0, the scale factor is dynamically computed based on the
106115
number of iterations. Introduced in 0.4.0.
116+
- `gamma0` (float): Memory strength parameter. Required for `bp_method=2`, and for
117+
`composition=1` (sequential relay). Introduced in 0.5.0.
118+
- `gamma_dist` (vector<float>): Gamma distribution interval [min, max] for disordered
119+
memory strength. Required for `bp_method=3` if `explicit_gammas` not provided.
120+
Introduced in 0.5.0.
121+
- `explicit_gammas` (vector<vector<float>>): Explicit gamma values for each variable node.
122+
For `bp_method=3` with `composition=0`, provide a 2D vector where each row has
123+
`block_size` columns. For `composition=1` (Sequential relay), provide `num_sets` rows
124+
(one per relay leg). Overrides `gamma_dist` if provided. Introduced in 0.5.0.
125+
- `srelay_config` (heterogeneous_map): Sequential relay configuration (required for
126+
`composition=1`). Contains the following parameters. Introduced in 0.5.0:
127+
128+
- `pre_iter` (int): Number of pre-iterations to run before relay legs
129+
- `num_sets` (int): Number of relay sets (legs) to run
130+
- `stopping_criterion` (string): When to stop relay legs:
131+
132+
- "All": Run all legs
133+
- "FirstConv": Stop relay after first convergence
134+
- "NConv": Stop after N convergences (requires `stop_nconv` parameter)
135+
- `stop_nconv` (int): Number of convergences to wait for before stopping
136+
(required only when `stopping_criterion="NConv"`)
137+
- `bp_seed` (int): Seed for random number generation used in `bp_method=3` (disordered
138+
memory BP). Optional parameter, defaults to 42 if not provided. Introduced in 0.5.0.
107139
- `opt_results` (heterogeneous_map): Optional results to return. This field can be
108140
left empty if no additional results are desired. Choices are:
109-
- `bp_llr_history` (int): Return the last `bp_llr_history` iterations
110-
of the BP LLR history. Minimum value is 0 and maximum value is
111-
max_iterations. The actual number of returned iterations might be fewer
112-
than `bp_llr_history` if BP converges before the requested number of
113-
iterations. Introduced in 0.4.0.
141+
142+
- `bp_llr_history` (int): Return the last `bp_llr_history` iterations
143+
of the BP LLR history. Minimum value is 0 and maximum value is
144+
max_iterations. The actual number of returned iterations might be fewer
145+
than `bp_llr_history` if BP converges before the requested number of
146+
iterations. Introduced in 0.4.0. Note: Not supported for `composition=1`.
147+
- `num_iter` (bool): If true, return the number of BP iterations run.
148+
Introduced in 0.5.0.
114149

‎docs/sphinx/components/qec/introduction.rst‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -640,13 +640,29 @@ The Quantum Low-Density Parity-Check (QLDPC) decoder leverages GPU-accelerated b
640640
Since belief propagation is an iterative method which may not converge, decoding can be improved with a second-stage post-processing step. The `nv-qldpc-decoder`
641641
API provides various post-processing options, which can be selected through its parameters.
642642

643+
**Belief Propagation Methods:**
644+
645+
The decoder supports multiple BP algorithms (configured via ``bp_method``):
646+
647+
* **Sum-Product BP** (``bp_method=0``, default): Classic belief propagation algorithm that computes exact probabilities.
648+
* **Min-Sum BP** (``bp_method=1``): Approximation to sum-product that uses min operations instead of sum. Optionally accepts ``scale_factor``.
649+
* **Memory-based BP** (``bp_method=2``): Min-sum with uniform memory strength across all variable nodes. **Requires:** ``gamma0``.
650+
* **Disordered Memory BP** (``bp_method=3``): Min-sum with per-variable memory strengths. **Requires:** ``gamma_dist`` [min, max] OR ``explicit_gammas`` (2D vector).
651+
652+
**Sequential Relay Decoding:**
653+
654+
Starting with version 0.5.0, the decoder supports Sequential Relay BP (configured via ``composition=1``), which combines disordered memory BP
655+
with multiple "relay legs" - sequential runs with different gamma configurations. **Requires:** ``bp_method=3``, ``gamma0``, ``srelay_config``, and either ``gamma_dist`` OR ``explicit_gammas``.
656+
643657
The QLDPC decoder `nv-qldpc-decoder` requires a CUDA-Q compatible GPU. See the list below for dependencies and compatibility:
644658
https://nvidia.github.io/cuda-quantum/latest/using/install/local_installation.html#dependencies-and-compatibility
645659

646660
The decoder is based on the following references:
647661

648662
* https://arxiv.org/pdf/2005.07016
649-
* https://github.com/quantumgizmos/ldpc
663+
* https://github.com/quantumgizmos/ldpc
664+
* https://arxiv.org/pdf/2506.01779
665+
* https://github.com/trmue/relay
650666

651667

652668
Usage:

‎docs/sphinx/examples/qec/python/nv-qldpc-decoder.py‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,154 @@ def run_decoder(filename, num_shots, run_as_batched):
199199
)
200200

201201

202+
def demonstrate_bp_methods():
203+
"""
204+
Demonstrate different BP methods available in nv-qldpc-decoder.
205+
Shows configurations for: sum-product, min-sum, memory BP,
206+
disordered memory BP, and sequential relay BP.
207+
"""
208+
# Simple 3x7 parity check matrix for demonstration
209+
H_list = [[1, 0, 0, 1, 0, 1, 1], [0, 1, 0, 1, 1, 0, 1],
210+
[0, 0, 1, 0, 1, 1, 1]]
211+
H = np.array(H_list, dtype=np.uint8)
212+
213+
print("=" * 60)
214+
print("Demonstrating BP Methods in nv-qldpc-decoder")
215+
print("=" * 60)
216+
217+
# Method 0: Sum-Product BP (default)
218+
print("\n1. Sum-Product BP (bp_method=0, default):")
219+
try:
220+
decoder_sp = qec.get_decoder("nv-qldpc-decoder",
221+
H,
222+
bp_method=0,
223+
max_iterations=30)
224+
except Exception as e:
225+
print(
226+
'The nv-qldpc-decoder is not available with your current CUDA-Q ' +
227+
'QEC installation.')
228+
exit(0)
229+
print(" Created decoder with sum-product BP")
230+
231+
# Method 1: Min-Sum BP
232+
print("\n2. Min-Sum BP (bp_method=1):")
233+
decoder_ms = qec.get_decoder("nv-qldpc-decoder",
234+
H,
235+
bp_method=1,
236+
max_iterations=30,
237+
scale_factor=1.0)
238+
print(" Created decoder with min-sum BP")
239+
240+
# Method 2: Min-Sum with uniform Memory (Mem-BP)
241+
print("\n3. Mem-BP (bp_method=2, uniform memory strength):")
242+
decoder_mem = qec.get_decoder("nv-qldpc-decoder",
243+
H,
244+
bp_method=2,
245+
max_iterations=30,
246+
gamma0=0.5)
247+
print(" Created decoder with Mem-BP (gamma0=0.5)")
248+
249+
# Method 3: Min-Sum with Disordered Memory (DMem-BP)
250+
print("\n4. DMem-BP (bp_method=3, disordered memory strength):")
251+
# Option A: Using gamma_dist (random gammas in range)
252+
decoder_dmem = qec.get_decoder("nv-qldpc-decoder",
253+
H,
254+
bp_method=3,
255+
max_iterations=30,
256+
gamma_dist=[0.1, 0.5],
257+
bp_seed=42)
258+
print(" Created decoder with DMem-BP (gamma_dist=[0.1, 0.5])")
259+
260+
# Option B: Using explicit_gammas (specify exact gamma for each variable)
261+
block_size = H.shape[1]
262+
explicit_gammas = [[0.1 + 0.05 * i for i in range(block_size)]]
263+
decoder_dmem_explicit = qec.get_decoder("nv-qldpc-decoder",
264+
H,
265+
bp_method=3,
266+
max_iterations=30,
267+
explicit_gammas=explicit_gammas)
268+
print(" Created decoder with DMem-BP (explicit gammas)")
269+
270+
# Method 4: Sequential Relay BP (composition=1)
271+
print("\n5. Sequential Relay BP (composition=1):")
272+
print(" Requires bp_method=3 and srelay_config")
273+
274+
# Configure relay parameters
275+
srelay_config = {
276+
'pre_iter': 5, # Run 5 iterations with gamma0 before relay legs
277+
'num_sets': 3, # Use 3 relay legs
278+
'stopping_criterion': 'FirstConv' # Stop after first convergence
279+
}
280+
281+
# Option A: Using gamma_dist for relay legs
282+
decoder_relay = qec.get_decoder("nv-qldpc-decoder",
283+
H,
284+
bp_method=3,
285+
composition=1,
286+
max_iterations=50,
287+
gamma0=0.3,
288+
gamma_dist=[0.1, 0.5],
289+
srelay_config=srelay_config,
290+
bp_seed=42)
291+
print(" Created decoder with Relay-BP (gamma_dist, FirstConv stopping)")
292+
293+
# Option B: Using explicit gammas for each relay leg
294+
num_relay_legs = 3
295+
explicit_relay_gammas = [
296+
[0.1 + 0.02 * i for i in range(block_size)], # First relay leg
297+
[0.2 + 0.03 * i for i in range(block_size)], # Second relay leg
298+
[0.3 + 0.04 * i for i in range(block_size)] # Third relay leg
299+
]
300+
301+
srelay_config_all = {
302+
'pre_iter': 10,
303+
'num_sets': 3,
304+
'stopping_criterion': 'All' # Run all relay legs
305+
}
306+
307+
decoder_relay_explicit = qec.get_decoder(
308+
"nv-qldpc-decoder",
309+
H,
310+
bp_method=3,
311+
composition=1,
312+
max_iterations=50,
313+
gamma0=0.3,
314+
explicit_gammas=explicit_relay_gammas,
315+
srelay_config=srelay_config_all)
316+
print(" Created decoder with Relay-BP (explicit gammas, All legs)")
317+
318+
# Option C: NConv stopping criterion
319+
srelay_config_nconv = {
320+
'pre_iter': 5,
321+
'num_sets': 10,
322+
'stopping_criterion': 'NConv',
323+
'stop_nconv': 3 # Stop after 3 convergences
324+
}
325+
326+
decoder_relay_nconv = qec.get_decoder("nv-qldpc-decoder",
327+
H,
328+
bp_method=3,
329+
composition=1,
330+
max_iterations=50,
331+
gamma0=0.3,
332+
gamma_dist=[0.1, 0.6],
333+
srelay_config=srelay_config_nconv,
334+
bp_seed=42)
335+
print(" Created decoder with Relay-BP (NConv stopping after 3)")
336+
337+
print("\n" + "=" * 60)
338+
print("All decoder configurations created successfully!")
339+
print("=" * 60)
340+
341+
202342
if __name__ == "__main__":
343+
# Demonstrate different BP methods (introduced in v0.5.0)
344+
print("\n### PART 1: BP Methods Demonstration ###\n")
345+
demonstrate_bp_methods()
346+
347+
# Full decoding with test data
348+
print("\n\n### PART 2: Full Decoding Example with Test Data ###\n")
349+
203350
# See other test data options in https://github.com/NVIDIA/cudaqx/releases/tag/0.2.0
204351
filename = 'osd_1008_8785_0.001.json'
205352
bz2filename = filename + '.bz2'

‎docs/sphinx/examples_rst/qec/decoders.rst‎

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -75,12 +75,33 @@ CUDA-Q QEC library. The library follows the CUDA-Q decoder Python and C++ interf
7575
:cpp:class:`cudaq::qec::decoder` for C++), but as documented in the API sections
7676
(:ref:`nv_qldpc_decoder_api_python` for Python and
7777
:ref:`nv_qldpc_decoder_api_cpp` for C++), there are many configuration options
78-
that can be passed to the constructor. The following example shows how to
79-
exercise the decoder using non-trivial pre-generated test data. The test data
80-
was generated using scripts originating from the GitHub repo for
81-
`BivariateBicycleCodes
82-
<https://github.com/sbravyi/BivariateBicycleCodes>`_ [#f1]_; it includes parity
83-
check matrices (PCMs) and test syndromes to exercise a decoder.
78+
that can be passed to the constructor.
79+
80+
Belief Propagation Methods
81+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
82+
83+
The ``nv-qldpc-decoder`` supports multiple belief propagation (BP) algorithms, each with different trade-offs
84+
between accuracy, convergence, and speed:
85+
86+
* **Sum-Product BP** (``bp_method=0``): The standard BP algorithm. Good baseline performance.
87+
* **Min-Sum BP** (``bp_method=1``): Faster approximation to sum-product. Can be tuned with ``scale_factor``.
88+
* **Memory-based BP** (``bp_method=2``): Adds uniform memory (``gamma0``) to help escape local minima. Useful when standard BP fails to converge.
89+
* **Disordered Memory BP** (``bp_method=3``): Uses per-variable memory strengths for better adaptability to code structure.
90+
* **Sequential Relay BP** (``composition=1``): Advanced method that runs multiple "relay legs" with different gamma configurations. See examples below for configuration.
91+
92+
Usage Example
93+
~~~~~~~~~~~~~
94+
95+
The following example shows how to exercise the decoder using non-trivial pre-generated test data.
96+
The test data was generated using scripts originating from the GitHub repo for
97+
`BivariateBicycleCodes <https://github.com/sbravyi/BivariateBicycleCodes>`_ [#f1]_;
98+
it includes parity check matrices (PCMs) and test syndromes to exercise a decoder.
99+
100+
The example demonstrates:
101+
102+
1. **Basic decoder configuration** with OSD post-processing
103+
2. **All BP methods** including Sequential Relay BP
104+
3. **Batched decoding** for improved performance
84105

85106
.. literalinclude:: ../../examples/qec/python/nv-qldpc-decoder.py
86107
:language: python

‎libs/qec/unittests/realtime/app_examples/CMakeLists.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,15 @@
66
# the terms of the Apache License 2.0 which accompanies this distribution. #
77
# ============================================================================ #
88

9+
#------------------------------------------------------------------------------#
10+
# Maintenance note: to generate QIR files and corresponding config files for
11+
# Quantinuum, you may manually run tests like the following:
12+
# CUDAQ_DUMP_JIT_IR=1 KEEP_LOG_FILES=1 ctest -R quantinuum
13+
# The resulting files will be in:
14+
# build/libs/qec/unittests/realtime/app_examples/config-*.yml
15+
# build/libs/qec/unittests/realtime/app_examples/qir-*.ll
16+
#------------------------------------------------------------------------------#
17+
918
#------------------------------------------------------------------------------#
1019
# Surface code 1, fully local, regular Stim simulator
1120
add_executable(surface_code-1-local)

‎libs/qec/unittests/realtime/app_examples/surface_code-1-test.sh‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ NUM_SHOTS=1000
5252
# Get timestamp suffix in YYYY-MM-DD-HH-MM-SS, with random number appended using /dev/urandom.
5353
timestamp=$(date +%Y-%m-%d-%H-%M-%S)
5454
RNG_SUFFIX=$(od -An -N4 -i /dev/urandom | tr -d ' ')
55+
# Remove any negative sign.
56+
RNG_SUFFIX=$(echo $RNG_SUFFIX | sed 's/-//g')
5557
FULL_SUFFIX=$timestamp-$RNG_SUFFIX
5658

5759
CONFIG_FILE=config-${FULL_SUFFIX}.yml
@@ -76,6 +78,15 @@ export CUDAQ_DUMP_JIT_IR=${CUDAQ_DUMP_JIT_IR:-0}
7678
echo Running $EXE_PATH2 --distance $DISTANCE --num_shots $NUM_SHOTS --load_dem $CONFIG_FILE --num_rounds $NUM_ROUNDS --decoder_window $DECODER_WINDOW --decoder_type $DECODER_TYPE --sw_window_size $SW_WINDOW_SIZE --sw_step_size $SW_STEP_SIZE
7779
$EXE_PATH2 --distance $DISTANCE --num_shots $NUM_SHOTS --load_dem $CONFIG_FILE --num_rounds $NUM_ROUNDS --decoder_window $DECODER_WINDOW --decoder_type $DECODER_TYPE --sw_window_size $SW_WINDOW_SIZE --sw_step_size $SW_STEP_SIZE |& tee load_dem-$FULL_SUFFIX.log
7880

81+
# If CUDAQ_DUMP_JIT_IR is "1", then extract the QIR from the
82+
# load_dem-$FULL_SUFFIX.log file and place it in qir-$FULL_SUFFIX.ll.
83+
if [[ "${CUDAQ_DUMP_JIT_IR}" == "1" ]]; then
84+
# The QIR starts with "ModuleID" and ends with "backwards_branching"
85+
QIR=$(sed -n '/ModuleID/,/backwards_branching/p' load_dem-$FULL_SUFFIX.log)
86+
echo "Writing QIR to qir-$FULL_SUFFIX.ll"
87+
echo "$QIR" > qir-$FULL_SUFFIX.ll
88+
fi
89+
7990

8091
# Look for results like this in the output:
8192
# Number of non-zero values measured : 2

‎libs/qec/unittests/realtime/app_examples/surface_code-2-test.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ NUM_SHOTS=1000
4242
# Get timestamp suffix in YYYY-MM-DD-HH-MM-SS, with random number appended using /dev/urandom.
4343
timestamp=$(date +%Y-%m-%d-%H-%M-%S)
4444
RNG_SUFFIX=$(od -An -N4 -i /dev/urandom | tr -d ' ')
45+
# Remove any negative sign.
46+
RNG_SUFFIX=$(echo $RNG_SUFFIX | sed 's/-//g')
4547
FULL_SUFFIX=$timestamp-$RNG_SUFFIX
4648

4749
CONFIG_FILE=config-${FULL_SUFFIX}.yml
@@ -66,6 +68,14 @@ export CUDAQ_DUMP_JIT_IR=${CUDAQ_DUMP_JIT_IR:-0}
6668
echo Running $EXE_PATH2 --distance $DISTANCE --num_shots $NUM_SHOTS --load_dem $CONFIG_FILE
6769
$EXE_PATH2 --distance $DISTANCE --num_shots $NUM_SHOTS --load_dem $CONFIG_FILE |& tee load_dem-$FULL_SUFFIX.log
6870

71+
# If CUDAQ_DUMP_JIT_IR is "1", then extract the QIR from the
72+
# load_dem-$FULL_SUFFIX.log file and place it in qir-$FULL_SUFFIX.ll.
73+
if [[ "${CUDAQ_DUMP_JIT_IR}" == "1" ]]; then
74+
# The QIR starts with "ModuleID" and ends with "backwards_branching"
75+
QIR=$(sed -n '/ModuleID/,/backwards_branching/p' load_dem-$FULL_SUFFIX.log)
76+
echo "Writing QIR to qir-$FULL_SUFFIX.ll"
77+
echo "$QIR" > qir-$FULL_SUFFIX.ll
78+
fi
6979

7080
# Look for results like this in the output:
7181
# Number of non-zero values measured : 2

‎libs/qec/unittests/realtime/app_examples/surface_code-3-test.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ NUM_SHOTS=1000
4343
# Get timestamp suffix in YYYY-MM-DD-HH-MM-SS, with random number appended using /dev/urandom.
4444
timestamp=$(date +%Y-%m-%d-%H-%M-%S)
4545
RNG_SUFFIX=$(od -An -N4 -i /dev/urandom | tr -d ' ')
46+
# Remove any negative sign.
47+
RNG_SUFFIX=$(echo $RNG_SUFFIX | sed 's/-//g')
4648
FULL_SUFFIX=$timestamp-$RNG_SUFFIX
4749

4850
CONFIG_FILE=config-${FULL_SUFFIX}.yml
@@ -66,6 +68,14 @@ export CUDAQ_DUMP_JIT_IR=${CUDAQ_DUMP_JIT_IR:-0}
6668
echo Running $EXE_PATH2 --distance $DISTANCE --num_shots $NUM_SHOTS --load_dem $CONFIG_FILE
6769
$EXE_PATH2 --distance $DISTANCE --num_shots $NUM_SHOTS --load_dem $CONFIG_FILE --p_spam $ERROR_RATE --state_prep $STATE_PREP |& tee load_dem-$FULL_SUFFIX.log
6870

71+
# If CUDAQ_DUMP_JIT_IR is "1", then extract the QIR from the
72+
# load_dem-$FULL_SUFFIX.log file and place it in qir-$FULL_SUFFIX.ll.
73+
if [[ "${CUDAQ_DUMP_JIT_IR}" == "1" ]]; then
74+
# The QIR starts with "ModuleID" and ends with "backwards_branching"
75+
QIR=$(sed -n '/ModuleID/,/backwards_branching/p' load_dem-$FULL_SUFFIX.log)
76+
echo "Writing QIR to qir-$FULL_SUFFIX.ll"
77+
echo "$QIR" > qir-$FULL_SUFFIX.ll
78+
fi
6979

7080
# ------------------------------------------------------------------------------
7181
# Validation of decoder results using mismatch percentage:

0 commit comments

Comments
 (0)