Deployment strategy — status board

[pcchen]

Deployment strategy — status board

Umbrella tracker grouping the existing build/packaging issues and PRs into a
phased deployment roadmap. This references existing issues/PRs; it does not
duplicate or re-litigate them. Checkboxes track whether each line's
underlying issue/PR is still open, not a separate approval step.

Phase gate — packaging model (Phases 2–3 depend on this)

• Decide PyTorch-style single-package vs JAX-style cpu/cuda12/cuda13 variants — Investigate CPU/CUDA wheel packaging strategy for PyPI, modeled on PyTorch and JAX #969 (+ Consider a PyTorch-style shared libcytnx.so to restore C++-extension support without the static-lib bloat #966)

Phase 0 — wheel size / PyPI quota

• Exclude C++ SDK (libcytnx.a, headers, CMake config) from the Python wheel — PyPI wheels are oversized: static lib + duplicate OpenBLAS bloat every platform wheel #947 (PR Reduce PyPI wheel size: exclude static libs/headers from the Python wheel #967)
• Dedup OpenBLAS across manylinux arpack+cytnx wheel builds — PyPI wheels are oversized: static lib + duplicate OpenBLAS bloat every platform wheel #947 (PR Reduce PyPI wheel size: exclude static libs/headers from the Python wheel #967)

Both are implemented in PR #967, pending merge. The dedup path was built and
inspected on the real manylinux_2_28 image (aarch64): the wheel vendors a single
OpenBLAS and excludes the SDK. Note (per #971): the dedup is a size optimization,
not a hard guarantee — two OpenBLAS variants are still permitted when arpack's
build lacks LAPACKE, so no single-OpenBLAS CI gate is enforced.

Phase 1 — build-time discovery

PR #950 is being split into focused PRs (see the comment thread on #950); the
lines below map to those split PRs.

• Fix the finder *_FOUND dead-code bug in FindCUTENSOR/FindCUQUANTUM — [build] Clarify compiler/CUDA/cuTENSOR requirements and fix FindCUTENSOR.cmake #945/[build] FindCUTENSOR/FindCUQUANTUM hard-code an outdated directory layout; tarball (2.x) and apt installs both break #946 (build: require GCC>=13, CUDA>=12 (12 & 13), cuTENSOR>=2.0 with early actionable errors; harden CUDA finders #950 split: finder-correctness PR)
• Version-aware cuTENSOR library-subdir search (drop dead lib/10.2,lib/11) — [build] FindCUTENSOR/FindCUQUANTUM hard-code an outdated directory layout; tarball (2.x) and apt installs both break #946 (build: require GCC>=13, CUDA>=12 (12 & 13), cuTENSOR>=2.0 with early actionable errors; harden CUDA finders #950 split: finder-layout PR)
• Modernize CUDA configure diagnostics and remove the stale legacy CUDA_*_LIBRARY/linkflags.tmp dead block — [build] CUDA configure output shows blank "CUDA Version"/"CUDA Toolkit Root" — uses legacy FindCUDA variables #949 (build: require GCC>=13, CUDA>=12 (12 & 13), cuTENSOR>=2.0 with early actionable errors; harden CUDA finders #950 split: diagnostics PR; build: require GCC>=13, CUDA>=12 (12 & 13), cuTENSOR>=2.0 with early actionable errors; harden CUDA finders #950's current diff fixes only the display half)
• Enforce CUDA/cuTENSOR version floors (CUDA ≥ 12, cuTENSOR ≥ 2.0) — [build] Decide supported CUDA toolkit under cuTENSOR >= 2.0 + cuQuantum >= 24.0 (CUDA 11? CUDA 13?) #962 (build: require GCC>=13, CUDA>=12 (12 & 13), cuTENSOR>=2.0 with early actionable errors; harden CUDA finders #950 split: version-policy PR, pending the [build] Decide supported CUDA toolkit under cuTENSOR >= 2.0 + cuQuantum >= 24.0 (CUDA 11? CUDA 13?) #962 decision)
• Correct the stale/incomplete compiling-options table in the install docs (missing USE_CUTENSOR/USE_CUQUANTUM/BACKEND_TORCH, wrong default install prefix) — ← open gap (untouched by build: require GCC>=13, CUDA>=12 (12 & 13), cuTENSOR>=2.0 with early actionable errors; harden CUDA finders #950/Reduce PyPI wheel size: exclude static libs/headers from the Python wheel #967)
• rpath-pin the installed CUDA extension to its build toolkit — [build] Installed CUDA extension is not rpath-pinned to the build toolkit; runtime loads system/apt CUDA runtime #948 ← open gap (decision-coupled to the Phase gate above)

Phase 2 — packaging & channels

• Document pip install cytnx / uv add cytnx as a first-class install path — ← open gap (docs; unblocked now that PR Reduce PyPI wheel size: exclude static libs/headers from the Python wheel #967 rewrites the C++-API docs)
• conda-forge channel story (move off the personal kaihsinwu channel) — reframed by, and pending, the packaging-model decision in Investigate CPU/CUDA wheel packaging strategy for PyPI, modeled on PyTorch and JAX #969

Phase 3 — GPU accelerators

• CUDA CI coverage and conda-forge GPU dependency packaging — reframed by, and pending, the packaging-model decision in Investigate CPU/CUDA wheel packaging strategy for PyPI, modeled on PyTorch and JAX #969

---

Posted by Claude Code on behalf of @pcchen

[IvanaGyro]

Here are some suggestions based on the investigation in the issue description.

Phase gate:

Both PyTorch and JAX styles need large refactoring in our code base. PyTorch style needs to guard all CUDA functions for users who only have CPU. JAX style needs us to separate all CUDA functions into another shared library. In long term, JAX style is more flexible for users. For short term, deploying two variants, which one for CPU only and one including CUDA, is the most easiest.

Phase 1,2,3

cuTENSOR, cuQuantum, and CUDA runtime should rely on dependency chain on PyPI or conda. We should not directly rely on cuQuantum, instead we should rely on only the subpackages we used.

[IvanaGyro]

BTW, I hope we can release package for Windows.