---
library_name: kernels
license: apache-2.0
tags:
- kernel
- webgpu
- wgsl
---
# com.microsoft.VarlenCausalConvWithState

`com.microsoft`  ·  ONNX Runtime contrib operator  ·  contrib since_version 1

## Description

Stateful causal depthwise convolution over packed token-major variable-length sequences, without reads across sequence boundaries. `initial_state` carries preceding raw samples and `final_state` is fully written. At positive `state_update_capacity`, `capture_count` selects a clamped prefix of raw input tokens for compact `state_update`; inactive slots are zero. SiLU and Swish are aliases. This implementation supports float16 and float32 with float32 accumulation; bfloat16 is not implemented.

See the [ONNX Runtime `VarlenCausalConvWithState` contrib-operator spec](https://github.com/microsoft/onnxruntime/blob/main/docs/ContribOperators.md#com.microsoft.VarlenCausalConvWithState) for the reference semantics.

## Inputs

| Name | Bind key | Logical dtype | WebGPU storage | Rank | Shape | Description | Presence |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `input` | `inputT` | `T` | same as logical dtype | `2` | — | Token-major packed input with shape `(total_tokens, channels)`. | required |
| `weight` | `weightT` | `T` | same as logical dtype | `3` | — | Depthwise kernel with shape `(channels, 1, kernel_size)`. | required |
| `cumulative_sequence_length` | `cumulativeSequenceLengthT` | `M` | `int32` | `1` | — | Exclusive prefix sums with shape `(batch_size + 1)`; sequence `i` owns tokens `[cum[i], cum[i + 1])`. | required |
| `bias` | `biasT` | `T` | same as logical dtype | `1` | — | Optional per-channel bias with shape `(channels,)`. In an ONNX graph an omitted bias must still occupy input index 3 as an empty name so `initial_state` stays at index 4. | optional |
| `initial_state` | `initialStateT` | `T` | same as logical dtype | `3` | — | Required committed carry state with shape `(batch_size, channels, kernel_size - 1)`, holding the raw samples immediately preceding this call. | required |
| `capture_count` | `captureCountT` | `M` | `int32` | `1` | — | Optional int32 vector with shape `(batch_size)`. Required exactly when `state_update_capacity` is positive; each value is clamped to `[0, min(state_update_capacity, sequence_length)]`. | optional |

## Outputs

| Name | Bind key | Logical dtype | Rank | Shape | Description | Presence |
| --- | --- | --- | --- | --- | --- | --- |
| `output` | `outputT` | `T` | same as `input` | same as `input` | Convolution output with the same shape as `input`. | required |
| `final_state` | `finalStateT` | `T` | `3` | derived; see description | State after each sequence's final token, shape `(batch_size, channels, kernel_size - 1)`. Always fully written. | required |
| `state_update` | `stateUpdateT` | `T` | `3` | derived; see description | Optional compact transition values with shape `(batch_size, state_update_capacity, channels)`. Active slots contain the original local input tokens and all other slots are zero. | optional |

## Attributes

Default values (overridable per request):

| Attribute | Default | Description |
| --- | --- | --- |
| `activation` | `"none"` | Fused activation applied after convolution and bias. One of `none`, `silu`, or `swish`; the standard default is `none`. |
| `state_update_capacity` | `0` | Static number of compact per-request prefix transition values to expose, in `[0, 8]`. The standard default is 0. |

## Type constraints

| Variable | Allowed dtypes |
| --- | --- |
| `T` | `float32`, `float16` |
| `M` | `int32` |

## Files

- [`metadata.json`](build/webgpu/metadata.json) — kernel metadata (id, digests, provenance)
- [`manifest.json`](build/webgpu/manifest.json) — the op contract (source of truth)
- [`test.json`](build/webgpu/test.json) — correctness cases
- [`bench.json`](build/webgpu/bench.json) — benchmark + tuning cases
- [`varlen-causal-conv-stream.wgsl.jinja`](build/webgpu/varlen-causal-conv-stream.wgsl.jinja)
- [`varlen-causal-conv.wgsl.jinja`](build/webgpu/varlen-causal-conv.wgsl.jinja)
- [`varlen-state-update.wgsl.jinja`](build/webgpu/varlen-state-update.wgsl.jinja)

## Use with `@huggingface/kernels`

The loader derives every required output's shape and logical dtype from the manifest contract and this call.
It then allocates the result tensors automatically.

The `version: 1` option selects the published kernel contract; it is independent of any operator opset, contrib `since_version`, or model version.

Replace each `*Data` placeholder with a typed array containing the corresponding input data.

```js
import { getKernel } from "@huggingface/kernels";

const kernel = await getKernel("webgpu-kernels/com.microsoft.VarlenCausalConvWithState", { version: 1 });
const { outputT, finalStateT } = await kernel({
  inputT: { data: inputTData, shape: [5, 6] },
  weightT: { data: weightTData, shape: [6, 1, 4] },
  cumulativeSequenceLengthT: { data: cumulativeSequenceLengthTData, shape: [3] },
  initialStateT: { data: initialStateTData, shape: [2, 6, 3] },
});
```