braketware hyperfold

PYTHON REFERENCE

Package utilities.

These package-level interfaces report build capabilities, expose the plug-in headers, describe failures, and query CUDA availability. Numerical functions are listed in the operation catalogue.

ERRORS

Distinguish inputs from backend failures.

Python validates ranks, shapes, dtypes, frameworks, devices, output buffers and context options before execution. Those failures use TypeError or ValueError. Allocation failures use MemoryError; recognised numerical factorisation and convergence failures use numpy.linalg.LinAlgError.

hyperfold.BackendError

BackendError(message, *, operation="", reason="backend_failure", device=None, native_status=None)

Reports dispatch, backend, CUDA runtime, device-scope, plug-in, or unsupported-signature failures that are not mapped to a numerical linear-algebra error.

AttributeMeaning
operationThe operation or boundary that failed.
reasonA stable machine-readable reason when the backend provides one.
deviceThe CUDA device involved, or None.
native_statusThe native status code when available, or None.

BUILD METADATA

Inspect the installed variant.

hyperfold.available_backends

available_backends() -> tuple[str, ...]

Returns the native backends compiled into the active wheel. This describes compiled capability rather than current device availability.

hyperfold.build_info

build_info() -> dict[str, Any]

Returns a fresh dictionary containing the Hyperfold version and native build feature information. Hyperfold 0.1.1 exposes the fields below.

FieldMeaning
versionThe native Hyperfold version.
cudaWhether CUDA support was compiled; this does not report device availability.
cpu_simdThe selected CPU implementation: AVX2, AVX512 or NEON.
cpu_simd_compiledA string listing the compiled CPU implementations.
cuda_architecturesThe compiled CUDA architecture list as a string, or an empty string for CPU-only builds.
nanobind_majorThe major version of nanobind used to build the Python extension.

x86 wheels select AVX2 or AVX-512 at runtime. Set HYPERFOLD_CPU_SIMD_RUNTIME=AVX2 before import to force AVX2; selection is fixed after initialisation. See platform availability and CPU selection.

hyperfold.get_include

get_include() -> str

Returns the installed include root containing hyperfold/plugin/abi.h and hyperfold/plugin/sdk.h. Use it when compiling a binary plug-in against a Python wheel.

hyperfold.__version__

__version__: str

The native Hyperfold version reported by the installed extension.

import hyperfold

print(hyperfold.__version__)
print(hyperfold.available_backends())
print(hyperfold.build_info())
print(hyperfold.get_include())

CUDA UTILITIES

Query runtime availability.

Importing hyperfold.cuda is safe for either distribution. These functions query the installed build and visible runtime; they do not select a device for later operations.

hyperfold.cuda.is_available

is_available() -> bool

Returns whether the installed wheel contains a usable CUDA backend.

hyperfold.cuda.device_count

device_count() -> int

Returns the number of CUDA devices visible to Hyperfold.

import hyperfold

if hyperfold.cuda.is_available():
    print(f"{hyperfold.cuda.device_count()} CUDA device(s)")
    context = hyperfold.Context(cuda_devices=0)