warp.utils.array_scan#

warp.utils.array_scan(in_array, out_array, inclusive=True, temp_storage=None)[source]#

Perform a scan (prefix sum) operation on an array.

This function computes the inclusive or exclusive scan of the input array and stores the result in the output array. The scan operation computes a running sum of elements in the array. Vector types are scanned component-wise.

During CPU graph capture, or CUDA graph capture with apic=True, int32, float32, int64, and float64 scalar and vector scans are recorded into the API Capture (APIC) operation stream, including positively-strided (non-contiguous) 1D arrays. Non-empty, negatively-strided arrays raise NotImplementedError; run those scans outside the captured region.

On CUDA devices, the scan allocates temporary storage and frees it before returning unless temp_storage is given. A caller-provided buffer is only accessed by work enqueued on the current stream of in_array.device, in stream order. Scans that run one after another on the same stream may share one buffer, but scans that can run concurrently, such as scans on different streams, need separate buffers. A CUDA graph that captures the scan refers to the buffer’s address, so keep the buffer alive and do not reallocate it for as long as the graph may be launched. A graph saved with warp.capture_save() does not store the buffer; warp.capture_load() gives the loaded graph its own scan storage, including for scans in conditional bodies.

Parameters:
  • in_array (array) – Input array to scan. Must be a scalar or vector type with scalar type int32, int64, float32, or float64.

  • out_array (array) – Output array to store scan results. Must match input array type and size.

  • inclusive (bool) – If True, performs an inclusive scan (includes current element in sum). If False, performs an exclusive scan (excludes current element).

  • temp_storage (array | None) – Optional caller-provided temporary storage for CUDA scans. If None, the scan allocates its temporary storage and frees it before returning. Otherwise, this must be a contiguous array on the same device as in_array holding at least array_scan_temp_storage_size() bytes; its data type does not matter and its contents are overwritten. The scan then neither allocates nor frees memory, which makes it usable in warp.capture_if() and warp.capture_while() bodies and in CUDA graph captures that Warp did not start. CPU scans do not use it.

Raises:
  • RuntimeError – If array storage devices don’t match, if storage size is insufficient, if data types are unsupported, or if temp_storage is invalid or too small.

  • NotImplementedError – If called with a non-empty, negatively-strided array during CPU graph capture or CUDA graph capture with apic=True.

Return type:

None