vibespatial.io.kvikio_reader¶

Accelerated file-to-device reader using kvikio.

When kvikio is installed, reads files directly to GPU device memory through parallel POSIX threads with pinned bounce buffers. No GDS (GPU Direct Storage) is required — kvikio falls back to buffered IO automatically.

When kvikio is not installed, falls back to np.fromfile + cp.asarray with a manual >2 GiB chunking workaround for CuPy limitations.

Attributes¶

cp

Classes¶

FileReadResult

Result of reading a file to device memory.

Functions¶

`read_file_to_device`(→ FileReadResult)	Read a file directly into a CuPy device array.
`has_kvikio`(→ bool)	Return True if kvikio is available for accelerated file reads.

Module Contents¶

vibespatial.io.kvikio_reader.cp = None¶

class vibespatial.io.kvikio_reader.FileReadResult¶

Result of reading a file to device memory.

Attributes¶

device_bytes: Device-resident uint8 array containing the file contents.
host_bytes: Host-resident uint8 array, or None when kvikio was used (the caller should read separately if needed — the OS page cache will be warm from the kvikio buffered read).

device_bytes: cupy.ndarray¶

host_bytes: numpy.ndarray | None¶

vibespatial.io.kvikio_reader.read_file_to_device(path: pathlib.Path, file_size: int) → FileReadResult¶

Read a file directly into a CuPy device array.

When kvikio is available, uses parallel POSIX reads through pinned bounce buffers (configurable via KVIKIO_NTHREADS). The read uses buffered IO by default, which populates the OS page cache as a side effect — a subsequent np.fromfile for the same path will hit warm cache.

When kvikio is not installed, falls back to np.fromfile followed by cp.asarray with chunking for files larger than 2 GiB. The host array is returned alongside the device array so callers can reuse it without a redundant second file read.

Parameters¶

path: Path to the file to read.
file_size: Size of the file in bytes. Passed explicitly to avoid a redundant stat call when the caller already knows it.

Returns¶

FileReadResult: .device_bytes is the device-resident uint8 array. .host_bytes is the host numpy array when the fallback path was used, or None when kvikio handled the transfer.

vibespatial.io.kvikio_reader.has_kvikio() → bool¶: Return True if kvikio is available for accelerated file reads.