ai.onnx.Loop

ai.onnx · internal tensor lowering (non-standard) · reviewed against ONNX opset 25

Description

Support status: the standard ONNX Loop control-flow operator is not implemented because standalone kernel packages cannot carry or execute its body graph. This internal lowering performs one fixed recurrence—adding step to a rank-1 loop-carried tensor for up to M iterations while writing a dense scan tensor; step is not an ONNX Loop input, and this lowering must not be treated as ONNX Loop.

See the standard ONNX Loop spec for the contract this internal lowering does not implement.

Inputs

Name	Bind key	Logical dtype	Rank	Shape	Description	Presence
`M`	`m`	`I`	—	—	Required uint32 trip-count limit encoded as either a scalar tensor or a one-element rank-1 tensor. The lowering executes at most `min(M, scan_output.shape[0])` iterations.	required
`cond`	`cond`	`B`	—	—	Required initial condition encoded as either a scalar tensor or a one-element rank-1 tensor. A false value executes zero iterations; a true value permits all iterations selected by `M`. This fixed lowering does not update the condition inside the loop.	required
`v_initial`	`v_initial`	`T`	`1`	—	Initial rank-1 loop-carried state of shape `[dim]`.	required
`step`	`step`	`T`	`1`	—	Implementation-specific rank-1 increment of shape `[dim]`, added elementwise to the state on every executed iteration. This is not a standard ONNX `Loop` input.	required

Outputs

Name	Bind key	Logical dtype	Rank	Shape	Description	Presence
`v_final`	`v_final`	`T`	`1`	same as `v_initial`	Final rank-1 state of shape `[dim]` after the executed additions.	required
`scan_output`	`scan_output`	`T`	`2`	—	Dense tensor of shape `[scan_steps, dim]`. Each executed row contains the updated state for that iteration; rows beyond the executed trip count are zero-filled.	required

Type constraints

Variable	Allowed dtypes
`T`	`float32`
`I`	`uint32`
`B`	`uint32`, `bool`

Files

metadata.json — kernel metadata (id, digests, provenance)
manifest.json — the op contract (source of truth)
test.json — correctness cases
bench.json — benchmark + tuning cases
loop-add-step.wgsl.jinja

Use with `@huggingface/kernels`

The loader automatically allocates outputs whose metadata it can derive from the manifest contract and this call.

The explicit outputs entries provide shape and logical dtype metadata for the results listed below:

scan_output

Each entry either requests an optional result or supplies metadata that cannot be inferred from the inputs.

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.

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

const kernel = await getKernel("webgpu-kernels/ai.onnx.Loop", { version: 1 });
// Explicit destinations request optional results or supply metadata that cannot be inferred.
const { v_final, scan_output } = await kernel({
  m: { data: mData, shape: [1] },
  cond: { data: condData, shape: [1] },
  v_initial: { data: v_initialData, shape: [1] },
  step: { data: stepData, shape: [1] },
}, {
  outputs: { scan_output: { shape: [1, 1], dtype: "float32" } },
});

Downloads last month: -

kernel

webgpu

wgsl

apache-2.0

WebGPU

Requires WebGPU support. See the compatibility table.