Pathfinder: add support on cuQuantum library loading and header descriptors

[yangcal]

Description

Add Pathfinder library loading and header discovery support for all five cuQuantum C libraries:

• cuTensorNet
• cuStateVec
• cuDensityMat
• cuStabilizer
• cuPauliProp

PyPI provides cuquantum-cu12 and cuquantum-cu13 metapackages, while conda-forge provides cuquantum to install all these sub-components. CUDA 12 and CUDA 13 use the same SONAMEs, headers, and cuquantum/lib and cuquantum/include layouts, so shared descriptors support both variants.

Changes

• Add dynamic-library and header descriptors for all five libraries.
• Add cuQuantum metapackages to the PyPI and conda test environments.
• Add distribution-name mappings used by strict header discovery.

Testing

No dedicated test cases are needed. Existing tests are parameterized from the descriptor catalogs, so new descriptors automatically receive loading, header-discovery, and structural validation coverage. The test-file update only registers component distribution names for installed-wheel detection.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[yangcal]

While cutensornet also has linkage to cublasLt/cusparse/nvJitLink, these are transitive through cublas/cutensor/cusolver and do not need to be explicitly listed here

[rwgk]

/ok to test ae950f8)

[rwgk]

Awesome!

---

Findings (gpt-5.6-sol)

No blocking or non-blocking findings were identified. The PR is ready for full CI validation.

Implementation verification

• The local checkout exactly matched the GitHub PR head and had a clean worktree.
• The current official CUDA 12 and
  CUDA 13 26.6.0 metapackage and
  component wheels were inspected directly.
• All five dynamic-library descriptors use the correct cuquantum/lib paths and
  SONAMEs for CUDA 12 and CUDA 13:
  • libcudensitymat.so.0
  • libcupauliprop.so.0
  • libcutensornet.so.2
  • libcustabilizer.so.0
  • libcustatevec.so.1
• The dependency tuples in
  cuda_pathfinder/cuda/pathfinder/_dynamic_libs/descriptor_catalog.py match the
  non-system ELF DT_NEEDED entries. Unlike cuTENSORMp in PR 2374, none of these
  five libraries directly requires libcudart.
• cuPauliProp and cuStabilizer genuinely have no non-system dynamic dependencies,
  so their empty Pathfinder dependency tuples are correct.
• The cuTensorNet note about cublasLt, cusparse, and nvJitLink being loaded
  transitively through existing cutensor, cublas, and cusolver descriptors
  is accurate.
• All five header descriptors use the correct public header basenames and
  cuquantum/include path. Both x86-64 and aarch64 wheel manifests were checked.
• The distribution-name regexes match the actual component metadata names for
  both -cu12 and -cu13 packages.
• Linux-only support is correct: the current component releases publish Linux
  x86-64 and aarch64 wheels, but no Windows wheels.
• Although the PyPI project-description text still mentions only three component
  packages, the downloadable 26.6.0 metapackage metadata explicitly depends on
  all five, including cuPauliProp and cuStabilizer. Therefore the single
  cuquantum-cu12/cuquantum-cu13 additions are sufficient.
• The conda-forge cuquantum metapackage likewise covers all five components and
  uses the expected $CONDA_PREFIX/include and $CONDA_PREFIX/lib layouts.

Automatic test and CI coverage

• Dynamic-library tests are parameterized from the descriptor catalog through
  SUPPORTED_LINUX_SONAMES and therefore include all five new libraries.
• Header-discovery tests are parameterized from the header catalog and verify the
  exact header basename for each component.
• None of the new dynamic libraries has an expected-failure exemption. In strict
  mode, either a missing library or a load error fails the test.
• Linux wheel CI installs the test-cu12 or test-cu13 dependency group and then
  reruns Pathfinder with all_must_work strictness for libraries and headers.
• The pull-request matrix covers CUDA 12.9, CUDA 13.0, and CUDA 13.3 across Linux
  x86-64 and aarch64, including both local-toolkit and wheel-only rows.
• The changed cuda_pathfinder/ and toolshed/ paths activate the appropriate
  full rebuild and test gating.