Add dem_sampling CPU/GPU across C++ and Python

.github/actions/build-lib/action.yaml

@@ -23,6 +23,14 @@ inputs:
     description: 'Install prefix'
     default: '~/.cudaqx'
     required: false
+  require-custabilizer:
+    description: 'Enable cuStabilizer GPU DEM sampling (ON or OFF)'
+    default: 'ON'
+    required: false
+  require-custabilizer-gpu-torch:
+    description: 'Install PyTorch for GPU Torch tensor path (ON or OFF, requires custabilizer ON)'
+    default: 'ON'
+    required: false
 outputs:
   build-dir:
     description: 'Build dir.'
@@ -66,6 +74,8 @@ runs:
       env:
         CCACHE_DIR: /ccache-${{ inputs.lib }}
         GH_TOKEN: ${{ github.token }} # REVERT-WITH-CUDAQ-REALTIME-BUILD
+        REQUIRE_CUSTABILIZER: ${{ inputs.require-custabilizer }}
+        REQUIRE_CUSTABILIZER_GPU_TORCH: ${{ inputs.require-custabilizer-gpu-torch }}
       run: |
         build_dir=build_${{ inputs.lib }}
         .github/actions/build-lib/build_${{ inputs.lib }}.sh $build_dir ${{ inputs.install-prefix }}

.github/actions/build-lib/build_all.sh

@@ -18,13 +18,96 @@ if [ -z "$CUDAQ_REALTIME_ROOT" ]; then
   cd "$_build_cwd"
 fi
 
+REQUIRE_CUSTABILIZER=${REQUIRE_CUSTABILIZER:-ON}
+REQUIRE_CUSTABILIZER_GPU_TORCH=${REQUIRE_CUSTABILIZER_GPU_TORCH:-ON}
+
+if [ "$REQUIRE_CUSTABILIZER" = "OFF" ]; then
+  REQUIRE_CUSTABILIZER_GPU_TORCH="OFF"
+fi
+
+if [ "$REQUIRE_CUSTABILIZER" = "ON" ] && [ -z "$CUSTABILIZER_ROOT" ] && [ -x "$(command -v python3)" ]; then
+  NVCC_BIN=${CUDACXX:-$(command -v nvcc)}
+  CUDA_MAJOR=""
+  if [ -n "$NVCC_BIN" ] && [ -x "$NVCC_BIN" ]; then
+    CUDA_MAJOR=$("$NVCC_BIN" --version | sed -nE 's/.*release ([0-9]+)\..*/\1/p' | head -n 1)
+  fi
+  CUSTAB_PIP="custabilizer-cu${CUDA_MAJOR:-12}"
+  CUQPY_PIP="cuquantum-python-cu${CUDA_MAJOR:-12}"
+  pip install --upgrade "${CUSTAB_PIP}>=0.3.0" "${CUQPY_PIP}>=26.3.0"
+fi
+
+if [ "$REQUIRE_CUSTABILIZER_GPU_TORCH" = "ON" ] && [ -x "$(command -v python3)" ]; then
+  NVCC_BIN=${CUDACXX:-$(command -v nvcc)}
+  if [ -n "$NVCC_BIN" ] && [ -x "$NVCC_BIN" ]; then
+    cuda_version=$("$NVCC_BIN" --version | sed -nE 's/.*release ([0-9]+\.[0-9]+).*/\1/p' | head -n 1)
+    cuda_no_dot=$(echo "$cuda_version" | tr -d '.')
+    pip install torch --index-url "https://download.pytorch.org/whl/cu${cuda_no_dot}" || true
+  fi
+fi
+
+if [ -z "$CUSTABILIZER_ROOT" ] && [ "$REQUIRE_CUSTABILIZER" = "ON" ] && [ -x "$(command -v python3)" ]; then
+  if [ -z "$CUSTABILIZER_PIP_PACKAGE" ]; then
+    CUDA_MAJOR=""
+    NVCC_BIN=${CUDACXX:-$(command -v nvcc)}
+    if [ -n "$NVCC_BIN" ] && [ -x "$NVCC_BIN" ]; then
+      CUDA_MAJOR=$("$NVCC_BIN" --version | sed -nE 's/.*release ([0-9]+)\..*/\1/p' | head -n 1)
+    fi
+    if [ -n "$CUDA_MAJOR" ]; then
+      CUSTABILIZER_PIP_PACKAGE="custabilizer-cu${CUDA_MAJOR}"
+    else
+      for candidate in custabilizer-cu13 custabilizer-cu12; do
+        if python3 -m pip show "$candidate" >/dev/null 2>&1; then
+          CUSTABILIZER_PIP_PACKAGE="$candidate"
+          break
+        fi
+      done
+    fi
+  fi
+
+  if [ -n "$CUSTABILIZER_PIP_PACKAGE" ] && \
+     python3 -m pip show "$CUSTABILIZER_PIP_PACKAGE" >/dev/null 2>&1; then
+    CUSTABILIZER_ROOT=$(python3 - "$CUSTABILIZER_PIP_PACKAGE" <<'PY'
+import pathlib, subprocess, sys
+package = sys.argv[1]
+show = subprocess.check_output([sys.executable, "-m", "pip", "show", package], text=True)
+location = ""
+for line in show.splitlines():
+    if line.startswith("Location:"):
+        location = line.split(":", 1)[1].strip(); break
+if not location:
+    print(""); raise SystemExit(0)
+base = pathlib.Path(location)
+for root in [base / "custabilizer", base / "cuquantum", base]:
+    h = root / "include" / "custabilizer.h"
+    lib = root / "lib" / "libcustabilizer.so.0"
+    lib64 = root / "lib64" / "libcustabilizer.so.0"
+    if h.exists() and (lib.exists() or lib64.exists()):
+        print(root); raise SystemExit(0)
+print("")
+PY
+)
+  fi
+fi
+
+CUSTABILIZER_CMAKE_ARG=""
+if [ -n "$CUSTABILIZER_ROOT" ]; then
+  echo "Resolved cuStabilizer root: $CUSTABILIZER_ROOT"
+  CUSTABILIZER_CMAKE_ARG="-DCUSTABILIZER_ROOT=$CUSTABILIZER_ROOT"
+  export LD_LIBRARY_PATH="$CUSTABILIZER_ROOT/lib:$CUSTABILIZER_ROOT/lib64:${LD_LIBRARY_PATH:-}"
+  export CPATH="$CUSTABILIZER_ROOT/include:${CPATH:-}"
+else
+  echo "Unable to resolve CUSTABILIZER_ROOT from pip wheel."
+fi
+
 cmake -S . -B "$1" \
   -DCMAKE_BUILD_TYPE=Release \
   -DCMAKE_C_COMPILER=gcc-11 \
   -DCMAKE_CXX_COMPILER=g++-11 \
   -DCMAKE_C_COMPILER_LAUNCHER=ccache \
   -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
   -DCUDAQ_DIR=/cudaq-install/lib/cmake/cudaq/ \
