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:
- nibble (
SIMD[.uint16, width]): One E2M1 nibble per lane in the low 4 bits (0..15).
Returns:
SIMD[.float16, width]: The decoded values as SIMD[.float16, width], bit-identical to
casting E2M1_TO_FLOAT32[nibble] to float16.