quantize::sgfp4_decoder¶

Classes¶

	Name
class	quantize::sgfp4_decoder::SGFP4FormatError

Functions¶

	Name
int	int4_to_int(int nib)
int	sym2_to_ternary(int sym)
np.ndarray	decode_v1(bytes binary, int O, int I)
np.ndarray	decode_v2(bytes binary, int O, int I)

Detailed Description¶

Reference SGFP4 decoder — normative decode semantics.

Implements the closed decode specification of "SGFP4: Adaptive Dual-Mode
Macroblock Quantization with GPU-Friendly Unpacking and Verifiable Decode
Semantics" so that containers can be replayed bit-exactly by an independent
implementation (paper Sec 8 conformance-vector use case):

  - Sec 3.2  affine reconstruction w = S*c + beta; FP16 (S, beta) packed
             scale-in-high-halfword (packHalf2x16 order)
  - Sec 4    v1 profile: headers[B] | offsets[B] | 2048-byte payload blob;
             mode flag in bit 0 of the 16-byte-aligned offsets
  - Sec 4.3  normative code ordering (nibble i at bit 4*(i mod 8); ternary
             symbol i at bit 2*(i mod 16); 11 reserved -> 0)
  - Sec 6.1  v2 framing: 'SGF4' | 0x02 | B(u32) | 7B pad | record_offsets[B]
  - Sec 6.2  v2 record: sb_header | split map (MIXED) | block headers |
             pad | 16B-padded payloads; Eq (6) beta flag truncation

All wire-format constants come from quantize.sgfp4_format; this module
contains decode logic only. Decoders raise SGFP4FormatError on malformed
streams.

Functions Documentation¶

function int4_to_int¶

int int4_to_int(
    int nib
)

Two's-complement 4-bit code (paper Sec 4.3, Listing 1).```


### function sym2_to_ternary

```python
int sym2_to_ternary(
    int sym
)

2-bit ternary symbol map; 11 is reserved and decodes as 0.```


### function decode_v1

```python
np.ndarray decode_v1(
    bytes binary,
    int O,
    int I
)

Decode a v1 fixed-payload container to a float32 (O, I) tensor.

Args:
    binary: headers[B] | offsets[B] | codes blob (B*2048 bytes).
    O: unpadded output-channel count (carried by the model manifest).
    I: unpadded input-channel count.

Returns:
    Decoded float32 array of shape (O, I).

Raises:
    SGFP4FormatError: on size mismatches or reserved-bit violations.

function decode_v2¶

np.ndarray decode_v2(
    bytes binary,
    int O,
    int I
)

Decode a v2 quadtree-adaptive container to a float32 (O, I) tensor.

Args:
    binary: self-framed v2 stream (paper Sec 6.1).
    O: unpadded output-channel count (carried by the model manifest).
    I: unpadded input-channel count.

Returns:
    Decoded float32 array of shape (O, I).

Raises:
    SGFP4FormatError: on framing, alignment, or reserved-bit violations.

Updated on 2026-07-25 at 22:56:57 +0000