[build] Decide supported CUDA toolkit under cuTENSOR >= 2.0 + cuQuantum >= 24.0 (CUDA 11? CUDA 13?)

[pcchen]

Summary

Decide (and document) which CUDA Toolkit version(s) Cytnx supports for GPU builds, given the intended dependency floors cuTENSOR ≥ 2.0 and cuQuantum ≥ 24.0. The short answer is CUDA 12 is the only universally-supported toolkit; CUDA 11 and CUDA 13 each require changing one or both floors. This issue lays out the matrix so we can make an explicit call.

Focused follow-up to the "SM 7.0 / CUDA 11 going forward" open question in #945; related: #950, #580.

What each dependency supports (from NVIDIA release notes)

cuTENSOR 2.x → CUDA Toolkit (latest 2.7.0):

cuTENSOR	CUDA	Min GPU
2.0.0 – 2.2.x	11 + 12	SM 7.0 (Volta)
2.3.0+ (→ 2.7.x)	12 + 13 (CUDA 11 removed)	SM 7.5 (Turing; SM 7.0 removed)

cuQuantum 24.x/25.x → CUDA Toolkit (SDK YY.MM; cuStateVec / cuTensorNet):

cuQuantum SDK	CUDA
24.03 / 24.08 / 24.11	11 + 12
25.03	12
~25.09 → 25.11 (latest)	12 + 13

(cuTensorNet 2.4.0 in cuQuantum 24.03 itself requires cuTENSOR ≥ 2.0.1, so the two floors are mutually consistent.)

Intersection under cuTENSOR ≥ 2.0 + cuQuantum ≥ 24.0

CUDA	cuTENSOR ≥ 2.0	cuQuantum ≥ 24.0	Usable?
11	only 2.0.0–2.2.x (dropped in 2.3.0)	only 24.x (dropped in 25.x)	⚠️ only at the low end of both ranges
12	all of 2.x ✅	all 24.x + 25.x ✅	✅ yes — for any qualifying versions
13	only cuTENSOR ≥ 2.3.0	only cuQuantum ≈ ≥ 25.09	❌ not with the floor versions

⇒ CUDA 12 is the only toolkit supported no matter which qualifying cuTENSOR (2.0→2.7) and cuQuantum (24.03→25.11) a user installs.

Discussion: CUDA 11 and/or CUDA 13?

CUDA 11

