sync 2e7068faf55e

Browse files

Files changed (7) hide show

README.md +65 -0
build/webgpu/bench.json +43 -0
build/webgpu/manifest.json +84 -0
build/webgpu/metadata.json +19 -0
build/webgpu/test.json +187 -0
build/webgpu/unary-scalar.wgsl.jinja +37 -0
build/webgpu/unary-vec4.wgsl.jinja +30 -0

README.md CHANGED Viewed

@@ -1,3 +1,68 @@
 ---
 license: apache-2.0
 ---

 ---
+library_name: kernels
 license: apache-2.0
+tags:
+- kernel
+- webgpu
+- wgsl
 ---
+# ai.onnx.Elu
+`ai.onnx`  ·  standard ONNX operator  ·  ONNX opset ≥ 6
+## Description
+Applies the Exponential Linear Unit activation elementwise: `f(x) = x` for `x >= 0`, and `f(x) = alpha * (exp(x) - 1)` for `x < 0`. The `alpha` coefficient controls the saturation value for negative inputs.
+See the [ONNX `Elu` spec](https://onnx.ai/onnx/operators/onnx__Elu.html) for the reference semantics.
+## Inputs
+| Name | Bind key | Logical dtype | Rank | Shape | Description | Presence |
+| --- | --- | --- | --- | --- | --- | --- |
+| `X` | `x` | `T` | — | — | Values transformed elementwise by the ELU activation. | required |
+## Outputs
+| Name | Bind key | Logical dtype | Rank | Shape | Description | Presence |
+| --- | --- | --- | --- | --- | --- | --- |
+| `Y` | `y` | `T` | same as `X` | same as `X` | Output tensor with ELU applied elementwise; same shape as X. | required |
+## Attributes
+Default values (overridable per request):
+| Attribute | Default | Description |
+| --- | --- | --- |
+| `alpha` | `1` | Scaling coefficient applied to the exponential term for negative inputs; defaults to `1.0`. |
+## Type constraints
+| Variable | Allowed dtypes |
+| --- | --- |
+| `T` | `float32`, `float16` |
+## 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
+- [`unary-scalar.wgsl.jinja`](build/webgpu/unary-scalar.wgsl.jinja)
+- [`unary-vec4.wgsl.jinja`](build/webgpu/unary-vec4.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/ai.onnx.Elu", { version: 1 });
+const { y } = await kernel({ x: { data: xData, shape: [3, 4, 5] } });
+```

build/webgpu/bench.json ADDED Viewed

	@@ -0,0 +1,43 @@

+{
+  "op": "ai.onnx.Elu",
+  "cases": [
+    {
+      "name": "1m_f32",
+      "inputs": { "x": { "dtype": "float32", "shape": [1048576] } },
+      "outputs": { "y": { "dtype": "float32", "shape": [1048576] } }
+    },
+    {
+      "name": "elu-f32-1m",
+      "preset": "smoke",
+      "vars": { "dtype": "float32", "count": 1048576 },
+      "inputs": {
+        "x": { "shape": [1048576], "dtype": "float32", "dist": "uniform", "seed": 5101, "scale": 4, "offset": -2 }
+      },
+      "outputs": { "y": { "shape": [1048576], "dtype": "float32" } },
+      "bench": {
+        "primary": true,
+        "metrics": [{ "type": "bandwidth", "value": "args.count * dtypeBytes(args.dtype) * 2" }]
+      }
+    },
+    {
+      "name": "elu-f32-1m-scalar-fallback",
+      "preset": "smoke",
+      "vars": { "dtype": "float32", "count": 1048577 },
+      "inputs": {
+        "x": { "shape": [1048577], "dtype": "float32", "dist": "uniform", "seed": 5102, "scale": 4, "offset": -2 }
+      },
+      "outputs": { "y": { "shape": [1048577], "dtype": "float32" } },
+      "bench": { "metrics": [{ "type": "bandwidth", "value": "args.count * dtypeBytes(args.dtype) * 2" }] }
+    },
+    {
+      "name": "elu-f16-1m",
+      "preset": "smoke",
+      "vars": { "dtype": "float16", "count": 1048576 },
+      "inputs": {
+        "x": { "shape": [1048576], "dtype": "float16", "dist": "uniform", "seed": 5103, "scale": 4, "offset": -2 }
+      },
+      "outputs": { "y": { "shape": [1048576], "dtype": "float16" } },
+      "bench": { "metrics": [{ "type": "bandwidth", "value": "args.count * dtypeBytes(args.dtype) * 2" }] }
+    }
+  ]
+}

build/webgpu/manifest.json ADDED Viewed

	@@ -0,0 +1,84 @@

+{
+  "domain": "ai.onnx",
+  "name": "Elu",
+  "sinceVersion": 6,
+  "description": "Applies the Exponential Linear Unit activation elementwise: `f(x) = x` for `x >= 0`, and `f(x) = alpha * (exp(x) - 1)` for `x < 0`. The `alpha` coefficient controls the saturation value for negative inputs.",
+  "inputs": [{ "role": "X", "dtype": "T", "description": "Values transformed elementwise by the ELU activation." }],
+  "outputs": [
+    {
+      "role": "Y",
+      "dtype": "T",
+      "rank": "ranks.X",
+      "description": "Output tensor with ELU applied elementwise; same shape as X.",
+      "shape": "shapes.X"
+    }
+  ],
+  "attributes": { "alpha": 1 },
+  "attributeDescriptions": {
+    "alpha": "Scaling coefficient applied to the exponential term for negative inputs; defaults to `1.0`."
+  },
+  "typeConstraints": { "T": ["float32", "float16"] },
+  "args": {
+    "x": { "kind": "tensor", "semantic": "X", "role": "input" },
+    "y": { "kind": "tensor", "semantic": "Y", "role": "output" }
+  },
+  "tunables": { "WORKGROUP_SIZE": 256 },
+  "constants": { "scalar": "dtypes.T", "usesF16": "dtypes.T == \"f16\"" },
+  "variants": [
+    {
+      "id": "same_layout_vec4",
+      "when": ["numel(shapes.X) > 0", "numel(shapes.X) % 4 == 0", "numel(shapes.X) == numel(shapes.Y)", "f16Ok(dtypes.T)"],
+      "constants": { "vectorScalar": "\"vec4<\" ~ dtypes.T ~ \">\"" },
+      "passes": [
+        {
+          "id": "main",
+          "name": "Elu.vec4",
+          "source": { "shader": "unary-vec4.wgsl.jinja", "inputs": { "op": "\"elu\"", "alpha": "attrs.alpha" } },
+          "bindings": [
+            { "name": "x", "arg": "x", "buffer": { "type": "read-only-storage" }, "elementType": "$vectorScalar" },
+            { "name": "y", "arg": "y", "buffer": { "type": "storage" }, "elementType": "$vectorScalar" },
+            {
+              "name": "params",
+              "semantic": "kernel.params",
+              "buffer": { "type": "uniform" },
+              "struct": {
+                "name": "Params",
+                "fields": [{ "name": "count", "type": "u32", "value": "numel(shapes.y) / 4" }]
+              }
+            }
+          ],
+          "dispatch": { "threads": "numel(shapes.Y) / 4", "workgroupSize": "tunables.WORKGROUP_SIZE" }
+        }
+      ],
+      "priority": 20
+    },
+    {
+      "id": "elementwise",
+      "when": "numel(shapes.X) == numel(shapes.Y) and (f16Ok(dtypes.T))",
+      "passes": [
+        {
+          "id": "main",
+          "name": "Elu",
+          "source": { "shader": "unary-scalar.wgsl.jinja", "inputs": { "op": "\"elu\"", "itemsPerInvocation": 4 } },
+          "bindings": [
+            { "name": "x", "arg": "x", "buffer": { "type": "read-only-storage" }, "elementType": "$scalar" },
+            { "name": "y", "arg": "y", "buffer": { "type": "storage" }, "elementType": "$scalar" },
+            {
+              "name": "params",
+              "semantic": "kernel.params",
+              "buffer": { "type": "uniform" },
+              "struct": {
+                "name": "Params",
+                "fields": [
+                  { "name": "count", "type": "u32", "value": "numel(shapes.y)" },
+                  { "name": "alpha", "type": "f32", "value": "attrs.alpha" }
+                ]
+              }
+            }
+          ],
+          "dispatch": { "threads": "ceilDiv(numel(shapes.Y), 4)", "workgroupSize": "tunables.WORKGROUP_SIZE" }
+        }
+      ]
+    }
+  ]
+}

build/webgpu/metadata.json ADDED Viewed

	@@ -0,0 +1,19 @@

+{
+  "name": "ai.onnx.Elu",
+  "id": "_ai_onnx_elu_webgpu_e27eb6b",
+  "version": 1,
+  "license": "Apache-2.0",
+  "backend": { "type": "webgpu" },
+  "digest": {
+    "algorithm": "sha256",
+    "files": {
+      "bench.json": "Fk685NfBNB1Zgf3q/ubBERo+pUczrEG/VeM9wSAtSok=",
+      "manifest.json": "JjDQbSvDifYG9piBDzIk8VmUoutDLm+HypEnzQnbcFE=",
+      "test.json": "PyjZAriKI7qWc4jh94V9Fm13hBYUuT9eK5Xlqeu9/24=",
+      "unary-scalar.wgsl.jinja": "jIfgc/qPA0E/qtbjHrzlkPXrKcr5NTj6MdZCGS4hk1g=",
+      "unary-vec4.wgsl.jinja": "NsfNFarG5uL16oqVeYJMOzArQ8At8c6otRbQZ697x6g="
+    }
+  },
+  "provenance": { "kernel": { "sha": "2e7068faf55e7f43df740015f6d1ee49391a41c5", "dirty": false } },
+  "webgpu": { "manifestSpec": "1.0", "specialized": true, "opPath": "ops/ai.onnx.Elu" }
+}

build/webgpu/test.json ADDED Viewed

	@@ -0,0 +1,187 @@

+{
+  "op": "ai.onnx.Elu",
+  "fixtureArrays": {
+    "onnx_backend_input_x": [1.764052391052246, 0.40015721321105957, 0.978738009929657, 2.2408931255340576, 1.8675580024719238, -0.9772778749465942, 0.9500884413719177, -0.15135720372200012, -0.10321885347366333, 0.4105985164642334, 0.14404356479644775, 1.4542734622955322, 0.7610377073287964, 0.12167501449584961, 0.44386324286460876, 0.3336743414402008, 1.4940791130065918, -0.2051582634449005, 0.3130677044391632, -0.8540957570075989, -2.5529897212982178, 0.653618574142456, 0.8644362092018127, -0.7421650290489197, 2.269754648208618, -1.4543657302856445, 0.04575851559638977, -0.18718385696411133, 1.5327792167663574, 1.4693588018417358, 0.154947429895401, 0.37816253304481506, -0.8877857327461243, -1.980796456336975, -0.34791216254234314, 0.15634897351264954, 1.2302906513214111, 1.202379822731018, -0.38732680678367615, -0.302302747964859, -1.0485529899597168, -1.420017957687378, -1.7062702178955078, 1.950775384902954, -0.5096521973609924, -0.4380742907524109, -1.2527953386306763, 0.7774903774261475, -1.6138978004455566, -0.21274028718471527, -0.8954665660858154, 0.38690251111984253, -0.5108051300048828, -1.18063223361969, -0.02818222902715206, 0.4283318817615509, 0.06651721894741058, 0.30247190594673157, -0.6343221068382263, -0.3627411723136902]
+  },
+  "cases": [
+    {
+      "name": "f32_values",
+      "attrs": { "alpha": 0.5 },
+      "inputs": {
+        "x": {
+          "dtype": "float32",
+          "shape": [6],
+          "data": { "kind": "values", "values": [-3.0, -1.0, 0.0, 0.5, 1.0, 3.0] }
+        }
+      },
+      "outputs": { "y": { "dtype": "float32", "shape": [6], "tolerance": 0.000001 } }
+    },
+    {
+      "name": "f32_non_finite_and_saturation_edges",
+      "attrs": { "alpha": 0.5 },
+      "inputs": {
+        "x": {
+          "dtype": "float32",
+          "shape": [7],
+          "data": { "kind": "values", "values": ["-Infinity", -1000.0, 0.0, 0.0, 1000.0, "Infinity", "NaN"] }
+        }
+      },
+      "outputs": { "y": { "dtype": "float32", "shape": [7], "tolerance": 0.000001, "allowNaN": true } }
+    },
+    {
+      "name": "f32_negative_subnormal_expm1_tail_gpu_gap",
+      "skipGpu": {
+        "category": "permanent",
+        "reason": "Portable WGSL floating-point semantics do not guarantee preservation of the subnormal values required by this fixture. Backend evidence: WebGPU/Metal flushes subnormals to zero (f32 and f16); the kernel cannot preserve denormal inputs/outputs bit-exactly."
+      },
+      "provenance": {
+        "source": "onnxruntime/test/providers/cpu/activation/activation_op_test.cc",
+        "test": "ActivationOpTest.Elu",
+        "notes": "ORT CPU rounds alpha * (exp(x) - 1) to zero for tiny negative inputs; current WebGPU leaks the original subnormal through."
+      },
+      "attrs": { "alpha": 0.5 },
+      "inputs": {
+        "x": {
+          "dtype": "float32",
+          "shape": [4],
+          "data": { "kind": "values", "values": [-1e-39, -1e-40, 1e-40, 1e-39] }
+        }
+      },
+      "outputs": { "y": { "dtype": "float32", "shape": [4], "tolerance": 1e-43 } }
+    },
+    {
+      "name": "f32_near_zero_negative_expm1_cancellation",
+      "provenance": {
+        "source": "onnxruntime/test/providers/cpu/activation/activation_op_test.cc",
+        "test": "ActivationOpTest.Elu",
+        "notes": "Valid normal-range ELU cancellation edge: exp(x) - 1 must preserve small negative values near zero, not round them to a coarser f32 exp step."
+      },
+      "attrs": { "alpha": 0.1 },
+      "inputs": {
+        "x": {
+          "dtype": "float32",
+          "shape": [4],
+          "data": { "kind": "values", "values": [-1e-7, -5e-7, -0.000001, -0.00001] }
+        }
+      },
+      "outputs": { "y": { "dtype": "float32", "shape": [4], "tolerance": 3e-9 } }
+    },
+    {
+      "name": "f32_negative_subnormal_expm1_tail_scalar_gpu_gap",
+      "skipGpu": {
+        "category": "permanent",
+        "reason": "Portable WGSL floating-point semantics do not guarantee preservation of the subnormal values required by this fixture. Backend evidence: WebGPU/Metal flushes subnormals to zero (f32 and f16); the kernel cannot preserve denormal inputs/outputs bit-exactly."
+      },
+      "provenance": {
+        "source": "onnxruntime/test/providers/cpu/activation/activation_op_test.cc",
+        "test": "ActivationOpTest.Elu",
+        "notes": "Scalar-path companion: tiny negative inputs round the expm1 branch to zero while positive subnormals pass through."
+      },
+      "attrs": { "alpha": 0.5 },
+      "inputs": {
+        "x": { "dtype": "float32", "shape": [3], "data": { "kind": "values", "values": [-1e-40, 0.0, 1e-40] } }
+      },
+      "outputs": { "y": { "dtype": "float32", "shape": [3], "tolerance": 1e-43 } }
+    },
+    {
+      "name": "f32_near_zero_negative_expm1_cancellation_scalar",
+      "provenance": {
+        "source": "onnxruntime/test/providers/cpu/activation/activation_op_test.cc",
+        "test": "ActivationOpTest.Elu",
+        "notes": "Scalar-path companion for the normal-range ELU cancellation edge."
+      },
+      "attrs": { "alpha": 0.1 },
+      "inputs": {
+        "x": { "dtype": "float32", "shape": [3], "data": { "kind": "values", "values": [-1e-7, -5e-7, -0.000001] } }
+      },
+      "outputs": { "y": { "dtype": "float32", "shape": [3], "tolerance": 3e-9 } }
+    },
+    {
+      "name": "f16_values",
+      "attrs": { "alpha": 1.25 },
+      "inputs": {
+        "x": {
+          "dtype": "float16",
+          "shape": [7],
+          "data": { "kind": "values", "values": [-8.0, -2.0, -0.25, 0.0, 0.25, 2.0, 8.0] }
+        }
+      },
+      "outputs": { "y": { "dtype": "float16", "shape": [7], "tolerance": 0.001 } }
+    },
+    {
+      "name": "ort_alpha_0_1_activation_extremes",
+      "provenance": {
+        "source": "onnxruntime/test/providers/cpu/activation/activation_op_test.cc",
+        "test": "ActivationOpTest.Elu",
+        "notes": "ORT shared activation vector with alpha set to 0.1."
+      },
+      "attrs": { "alpha": 0.1 },
+      "inputs": {
+        "x": {
+          "dtype": "float32",
+          "shape": [13],
+          "data": {
+            "kind": "values",
+            "values": [-1.0, 0.0, 1.0, 100.0, -100.0, 1000.0, -1000.0, 1.1754943508222875e-38, 1.1754943508222876e-39, -1.1754943508222876e-39, 3.4028234663852886e+38, -3.4028234663852886e+38, "Infinity"]
+          }
+        }
+      },
+      "outputs": { "y": { "dtype": "float32", "shape": [13], "tolerance": 0.000001 } }
+    },
+    {
+      "name": "onnx_backend_alpha2_example",
+      "provenance": {
+        "source": "cmake/external/onnx/onnx/backend/test/data/node/test_elu_example",
+        "test": "test_elu_example"
+      },
+      "attrs": { "alpha": 2 },
+      "inputs": { "x": { "dtype": "float32", "shape": [3], "data": { "kind": "values", "values": [-1.0, 0.0, 1.0] } } },
+      "outputs": { "y": { "dtype": "float32", "shape": [3], "tolerance": 0.000001 } }
+    },
+    {
+      "name": "onnx_backend_elu",
+      "provenance": { "source": "cmake/external/onnx/onnx/backend/test/data/node/test_elu" },
+      "attrs": { "alpha": 2 },
+      "inputs": {
+        "x": {
+          "dtype": "float32",
+          "shape": [3, 4, 5],
+          "data": { "kind": "values", "values": { "$ref": "#/fixtureArrays/onnx_backend_input_x" } }
+        }
+      },
+      "outputs": { "y": { "dtype": "float32", "shape": [3, 4, 5], "tolerance": 0.00001 } }
+    },
+    {
+      "name": "onnx_backend_default_alpha",
+      "provenance": { "source": "cmake/external/onnx/onnx/backend/test/data/node/test_elu_default" },
+      "inputs": {
+        "x": {
+          "dtype": "float32",
+          "shape": [3, 4, 5],
+          "data": { "kind": "values", "values": { "$ref": "#/fixtureArrays/onnx_backend_input_x" } }
+        }
+      },
+      "outputs": { "y": { "dtype": "float32", "shape": [3, 4, 5], "tolerance": 0.00001 } }
+    },
+    {
+      "name": "vec4_f16_lanes",
+      "inputs": {
+        "x": {
+          "dtype": "float16",
+          "shape": [16],
+          "data": {
+            "kind": "values",
+            "values": [-6.0, -4.0, -3.0, -2.0, -1.5, -1.0, -0.5, -0.25, 0.0, 0.25, 0.5, 1.0, 1.5, 2.0, 4.0, 6.0]
+          }
+        }
+      },
+      "outputs": { "y": { "dtype": "float16", "shape": [16], "tolerance": 0.001, "relTolerance": 0.002 } }
+    },
+    {
+      "name": "empty_input_zero_dim",
+      "attrs": { "alpha": 0.5 },
+      "inputs": { "x": { "dtype": "float32", "shape": [0], "data": { "kind": "values", "values": [] } } },
+      "outputs": { "y": { "dtype": "float32", "shape": [0], "tolerance": 0 } }
+    }
+  ]
+}

build/webgpu/unary-scalar.wgsl.jinja ADDED Viewed

	@@ -0,0 +1,37 @@

+{% macro flat_tail_open() %}
+@compute @workgroup_size({{ tunables.WORKGROUP_SIZE }})
+fn main(@builtin(global_invocation_id) gid: vec3<u32>, @builtin(num_workgroups) nwg: vec3<u32>) {
+  // 2D-folded flat index: gid.y carries the high bits when the element count exceeds the
+  // maxComputeWorkgroupsPerDimension limit (the dispatch caps x and spills the rest into y).
+  let invocation = gid.x + gid.y * nwg.x * {{ tunables.WORKGROUP_SIZE }}u;
+  // Tail-safe scalar x4 keeps vector-like dispatch density without requiring
+  // the logical tensor length (or its storage binding) to be vec4 aligned.
+  let begin = invocation * {{ source.itemsPerInvocation }}u;
+  let end = min(begin + {{ source.itemsPerInvocation }}u, params.count);
+  for (var i = begin; i < end; i = i + 1u) {
+{%- endmacro %}
+{% macro flat_tail_close() %}
+  }
+{% endmacro %}
+// Scalar unary fallback. Each branch retains the operation's numeric hardening,
+// including Payne-Hanek trigonometric range reduction and NaN/overflow guards.
+{% if usesF16 %}
+enable f16;
+{% endif %}
+{{ env.wgsl.resourceDeclarations }}
+fn expm1_safe(x: f32) -> f32 {
+  // exp(x) - 1 without the catastrophic cancellation of the literal exp(x) - 1.0,
+  // which loses all significance for small |x| (exp(x) rounds to 1.0). A 6-term
+  // Maclaurin series is exact to < 1 ULP for |x| < 0.125 and matches the direct
+  // form at the switchover, so the normal range is unchanged.
+  if (x > -0.125 && x < 0.125) {
+    return x * (1.0 + x * (0.5 + x * (0.16666666666666666 + x * (0.041666666666666664 + x * (0.008333333333333333 + x * 0.001388888888888889)))));
+  }
+  return exp(x) - 1.0;
+}
+{{ flat_tail_open() }}
+  let v = f32(x[i]);
+  y[i] = {{ scalar }}(select(params.alpha * expm1_safe(v), v, v >= 0.0));
+{{ flat_tail_close() -}}
+}

build/webgpu/unary-vec4.wgsl.jinja ADDED Viewed

	@@ -0,0 +1,30 @@

+// Loads and stores vec4<T> (128 bits) while retaining scalar per-component
+// arithmetic, including per-component helper calls for guard-heavy operations.
+{% if usesF16 %}
+enable f16;
+{% endif %}
+{{ env.wgsl.resourceDeclarations }}
+fn expm1_safe(x: vec4<f32>) -> vec4<f32> {
+  // exp(x) - 1 without the catastrophic cancellation of the literal exp(x) - 1.0,
+  // which loses all significance for small |x| (exp(x) rounds to 1.0). A 6-term
+  // Maclaurin series is exact to < 1 ULP for |x| < 0.125 and matches the direct
+  // form at the switchover, so the normal range is unchanged. Componentwise.
+  let series = x * (1.0 + x * (0.5 + x * (0.16666666666666666 + x * (0.041666666666666664 + x * (0.008333333333333333 + x * 0.001388888888888889)))));
+  let direct = exp(x) - 1.0;
+  return select(direct, series, abs(x) < vec4<f32>(0.125));
+}
+const ELU_ALPHA: f32 = f32({{ source.alpha }});
+@compute @workgroup_size({{ tunables.WORKGROUP_SIZE }})
+fn main(@builtin(global_invocation_id) gid: vec3<u32>, @builtin(num_workgroups) nwg: vec3<u32>) {
+  // 2D-folded flat index: gid.y carries the high bits when the element count exceeds the
+  // maxComputeWorkgroupsPerDimension limit (the dispatch caps x and spills the rest into y).
+  let i = gid.x + gid.y * nwg.x * {{ tunables.WORKGROUP_SIZE }}u;
+  if (i >= params.count) {
+    return;
+  }
+  let xv = x[i];
+  let fv = vec4<f32>(xv);
+  y[i] = {{ vectorScalar }}(select(ELU_ALPHA * expm1_safe(fv), fv, fv >= vec4<f32>(0.0)));
+}