pyqcu 0.1.0__tar.gz

pyqcu-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+Copyright (c) 2024 ZhangXin8069
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyqcu-0.1.0/MANIFEST.in

@@ -0,0 +1,47 @@
+# PyQCU source distribution contents.
+#
+# The sdist must be installable on a machine without a pre-built native
+# library, so the KUPL/CUDA sources and the build scripts are shipped. The
+# installer builds KUPL unconditionally (when a toolchain exists) and CUDA/DCU
+# opportunistically; test trees and build products never enter the sdist.
+
+include LICENSE
+include README.md
+include pyproject.toml
+include setup.py
+include MANIFEST.in
+
+include env.sh
+include build-nv.sh
+include build-dcu.sh
+include install.sh
+
+recursive-include pyqcu *.py *.pyi *.pyx *.pxd
+
+recursive-include cpp/kupl/qcu *.txt *.sh *.map *.md *.h *.hpp *.cpp
+prune cpp/kupl/qcu/tests
+prune cpp/kupl/qcu/build
+prune cpp/kupl/qcu/build-lto
+include cpp/cuda/qcu/LICENSE
+include cpp/cuda/qcu/CMakeLists-nv.txt
+include cpp/cuda/qcu/CMakeLists-dcu.txt
+include cpp/cuda/qcu/make-nv.sh
+include cpp/cuda/qcu/make-dcu.sh
+include cpp/cuda/qcu/env.sh
+recursive-include cpp/cuda/qcu/python *.h
+recursive-include cpp/cuda/qcu/include *.h *.hpp
+recursive-include cpp/cuda/qcu/src *.cu *.cpp *.h *.hpp
+
+prune pyqcu/testing
+prune build
+prune dist
+prune data
+prune docs
+prune logs
+prune refer
+prune skills
+
+global-exclude *.so *.so.* *.o *.pyc *.pyo *.pyd
+global-exclude __pycache__ *.egg-info
+global-exclude CMakeCache.txt cmake_install.cmake CTestTestfile.cmake Makefile
+global-exclude AGENTS.md