+  ${CUSTABILIZER_CMAKE_ARG:+$CUSTABILIZER_CMAKE_ARG} \
+  -DCUDAQ_QEC_REQUIRE_CUSTABILIZER=$REQUIRE_CUSTABILIZER \
   -DCUDAQX_ENABLE_LIBS="all" \
   -DCUDAQX_INCLUDE_TESTS=ON \
   -DCUDAQX_BINDINGS_PYTHON=ON \

.github/actions/build-lib/build_qec.sh

@@ -19,15 +19,117 @@ if [ -z "$CUDAQ_REALTIME_ROOT" ]; then
   cd "$_build_cwd"
 fi
 
+REQUIRE_CUSTABILIZER=${REQUIRE_CUSTABILIZER:-ON}
+REQUIRE_CUSTABILIZER_GPU_TORCH=${REQUIRE_CUSTABILIZER_GPU_TORCH:-ON}
+
+# Enforce: cuStabilizer OFF forces GPU Torch OFF
+if [ "$REQUIRE_CUSTABILIZER" = "OFF" ]; then
+  REQUIRE_CUSTABILIZER_GPU_TORCH="OFF"
+fi
+
+# Install cuStabilizer dependencies if required
+if [ "$REQUIRE_CUSTABILIZER" = "ON" ] && [ -z "$CUSTABILIZER_ROOT" ] && [ -x "$(command -v python3)" ]; then
+  NVCC_BIN=${CUDACXX:-$(command -v nvcc)}
+  CUDA_MAJOR=""
+  if [ -n "$NVCC_BIN" ] && [ -x "$NVCC_BIN" ]; then
+    CUDA_MAJOR=$("$NVCC_BIN" --version | sed -nE 's/.*release ([0-9]+)\..*/\1/p' | head -n 1)
+  fi
+  CUSTAB_PIP="custabilizer-cu${CUDA_MAJOR:-12}"
+  CUQPY_PIP="cuquantum-python-cu${CUDA_MAJOR:-12}"
+  pip install --upgrade "${CUSTAB_PIP}>=0.3.0" "${CUQPY_PIP}>=26.3.0"
+fi
+
+# Install Torch if GPU Torch path is required
+if [ "$REQUIRE_CUSTABILIZER_GPU_TORCH" = "ON" ] && [ -x "$(command -v python3)" ]; then
+  NVCC_BIN=${CUDACXX:-$(command -v nvcc)}
+  if [ -n "$NVCC_BIN" ] && [ -x "$NVCC_BIN" ]; then
+    cuda_version=$("$NVCC_BIN" --version | sed -nE 's/.*release ([0-9]+\.[0-9]+).*/\1/p' | head -n 1)
+    cuda_no_dot=$(echo "$cuda_version" | tr -d '.')
+    pip install torch --index-url "https://download.pytorch.org/whl/cu${cuda_no_dot}" || true
+  fi
+fi
+
+if [ -z "$CUSTABILIZER_ROOT" ] && [ "$REQUIRE_CUSTABILIZER" = "ON" ] && [ -x "$(command -v python3)" ]; then
+  if [ -z "$CUSTABILIZER_PIP_PACKAGE" ]; then
+    CUDA_MAJOR=""
+    NVCC_BIN=${CUDACXX:-$(command -v nvcc)}
+    if [ -n "$NVCC_BIN" ] && [ -x "$NVCC_BIN" ]; then
+      CUDA_MAJOR=$("$NVCC_BIN" --version | sed -nE 's/.*release ([0-9]+)\..*/\1/p' | head -n 1)
+    fi
+
+    if [ -n "$CUDA_MAJOR" ]; then
+      CUSTABILIZER_PIP_PACKAGE="custabilizer-cu${CUDA_MAJOR}"
+    else
+      for candidate in custabilizer-cu13 custabilizer-cu12; do
+        if python3 -m pip show "$candidate" >/dev/null 2>&1; then
+          CUSTABILIZER_PIP_PACKAGE="$candidate"
+          break
+        fi
+      done
+    fi
+  fi
+
+  if [ -n "$CUSTABILIZER_PIP_PACKAGE" ] && \
+     python3 -m pip show "$CUSTABILIZER_PIP_PACKAGE" >/dev/null 2>&1; then
+    CUSTABILIZER_ROOT=$(python3 - "$CUSTABILIZER_PIP_PACKAGE" <<'PY'
+import pathlib
+import subprocess
+import sys
+
+package = sys.argv[1]
+show = subprocess.check_output(
+    [sys.executable, "-m", "pip", "show", package], text=True
+)
+location = ""
+for line in show.splitlines():
+    if line.startswith("Location:"):
+        location = line.split(":", 1)[1].strip()
+        break
+
+if not location:
+    print("")
+    raise SystemExit(0)
+
+base = pathlib.Path(location)
+candidates = [base / "custabilizer", base / "cuquantum", base]
+for root in candidates:
+    include = root / "include" / "custabilizer.h"
+    if not include.exists():
+        continue
+    lib = root / "lib" / "libcustabilizer.so.0"
+    lib64 = root / "lib64" / "libcustabilizer.so.0"
+    if lib.exists() or lib64.exists():
+        print(root)
+        raise SystemExit(0)
+
+print("")
+PY
+)
+  fi
+fi
+
+CUSTABILIZER_CMAKE_ARG=""
+if [ -n "$CUSTABILIZER_ROOT" ]; then
+  echo "Resolved cuStabilizer root: $CUSTABILIZER_ROOT"
+  CUSTABILIZER_CMAKE_ARG="-DCUSTABILIZER_ROOT=$CUSTABILIZER_ROOT"
+  # Ensure the resolved path wins over any stale container paths.
+  export LD_LIBRARY_PATH="$CUSTABILIZER_ROOT/lib:$CUSTABILIZER_ROOT/lib64:${LD_LIBRARY_PATH:-}"
+  export CPATH="$CUSTABILIZER_ROOT/include:${CPATH:-}"
+else
+  echo "Unable to resolve CUSTABILIZER_ROOT from pip wheel."
+fi
+
 cmake -S libs/qec -B "$1" \
   -DCMAKE_BUILD_TYPE=Release \
   -DCMAKE_C_COMPILER=gcc-11 \
   -DCMAKE_CXX_COMPILER=g++-11 \
   -DCMAKE_C_COMPILER_LAUNCHER=ccache \
   -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
   -DCUDAQ_DIR=/cudaq-install/lib/cmake/cudaq/ \
