Merge down from main

Author: cketcham2333

.github/workflows/all_libs.yaml

@@ -109,7 +109,7 @@ jobs:
           # Install the correct torch first.
           cuda_no_dot=$(echo ${{ matrix.cuda_version }} | sed 's/\.//')
           pip install torch==2.9.0 --index-url https://download.pytorch.org/whl/cu${cuda_no_dot}
-          pip install numpy pytest cupy-cuda${{ steps.config.outputs.cuda_major }}x cuquantum-cu${{ steps.config.outputs.cuda_major }} lightning ml_collections mpi4py transformers quimb opt_einsum nvidia-cublas cuquantum-python-cu${{ steps.config.outputs.cuda_major }}==25.09.1
+          pip install numpy pytest onnxscript cupy-cuda${{ steps.config.outputs.cuda_major }}x cuquantum-cu${{ steps.config.outputs.cuda_major }} lightning ml_collections mpi4py transformers quimb opt_einsum nvidia-cublas cuquantum-python-cu${{ steps.config.outputs.cuda_major }}==25.09.1
           # The following tests are needed for docs/sphinx/examples/qec/python/tensor_network_decoder.py.
           if [ "$(uname -m)" == "x86_64" ]; then
               # Stim is not currently available on manylinux ARM wheels, so only

.github/workflows/all_libs_release.yaml

@@ -133,7 +133,7 @@ jobs:
           # Install the correct torch first.
           cuda_no_dot=$(echo ${{ matrix.cuda_version }} | sed 's/\.//')
           pip install torch==2.9.0 --index-url https://download.pytorch.org/whl/cu${cuda_no_dot}
-          pip install numpy pytest cupy-cuda${{ steps.config.outputs.cuda_major }}x cuquantum-cu${{ steps.config.outputs.cuda_major }} lightning ml_collections mpi4py transformers quimb opt_einsum nvidia-cublas cuquantum-python-cu${{ steps.config.outputs.cuda_major }}==25.09.1
+          pip install numpy pytest onnxscript cupy-cuda${{ steps.config.outputs.cuda_major }}x cuquantum-cu${{ steps.config.outputs.cuda_major }} lightning ml_collections mpi4py transformers quimb opt_einsum nvidia-cublas cuquantum-python-cu${{ steps.config.outputs.cuda_major }}==25.09.1
           # The following tests are needed for docs/sphinx/examples/qec/python/tensor_network_decoder.py.
           if [ "$(uname -m)" == "x86_64" ]; then
               # Stim is not currently available on manylinux ARM wheels, so only

.github/workflows/lib_qec.yaml

@@ -106,7 +106,7 @@ jobs:
           # Install the correct torch first.
           cuda_no_dot=$(echo ${{ matrix.cuda_version }} | sed 's/\.//')
           pip install torch==2.9.0 --index-url https://download.pytorch.org/whl/cu${cuda_no_dot}
-          pip install numpy pytest cupy-cuda${{ steps.config.outputs.cuda_major }}x cuquantum-cu${{ steps.config.outputs.cuda_major }} quimb opt_einsum nvidia-cublas cuquantum-python-cu${{ steps.config.outputs.cuda_major }}==25.09.1
+          pip install numpy pytest onnxscript cupy-cuda${{ steps.config.outputs.cuda_major }}x cuquantum-cu${{ steps.config.outputs.cuda_major }} quimb opt_einsum nvidia-cublas cuquantum-python-cu${{ steps.config.outputs.cuda_major }}==25.09.1
           # The following tests are needed for docs/sphinx/examples/qec/python/tensor_network_decoder.py.
           if [ "$(uname -m)" == "x86_64" ]; then
               # Stim is not currently available on manylinux ARM wheels, so only

.github/workflows/lib_solvers.yaml

@@ -94,7 +94,7 @@ jobs:
           # Install the correct torch first.
           cuda_no_dot=$(echo ${{ matrix.cuda_version }} | sed 's/\.//')
           pip install torch==2.9.0 --index-url https://download.pytorch.org/whl/cu${cuda_no_dot}
-          pip install numpy pytest cupy-cuda${{ steps.config.outputs.cuda_major }}x cuquantum-cu${{ steps.config.outputs.cuda_major }} lightning ml_collections mpi4py transformers pytest
+          pip install numpy pytest onnxscript cupy-cuda${{ steps.config.outputs.cuda_major }}x cuquantum-cu${{ steps.config.outputs.cuda_major }} lightning ml_collections mpi4py transformers pytest
 
 
       - name: Run Python tests

.gitignore