• Supported only by cuTENSOR 2.0.0–2.2.x and cuQuantum 24.x. It disappears the moment a user installs cuTENSOR ≥ 2.3 or cuQuantum ≥ 25.
• To actually support CUDA 11 we'd need upper caps: cuTENSOR < 2.3 and cuQuantum < 25 — i.e. pinning to an aging, soon-EOL band. CUDA 11 also implies keeping Volta sm_70 (dropped by cuTENSOR 2.3 / CUDA 13).
• Recommendation: drop CUDA 11. Open-ended >= 2.0 / >= 24.0 floors are incompatible with guaranteeing CUDA-11 support, and maintaining the caps is not worth it. (This resolves the [build] Clarify compiler/CUDA/cuTENSOR requirements and fix FindCUTENSOR.cmake #945 CUDA-11 question in the "drop" direction.)

CUDA 13

• Not supported by the floor versions. Requires raising both floors: cuTENSOR ≥ 2.3 and cuQuantum ≈ ≥ 25.09.
• If we only depend on cuTENSOR (no cuQuantum), CUDA 13 needs just cuTENSOR ≥ 2.3.
• Recommendation: support CUDA 13, but gate the dependency floors on it, e.g.
  • USE_CUTENSOR + CUDA 13 ⇒ require cuTENSOR ≥ 2.3
  • USE_CUQUANTUM + CUDA 13 ⇒ require cuQuantum ≥ 25.09 (exact minor TBD — see caveat)

Proposed policy (for discussion)

• Baseline: support CUDA 12 unconditionally (the safe common denominator).
• CUDA 13: allowed, but conditionally raise floors — cuTENSOR ≥ 2.3, and cuQuantum ≥ 25.09 when cuQuantum is enabled.
• CUDA 11: drop (not compatible with open-ended cuTENSOR ≥ 2.0 / cuQuantum ≥ 24.0; keeping it needs upper caps + Volta sm_70).
• GPU-arch floor follows from the above: SM 7.5 (Turing) once CUDA 11 is dropped; SM 7.0 (Volta) only survives on the CUDA-11 / cuTENSOR<2.3 path we're proposing to drop.

Caveat / to verify

The cuQuantum "CUDA 13 from ~25.09" boundary is approximate — NVIDIA's SDK pages truncated/redirected through fetching. Confirm the exact 25.x minor that first ships -cu13 (cuStateVec/cuTensorNet) before hard-coding a version in CMake.

Sources

• cuTENSOR release notes: https://docs.nvidia.com/cuda/cutensor/latest/release_notes.html
• cuQuantum SDK release notes: https://docs.nvidia.com/cuda/cuquantum/latest/cuquantum-sdk-release-notes.html
• cuTensorNet 24.03 (requires cuTENSOR ≥ 2.0.1): https://archive.docs.nvidia.com/cuda/cuquantum/24.03.0/cutensornet/release_notes.html
• CUDA host-compiler ranges (context): https://docs.nvidia.com/cuda/cuda-installation-guide-linux/

---

Filed by Claude Code on behalf of @pcchen

[pcchen]

If we want to keep SM 7.0 (Volta): what combinations are possible?

SM 7.0 support is an all-components-must-agree constraint — every enabled component has to still support Volta. Three gates:

1. CUDA Toolkit ≤ 12.x — CUDA 13.0 removed offline compilation for compute capability < 7.5, so sm_70 is gone on CUDA 13.
2. cuTENSOR 2.0.1 – 2.2.x (i.e. < 2.3) — cuTENSOR 2.3.0 removed SM 7.0. Applies whether cuTENSOR is used directly or transitively via cuQuantum's cuTensorNet.
3. cuQuantum 24.x (if used) — cuStateVec supports cc 7.0+, but Cytnx uses cuTensorNet, whose cuTENSOR dependency must stay < 2.3; the 24.x line pairs with cuTENSOR 2.0–2.2, whereas 25.x trends to cuTENSOR ≥ 2.3.

Possible combinations

Build config	CUDA	cuTENSOR	cuQuantum
Core CUDA only (no cuTENSOR/cuQuantum)	11.x or 12.x	—	—
+ cuTENSOR	11.x or 12.x	2.0.1 – 2.2.x	—
+ cuQuantum (cuTensorNet)	11.x or 12.x	2.0.1 – 2.2.x	24.03 – 24.11

Incompatible with SM 7.0 (any one kills Volta): CUDA 13 · cuTENSOR ≥ 2.3 · cuQuantum ≥ 25 (its cuTensorNet needs cuTENSOR ≥ 2.3).

Implications for the decision above

• SM 7.0 and CUDA 13 are mutually exclusive — you cannot support both. Keeping Volta pins the whole stack to CUDA ≤ 12, cuTENSOR < 2.3, cuQuantum 24.x.
• Dropping CUDA 11 does not drop Volta. CUDA 12 + cuTENSOR 2.0–2.2 + cuQuantum 24.x still targets sm_70. What removes Volta is CUDA 13 / cuTENSOR 2.3, not the CUDA-11 decision — so the "drop CUDA 11" and "keep SM 7.0" choices are independent.
• To guarantee SM 7.0 under the proposed floors, we'd need upper caps: cuTENSOR < 2.3 and cuQuantum < 25, and forgo CUDA 13. That is the core trade-off: Volta support ⟺ capping the deps below the CUDA-13-capable versions.

Net recommendation (folding into the decision)

• If we adopt CUDA 13 (per the proposal), SM 7.0 must be dropped; floor becomes SM 7.5 (Turing).
• If SM 7.0 is a hard requirement for some users, that forces a legacy build profile (CUDA ≤ 12, cuTENSOR < 2.3, cuQuantum 24.x) that cannot coexist with CUDA 13 in the same configuration — likely a separate, capped build matrix rather than the mainline.

Sources: cuTENSOR release notes (2.3.0 removed SM 7.0) · cuQuantum Getting Started (cc 7.0+ / Volta) · CUDA install guide (CUDA 13 arch floor)

---

Posted by Claude Code on behalf of @pcchen

[pcchen]

cuTensorNet requirements (and why USE_CUQUANTUM sets the cuTENSOR floor)

Cytnx's cuQuantum usage is cuTensorNet (Network contraction). The defining fact: cuTensorNet is built on cuTENSOR — cuTENSOR is a hard dependency, not optional. So enabling cuTensorNet always imposes a cuTENSOR version requirement.

Requirement	Detail
cuTENSOR	Required. cuTensorNet 2.4.0 (cuQuantum 24.03) requires cuTENSOR ≥ 2.0.1 (verified). CUDA-13-capable cuTensorNet (~cuQuantum 25.09+) requires cuTENSOR ≥ 2.3.
CUDA Toolkit	Tracks the cuQuantum SDK: 24.x → CUDA 11.x + 12.x; 25.x → CUDA 12 (and CUDA 13 from ~25.09+).
GPU compute capability	Base cc 7.0+ (Volta), but bounded by its cuTENSOR/CUDA — with cuTENSOR ≥ 2.3 or CUDA 13, sm_70 is dropped and the floor rises to 7.5 (Turing).
Other	cuBLAS (from CUDA Toolkit); MPI/NCCL only for optional multi-GPU/distributed paths. Host compiler/glibc inherited from the CUDA Toolkit.

cuTensorNet -> cuTENSOR / CUDA (what could be verified)

cuTensorNet	cuQuantum SDK	Requires cuTENSOR	CUDA
2.4.0	24.03	≥ 2.0.1 (verified)	11.x + 12.x
2.5.0	24.08	≥ 2.x (compatible)	11.x + 12.x
2.6.0	24.11 / 25.03	≥ 2.x	11/12 (24.11), 12 (25.03)
newer (CUDA-13 capable)	~25.09+	≥ 2.3	12 + 13

Implication for the decision here

• USE_CUQUANTUM ⇒ a compatible cuTENSOR is mandatory — cuTensorNet can't be used standalone, so the effective cuTENSOR floor is set by whichever cuTensorNet/cuQuantum we pick. This is why the whole matrix in this issue collapses onto cuTENSOR:
  • Volta (SM 7.0): cuTensorNet's cuTENSOR must be < 2.3 ⇒ cuQuantum 24.x, CUDA ≤ 12.
  • CUDA 13: cuTensorNet's cuTENSOR must be ≥ 2.3 ⇒ cuQuantum ~25.09+, CUDA 12 + 13.
• Practical CMake consequence: don't gate cuTENSOR and cuQuantum independently. When USE_CUQUANTUM=ON, the cuTENSOR requirement should be derived from the selected cuQuantum/CUDA (e.g. CUDA 13 ⇒ cuTENSOR ≥ 2.3 and cuQuantum ≥ 25.09), not pinned separately.

Caveat: only the 2.4.0 → cuTENSOR ≥ 2.0.1 mapping is firmly verified; the later cuTensorNet minimums are inferred from the CUDA/cuTENSOR timeline — confirm in the specific release notes before hard-coding.

Sources: cuTensorNet 24.03 release notes (cuTENSOR ≥ 2.0.1) · cuQuantum SDK release notes · cuTENSOR release notes

---

Posted by Claude Code on behalf of @pcchen