pyqcu-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: pyqcu
+Version: 0.1.0
+Summary: CUDA/DCU/KUPL-accelerated lattice-QCD Dirac operators and multigrid solvers.
+Author-email: ZhangXin8069 <zhangxin8069@qq.com>
+License-Expression: MIT
+Project-URL: Documentation, https://pyqcu.readthedocs.io/
+Project-URL: Homepage, https://gitlab.itp.ac.cn/ZhangXin8069/PyQCU
+Project-URL: Issues, https://gitlab.itp.ac.cn/ZhangXin8069/PyQCU/-/issues
+Keywords: lattice-qcd,dirac-operator,multigrid,bistabcg,cuda,dcu,kupl,mpi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: torch>=2.0
+Requires-Dist: mpi4py>=3.1
+Requires-Dist: h5py>=3.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == "plot"
+Provides-Extra: monitor
+Requires-Dist: psutil>=5.9; extra == "monitor"
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.6; extra == "all"
+Requires-Dist: psutil>=5.9; extra == "all"
+Dynamic: license-file
+
+# PyQCU
+
+PyQCU is a lattice-QCD operator and solver toolkit with three execution
+paths:
+
+* a Torch/CANN backend for CPU, CUDA, and Ascend NPU;
+* an independent C++17 MPI+OpenMP CPU backend (KUPL);
+* a CUDA/DCU C++ backend exposed through a Cython bridge.
+
+It provides Wilson and Clover Dirac operators, stout and Wuppertal smearing,
+BiCGStab/CG/FGMRES solvers, Legacy and Strict multigrid hierarchies, HDF5
+helpers, and a four-dimensional MPI rank grid.
+
+## Install
+
+```bash
+pip install pyqcu
+```
+
+Requirements: Python 3.10+, Linux, `numpy`, `torch`, `mpi4py`, and `h5py`
+(installed automatically). A C++17 compiler, CMake, and MPI are needed to
+build the KUPL CPU library; `nvcc` is needed for the optional CUDA library.
+
+The package is distributed as a source archive. The first install builds KUPL
+when the toolchain is available and tries CUDA/DCU opportunistically; a
+missing toolchain leaves the pure-Torch paths usable and does not fail the
+install.
+
+```bash
+# CPU-only
+PYQCU_BUILD_BACKEND=kupl pip install pyqcu
+
+# Require the KUPL build
+PYQCU_BUILD_BACKEND=kupl PYQCU_REQUIRE_NATIVE=1 pip install pyqcu
+
+# Build KUPL and CUDA on a machine with nvcc
+PYQCU_BUILD_BACKEND=cuda pip install pyqcu
+```
+
+Verify the installation:
+
+```bash
+python -m pyqcu
+python -m pyqcu --json
+```
+
+## Quick start
+
+```python
+import torch
+from pyqcu import lattice
+from pyqcu.torch import dslash
+
+shape = (8, 8, 8, 8)
+U = torch.zeros((3, 3, 4, *shape), dtype=torch.complex64)
+lattice.generate_gauge_field(U, seed=7, sigma=0.1)
+assert lattice.check_su3(U, tol=1e-3)
+
+src = torch.randn((4, 3, *shape), dtype=torch.complex64)
+kappa = torch.tensor([0.125])
+out = dslash.give_wilson(src=src, U=U, kappa=kappa)
+assert out.shape == src.shape
+assert torch.isfinite(out).all()
+```
+
+The public layers are `pyqcu.api` (backend-neutral contracts), `pyqcu.lattice`
+(gamma/SU(3) and gauge/source generation), `pyqcu.torch` (Torch operators and
+solvers), `pyqcu.kupl` (CPU ctypes binding), `pyqcu.cuda` (CUDA/DCU Cython
+bridge), `pyqcu.solver` (unified Krylov/Multigrid selectors), and `pyqcu.tools`
+(MPI/layout, HDF5, environment, and plotting helpers).
+
+## Native backends
+
+`python -m pyqcu` reports the package location and whether the KUPL and CUDA
+libraries are available. The KUPL binding searches `PYQCU_KUPL_LIB`, then the
+installed `pyqcu/kupl/libqcu.so`, then the source checkout. The CUDA bridge is
+built only when `nvcc` and the CUDA library are available; the extension uses
+an `$ORIGIN` rpath so it finds the library inside the installed package.
+
+Typical release verification uses a `8x8x16x16` complex64 lattice with a
+Gaussian SU(3) gauge field (`sigma=0.1`, `seed=42`), `mass=0.17`, `csw=1.0`,
+and `atol=1e-6`. On the release machine (WSL2, Intel i7-13620H, RTX 4060
+Laptop sm_89), both the installed KUPL and CUDA paths converged in 26
+iterations with full-lattice true residuals below `3e-7`; the acceptance
+threshold for complex64 is `max(atol, 2048*eps32) ≈ 2.4414e-4`.
+
+## Historical performance
+
+The table records measurements on hardware that is not part of this checkout.
+Absolute seconds are not comparable across machines, and CPU/GPU rows are
+never combined into one speed-up. Raw JSON files for these runs are not
+retained in the current tree; the linked report and git tag are the
+provenance.
+
+| Case | Platform | Lattice / precision | Result | Comparison | Reproducibility |
+|---|---|---|---|---|---|
+| CUDA BiCGStab vs QUDA | Tesla V100-SXM2-32GB, sm_70 | 24³×64, c64 | 0.147801 s / 18 iterations | QUDA 0.156680 s / 19 iterations → 1.060× | Historical; needs V100 and the `dev103`-era checkout |
+| KUPL parity-Schur BiCGStab | Intel Xeon E5-2696 v3, 18 cores | 24³×64, c64 | 8 ranks×2 threads: 7.532 s / 19 iterations | 1 rank×4 threads 19.229 s → 2.553× | Historical; same CPU class required |
+| CUDA Legacy-MG vs QUDA GCR-MG | A100-PCIE-40GB | 32³×64, c64 | 1/2/4 ranks: 0.2145 / 0.2195 / 0.2183 s | QUDA 0.4824 / 0.3144 / 0.2875 s → 2.2495× / 1.4323× / 1.3166× | Historical; needs A100, L32 LIME, E12 cache |
+| CUDA native BiCGStab | A100-PCIE-40GB | 32³×64, c64 | 1 rank 0.1224 s; 2 ranks 0.1154 s | QUDA 0.1304 / 0.0961 s → 1.065× / **0.833×** | Historical; shows the native solver is not universally faster |
+| CUDA Strict-MG vs QUDA aligned MG | Tesla V100-SXM2-32GB | 8×8×8×16, c64 | 0.021693 s / 10 iterations | QUDA 0.144755 s / 8 outer GCR → 6.673× | Time-point evidence; small-lattice fixed overhead dominates |
+| CUDA(HIP) Legacy-MG | DCU Pre-Wukong D160A1, gfx906 | 24³×64, c64 | 1/2/4 ranks: 0.3017 / 0.4619 / 1.0247 s | QUDA blocked; no ratio | Historical; needs the same DCU and DTK |
+
+The full table, including the historical tag-only rows and the local
+`8x8x16x16` measurement, is in the performance documentation.
+
+## Documentation
+
+* English: https://pyqcu.readthedocs.io/en/latest/
+* 中文: https://pyqcu.readthedocs.io/zh-cn/latest/
+
+The documentation sources live in `docs/en/` and `docs/zh/`. Both sites are
+built with Sphinx and MyST; the release check builds them with `-W`.
+
+## From a source checkout
+
+```bash
+git clone git@gitlab.itp.ac.cn:zhangxin8069/PyQCU.git
+cd PyQCU
+source ./env.sh
+
+bash ./install.sh kupl    # CPU KUPL backend
+bash ./install.sh cuda    # CUDA backend + Cython bridge
+QCU_DCU_CUDA_COMPILER=/path/to/dtk/nvcc bash ./install.sh dcu
+```
+
+Tests and benchmark drivers live under `pyqcu/testing/` and are intentionally
+excluded from the PyPI package:
+
+```bash
+cd pyqcu/testing
+pytest .
+```
+
+## License
+
+MIT. See `LICENSE`.

