Choose one runtime.

PLATFORMS AND RELEASES

Check your platform.

Hyperfold 0.1.1 provides the prebuilt wheels below. Windows CUDA is a local source-build option and requires a system CUDA toolkit.

Wheels target standard CPython 3.11–3.14. PyPy, free-threaded CPython, musllinux, 32-bit systems, Intel macOS and Windows ARM64 are outside the release matrix. Prebuilt CUDA wheels target Linux x86_64 only. PyPI releases are wheel-only: pip cannot automatically fall back to a source distribution. Local builds use an explicit source checkout.

CPU selection

x86 wheels contain AVX2 and AVX-512 implementations and select once after checking CPU and operating-system support. Unsupported CPUs fail at import. Set HYPERFOLD_CPU_SIMD_RUNTIME=AVX2 before importing Hyperfold to force AVX2; the selection cannot change after initialisation. NEON builds accept AUTO or NEON. Different instruction sets may produce different reduction rounding. build_info() reports the compiled and selected implementations.

The macOS 14.0 deployment target is configured; minimum-OS runtime testing and a verified Windows version floor remain outstanding, as does Windows AVX-512 hardware verification.

QUICKSTART

Run a matrix operation.

The high-level functions accept ordinary framework arrays and return results in the same framework and on the same device.

import numpy as np
import hyperfold

a = np.array([[1, 2], [3, 4]], dtype=np.float32)
b = np.array([[5, 6], [7, 8]], dtype=np.float32)
product = hyperfold.matmul(a, b)

system = np.array([[4, 1 - 1j], [1 + 1j, 3]], dtype=np.complex64)
rhs = np.array([1 + 2j, 3 - 1j], dtype=np.complex64)
solution = hyperfold.solve(system, rhs)

Python sequences are accepted and infer float32 or complex64. Existing arrays retain their dtype and are never silently narrowed.

CUDA ARRAYS

Keep framework and device placement.

CuPy and PyTorch use DLPack interchange. Inputs must already be CUDA arrays on one device; Hyperfold does not perform implicit host/device transfers.

import cupy as cp
import torch
import hyperfold

x_cp = cp.arange(8, dtype=cp.float32)
y_cp = hyperfold.add(x_cp, x_cp)

x_pt = torch.arange(8, dtype=torch.float32, device="cuda")
y_pt = hyperfold.scale(x_pt, 2.0)

assert isinstance(y_cp, cp.ndarray)
assert isinstance(y_pt, torch.Tensor)

CUDA calls are synchronous when they return. Reductions stay on-device as zero-dimensional CuPy or PyTorch arrays.

LOCAL BUILDS

Build from a source checkout.

From a Hyperfold source checkout, choose one variant and build a wheel for the active interpreter. Native builds require CMake 3.30+ and a compatible C++23 compiler; CUDA builds also require CUDA Toolkit 13.0 or newer.

# CPU
bash scripts/python/build_wheels.sh cpu wheelhouse/cpu
python -m pip install wheelhouse/cpu/hyperfold-*.whl

# Or CUDA, in a separate environment
bash scripts/python/build_wheels.sh cuda wheelhouse/cuda
python -m pip install wheelhouse/cuda/hyperfold_cuda-*.whl

Local wheels are native test artefacts and are not repaired portable distributions.

WINDOWS CUDA · LOCAL BUILD

Compile the CUDA Python package on Windows.

On Windows AMD64, pip can build hyperfold-cuda from the packaging/cuda directory in a Hyperfold 0.1.1 source checkout. Use an x64 Visual Studio developer terminal with a CUDA-compatible MSVC toolchain, CMake 3.30+, standard CPython 3.11–3.14, CUDA Toolkit 13.0+ and a compatible NVIDIA driver. See NVIDIA's Windows installation guide for toolkit and compiler setup.

python -m venv .venv-cuda
.\.venv-cuda\Scripts\python.exe -m pip install --upgrade pip
.\.venv-cuda\Scripts\python.exe -m pip install ./packaging/cuda

pip compiles a wheel for the active interpreter and installs it. The NVIDIA pip runtime dependencies are Linux-only; Windows uses the system toolkit's CUDA runtime, cuBLAS, cuSOLVER and their dependencies. Register the directory containing those DLLs with os.add_dll_directory() before importing Hyperfold, and retain the returned handle while using the library. CuPy and PyTorch are optional and installed separately.

Windows CUDA is outside the prebuilt wheel and automated CUDA test matrices. This source-build route has not been verified by Windows CUDA CI.

TROUBLESHOOTING

Diagnose environment failures.

V1 LIMITS

Know the current boundary.

• 01

  Vectors and matrices only; no batching or broadcasting.

• 02

  No JAX framework preservation, futures, __array_ufunc__, or __array_function__ integration.

• 03

  CUDA calls complete synchronously before returning.

• 04

  matrix_power accepts non-negative signed 32-bit exponents.

• 05

  Python native extension wheels are specific to each CPython and platform combination. C ABI plug-ins must match the host ABI, operating system, architecture and runtime; they do not link to Python or Hyperfold.