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.
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.