+  ${CUSTABILIZER_CMAKE_ARG:+$CUSTABILIZER_CMAKE_ARG} \
   -DCUDAQX_INCLUDE_TESTS=ON \
   -DCUDAQX_BINDINGS_PYTHON=ON \
+  -DCUDAQ_QEC_REQUIRE_CUSTABILIZER=$REQUIRE_CUSTABILIZER \
   -DCMAKE_INSTALL_PREFIX="$2" \
   -DCUDAQ_REALTIME_ROOT=$CUDAQ_REALTIME_ROOT
 

.github/workflows/all_libs.yaml

@@ -65,6 +65,7 @@ jobs:
       - name: Install build requirements
         run: |
           apt install -y --no-install-recommends gfortran libblas-dev wget
+          pip install --upgrade cuquantum-python-cu${{ steps.config.outputs.cuda_major }}>=26.3.0 custabilizer-cu${{ steps.config.outputs.cuda_major }}>=0.3.0
 
       - name: Install TensorRT (amd64)
         if: matrix.platform == 'amd64'
@@ -108,20 +109,33 @@ jobs:
           LD_LIBRARY_PATH: ${{ env.MPI_PATH }}/lib:${{ env.LD_LIBRARY_PATH }}
         shell: bash
         run: |
-          # 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 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 }}==26.01.0
+          pip install --upgrade 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 }}>=26.3.0 custabilizer-cu${{ steps.config.outputs.cuda_major }}>=0.3.0
+          echo "=== cuStabilizer verification ==="
+          pip show custabilizer-cu${{ steps.config.outputs.cuda_major }} | grep Version
+          find / -name "libcustabilizer.so*" 2>/dev/null || true
           # 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
               # install for x86_64.
               pip install stim beliefmatching
           fi
 
