Port to custatevecEx

Signed-off-by: Thien Nguyen <thiennguyen@nvidia.com>

Author: 1tnguyen

CMakeLists.txt

@@ -845,7 +845,7 @@ endif()
 
 # cuQuantum / cuTensor component discovery
 if (CUDA_FOUND)
-  find_package(cuStateVec)
+  find_package(cuStateVec 1.14)
   find_package(cuTensor)
   find_package(cuTensorNet)
   find_package(cuDensityMat)

cmake/modules/CUDAQConfig.cmake

@@ -63,67 +63,53 @@ if (NOT CUDAQ_LIBRARY_MODE)
 endif() 
 
 # ---- TARGET EXPORTS ----
-# Prefer cusvsim libraries if they are present
-set (__base_nvtarget_name "custatevec") 
-find_library(CUDAQ_CUSVSIM_PATH NAMES cusvsim-fp32 HINTS ${CUDAQ_LIBRARY_DIR})
-if (CUDAQ_CUSVSIM_PATH)
-  set(__base_nvtarget_name "cusvsim")
-endif() 
-
 # Default Target
 add_library(cudaq::cudaq-default-target SHARED IMPORTED)
 set_target_properties(cudaq::cudaq-default-target PROPERTIES
-  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-${__base_nvtarget_name}-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
-  IMPORTED_SONAME "libnvqir-${__base_nvtarget_name}-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-custatevec-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_SONAME "libnvqir-custatevec-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
   IMPORTED_LINK_INTERFACE_LIBRARIES "cudaq::cudaq-platform-default;cudaq::cudaq-em-default")
 
 # NVIDIA Target
 add_library(cudaq::cudaq-nvidia-target SHARED IMPORTED)
 set_target_properties(cudaq::cudaq-nvidia-target PROPERTIES
-  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-${__base_nvtarget_name}-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
-  IMPORTED_SONAME "libnvqir-${__base_nvtarget_name}-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
-  IMPORTED_LINK_INTERFACE_LIBRARIES "cudaq::cudaq-platform-default;cudaq::cudaq-em-default")
-
-# NVIDIA Legacy Target
-add_library(cudaq::cudaq-nvidia-legacy-target SHARED IMPORTED)
-set_target_properties(cudaq::cudaq-nvidia-legacy-target PROPERTIES
   IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-custatevec-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
   IMPORTED_SONAME "libnvqir-custatevec-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
   IMPORTED_LINK_INTERFACE_LIBRARIES "cudaq::cudaq-platform-default;cudaq::cudaq-em-default")
 
 # NVIDIA FP64 Target
 add_library(cudaq::cudaq-nvidia-fp64-target SHARED IMPORTED)
 set_target_properties(cudaq::cudaq-nvidia-fp64-target PROPERTIES
-  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-${__base_nvtarget_name}-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
-  IMPORTED_SONAME "libnvqir-${__base_nvtarget_name}-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-custatevec-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_SONAME "libnvqir-custatevec-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
   IMPORTED_LINK_INTERFACE_LIBRARIES "cudaq::cudaq-platform-default;cudaq::cudaq-em-default")
 
 # NVIDIA MGPU Target
 add_library(cudaq::cudaq-nvidia-mgpu-target SHARED IMPORTED)
 set_target_properties(cudaq::cudaq-nvidia-mgpu-target PROPERTIES
-  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-mgpu-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
-  IMPORTED_SONAME "libnvqir-mgpu-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-nvidia-mgpu-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_SONAME "libnvqir-nvidia-mgpu-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
   IMPORTED_LINK_INTERFACE_LIBRARIES "cudaq::cudaq-platform-default;cudaq::cudaq-em-default")
 
 # NVIDIA MGPU-FP64 Target
 add_library(cudaq::cudaq-nvidia-mgpu-fp64-target SHARED IMPORTED)
 set_target_properties(cudaq::cudaq-nvidia-mgpu-fp64-target PROPERTIES
-  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-mgpu-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
-  IMPORTED_SONAME "libnvqir-mgpu-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-nvidia-mgpu${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_SONAME "libnvqir-nvidia-mgpu${CMAKE_SHARED_LIBRARY_SUFFIX}"
   IMPORTED_LINK_INTERFACE_LIBRARIES "cudaq::cudaq-platform-default;cudaq::cudaq-em-default")
 
 # NVIDIA MQPU Target
 add_library(cudaq::cudaq-nvidia-mqpu-target SHARED IMPORTED)
 set_target_properties(cudaq::cudaq-nvidia-mqpu-target PROPERTIES
-  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-${__base_nvtarget_name}${CMAKE_SHARED_LIBRARY_SUFFIX}"
-  IMPORTED_SONAME "libnvqir-${__base_nvtarget_name}${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-custatevec-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_SONAME "libnvqir-custatevec-fp32${CMAKE_SHARED_LIBRARY_SUFFIX}"
   IMPORTED_LINK_INTERFACE_LIBRARIES "cudaq::cudaq-platform-mqpu;cudaq::cudaq-em-default")
 
 # NVIDIA MQPU FP64 Target
 add_library(cudaq::cudaq-nvidia-mqpu-fp64-target SHARED IMPORTED)
 set_target_properties(cudaq::cudaq-nvidia-mqpu-fp64-target PROPERTIES
-  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-${__base_nvtarget_name}-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
-  IMPORTED_SONAME "libnvqir-${__base_nvtarget_name}-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_LOCATION "${CUDAQ_LIBRARY_DIR}/libnvqir-custatevec-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
+  IMPORTED_SONAME "libnvqir-custatevec-fp64${CMAKE_SHARED_LIBRARY_SUFFIX}"
   IMPORTED_LINK_INTERFACE_LIBRARIES "cudaq::cudaq-platform-mqpu;cudaq::cudaq-em-default")
 
 # QPP CPU Target