@@ -98,6 +98,9 @@ apps/
 # vim files
 *.tmp
 
+# Wheel files
+*.whl
+
 # Temporary build files for metapackages
 libs/*/python/metapackages/LICENSE
 libs/*/python/metapackages/NOTICE

README.md

@@ -1,29 +1,37 @@
 # Welcome to the CUDA-QX repository
 
-This repository contains a set of libraries that build on 
-NVIDIA CUDA-Q. These libraries enable the rapid development of hybrid quantum-classical 
-application code leveraging state-of-the-art CPUs, GPUs, and QPUs. 
+This repository contains a set of libraries that build on
+NVIDIA CUDA-Q. These libraries enable the rapid development of hybrid quantum-classical
+application code leveraging state-of-the-art CPUs, GPUs, and QPUs.
 
 ## Getting Started
-To learn more about how to work with the CUDA-QX libraries, please take a look at the 
-[CUDA-QX Documentation][cudaqx_docs]. The page contains detailed 
-[installation instructions][official_install] for officially released packages. 
+
+To learn more about how to work with the CUDA-QX libraries, please take a look at the
+[CUDA-QX Documentation][cudaqx_docs]. The page contains detailed
+[installation instructions][official_install] for officially released packages.
 
 [cudaqx_docs]: https://nvidia.github.io/cudaqx
 [official_install]: https://nvidia.github.io/cudaqx/quickstart/installation.html
 
 ## Contributing
 
 There are many ways in which you can get involved with CUDA-QX. If you are
-interested in developing quantum applications with the CUDA-QX libraries, 
-this repository is a great place to get started! For more information about 
-contributing to the CUDA-QX platform, please take a look at 
+interested in developing quantum applications with the CUDA-QX libraries,
+this repository is a great place to get started! For more information about
+contributing to the CUDA-QX platform, please take a look at
 [Contributing.md](./Contributing.md).
 
 ## License
 
 The code in this repository is licensed under [Apache License 2.0](./LICENSE).
 
+When distributed via PyPI, GHCR, or NGC, the binaries generated from this source
+code are also distributed under the Apache License 2.0; however, the
+`libcudaq-qec-nv-qldpc-decoder.so` library is closed source and is subject to
+the [NVIDIA Software License Agreement][github_qec_license]
+
+[github_qec_license]: https://github.com/NVIDIA/cudaqx/blob/main/libs/qec/LICENSE
+
 Contributing a pull request to this repository requires accepting the
 Contributor License Agreement (CLA) declaring that you have the right to, and
 actually do, grant us the rights to use your contribution. A CLA-bot will

docker/release/Dockerfile

@@ -27,6 +27,11 @@ ARG TARGETARCH
 
 USER root
 
+# Update the copyright notification:
+RUN echo -e "This container also includes CUDA-Q QEC and CUDA-Q Solvers.\n"\
+"Use of this container implies consent to the NVIDIA Software License agreement at\n"\
+"https://github.com/NVIDIA/cudaqx/blob/main/libs/qec/LICENSE\n" >> "$CUDA_QUANTUM_PATH/Copyright.txt"
+
 # Determine the appropriate zip file
 COPY installed_files-${TARGETARCH}.zip /tmp/
 

docs/Doxyfile.in

@@ -27,7 +27,8 @@ EXTRACT_STATIC         = YES
 ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
-PREDEFINED             = "__qpu__="
+PREDEFINED             = "__qpu__=" \
+                         "__attribute__(x)="
 
 #---------------------------------------------------------------------------
 # Configuration options related to the HTML output

docs/sphinx/api/qec/cpp_api.rst

@@ -51,16 +51,32 @@ NVIDIA QLDPC Decoder
 
 .. include:: nv_qldpc_decoder_api.rst
 
+Sliding Window Decoder
+----------------------
+
+.. include:: sliding_window_api.rst
+
+Real-Time Decoding
+==================
+
+.. include:: cpp_realtime_decoding_api.rst
+
+.. _parity_check_matrix_utilities:
+
 Parity Check Matrix Utilities
 =============================
 
 .. doxygenfunction:: cudaq::qec::dense_to_sparse(const cudaqx::tensor<uint8_t> &)
 .. doxygenfunction:: cudaq::qec::generate_random_pcm(std::size_t, std::size_t, std::size_t, int, std::mt19937_64 &&);
