Pathfinder: add support on cuQuantum library loading and header descriptors (#2376)

* Pathfinder: add support on cutensornet for library loading and header descriptors

* Pathfinder: add support on custatevec for library loading and header descriptors

* Pathfinder: add support on cudensitymat for library loading and header descriptors

* Pathfinder: add support on custabilizer for library loading and header descriptors

* Pathfinder: add support on cupauliprop for library loading and header descriptors

* switch to cuquantum metapackage to simplify dependency listing

---------

Co-authored-by: Ralf W. Grosse-Kunstleve <rwgkio@gmail.com>

Author: yangcal

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/descriptor_catalog.py

@@ -382,6 +382,48 @@ class DescriptorSpec:
         site_packages_linux=("cutensor/lib",),
         dependencies=("cutensor", "cublasLt", "cudart", "nccl"),
     ),
+    DescriptorSpec(
+        name="cudensitymat",
+        packaged_with="other",
+        linux_sonames=("libcudensitymat.so.0",),
+        site_packages_linux=("cuquantum/lib",),
+        dependencies=(
+            "cutensornet",
+            "cutensor",
+            "cusolver",
+            "cublasLt",
+            "cublas",
+            "curand",
+            "cusparse",
+            "nvJitLink",
+        ),
+    ),
+    DescriptorSpec(
+        name="cupauliprop",
+        packaged_with="other",
+        linux_sonames=("libcupauliprop.so.0",),
+        site_packages_linux=("cuquantum/lib",),
+    ),
+    DescriptorSpec(
+        name="cutensornet",
+        packaged_with="other",
+        linux_sonames=("libcutensornet.so.2",),
+        site_packages_linux=("cuquantum/lib",),
+        dependencies=("cutensor", "cublas", "cusolver"),
+    ),
+    DescriptorSpec(
+        name="custabilizer",
+        packaged_with="other",
+        linux_sonames=("libcustabilizer.so.0",),
+        site_packages_linux=("cuquantum/lib",),
+    ),
+    DescriptorSpec(
+        name="custatevec",
+        packaged_with="other",
+        linux_sonames=("libcustatevec.so.1",),
+        site_packages_linux=("cuquantum/lib",),
+        dependencies=("cublas", "cublasLt"),
+    ),
     DescriptorSpec(
         name="nccl",
         packaged_with="other",

cuda_pathfinder/cuda/pathfinder/_headers/header_descriptor_catalog.py

@@ -183,6 +183,51 @@ class HeaderDescriptorSpec:
         conda_targets_layout=False,
         use_ctk_root_canary=False,
     ),
+    HeaderDescriptorSpec(
+        name="cudensitymat",
+        packaged_with="other",
+        header_basename="cudensitymat.h",
+        site_packages_dirs=("cuquantum/include",),
+        available_on_windows=False,
+        conda_targets_layout=False,
+        use_ctk_root_canary=False,
+    ),
+    HeaderDescriptorSpec(
+        name="cupauliprop",
+        packaged_with="other",
+        header_basename="cupauliprop.h",
+        site_packages_dirs=("cuquantum/include",),
+        available_on_windows=False,
+        conda_targets_layout=False,
+        use_ctk_root_canary=False,
+    ),
+    HeaderDescriptorSpec(
+        name="cutensornet",
+        packaged_with="other",
+        header_basename="cutensornet.h",
+        site_packages_dirs=("cuquantum/include",),
+        available_on_windows=False,
+        conda_targets_layout=False,
+        use_ctk_root_canary=False,
+    ),
+    HeaderDescriptorSpec(
+        name="custabilizer",
+        packaged_with="other",
+        header_basename="custabilizer.h",
+        site_packages_dirs=("cuquantum/include",),
+        available_on_windows=False,
+        conda_targets_layout=False,
+        use_ctk_root_canary=False,
+    ),
+    HeaderDescriptorSpec(
+        name="custatevec",
+        packaged_with="other",
+        header_basename="custatevec.h",
+        site_packages_dirs=("cuquantum/include",),
+        available_on_windows=False,
+        conda_targets_layout=False,
+        use_ctk_root_canary=False,
+    ),
     HeaderDescriptorSpec(
         name="cutlass",
         packaged_with="other",

cuda_pathfinder/pyproject.toml

@@ -21,6 +21,7 @@ test = [
 cu12 = [
     "cuda-toolkit[nvcc,cublas,nvrtc,cudart,cufft,curand,cusolver,cusparse,npp,nvfatbin,nvjitlink,nvjpeg,cccl,cupti,profiler]==12.*",
     "cuda-toolkit[cufile]==12.*; sys_platform != 'win32'",
+    "cuquantum-cu12; sys_platform != 'win32'",
     "cutensor-cu12",
     "nvidia-cublasmp-cu12; sys_platform != 'win32'",
     "nvidia-cudss-cu12",
@@ -34,6 +35,7 @@ cu12 = [
 cu13 = [
     "cuda-toolkit[nvcc,cublas,nvrtc,cudart,cufft,curand,cusolver,cusparse,npp,nvfatbin,nvjitlink,nvjpeg,cccl,cupti,profiler,nvvm]==13.*",
     "cuda-toolkit[cufile]==13.*; sys_platform != 'win32'",
+    "cuquantum-cu13; sys_platform != 'win32'",
     "cutensor-cu13",
     "nvidia-cublasmp-cu13; sys_platform != 'win32'",
     "nvidia-cudla; platform_system == 'Linux' and platform_machine == 'aarch64'",

cuda_pathfinder/tests/test_find_nvidia_headers.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
 # Currently these installations are only manually tested:
@@ -42,10 +42,15 @@
 assert STRICTNESS in ("see_what_works", "all_must_work")
 
 NON_CTK_IMPORTLIB_METADATA_DISTRIBUTIONS_NAMES = {
+    "cudensitymat": r"^cudensitymat-.*$",
+    "cupauliprop": r"^cupauliprop-.*$",
     "cusolverMp": r"^nvidia-cusolvermp-.*$",
     "cusparseLt": r"^nvidia-cusparselt-.*$",
     "cute": r"^nvidia-cutlass$",
     "cutensor": r"^cutensor-.*$",
+    "cutensornet": r"^cutensornet-.*$",
+    "custabilizer": r"^custabilizer-.*$",
+    "custatevec": r"^custatevec-.*$",
     "cutlass": r"^nvidia-cutlass$",
     "mathdx": r"^nvidia-libmathdx-.*$",
     "nvshmem": r"^nvidia-nvshmem-.*$",

toolshed/conda_create_for_pathfinder_testing.sh

@@ -25,6 +25,7 @@ set -u
 # Keep this list aligned with the Linux-installable subset of
 # cuda_pathfinder/pyproject.toml.
 cpkgs=(
+    "cuquantum"
     "cusparselt-dev"
     "cutensor"
     "cutlass"