docs/sphinx/using/backends/sims/svsims.rst

@@ -106,14 +106,14 @@ It is worth drawing attention to gate fusion, a powerful tool for improving simu
     - Value
     - Description
   * - ``CUDAQ_FUSION_MAX_QUBITS``
-    - positive integer
-    - The max number of qubits used for gate fusion. The default value depends on `GPU Compute Capability <https://developer.nvidia.com/cuda-gpus>`__ (CC) and the floating point precision selected for the simulator as specified :ref:`here <gate-fusion-table>`.
+    - integer (maximum effective value: 10)
+    - The max number of qubits used for gate fusion. Values greater than 10 are clamped to 10, while a non-positive value disables gate fusion. The default value depends on `GPU Compute Capability <https://developer.nvidia.com/cuda-gpus>`__ (CC) and the floating point precision selected for the simulator as specified :ref:`here <gate-fusion-table>`.
   * - ``CUDAQ_FUSION_DIAGONAL_GATE_MAX_QUBITS``
-    - integer greater than or equal to -1
-    - The max number of qubits used for diagonal gate fusion. The default value is set to `-1` and the fusion size will be automatically adjusted for the better performance. If 0, the gate fusion for diagonal gates is disabled.
+    - integer greater than or equal to -1 (maximum effective value: 20)
+    - The max number of qubits used for diagonal gate fusion. Values greater than 20 are clamped to 20. The default value is set to `-1` and the fusion size will be automatically adjusted for better performance. If 0, gate fusion for diagonal gates is disabled.
   * - ``CUDAQ_FUSION_NUM_HOST_THREADS``
-    - positive integer
-    - Number of CPU threads used for circuit processing. The default value is `8`.
+    - positive integer (maximum effective value: 32)
+    - Number of CPU threads used for circuit processing. Values greater than 32 are clamped to 32. The default value is `8`.
   * - ``CUDAQ_MAX_CPU_MEMORY_GB``
     - non-negative integer, or `NONE`
     - CPU memory size (in GB) allowed for state-vector migration. `NONE` means unlimited (up to physical memory constraints). Default is 0GB (disabled, variable is not set to any value).
@@ -123,6 +123,9 @@ It is worth drawing attention to gate fusion, a powerful tool for improving simu
   * - ``CUDAQ_ALLOW_FP32_EMULATED``
     - `TRUE` (`1`, `ON`) or `FALSE` (`0`, `OFF`)
     - [Blackwell (compute capability 10.0+) only] Enable or disable floating point math emulation. If enabled, allows `FP32` emulation kernels using `BFloat16` (`BF16`) whenever possible. Enabled by default. 
+  * - ``CUDAQ_GPU_RNG_THRESHOLD``
+    - non-negative integer
+    - The minimum random-number count that uses GPU generation. The default is 100,000; 0 selects GPU generation for every request.
   * - ``CUDAQ_ENABLE_MEMPOOL``
     - `TRUE` (`1`, `ON`) or `FALSE` (`0`, `OFF`)
     - Enable or disable `CUDA memory pool <https://developer.nvidia.com/blog/using-cuda-stream-ordered-memory-allocator-part-1/#memory_pools>`__ for state vector allocation/deallocation. Enabled by default. 
@@ -134,14 +137,10 @@ It is worth drawing attention to gate fusion, a powerful tool for improving simu
 
 .. note:: 
 