+.. doxygenfunction:: cudaq::qec::generate_timelike_sparse_detector_matrix(std::uint32_t num_syndromes_per_round, std::uint32_t num_rounds, bool include_first_round = false)
+.. doxygenfunction:: cudaq::qec::generate_timelike_sparse_detector_matrix(std::uint32_t num_syndromes_per_round, std::uint32_t num_rounds, std::vector<std::int64_t> first_round_matrix)
 .. doxygenfunction:: cudaq::qec::get_pcm_for_rounds(const cudaqx::tensor<uint8_t> &, std::uint32_t, std::uint32_t, std::uint32_t, bool, bool);
 .. doxygenfunction:: cudaq::qec::get_sorted_pcm_column_indices(const std::vector<std::vector<std::uint32_t>> &, std::uint32_t);
 .. doxygenfunction:: cudaq::qec::get_sorted_pcm_column_indices(const cudaqx::tensor<uint8_t> &, std::uint32_t);
 .. doxygenfunction:: cudaq::qec::pcm_extend_to_n_rounds(const cudaqx::tensor<uint8_t> &, std::size_t, std::uint32_t);
+.. doxygenfunction:: cudaq::qec::pcm_from_sparse_vec(const std::vector<std::int64_t>& sparse_vec, std::size_t num_rows, std::size_t num_cols)
 .. doxygenfunction:: cudaq::qec::pcm_is_sorted(const cudaqx::tensor<uint8_t> &, std::uint32_t);
+.. doxygenfunction:: cudaq::qec::pcm_to_sparse_vec(const cudaqx::tensor<uint8_t>& pcm)
 .. doxygenfunction:: cudaq::qec::reorder_pcm_columns(const cudaqx::tensor<uint8_t> &, const std::vector<std::uint32_t> &, uint32_t, uint32_t);
 .. doxygenfunction:: cudaq::qec::shuffle_pcm_columns(const cudaqx::tensor<uint8_t> &, std::mt19937_64 &&);
 .. doxygenfunction:: cudaq::qec::simplify_pcm(const cudaqx::tensor<uint8_t> &, const std::vector<double> &, std::uint32_t);

docs/sphinx/api/qec/cpp_realtime_decoding_api.rst

@@ -0,0 +1,53 @@
+.. _cpp_realtime_decoding_api:
+
+
+The Real-Time Decoding API enables low-latency error correction on quantum hardware by allowing CUDA-Q quantum kernels to interact with decoders during circuit execution. This API is designed for use cases where corrections must be calculated and applied within qubit coherence times.
+
+The real-time decoding system supports simulation environments for local testing and hardware integration (e.g., on
+`Quantinuum's Helios QPU
+<https://www.quantinuum.com/products-solutions/quantinuum-systems/helios>`_).
+
+Core Decoding Functions
+------------------------
+
+These functions can be called from within CUDA-Q quantum kernels (``__qpu__`` functions) to interact with real-time decoders.
+
+.. doxygenfunction:: cudaq::qec::decoding::enqueue_syndromes
+.. doxygenfunction:: cudaq::qec::decoding::get_corrections
+.. doxygenfunction:: cudaq::qec::decoding::reset_decoder
+
+
+Configuration API
+-----------------
+
+The configuration API enables setting up decoders before circuit execution. Decoders are configured using YAML files or programmatically constructed configuration objects.
+
+.. doxygenfunction:: cudaq::qec::decoding::config::configure_decoders
+.. doxygenfunction:: cudaq::qec::decoding::config::configure_decoders_from_file
+.. doxygenfunction:: cudaq::qec::decoding::config::configure_decoders_from_str
+.. doxygenfunction:: cudaq::qec::decoding::config::finalize_decoders
+
+Helper Functions
+----------------
+
+Real-time decoding requires converting matrices to sparse format for efficient decoder configuration. The following utility functions are essential:
+
+- :cpp:func:`cudaq::qec::pcm_to_sparse_vec` for converting a dense PCM to a sparse PCM.
+   
+   **Usage in real-time decoding:**
+
+   .. code-block:: cpp
+
+      config.H_sparse = cudaq::qec::pcm_to_sparse_vec(dem.detector_error_matrix);
+      config.O_sparse = cudaq::qec::pcm_to_sparse_vec(dem.observables_flips_matrix);
+- :cpp:func:`cudaq::qec::pcm_from_sparse_vec` for converting a sparse PCM to a dense PCM.
+- :cpp:func:`cudaq::qec::generate_timelike_sparse_detector_matrix` for generating a sparse detector matrix.
+
+   **Usage in real-time decoding:**
+
+   .. code-block:: cpp
+
+      config.D_sparse = cudaq::qec::generate_timelike_sparse_detector_matrix(
+          numSyndromesPerRound, numRounds, false);
+
+See also :ref:`parity_check_matrix_utilities` for additional PCM manipulation functions.