diff --git a/.agents/skills/model-schema-validation/SKILL.md b/.agents/skills/model-schema-validation/SKILL.md index ebbea32cbd..2e819edab5 100644 --- a/.agents/skills/model-schema-validation/SKILL.md +++ b/.agents/skills/model-schema-validation/SKILL.md @@ -65,7 +65,7 @@ const L = dims.range('L'); ### Key Schema Utilities from `src/core/schema.ts`: - **`method(name, inputs, outputs, runtimeConstraints?)`**: Constructs a method specification. -- **`f32(...)` / `i64(...)` / `i32(...)` / `ui8(...)`**: Shorthand helpers for tensor parameter specs. +- **`f32(...)` / `f16(...)` / `i64(...)` / `i32(...)` / `ui8(...)`**: Shorthand helpers for tensor parameter specs. - **`StaticDim('symbol')` / String Literals**: Strings passed to shape helpers (e.g. `'H'`, `'W'`) automatically map to `StaticDim`, acting as **static dimension wildcards**. They bind strictly to `constant` positive integer dimensions in the exported spec. - **`DynamicDim('symbol')` (or `Dyn('symbol')`)**: Creates a dynamic dimension symbol. Must be used when a dimension genuinely varies at runtime and binds to a `range` or `enum` domain in the exported spec. - **Constraint Helpers (`constraint`)**: diff --git a/docs/docs/03-core-and-advanced/02-models-and-tensors.md b/docs/docs/03-core-and-advanced/02-models-and-tensors.md index 9250088c08..dde6dfd2bc 100644 --- a/docs/docs/03-core-and-advanced/02-models-and-tensors.md +++ b/docs/docs/03-core-and-advanced/02-models-and-tensors.md @@ -96,6 +96,7 @@ reports the total element count, derived from the shape. | `DType` | Element type | TypedArray for transfers | Bytes / element | | :---------- | :----------------- | :----------------------- | :-------------- | | `'float32'` | 32-bit float | `Float32Array` | 4 | +| `'float16'` | 16-bit float | `Uint16Array` (raw bits) | 2 | | `'int32'` | 32-bit signed int | `Int32Array` | 4 | | `'int64'` | 64-bit signed int | `BigInt64Array` | 8 | | `'uint8'` | 8-bit unsigned int | `Uint8Array` | 1 | diff --git a/docs/docs/03-core-and-advanced/03-schema-validation.md b/docs/docs/03-core-and-advanced/03-schema-validation.md index 61bc0c9877..d08b2e4dc8 100644 --- a/docs/docs/03-core-and-advanced/03-schema-validation.md +++ b/docs/docs/03-core-and-advanced/03-schema-validation.md @@ -91,6 +91,7 @@ Build a method spec with Inputs and outputs are ordered lists of parameter specs; for tensors, use the dtype shorthands — [`f32`](../06-api-reference/react-native-executorch/namespaces/schema/functions/f32.md), +[`f16`](../06-api-reference/react-native-executorch/namespaces/schema/functions/f16.md), [`i64`](../06-api-reference/react-native-executorch/namespaces/schema/functions/i64.md), [`i32`](../06-api-reference/react-native-executorch/namespaces/schema/functions/i32.md), [`ui8`](../06-api-reference/react-native-executorch/namespaces/schema/functions/ui8.md), diff --git a/packages/react-native-executorch/__tests__/api/__snapshots__/apiSurface.test.ts.snap b/packages/react-native-executorch/__tests__/api/__snapshots__/apiSurface.test.ts.snap index 6ea42949f8..b5603d08d1 100644 --- a/packages/react-native-executorch/__tests__/api/__snapshots__/apiSurface.test.ts.snap +++ b/packages/react-native-executorch/__tests__/api/__snapshots__/apiSurface.test.ts.snap @@ -89,6 +89,7 @@ exports[`public API surface matches the recorded contents of each namespace 1`] "SymbolicTensor", "bool", "constraint", + "f16", "f32", "i32", "i64", diff --git a/packages/react-native-executorch/__tests__/support/fakeTensor.ts b/packages/react-native-executorch/__tests__/support/fakeTensor.ts index b70ddcfc79..2d4a60c15a 100644 --- a/packages/react-native-executorch/__tests__/support/fakeTensor.ts +++ b/packages/react-native-executorch/__tests__/support/fakeTensor.ts @@ -8,10 +8,11 @@ */ import type { DType } from '../../src/core/tensor'; -type Storage = Float32Array | Uint8Array | Int32Array | BigInt64Array; +type Storage = Float32Array | Uint16Array | Uint8Array | Int32Array | BigInt64Array; const STORAGE: Record Storage> = { float32: Float32Array, + float16: Uint16Array, // raw half-precision bits, as the native runtime transfers them uint8: Uint8Array, int32: Int32Array, int64: BigInt64Array, @@ -20,6 +21,7 @@ const STORAGE: Record Storage> = { const BYTES_PER_ELEMENT: Record = { float32: 4, + float16: 2, uint8: 1, int32: 4, int64: 8, diff --git a/packages/react-native-executorch/cpp/core/dtype.cpp b/packages/react-native-executorch/cpp/core/dtype.cpp index d02edfef26..7593058ae7 100644 --- a/packages/react-native-executorch/cpp/core/dtype.cpp +++ b/packages/react-native-executorch/cpp/core/dtype.cpp @@ -14,6 +14,9 @@ DType dtypeFromString(const std::string &s) { if (s == "int64") { return DType::int64; } + if (s == "float16") { + return DType::float16; + } if (s == "float32") { return DType::float32; } @@ -21,7 +24,7 @@ DType dtypeFromString(const std::string &s) { return DType::boolean; } throw error::InvalidArgument( - std::format("Unsupported dtype: '{}'. Expected 'uint8', 'int32', 'int64', 'float32' or 'bool'", s)); + std::format("Unsupported dtype: '{}'. Expected 'uint8', 'int32', 'int64', 'float16', 'float32' or 'bool'", s)); } std::string dtypeToString(DType dtype) { @@ -32,6 +35,8 @@ std::string dtypeToString(DType dtype) { return "int32"; case DType::int64: return "int64"; + case DType::float16: + return "float16"; case DType::float32: return "float32"; case DType::boolean: @@ -47,6 +52,8 @@ executorch::aten::ScalarType dtypeToScalarType(DType dtype) { return executorch::aten::ScalarType::Int; case DType::int64: return executorch::aten::ScalarType::Long; + case DType::float16: + return executorch::aten::ScalarType::Half; case DType::float32: return executorch::aten::ScalarType::Float; case DType::boolean: @@ -62,6 +69,8 @@ DType dtypeFromScalarType(executorch::aten::ScalarType st) { return DType::int32; case executorch::aten::ScalarType::Long: return DType::int64; + case executorch::aten::ScalarType::Half: + return DType::float16; case executorch::aten::ScalarType::Float: return DType::float32; case executorch::aten::ScalarType::Bool: @@ -83,6 +92,8 @@ size_t elementSize(DType dtype) { return 4; case DType::int64: return 8; + case DType::float16: + return 2; case DType::float32: return 4; } diff --git a/packages/react-native-executorch/cpp/core/dtype.h b/packages/react-native-executorch/cpp/core/dtype.h index 99b84e5c8d..21be040ae4 100644 --- a/packages/react-native-executorch/cpp/core/dtype.h +++ b/packages/react-native-executorch/cpp/core/dtype.h @@ -13,6 +13,7 @@ enum class DType { uint8, int32, int64, + float16, float32, boolean }; @@ -20,7 +21,7 @@ enum class DType { /** * Parses a string representation into a DType enum value. * - * @param s The string name of the data type (e.g. "uint8", "int32", "int64", "float32", "bool"). + * @param s The string name of the data type (e.g. "uint8", "int32", "int64", "float16", "float32", "bool"). * @return The corresponding DType enum value. * @throws error::RnExecuTorchException with code InvalidArgument if the string * does not match any known DType. diff --git a/packages/react-native-executorch/cpp/extensions/cv/utils.h b/packages/react-native-executorch/cpp/extensions/cv/utils.h index f9b8c468a8..a5c986ef58 100644 --- a/packages/react-native-executorch/cpp/extensions/cv/utils.h +++ b/packages/react-native-executorch/cpp/extensions/cv/utils.h @@ -23,6 +23,7 @@ inline int dtypeToCvDepth(rnexecutorch::core::types::DType dtype) { case rnexecutorch::core::types::DType::float32: return CV_32F; case rnexecutorch::core::types::DType::int64: + case rnexecutorch::core::types::DType::float16: case rnexecutorch::core::types::DType::boolean: break; } diff --git a/packages/react-native-executorch/cpp/tests/core/DTypeTest.cpp b/packages/react-native-executorch/cpp/tests/core/DTypeTest.cpp index 8b8289f968..61d334dbea 100644 --- a/packages/react-native-executorch/cpp/tests/core/DTypeTest.cpp +++ b/packages/react-native-executorch/cpp/tests/core/DTypeTest.cpp @@ -14,12 +14,13 @@ namespace types = rnexecutorch::core::types; constexpr auto kInvalidArgument = error::RnExecuTorchErrorCode::InvalidArgument; constexpr DType kAllDTypes[] = {DType::uint8, DType::int32, DType::int64, - DType::float32, DType::boolean}; + DType::float16, DType::float32, DType::boolean}; TEST(DType, ParsesEverySupportedName) { EXPECT_EQ(types::dtypeFromString("uint8"), DType::uint8); EXPECT_EQ(types::dtypeFromString("int32"), DType::int32); EXPECT_EQ(types::dtypeFromString("int64"), DType::int64); + EXPECT_EQ(types::dtypeFromString("float16"), DType::float16); EXPECT_EQ(types::dtypeFromString("float32"), DType::float32); // The JS name is "bool"; the enumerator is `boolean` because `bool` is a // keyword. A mismatch here would only surface as a rejected tensor dtype. @@ -54,13 +55,14 @@ TEST(DType, RejectsUnsupportedScalarType) { EXPECT_TRUE(throwsCoded( [] { types::dtypeFromScalarType(executorch::aten::ScalarType::Double); }, kInvalidArgument)); EXPECT_TRUE(throwsCoded( - [] { types::dtypeFromScalarType(executorch::aten::ScalarType::Half); }, kInvalidArgument)); + [] { types::dtypeFromScalarType(executorch::aten::ScalarType::BFloat16); }, kInvalidArgument)); } TEST(DType, ElementSizeMatchesScalarType) { EXPECT_EQ(types::elementSize(DType::uint8), 1u); EXPECT_EQ(types::elementSize(DType::int32), 4u); EXPECT_EQ(types::elementSize(DType::int64), 8u); + EXPECT_EQ(types::elementSize(DType::float16), 2u); EXPECT_EQ(types::elementSize(DType::float32), 4u); // ExecuTorch stores Bool one byte per element, so a bool tensor's buffer is // sized like a uint8 one. diff --git a/packages/react-native-executorch/cpp/tests/core/TensorTest.cpp b/packages/react-native-executorch/cpp/tests/core/TensorTest.cpp index cb988e4c9f..b568cd4d56 100644 --- a/packages/react-native-executorch/cpp/tests/core/TensorTest.cpp +++ b/packages/react-native-executorch/cpp/tests/core/TensorTest.cpp @@ -53,6 +53,26 @@ TEST_F(TensorTest, AcceptsTheBoolDtype) { EXPECT_EQ(evalString(std::format("{} return rne.createTensor([2, 3], 'bool').dtype;", kNs)), "bool"); } +TEST_F(TensorTest, Float16TransfersRawHalfBitsAsUint16) { + // float16 tensors hold the K/V caches of fp16 programs; JS has no Float16Array on Hermes, so the data moves as + // the raw IEEE 754 bits in a Uint16Array (0x3C00 = 1.0, 0xC000 = -2.0), two bytes per element. + auto result = evalNumberArray(std::format(R"( + {} + const t = rne.createTensor([2, 2], 'float16'); + t.setData(new Uint16Array([0x3C00, 0xC000, 0x0000, 0x7BFF])); + const out = new Uint16Array(4); + t.getData(out); + return [t.numel, ...Array.from(out)]; + )", + kNs)); + EXPECT_TRUE(almostEqual(result, {4, 0x3C00, 0xC000, 0x0000, 0x7BFF})); + EXPECT_EQ(evalString(std::format("{} return rne.createTensor([2], 'float16').dtype;", kNs)), "float16"); + // A Float32Array of the same element count is twice the bytes, so it is rejected rather than reinterpreted. + EXPECT_TRUE(isCodedError( + evalThrowing(std::format("{} rne.createTensor([2, 2], 'float16').setData(new Float32Array(4));", kNs)), + "INVALID_ARGUMENT", "Data size mismatch")); +} + TEST_F(TensorTest, RejectsWrongArgumentCount) { EXPECT_THAT(evalThrowingMessage(std::format("{} rne.createTensor([2]);", kNs)), HasSubstr("Usage: createTensor(shape, dtype)")); diff --git a/packages/react-native-executorch/src/core/schema.ts b/packages/react-native-executorch/src/core/schema.ts index 6e74bbb62e..c17e8282b2 100644 --- a/packages/react-native-executorch/src/core/schema.ts +++ b/packages/react-native-executorch/src/core/schema.ts @@ -343,6 +343,13 @@ export const SymbolicTensor = (dtype: DType, shape: SymbolicShape) => { * @returns A {@link SymbolicTensor} with `float32` data type. */ export const f32 = (...shape: SymbolicShape) => SymbolicTensor('float32', shape); +/** + * Shorthand for `SymbolicTensor('float16', shape)`. + * @category Core / Schema / Functions + * @param shape Dimension sizes of the tensor. + * @returns A {@link SymbolicTensor} with `float16` data type. + */ +export const f16 = (...shape: SymbolicShape) => SymbolicTensor('float16', shape); /** * Shorthand for `SymbolicTensor('int64', shape)`. * @category Core / Schema / Functions diff --git a/packages/react-native-executorch/src/core/tensor.ts b/packages/react-native-executorch/src/core/tensor.ts index 2fcbeb21ef..3626a3a94a 100644 --- a/packages/react-native-executorch/src/core/tensor.ts +++ b/packages/react-native-executorch/src/core/tensor.ts @@ -14,7 +14,7 @@ declare const tensorBrand: unique symbol; * Element data type of a {@link Tensor}. * @category Core / Types */ -export type DType = 'float32' | 'uint8' | 'int32' | 'int64' | 'bool'; +export type DType = 'float32' | 'float16' | 'uint8' | 'int32' | 'int64' | 'bool'; /** * A native ExecuTorch tensor allocated in C++ memory. @@ -62,14 +62,15 @@ export type Tensor = { /** * Writes data from a typed array into this tensor's native buffer. * @param src The source typed array. Its size in bytes must match the - * tensor's size. Use a `BigInt64Array` for `int64` tensors and a - * `Uint8Array` for `bool` tensors. + * tensor's size. Use a `BigInt64Array` for `int64` tensors, a `Uint8Array` + * for `bool` tensors, and a `Uint16Array` of raw IEEE 754 half-precision bits + * for `float16` tensors. * @returns `this` tensor. * @throws {RnExecuTorchError} Thrown with code `INVALID_ARGUMENT` if `src` * byte length does not match tensor size, `RESOURCE_BUSY` if the tensor is in * use, or `RESOURCE_DISPOSED` if disposed. */ - setData(src: Float32Array | Uint8Array | Int32Array | BigInt64Array): Tensor; + setData(src: Float32Array | Uint16Array | Uint8Array | Int32Array | BigInt64Array): Tensor; /** * Copies data out of this tensor's native buffer into a typed array. @@ -81,7 +82,9 @@ export type Tensor = { * byte length does not match tensor size, `RESOURCE_BUSY` if the tensor is in * use, or `RESOURCE_DISPOSED` if disposed. */ - getData(dst: T): T; + getData( + dst: T + ): T; /** * Passes `this` tensor as the first argument to `fn` and returns the result. @@ -147,7 +150,7 @@ export type Tensor = { export function tensor( dtype: DType, shape: number[], - src?: Float32Array | Uint8Array | Int32Array | BigInt64Array + src?: Float32Array | Uint16Array | Uint8Array | Int32Array | BigInt64Array ): Tensor { 'worklet'; const t: Tensor = rnexecutorchJsi.createTensor(shape, dtype);