-    In host-device simulation, `CUDAQ_MAX_CPU_MEMORY_GB` is not 0, the backend automatically switching between inner product (default) and operator matrix-based 
-    methods for expectation calculations (`cudaq::observe`) depending on whether a clone of the state can be allocated or not. 
-
-    For example, when `CUDAQ_MAX_GPU_MEMORY_GB` is unconstrained, the quantum state vector would consume all device memory before utilizing host memory.
-    Thus, the backend would fall back to the operator matrix-based approach as cloning the state is not possible. 
-    For performance reason, only Pauli operator matrices of up to 8 qubits (identity padding not included) are allowed in this mode.
-    This constrain can be relaxed by setting the `CUDAQ_MATRIX_EXP_VAL_MAX_SIZE` environment variable. 
-    Users would need to take into account the full operator matrix size when increasing this setting.
+    The ``CUDAQ_MATRIX_EXP_VAL_MAX_SIZE`` environment variable has been removed.
+    The ``nvidia`` state-vector backend now evaluates Pauli expectations directly
+    on host-migrated states without a dense-matrix fallback, so migrated Pauli
+    terms no longer require a separate width limit.
 
 
 Multi-GPU multi-node 
@@ -240,17 +239,17 @@ the multi-node multi-GPU configuration. Any environment variables must be set pr
     - string
     - The shared library name for inter-process communication. The default value is `libmpi.so`.
   * - ``CUDAQ_MGPU_COMM_PLUGIN_TYPE``
-    - `AUTO`, `EXTERNAL`, `OpenMPI`, or `MPICH` 
-    - Selecting :code:`cuStateVec` `CommPlugin` for inter-process communication. The default is `AUTO`. If `EXTERNAL` is selected, `CUDAQ_MGPU_LIB_MPI` should point to an implementation of :code:`cuStateVec` `CommPlugin` interface.
+    - `AUTO`, `SELF`, `EXTERNAL`, `OpenMPI`, or `MPICH`
+    - Select the communicator provider. The default `AUTO` uses activated CUDA-Q MPI when available and otherwise detects OpenMPI or MPICH from `CUDAQ_MGPU_LIB_MPI`. `SELF` requires and uses activated CUDA-Q MPI across all ranks. `OpenMPI`, `MPICH`, and `EXTERNAL` always use the corresponding ``cuStateVecEx`` provider and bypass CUDA-Q MPI. If `EXTERNAL` is selected, `CUDAQ_MGPU_LIB_MPI` must point to a ``cuStateVecEx`` communicator module. Custom communicators set with :code:`cudaq::mpi::set_communicator` are supported only by CUDA-Q-backed `AUTO` and `SELF`.
   * - ``CUDAQ_MGPU_NQUBITS_THRESH``
     - positive integer
     - The qubit count threshold where state vector distribution is activated. Below this threshold, simulation is performed as independent (non-distributed) tasks across all MPI processes for optimal performance. Default is 25. 
   * - ``CUDAQ_MGPU_FUSE``
-    - positive integer
-    - The max number of qubits used for gate fusion. The default value depends on `GPU Compute Capability <https://developer.nvidia.com/cuda-gpus>`__ (CC) and the floating point precision selected for the simulator as specified :ref:`here <gate-fusion-table>`. 
+    - integer (maximum effective value: 10)
+    - The max number of qubits used for gate fusion. Values greater than 10 are clamped to 10, while a non-positive value disables gate fusion. The default value depends on `GPU Compute Capability <https://developer.nvidia.com/cuda-gpus>`__ (CC) and the floating point precision selected for the simulator as specified :ref:`here <gate-fusion-table>`.
   * - ``CUDAQ_MGPU_P2P_DEVICE_BITS``
-    - positive integer
-    - Specify the number of GPUs that can communicate by using GPUDirect P2P. Default value is 0 (P2P communication is disabled).
+    - non-negative integer
+    - Specify the number of global device-index bits that use GPUDirect P2P communication. A value of 0 disables P2P communication.
   * - ``CUDAQ_GPU_FABRIC``
     - `MNNVL`, `NVL`, `NONE`, or NVLink domain size (power of 2 integer)
     - Automatically set the number of P2P device bits based on the total number of processes when multi-node NVLink (`MNNVL`) is selected; or the number of processes per node when NVLink (`NVL`) is selected; or disable P2P (with `NONE`); or a specific NVLink domain size.
@@ -327,4 +326,4 @@ environment variable to another integer value as shown below.
 .. note:: 
 
   On multi-node systems without `MNNVL` support, the `nvidia` target in `mgpu` mode may fail to allocate memory. 
