Experimental CUDA execution

Install pipewhy[cuda] for pipewhy.model.cuda.CudaIntegerView. This experimental view borrows a provider’s existing CUDA Array Interface v3 integer allocation in the current context. It checks dtype, layout, allocation bounds, device/context, ownership and producer synchronization. It preserves the device pointer and requests no payload copy. Masks, managed memory, noncontiguous/structured storage and host objects raise explicit errors. Keep the view and mutable aliases stable until consuming work finishes.

Importing the package or view adds no CUDA binding or Numba CUDA imports. cuda_availability() explicitly queries driver readiness and returns a reason and diagnostic; unknown device counts remain None. Readiness does not qualify GPU fingerprints. The extra supplies the qualified driver bindings, compiler and native libraries. Core/reference installs still require none of these dependencies.

pipewhy.fingerprint.cuda.record_contributions_from_host(batch, context) validates a host C2 RecordBatch, explicitly uploads its inputs, hashes on the GPU, synchronizes and downloads four uint64 limbs per record. Ordered mode accepts the original global start. The returned CudaResult contains the owned limb array and requested upload/download/device-buffer byte counts. Counts exclude compiler, context and private kernel scratch allocations. Defaults bound each batch to 65,536 records and 1,048,576 words; oversized or malformed batches fail before GPU entry. Inputs must stay stable until completion. Native failures trigger cleanup synchronization and retain their original causes; cleanup failures remain visible. Simulation is refused by the public runtime. This API performs explicit transfers; it does not consume CudaIntegerView or promise zero-copy hashing.

fingerprint_batch_from_host(batch, context) additionally reduces contributions on the GPU and returns CudaResult[FingerprintState]. It downloads only the four sum limbs for a nonempty batch, preserving the exact record count and ordered range. The same bounded validation and transfer receipts apply. Intermediate device buffers stay owned until synchronization; their allocations are included in the receipt.

fingerprint_batches_from_host(batches, context) consumes a bounded stream once, finishing each batch before requesting the next. It composes each GPU-reduced state with C3’s canonical host operator, preserving counts and global ordered positions. Its transfer/allocation totals count requests across batches, not peak memory. Even an empty stream checks CUDA readiness; source failures propagate without a successful partial result.

Real borrowing and contributions are verified on the Windows GTX 1660 target. Both CPU and CUDA extras now select NumPy 2.4.6: Numba-CUDA 0.30.4 fails to import with NumPy 2.5.4 despite a successful installation and pip check. Both extras use the same Numba compiler family.

scan --backend cuda explicitly uploads the fixture’s host batches and uses the GPU stream API. Readiness is checked before dataset reads, so an unavailable extra, driver or compiler fails even when source observations would all be unavailable. Errors exit 3 without a successful partial snapshot or reference fallback. --backend auto keeps this host-resident source on the host: it selects CPU when the Numba provider is discoverable and otherwise reference. An installed CPU provider that fails during execution raises its error. Auto does not query CUDA or silently upload data. Captures record the resolved backend (reference, cpu or cuda); historical read commands need no GPU. Reference remains the default. These entry points accept host C2 batches; borrowed device C2 framing/execution is not exposed by them. See blueprint/CUDA_CONTRACT.txt for the tested environment, boundaries and evidence. blueprint/CUDA_ACCEPTANCE.txt maps the real-device, installed-package and persisted CPU/GPU slice checks; blueprint/CUDA_BASELINE.txt records the scoped timing baseline.