pyqcu-0.1.0/README.md

@@ -0,0 +1,137 @@
+# PyQCU
+
+PyQCU is a lattice-QCD operator and solver toolkit with three execution
+paths:
+
+* a Torch/CANN backend for CPU, CUDA, and Ascend NPU;
+* an independent C++17 MPI+OpenMP CPU backend (KUPL);
+* a CUDA/DCU C++ backend exposed through a Cython bridge.
+
+It provides Wilson and Clover Dirac operators, stout and Wuppertal smearing,
+BiCGStab/CG/FGMRES solvers, Legacy and Strict multigrid hierarchies, HDF5
+helpers, and a four-dimensional MPI rank grid.
+
+## Install
+
+```bash
+pip install pyqcu
+```
+
+Requirements: Python 3.10+, Linux, `numpy`, `torch`, `mpi4py`, and `h5py`
+(installed automatically). A C++17 compiler, CMake, and MPI are needed to
+build the KUPL CPU library; `nvcc` is needed for the optional CUDA library.
+
+The package is distributed as a source archive. The first install builds KUPL
+when the toolchain is available and tries CUDA/DCU opportunistically; a
+missing toolchain leaves the pure-Torch paths usable and does not fail the
+install.
+
+```bash
+# CPU-only
+PYQCU_BUILD_BACKEND=kupl pip install pyqcu
+
+# Require the KUPL build
+PYQCU_BUILD_BACKEND=kupl PYQCU_REQUIRE_NATIVE=1 pip install pyqcu
+
+# Build KUPL and CUDA on a machine with nvcc
+PYQCU_BUILD_BACKEND=cuda pip install pyqcu
+```
+
+Verify the installation:
+
+```bash
+python -m pyqcu
+python -m pyqcu --json
+```
+
+## Quick start
+
+```python
+import torch
+from pyqcu import lattice
+from pyqcu.torch import dslash
+
+shape = (8, 8, 8, 8)
+U = torch.zeros((3, 3, 4, *shape), dtype=torch.complex64)
+lattice.generate_gauge_field(U, seed=7, sigma=0.1)
+assert lattice.check_su3(U, tol=1e-3)
+
+src = torch.randn((4, 3, *shape), dtype=torch.complex64)
+kappa = torch.tensor([0.125])
+out = dslash.give_wilson(src=src, U=U, kappa=kappa)
+assert out.shape == src.shape
+assert torch.isfinite(out).all()
+```
+
+The public layers are `pyqcu.api` (backend-neutral contracts), `pyqcu.lattice`
+(gamma/SU(3) and gauge/source generation), `pyqcu.torch` (Torch operators and
+solvers), `pyqcu.kupl` (CPU ctypes binding), `pyqcu.cuda` (CUDA/DCU Cython
+bridge), `pyqcu.solver` (unified Krylov/Multigrid selectors), and `pyqcu.tools`
+(MPI/layout, HDF5, environment, and plotting helpers).
+
+## Native backends
+
+`python -m pyqcu` reports the package location and whether the KUPL and CUDA
+libraries are available. The KUPL binding searches `PYQCU_KUPL_LIB`, then the
+installed `pyqcu/kupl/libqcu.so`, then the source checkout. The CUDA bridge is
+built only when `nvcc` and the CUDA library are available; the extension uses
+an `$ORIGIN` rpath so it finds the library inside the installed package.
+
+Typical release verification uses a `8x8x16x16` complex64 lattice with a
+Gaussian SU(3) gauge field (`sigma=0.1`, `seed=42`), `mass=0.17`, `csw=1.0`,
+and `atol=1e-6`. On the release machine (WSL2, Intel i7-13620H, RTX 4060
+Laptop sm_89), both the installed KUPL and CUDA paths converged in 26
+iterations with full-lattice true residuals below `3e-7`; the acceptance
+threshold for complex64 is `max(atol, 2048*eps32) ≈ 2.4414e-4`.
+
+## Historical performance
+
+The table records measurements on hardware that is not part of this checkout.
+Absolute seconds are not comparable across machines, and CPU/GPU rows are
+never combined into one speed-up. Raw JSON files for these runs are not
+retained in the current tree; the linked report and git tag are the
+provenance.
+
+| Case | Platform | Lattice / precision | Result | Comparison | Reproducibility |
+|---|---|---|---|---|---|
+| CUDA BiCGStab vs QUDA | Tesla V100-SXM2-32GB, sm_70 | 24³×64, c64 | 0.147801 s / 18 iterations | QUDA 0.156680 s / 19 iterations → 1.060× | Historical; needs V100 and the `dev103`-era checkout |
+| KUPL parity-Schur BiCGStab | Intel Xeon E5-2696 v3, 18 cores | 24³×64, c64 | 8 ranks×2 threads: 7.532 s / 19 iterations | 1 rank×4 threads 19.229 s → 2.553× | Historical; same CPU class required |
+| CUDA Legacy-MG vs QUDA GCR-MG | A100-PCIE-40GB | 32³×64, c64 | 1/2/4 ranks: 0.2145 / 0.2195 / 0.2183 s | QUDA 0.4824 / 0.3144 / 0.2875 s → 2.2495× / 1.4323× / 1.3166× | Historical; needs A100, L32 LIME, E12 cache |
+| CUDA native BiCGStab | A100-PCIE-40GB | 32³×64, c64 | 1 rank 0.1224 s; 2 ranks 0.1154 s | QUDA 0.1304 / 0.0961 s → 1.065× / **0.833×** | Historical; shows the native solver is not universally faster |
+| CUDA Strict-MG vs QUDA aligned MG | Tesla V100-SXM2-32GB | 8×8×8×16, c64 | 0.021693 s / 10 iterations | QUDA 0.144755 s / 8 outer GCR → 6.673× | Time-point evidence; small-lattice fixed overhead dominates |
+| CUDA(HIP) Legacy-MG | DCU Pre-Wukong D160A1, gfx906 | 24³×64, c64 | 1/2/4 ranks: 0.3017 / 0.4619 / 1.0247 s | QUDA blocked; no ratio | Historical; needs the same DCU and DTK |
+
+The full table, including the historical tag-only rows and the local
+`8x8x16x16` measurement, is in the performance documentation.
+
+## Documentation
+
+* English: https://pyqcu.readthedocs.io/en/latest/
+* 中文: https://pyqcu.readthedocs.io/zh-cn/latest/
+
+The documentation sources live in `docs/en/` and `docs/zh/`. Both sites are
+built with Sphinx and MyST; the release check builds them with `-W`.
+
+## From a source checkout
+
+```bash
+git clone git@gitlab.itp.ac.cn:zhangxin8069/PyQCU.git
+cd PyQCU
+source ./env.sh
+
+bash ./install.sh kupl    # CPU KUPL backend
+bash ./install.sh cuda    # CUDA backend + Cython bridge
+QCU_DCU_CUDA_COMPILER=/path/to/dtk/nvcc bash ./install.sh dcu
+```
+
+Tests and benchmark drivers live under `pyqcu/testing/` and are intentionally
+excluded from the PyPI package:
+
+```bash
+cd pyqcu/testing
+pytest .
+```
+
+## License
+
+MIT. See `LICENSE`.