+      - name: Set cuStabilizer runtime paths
+        run: |
+          CUSTAB_ROOT=$(python3 -c "
+          import subprocess, pathlib, sys
+          pkg = 'custabilizer-cu' + '${{ steps.config.outputs.cuda_major }}'
+          show = subprocess.check_output([sys.executable, '-m', 'pip', 'show', pkg], text=True)
+          loc = [l.split(':',1)[1].strip() for l in show.splitlines() if l.startswith('Location:')][0]
+          root = pathlib.Path(loc) / 'cuquantum'
+          print(root if (root / 'lib' / 'libcustabilizer.so.0').exists() else '')
+          ")
+          if [ -n "$CUSTAB_ROOT" ]; then
+            echo "LD_LIBRARY_PATH=$CUSTAB_ROOT/lib:$CUSTAB_ROOT/lib64:${{ env.MPI_PATH }}/lib:${LD_LIBRARY_PATH:-}" >> $GITHUB_ENV
+          fi
+
       - name: Run Python tests
         env:
-          LD_LIBRARY_PATH: ${{ env.MPI_PATH }}/lib:${{ env.LD_LIBRARY_PATH }}
           OMPI_MCA_pml: ob1
         run: cmake --build ${{ steps.build.outputs.build-dir }} --target run_python_tests
 
@@ -131,6 +145,5 @@ jobs:
 
       - name: Run example tests
         env:
-          LD_LIBRARY_PATH: ${{ env.MPI_PATH }}/lib:${{ env.LD_LIBRARY_PATH }}
           OMPI_MCA_pml: ob1
         run: bash scripts/ci/test_examples.sh all

.github/workflows/all_libs_release.yaml

@@ -41,8 +41,12 @@ jobs:
     permissions: write-all
     steps:
       - name: Install dependencies
+        id: deps
         run: |
           apt update && apt install -y --no-install-recommends zip unzip patchelf git-lfs
+          cuda_major=$(echo ${{ matrix.cuda_version }} | cut -d . -f1)
+          echo "cuda_major=$cuda_major" >> $GITHUB_OUTPUT
+          pip install --upgrade cuquantum-python-cu${cuda_major}>=26.3.0 custabilizer-cu${cuda_major}>=0.3.0
 
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -130,24 +134,36 @@ jobs:
           LD_LIBRARY_PATH: ${{ env.MPI_PATH }}/lib:${{ env.LD_LIBRARY_PATH }}
         shell: bash
         run: |
-          # 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 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 }}==26.01.0
+          pip install --upgrade 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 }}>=26.3.0 custabilizer-cu${{ steps.config.outputs.cuda_major }}>=0.3.0
+          echo "=== cuStabilizer verification ==="
+          pip show custabilizer-cu${{ steps.config.outputs.cuda_major }} | grep Version
+          find / -name "libcustabilizer.so*" 2>/dev/null || true
           # 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
               # install for x86_64.
               pip install stim beliefmatching
           fi
 
