IMPORTANT: To view this page as Markdown, append `.md` to the URL (e.g. /get-started.md). For the complete documentation index, see llms.txt.
Skip to main content
For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).

Mojo function

decode_e2m1_to_f16

def decode_e2m1_to_f16[width: SIMDLength, //](nibble: SIMD[.uint16, width]) -> SIMD[.float16, width]

Decodes E2M1 nibbles to float16 by exponent injection (Preston's trick).

It injects the 3 magnitude bits (e1 e0 m0) at float16 bits 11:9 and the sign at bit 15, then renormalizes with a single * 2^14 (a power of two, hence exact). The result is bit-identical to E2M1_TO_FLOAT32[nibble] cast to float16 for all 16 values (every {+-0, +-0.5, ..., +-6} is exactly representable in float16), so decode_e2m1_to_f16(n).cast[float32]() equals decode_e2m1_to_f32(n) bit-for-bit.

Why the injection is done in float16: the +-0.5 codes (E == 0, m == 1) are the only ones that pass through a subnormal intermediate. The same trick in float32 (inject at bits 22..24, renormalize by * 2^126) makes that intermediate the float32 denormal 0x00400000, and the bf16 variant makes it 0x0040. Any target that flushes f32/bf16 denormals to zero on arithmetic inputs -- the Apple M5, and NVIDIA/AMD under --fp-mode=denormal=flush -- zeroes it before the multiply, so +-0.5 decodes to +-0 (verified on-device on the M5: nibbles 1 and 9 mismatch). Here the intermediate is the float16 subnormal 0x0200 / 0x8200 (value 2^-15), which * 2^14 renormalizes to +-0.5. The M5 preserves float16 subnormals (see patterns/apple-m5-denormal-flush-to-zero), so this decode keeps +-0.5 exact there (verified on-device: all 16 codes match E2M1_TO_FLOAT32). Callers that need f32/bf16 cast the f16 result afterwards; the cast of the now-normal +-0.5 is exact. On a target that also flushes f16 denormals, use decode_e2m1_to_f32 or decode_e2m1_to_bf16, which never form a denormal.

It is also cheaper than decode_e2m1_to_f32 (no uint32 widen, no select, no E == 0 compare) while staying bit-exact -- the reason to prefer it on the M5 dequant path.

Parameters:

  • ​width (SIMDLength): SIMD width (lane count) of the nibble vector.

Args:

Returns:

SIMD[.float16, width]: The decoded values as SIMD[.float16, width], bit-identical to casting E2M1_TO_FLOAT32[nibble] to float16.

Was this page helpful?