pyqcu-0.1.0/build-dcu.sh

@@ -0,0 +1,8 @@
+# BUGFIX 2026-07-28 R3: add set -e so build failures stop the pipeline.
+set -e
+echo "=== PyQCU build.sh ==="
+source ./env.sh
+pushd ./cpp/cuda/qcu
+bash ./make-dcu.sh
+popd
+echo "=== PyQCU build.sh: SUCCESS ==="

pyqcu-0.1.0/build-nv.sh

@@ -0,0 +1,8 @@
+# BUGFIX 2026-07-28 R3: add set -e so build failures stop the pipeline.
+set -e
+echo "=== PyQCU build.sh ==="
+source ./env.sh
+pushd ./cpp/cuda/qcu
+bash ./make-nv.sh
+popd
+echo "=== PyQCU build.sh: SUCCESS ==="

pyqcu-0.1.0/cpp/cuda/qcu/CMakeLists-dcu.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.8)
+if(POLICY CMP0104)
+  # DTK's nvcc-compatible wrapper owns target selection; an empty CMake CUDA
+  # architecture list is valid for this compatibility build.
+  cmake_policy(SET CMP0104 OLD)
+endif()
+project(qcu LANGUAGES C CXX CUDA)
+# DTK 23.10's nvcc-compatible wrapper rejects CMake's --options-file syntax.
+set(CMAKE_CUDA_USE_RESPONSE_FILE_FOR_INCLUDES 0)
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CUDA_STANDARD 11)
+message(STATUS "PATH is: $ENV{PATH}")
+message(STATUS "LD_LIBRARY_PATH is: $ENV{LD_LIBRARY_PATH}")
+find_package(MPI REQUIRED COMPONENTS C CXX)
+include(GNUInstallDirs)
+include_directories(./include)
+aux_source_directory(./src SOURCE_FILE)
+add_library(qcu SHARED ${SOURCE_FILE})
+find_package(CUDA REQUIRED)
+target_include_directories(qcu PRIVATE ${MPI_C_INCLUDE_DIRS})
+target_link_libraries(qcu ${MPI_C_LIBRARIES})
+target_link_libraries(qcu ${CUDA_LIBRARIES})
+target_link_libraries(qcu curand)
+target_link_libraries(qcu cublas)

