A user-friendly cupy interface over the
fastfields.dlpack nanobind bindings to the
fastfields-lib C++/CUDA library.
It mirrors the numpy-style fastfields API but operates on cupy arrays in CUDA
device memory. cupy arrays expose __dlpack__, so the bindings share device
memory with them at zero copy.
pip install fastfields-cupy # pulls fastfields-dlpack + fastfields-helpers
pip install "fastfields-cupy[cupy]"# also install a CUDA 12.x cupy buildcupy is not a hard dependency because the correct wheel depends on your
CUDA toolkit. Install cupy-cuda12x, cupy-cuda11x, ... to match your system.
importcupyascpimportfastfields.cupyasffc# Euclidean distance transform along the last axis (functional).x=cp.array([[0, cp.inf, cp.inf, 0, cp.inf]], dtype=cp.float32)
d=ffc.dt_euclidean(x) # new array; x is untouchedffc.dt_euclidean_(x) # in-place variant# Compact-symmetric mat-vec: out = H @ vout=ffc.sym_matvec(hessian, v)- Functional wrappers (
dt_euclidean,sym_matvec,resample, ...) take cupy arrays, allocate their outputs, and return cupy arrays. Inputs are made C-contiguous and must befloat32/float64. - Trailing-underscore wrappers (
dt_euclidean_,sym_solve_, ...) operate in place / through the caller's output and return it. They require C-contiguous arrays and never silently copy.
cupy queues work on its current CUDA stream. Every wrapper forwards
cupy.cuda.get_current_stream().ptr to the binding's stream argument, so the
kernels are ordered correctly with respect to surrounding cupy operations. To
target a specific stream:
s=cp.cuda.Stream()
withs:
d=ffc.dt_euclidean(x) # runs on stream `s`Runtime tests require a GPU and cupy; they are skipped otherwise:
python -m pytest tests/ -q