+      - name: Set cuStabilizer runtime paths
+        run: |
+          CUSTAB_ROOT=$(python3 -c "
+          import subprocess, pathlib, sys
+          pkg = 'custabilizer-cu' + '${{ steps.config.outputs.cuda_major }}'
+          show = subprocess.check_output([sys.executable, '-m', 'pip', 'show', pkg], text=True)
+          loc = [l.split(':',1)[1].strip() for l in show.splitlines() if l.startswith('Location:')][0]
+          root = pathlib.Path(loc) / 'cuquantum'
+          print(root if (root / 'lib' / 'libcustabilizer.so.0').exists() else '')
+          ")
+          if [ -n "$CUSTAB_ROOT" ]; then
+            echo "LD_LIBRARY_PATH=$CUSTAB_ROOT/lib:$CUSTAB_ROOT/lib64:${{ env.MPI_PATH }}/lib:${LD_LIBRARY_PATH:-}" >> $GITHUB_ENV
+          fi
+
       - name: Run Python tests
         env:
-          LD_LIBRARY_PATH: ${{ env.MPI_PATH }}/lib:${{ env.LD_LIBRARY_PATH }}
           OMPI_MCA_pml: ob1
         run: |
           if [[ -n "${{ env.QEC_EXTERNAL_DECODERS }}" ]]; then
-            # Verify that external decoder is available if applicable
             export PYTHONPATH="/usr/local/cudaq:$HOME/.cudaqx"
             python3 -c "import cudaq_qec as qec; print(qec.__version__); d = qec.get_decoder('nv-qldpc-decoder', qec.get_code('steane').get_parity()); print(d.get_version())"
           fi
@@ -160,7 +176,6 @@ jobs:
 
       - name: Run example tests
         env:
-          LD_LIBRARY_PATH: ${{ env.MPI_PATH }}/lib:${{ env.LD_LIBRARY_PATH }}
           OMPI_MCA_pml: ob1
         run: |
           ln -s /usr/local/cudaq /cudaq-install

.github/workflows/docs.yaml

@@ -60,12 +60,24 @@ jobs:
           apt install -y --no-install-recommends \
             gfortran libblas-dev doxygen
 
-          python3 -m pip install IPython breathe enum_tools myst_parser nbsphinx \
+          python3 -m pip install --break-system-packages --upgrade IPython breathe enum_tools myst_parser nbsphinx \
             sphinx_copybutton sphinx_inline_tabs sphinx_gallery sphinx_rtd_theme \
-            sphinx_reredirects sphinx_toolbox cupy-cuda12x cuquantum-python-cu12
+            sphinx_reredirects "sphinx-autodoc-typehints<3.8" sphinx_toolbox cupy-cuda12x cuquantum-python-cu12>=26.3.0 custabilizer-cu12>=0.3.0
+          echo "=== cuStabilizer verification ==="
+          pip show custabilizer-cu12 | grep Version
+          find / -name "libcustabilizer.so*" 2>/dev/null || true
 
       - name: Build docs
         run: |
+          # Resolve cuStabilizer root from the pip wheel.
+          CUSTABILIZER_ROOT=$(python3 -c "
+          import subprocess, pathlib, sys
+          show = subprocess.check_output([sys.executable, '-m', 'pip', 'show', 'custabilizer-cu12'], text=True)
+          loc = [l.split(':',1)[1].strip() for l in show.splitlines() if l.startswith('Location:')][0]
+          root = pathlib.Path(loc) / 'cuquantum'
+          print(root if (root / 'include' / 'custabilizer.h').exists() else '')
+          ")
+
           # Note: TRT decoder is disabled because all docs for the TRT decoder
           # are generated independently of the source code (no Doxygen
           # documentation).
@@ -74,6 +86,7 @@ jobs:
             -DCMAKE_C_COMPILER=gcc-11 \
             -DCMAKE_CXX_COMPILER=g++-11 \
             -DCUDAQ_DIR=/cudaq-install/lib/cmake/cudaq/ \
+            ${CUSTABILIZER_ROOT:+-DCUSTABILIZER_ROOT=$CUSTABILIZER_ROOT} \
             -DCUDAQX_ENABLE_LIBS="all" \
             -DCUDAQX_INCLUDE_DOCS=ON \
             -DCUDAQX_BINDINGS_PYTHON=ON \