pyqcu-0.1.0/cpp/cuda/qcu/CMakeLists-nv.txt

@@ -0,0 +1,104 @@
+cmake_minimum_required(VERSION 3.8)
+project(qcu LANGUAGES C CXX CUDA)
+set(CMAKE_CXX_STANDARD 11)
+option(QCU_ENABLE_NVSHMEM "Enable the optional NVSHMEM coarse-grid transport" OFF)
+message(STATUS "PATH is: $ENV{PATH}")
+message(STATUS "LD_LIBRARY_PATH is: $ENV{LD_LIBRARY_PATH}")
+# Architecture precedence: explicit CMake/environment override, env.sh's
+# detected sm_arch, then the compute capability of the active GPU.  Auto
+# detected values are emitted as cubin + PTX so they remain portable across a
+# minor driver/toolkit mismatch; an explicit override is passed through
+# unchanged.
+set(_QCU_AUTO_CUDA_ARCHITECTURES "")
+if(DEFINED QCU_CUDA_ARCHITECTURES AND NOT "${QCU_CUDA_ARCHITECTURES}" STREQUAL "")
+  set(_QCU_CUDA_ARCHITECTURES "${QCU_CUDA_ARCHITECTURES}")
+elseif(DEFINED CMAKE_CUDA_ARCHITECTURES AND NOT "${CMAKE_CUDA_ARCHITECTURES}" STREQUAL "")
+  set(_QCU_CUDA_ARCHITECTURES "${CMAKE_CUDA_ARCHITECTURES}")
+elseif(DEFINED ENV{QCU_CUDA_ARCHITECTURES} AND NOT "$ENV{QCU_CUDA_ARCHITECTURES}" STREQUAL "")
+  set(_QCU_CUDA_ARCHITECTURES "$ENV{QCU_CUDA_ARCHITECTURES}")
+elseif(DEFINED ENV{sm_arch} AND NOT "$ENV{sm_arch}" STREQUAL "")
+  set(_QCU_AUTO_CUDA_ARCHITECTURES "$ENV{sm_arch}")
+  message(STATUS "QCU CUDA architecture auto-detected from env.sh: sm_${_QCU_AUTO_CUDA_ARCHITECTURES}")
+else()
+  find_program(_QCU_NVIDIA_SMI NAMES nvidia-smi)
+  if(_QCU_NVIDIA_SMI)
+    execute_process(
+      COMMAND "${_QCU_NVIDIA_SMI}" --query-gpu=compute_cap --format=csv,noheader
+      RESULT_VARIABLE _QCU_NVIDIA_SMI_RESULT
+      OUTPUT_VARIABLE _QCU_NVIDIA_SMI_OUTPUT
+      ERROR_QUIET
+      OUTPUT_STRIP_TRAILING_WHITESPACE)
+    if(_QCU_NVIDIA_SMI_RESULT EQUAL 0 AND NOT "${_QCU_NVIDIA_SMI_OUTPUT}" STREQUAL "")
+      string(REPLACE "\n" ";" _QCU_GPU_CAPS "${_QCU_NVIDIA_SMI_OUTPUT}")
+      list(GET _QCU_GPU_CAPS 0 _QCU_GPU_CAP)
+      string(STRIP "${_QCU_GPU_CAP}" _QCU_GPU_CAP)
+      string(REGEX MATCH "^([0-9]+)\\.([0-9]+)$" _QCU_GPU_CAP_MATCH "${_QCU_GPU_CAP}")
+      if(_QCU_GPU_CAP_MATCH)
+        set(_QCU_AUTO_CUDA_ARCHITECTURES "${CMAKE_MATCH_1}${CMAKE_MATCH_2}")
+        message(STATUS "QCU CUDA architecture auto-detected from nvidia-smi: sm_${_QCU_AUTO_CUDA_ARCHITECTURES}")
+      endif()
+    endif()
+  endif()
+endif()
+
+if(_QCU_AUTO_CUDA_ARCHITECTURES)
+  set(_QCU_CUDA_ARCHITECTURES
+      "${_QCU_AUTO_CUDA_ARCHITECTURES}-real;${_QCU_AUTO_CUDA_ARCHITECTURES}-virtual")
+endif()
+
+if(NOT DEFINED _QCU_CUDA_ARCHITECTURES OR "${_QCU_CUDA_ARCHITECTURES}" STREQUAL "")
+  message(FATAL_ERROR
+    "Unable to determine CUDA architecture. Set QCU_CUDA_ARCHITECTURES "
+    "(for example 70-real;70-virtual), pass -DCMAKE_CUDA_ARCHITECTURES, "
+    "or source env.sh on a machine with nvidia-smi.")
+endif()
+
+set(QCU_CUDA_ARCHITECTURES "${_QCU_CUDA_ARCHITECTURES}")
+set(CMAKE_CUDA_ARCHITECTURES "${_QCU_CUDA_ARCHITECTURES}")
+set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -O3 --expt-relaxed-constexpr")
+message(STATUS "QCU CUDA architectures: ${QCU_CUDA_ARCHITECTURES}")
+set(MPI_INCLUDE_PATH $ENV{mpi_home}/include)
+set(MPI_CXX_LIBRARIES $ENV{mpi_home}/lib/libmpi.so)
+include(GNUInstallDirs)
+include_directories(${LD_LIBRARY_PATH})
+include_directories(${MPI_INCLUDE_PATH})
+include_directories(./include)
+aux_source_directory(./src SOURCE_FILE)
+add_library(qcu SHARED ${SOURCE_FILE})
+find_package(MPI REQUIRED)
+find_package(CUDA REQUIRED)
+target_link_libraries(qcu ${MPI_C_LIBRARIES})
+target_link_libraries(qcu ${CUDA_LIBRARIES})
+target_link_libraries(qcu curand)
+target_link_libraries(qcu cublas)
+
+# NVSHMEM is deliberately opt-in.  A normal CUDA/MPI build must not need the
+# headers or library, while an explicit request must fail during configure
+# instead of producing a binary whose optional transport silently disappears.
+if(QCU_ENABLE_NVSHMEM)
+  find_path(QCU_NVSHMEM_INCLUDE_DIR
+            NAMES nvshmem.h
+            HINTS $ENV{NVSHMEM_HOME} $ENV{NVSHMEM_ROOT}
+            PATH_SUFFIXES include)
+  find_path(QCU_NVSHMEMX_INCLUDE_DIR
+            NAMES nvshmemx.h
+            HINTS $ENV{NVSHMEM_HOME} $ENV{NVSHMEM_ROOT}
+            PATH_SUFFIXES include)
+  find_library(QCU_NVSHMEM_LIBRARY
+               NAMES nvshmem
+               HINTS $ENV{NVSHMEM_HOME} $ENV{NVSHMEM_ROOT}
+               PATH_SUFFIXES lib lib64)
+  if(NOT QCU_NVSHMEM_INCLUDE_DIR OR
+     NOT QCU_NVSHMEMX_INCLUDE_DIR OR
+     NOT QCU_NVSHMEM_LIBRARY)
+    message(FATAL_ERROR
+      "QCU_ENABLE_NVSHMEM=ON requires nvshmem.h, nvshmemx.h and libnvshmem")
+  endif()
+  target_include_directories(qcu PRIVATE
+    ${QCU_NVSHMEM_INCLUDE_DIR} ${QCU_NVSHMEMX_INCLUDE_DIR})
+  target_compile_definitions(qcu PRIVATE QCU_HAVE_NVSHMEM=1)
+  target_link_libraries(qcu ${QCU_NVSHMEM_LIBRARY})
+  message(STATUS "NVSHMEM enabled: ${QCU_NVSHMEM_LIBRARY}")
+else()
+  message(STATUS "NVSHMEM disabled (set -DQCU_ENABLE_NVSHMEM=ON to enable)")
+endif()