-  Users can disable `MNNVL` fabric-based memory sharing by setting the environment variable `UBACKEND_USE_FABRIC_HANDLE=0`.  
+  Users can disable GPU-fabric P2P memory sharing by setting the environment variable `CUDAQ_GPU_FABRIC=NONE`.

docs/sphinx/using/backends/simulators.rst

@@ -38,12 +38,6 @@ technical details and code examples for using each circuit simulator.
      - multi-GPU multi-node
      - single (default) / double
      - 33+
-   * - `nvidia-legacy`
-     - State Vector
-     - Legacy state vector simulator that does not support multi-GPU, gate fusion, or trajectory sampling. Can perform better at low qubit counts.
-     - Single GPU
-     - single (default) / double
-     - < 33 / 32 (64 GB)
    * - `tensornet` *
      - Tensor Network
      - Shallow-depth (low-entanglement) and high width circuits (exact)

docs/sphinx/using/extending/nvqir_simulator.rst

@@ -29,7 +29,7 @@ This is the type that downstream simulation developers should extend.
 
 The actual definition of the quantum state data structure, and its overall evolution are 
 left as tasks for :code:`CircuitSimulatorBase` subclasses. Examples of simulation subtypes can be found 
-in :code:`runtime/nvqir/qpp/QppCircuitSimulator.cpp` or :code:`runtime/nvqir/custatevec/CuStateVecCircuitSimulator.cpp`.
+in :code:`runtime/nvqir/qpp/QppCircuitSimulator.cpp` or :code:`runtime/nvqir/custatevec/CuStateVecCircuitSimulatorEx.h`.
 The :code:`QppCircuitSimulator` models the state vector using the `Q++ <https://github.com/softwareqinc/qpp>`_ library, which 
 leverages the :code:`Eigen::Matrix` type and OpenMP threading for matrix-vector operations. 
 The :code:`CuStateVecCircuitSimulator` type models the state vector on an NVIDIA GPU device 

python/tests/custom/test_custom_operations.py

@@ -111,8 +111,8 @@ def test_toffoli():
 
 # NOTE: Ref - https://github.com/NVIDIA/cuda-quantum/issues/1925
 @pytest.mark.parametrize("target", [
-    'density-matrix-cpu', 'nvidia', 'nvidia-legacy', 'nvidia-fp64',
-    'nvidia-mqpu', 'nvidia-mqpu-fp64', 'qpp-cpu'
+    'density-matrix-cpu', 'nvidia', 'nvidia-fp64', 'nvidia-mqpu',
+    'nvidia-mqpu-fp64', 'qpp-cpu'
 ])
 def test_simulators(target):
     """Test simulation of custom operation on all available simulation targets."""

runtime/cudaq/distributed/builtin/mpi_comm_impl.cpp

@@ -40,12 +40,20 @@ MPI_Datatype convertType(DataType dataType) {
   switch (dataType) {
   case INT_8:
     return MPI_INT8_T;
+  case UINT_8:
+    return MPI_UINT8_T;
   case INT_16:
     return MPI_INT16_T;
+  case UINT_16:
+    return MPI_UINT16_T;
   case INT_32:
     return MPI_INT32_T;
+  case UINT_32:
+    return MPI_UINT32_T;
   case INT_64:
     return MPI_INT64_T;
+  case UINT_64:
+    return MPI_UINT64_T;
   case FLOAT_32:
     return MPI_FLOAT;
   case FLOAT_64:

runtime/cudaq/distributed/distributed_capi.h

@@ -42,7 +42,11 @@ enum DataType {
   FLOAT_32,
   FLOAT_64,
   FLOAT_COMPLEX,
-  DOUBLE_COMPLEX
+  DOUBLE_COMPLEX,
+  UINT_8,
+  UINT_16,
+  UINT_32,
+  UINT_64
 };
 
 /// @brief Type of MPI reduce ops that we support

runtime/cudaq/platform/default/CMakeLists.txt

@@ -54,6 +54,5 @@ add_target_config(compiler-bench-ftqc-logical)
 
 if (cuStateVec_FOUND)
   add_target_config(nvidia)
-  add_target_config(nvidia-legacy)
   add_target_config(nvidia-fp64)
 endif()

runtime/cudaq/platform/default/nvidia-fp64.yml

@@ -12,6 +12,6 @@ warning: "This target is deprecating. Please use the 'nvidia' target with option
 gpu-requirements: true
 
 config:
-  nvqir-simulation-backend: cusvsim-fp64, custatevec-fp64
+  nvqir-simulation-backend: custatevec-fp64
   preprocessor-defines: ["-D CUDAQ_SIMULATION_SCALAR_FP64"]