Adjacent Difference#

cuda.coop.cutlass.adjacent_difference() subtracts a neighboring item from each item in a block tile. The result has the input’s dtype, extent, and blocked ownership. The input remains unchanged.

The neighbor may belong to another thread. Choose left or right to follow that dependency, then change valid_items or supply a value just outside the tile. The explorer uses eight teaching threads and small int32 values; every subtraction fits in that dtype.

With five valid inputs and predecessor zero, left differences of 2, 2, 5, 5, 9, 9, 9, 3 are 2, 0, 3, 0, 4, 9, 9, 3. The last three items are copied unchanged.

Left differences for five valid items. The invalid suffix is copied from the input into the returned payload.#

For direction="left", valid_items=5, tile_predecessor_item=0:

Position       0  1  2  3  4 | 5  6  7
Input          2  2  5  5  9 | 9  9  3
Left neighbor  0  2  2  5  5 | not used
Result         2  0  3  0  4 | 9  9  3
Input after    2  2  5  5  9 | 9  9  3

Reading the stages#

Flatten the blocked payloads in thread-rank order. With K items per thread, slot i of thread t has position t * K + i. Left Difference computes input[p] - input[p - 1]; Right Difference computes input[p] - input[p + 1]. Both subtract the neighbor from the current item.

The input row stays in place. The neighbor row shows the value each position reads, including reads across thread boundaries. The final row contains a new payload. Select any result to see its subtraction or the reason it copies the input.

At the tile edge, an omitted neighbor leaves the current input unchanged. tile_predecessor_item supplies the missing left neighbor; tile_successor_item supplies the missing right neighbor. Neither argument wraps around to the other end of the tile. These scalar boundary values must match the input dtype and agree across the block.

Every thread in the complete block must call the operation, including for partial tiles; warp groups are unsupported. The function infers dtype and per-thread extent from ThreadData. It accepts automatic scratch or an explicit TempStorage.

For a partial tile, valid_items must agree across the block. Only positions below that count compute a difference. Every later position copies its input, so those slots must also be initialized. A count of zero copies the entire tile. A count equal to the tile capacity processes the entire tile.

Right partial tiles do not accept tile_successor_item, even when the supplied count equals the capacity. The last valid item is copied unchanged. The explorer disables the boundary-value control for this combination, matching the API’s rejection of that CUB overload.

A complete neighbor example#

This CuTe example computes differences and head/tail flags while preserving the input. It reuses scratch with explicit synchronization policy.

@cute.kernel
def compare_neighbors(
    source: cute.Pointer,
    deltas: cute.Pointer,
    head_flags: cute.Pointer,
    tail_flags: cute.Pointer,
    items_per_thread: cutlass.Constexpr,
):
    block = coop.this_block()
    values = coop.load(block, source, items_per_thread=items_per_thread)
    scratch = coop.TempStorage(alignment=16, auto_sync=True)
    differences = coop.adjacent_difference(
        block, values, temp_storage=scratch
    )
    heads, tails = coop.discontinuity(
        block, values, mode="heads_and_tails", temp_storage=scratch
    )
    coop.store(block, deltas, differences)
    coop.store(block, head_flags, heads)
    coop.store(block, tail_flags, tails)

@cute.jit
def launch(
    source: cute.Pointer,
    deltas: cute.Pointer,
    head_flags: cute.Pointer,
    tail_flags: cute.Pointer,
    items_per_thread: cutlass.Constexpr,
):
    compare_neighbors(
        source, deltas, head_flags, tail_flags, items_per_thread
    ).launch(grid=1, block=128)

An inclusive sum of left differences reconstructs the sequence when the first delta is the first input value. Across block tiles, supply the preceding tile’s final source item as the left boundary. Keep global source and output buffers distinct so a writer cannot overwrite another block’s predecessor.