From d06e485c3ba49b44716bc73d02c661fdd97ea2dd Mon Sep 17 00:00:00 2001 From: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> Date: Fri, 13 Nov 2026 17:13:11 -0500 Subject: [PATCH] Model L: weight packing of Model L's own launches (Python) clean/l/runner/l_pack.py derives the encoder's launch list from the structure table (a select is folded into the linear it feeds as zero weights) and packs one blob per launch, each in a format Model M already uses: - enc0.values: Model M's enc0 blob with a zero projection (dither table and the two scalars only); - enc0. per linear: the merge / expand section format (bias tile vector, fragments with rows R_L(C_out) and K order K_L(C_in)); - enc0., dec0.: packing.pack_block at the block's width; - enc0.project: bias, then fragments in groups of 32 input channels (dec0's K order over every group); - dec0: Model M's dec0 blob. The ten shared Swin stages keep packing.pack_stage. Decoders for the blobs are included for the tests. Tests (synthetic): round trips of every format, the block packer against Model M's stage blobs byte for byte, and the weights decoded from the blobs applied the kernels' way (whole input maps, zero weights outside a select) against the oracle's maps, byte for byte. Refs #89 Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> --- clean/l/README.md | 2 + clean/l/runner/__init__.py | 1 + clean/l/runner/l_pack.py | 192 +++++++++++++++++++++++++++++++++++ clean/l/tests/test_l_pack.py | 140 +++++++++++++++++++++++++ 4 files changed, 335 insertions(+) create mode 100644 clean/l/runner/__init__.py create mode 100644 clean/l/runner/l_pack.py create mode 100644 clean/l/tests/test_l_pack.py diff --git a/clean/l/README.md b/clean/l/README.md index b40b284e..536e6858 100644 --- a/clean/l/README.md +++ b/clean/l/README.md @@ -7,6 +7,8 @@ launcher yet. |---|---| | `reference/table.py` | Model L's structure table: the encoder's op list, the decoder's channel segments and block, window offsets, block constants, map names; parameter shapes from the table; matrix work per frame (computed, not measured). Entries in `PROVISIONAL` are pending confirmation and are changed here only | | `reference/oracle.py` | NumPy oracle (float64, only the prescribed FP8 / FP16 roundings): `encode`, `decode`, `network`, synthetic `random_params`. The Swin stages it shares with Model M call Model M's oracle (`clean/reference/swin.py`); the output reconstruction is not written yet | +| `runner/l_pack.py` | weight packing of Model L's own launches: the encoder's launch list derived from the table (`encoder_launches`) and one blob per launch (`pack_model_l`), each in a format Model M already uses (merge / expand section, Swin block section, enc0 and dec0 blobs); decoders for tests. The ten shared stages use `clean/runner/packing.py` unchanged | +| `tests/test_l_pack.py` | packing round trips, the block packer against Model M's stage blobs, and the unpacked weights applied the kernels' way against the oracle's maps, byte for byte | | `tests/test_l_reference.py` | self-checks on synthetic data; the main ones reduce Model L to Model M through the table and require Model M's oracle results byte for byte | ``` diff --git a/clean/l/runner/__init__.py b/clean/l/runner/__init__.py new file mode 100644 index 00000000..548d2d44 --- /dev/null +++ b/clean/l/runner/__init__.py @@ -0,0 +1 @@ +# SPDX-License-Identifier: MIT diff --git a/clean/l/runner/l_pack.py b/clean/l/runner/l_pack.py new file mode 100644 index 00000000..5c578b8c --- /dev/null +++ b/clean/l/runner/l_pack.py @@ -0,0 +1,192 @@ +# SPDX-License-Identifier: MIT +"""Model L weight packing (issue #89): the device blobs of Model L's own launches, from the structure table +(clean/l/reference/table.py) and the logical tensors of the oracle (clean/l/reference/oracle.py). + +Model L's encoder and decoder are run as a chain of small FP8-map kernels, each with a blob in a format Model M +already uses (clean/FORMATS.md): + +| Blob | Format | Kernel input -> output | +|---|---|---| +| `enc0.values` | Model M's enc0 blob (clean/runner/enc0.py pack) with W = 0 and b = 0 | frame -> the quantised values as a token map [F/2][80] (space_to_depth order 20 p + i) | +| `enc0.` per linear | merge / expand section format: bias tile vector (rows R_L(C_out)), then fragments [mt < C_out/16][kc < C_in/16], rows R_L(C_out), K order K_L(C_in) | FP8 map [C_in] -> FP8 map [C_out]; a `select` feeding the linear is folded in as zero weights outside its channels | +| `enc0.` per block | Model M's Swin block section (packing.pack_block) at the block's width, padded to 256 | FP8 map -> FP8 map | +| `enc0.project` | bias tile vector (rows R_L(n_out)), then fragments [mt][kb], rows R_L(n_out), K order: groups of 32 channels, block 2i + s holds channel 32 i + 16 h + 8 s + j (dec0's order, clean/runner/dec0.py kord_decoder, over every group) | the concatenated maps -> the 64 FP8 features enc1 reads | +| `dec0.` | Model M's Swin block section at the decoder block's width | dec1's channels of the block segment -> same width | +| `dec0` | Model M's dec0 blob (clean/runner/dec0.py pack) | as Model M | + +The ten shared Swin stages use clean/runner/packing.py pack_stage unchanged. +""" +import numpy as np + +from clean.l.reference import table as _table +from clean.reference.fp8 import fp8_decode +from clean.runner import dec0 as _dec0 +from clean.runner import enc0 as _enc0 +from clean.runner import packing as P + +ALIGN = P.ALIGN + + +# ---- orders --------------------------------------------------------------------------------------------------------- + +def kord_groups32(n): + """K slot (h, j) of block kb holds channel 32 (kb // 2) + 16 h + 8 (kb % 2) + j: each group of 32 channels is two + whole blocks, so a kernel can round its running sum after every second block.""" + if n % 32: + raise ValueError(f"project input of {n} channels: groups of 32 only") + K = np.empty(n, dtype=np.int64) + for kb in range(n // 16): + for h in range(2): + for j in range(8): + K[16 * kb + 8 * h + j] = 32 * (kb // 2) + 16 * h + 8 * (kb % 2) + j + return K + + +# ---- blob packers --------------------------------------------------------------------------------------------------- + +def pack_linear(W, b, C_in, C_out, lo=0, d_row="gfx12"): + """W [C_out, n] reading input channels lo .. lo + n of a C_in-wide map (zero weights elsewhere), bias [C_out].""" + drow = P.resolve_d_row(d_row) + W = np.asarray(W, dtype=np.float64) + n = W.shape[1] + if W.shape[0] != C_out or lo < 0 or lo + n > C_in or C_in % 16 or C_out % 16: + raise ValueError(f"linear {W.shape} at {lo} of {C_in} -> {C_out}: bad shape (multiples of 16 needed)") + Wx = np.zeros((C_out, C_in)) + Wx[:, lo:lo + n] = W + RL = P.rows_layout_l(C_out, drow) + return P.pack_tile_vector(b, RL, drow) + P.pack_frags(Wx, RL, P.kord_layout_l(C_in)) + + +def pack_project(W, b, groups, d_row="gfx12"): + drow = P.resolve_d_row(d_row) + W = np.asarray(W, dtype=np.float64) + n_out, n = W.shape + if any(g != 32 for g in groups) or sum(groups) != n: + raise ValueError(f"project groups {groups}: groups of 32 covering {n} channels only") + RL = P.rows_layout_l(n_out, drow) + return P.pack_tile_vector(b, RL, drow) + P.pack_frags(W, RL, kord_groups32(n)) + + +def pack_block(tensors, prefix, C, heads, mlp, d_row="gfx12"): + drow = P.resolve_d_row(d_row) + p = {k[len(prefix):]: v for k, v in tensors.items() if k.startswith(prefix)} + blob = P.pack_block(p, C, heads, mlp, drow) + return blob + bytes((-len(blob)) % ALIGN) + + +def pack_values(tensors, d_row="gfx12"): + """Model M's enc0 blob with zero projection: only the dither table and the two scalars are used.""" + t = {"W": np.zeros((64, 80), np.float32), "b": np.zeros(64, np.float32), + "T": tensors.get("T", np.zeros((8, 16, 16), np.float32)), + "sigma1": tensors.get("sigma1", np.float32(0)), "sigma2": tensors.get("sigma2", np.float32(0))} + return _enc0.pack(t, d_row) + + +# ---- the encoder's launch list -------------------------------------------------------------------------------------- + +def encoder_launches(t=_table.TABLE): + """The kernels of the table's encoder, in order: [{"kind", "blob", "src", "dst", ...}]. kinds: "values" (quant + + space_to_depth into the raw map), "linear", "swin", "project". A select is folded into the linear it feeds.""" + ops = t["enc_ops"] + plan = _table.encoder_plan(t) + chans = {"values": 20} + launches = [] + selects = {} + i = 0 + while i < len(ops): + op = ops[i] + k = op["op"] + if k == "quant": + nxt = ops[i + 1] if i + 1 < len(ops) else None + if not nxt or nxt["op"] != "space_to_depth" or nxt["src"] != op["dst"]: + raise ValueError("the encoder's kernels need quant directly followed by its space_to_depth") + if op["mode"] != "dither": + raise ValueError("the encoder's value kernel quantises with the dither table") + launches.append({"kind": "values", "blob": "enc0.values", "dst": nxt["dst"]}) + chans[nxt["dst"]] = 80 + i += 2 + continue + if k == "select": + selects[op["dst"]] = (op["src"], op["lo"], op["hi"]) + chans[op["dst"]] = op["hi"] - op["lo"] + elif k == "linear": + src, lo = op["src"], 0 + if src in selects: + src, lo, _ = selects[src] + launches.append({"kind": "linear", "blob": "enc0." + op["w"], "src": src, "dst": op["dst"], + "C_in": chans[src], "C_out": op["n_out"], "lo": lo, "w": op["w"], "b": op["b"]}) + chans[op["dst"]] = op["n_out"] + elif k == "swin": + launches.append({"kind": "swin", "blob": "enc0." + op["prefix"].rstrip("."), "src": op["src"], + "dst": op["dst"], "prefix": op["prefix"], "C": op["C"], "heads": op["heads"], + "mlp": op["mlp"], "offsets": op["offsets"]}) + elif k == "concat": + chans[op["dst"]] = plan[i][2] + launches.append({"kind": "concat", "srcs": op["srcs"], "dst": op["dst"], "pad_to": plan[i][2]}) + elif k == "project": + launches.append({"kind": "project", "blob": "enc0.project", "src": op["src"], "groups": op["groups"]}) + else: + raise ValueError(f"no kernel for encoder op {k!r}") + if k != "select": + selects.pop(op.get("dst"), None) # the name now holds this op's output + i += 1 + return launches + + +def pack_model_l(params, t=_table.TABLE, d_row="gfx12"): + """{blob name: bytes} of Model L's own launches (the shared Swin stages: packing.pack_stage).""" + enc = params["enc0"] + out = {} + for ln in encoder_launches(t): + if ln["kind"] == "values": + out[ln["blob"]] = pack_values(enc, d_row) + elif ln["kind"] == "linear": + out[ln["blob"]] = pack_linear(enc[ln["w"]], enc[ln["b"]], ln["C_in"], ln["C_out"], ln["lo"], d_row) + elif ln["kind"] == "swin": + out[ln["blob"]] = pack_block(enc, ln["prefix"], ln["C"], ln["heads"], ln["mlp"], d_row) + elif ln["kind"] == "project": + op = t["enc_ops"][-1] + out[ln["blob"]] = pack_project(enc[op["w"]], enc[op["b"]], ln["groups"], d_row) + dec = params["dec0"] + if any(s[0] == "block" for s in t["dec_connect"]): + b = t["dec_block"] + out["dec0." + b["prefix"].rstrip(".")] = pack_block(dec, b["prefix"], b["C"], b["heads"], b["mlp"], d_row) + out["dec0"] = _dec0.pack({k: dec[k] for k in ("W", "b", "S", "T")}, d_row) + return out + + +# ---- decoding (tests) ----------------------------------------------------------------------------------------------- + +def unpack_frags(raw, R, K): + """Inverse of packing.frag_array: fragment bytes [MT][KC][256] -> the matrix M [len(R), len(K)] (FP8 values).""" + MT, KC = len(R) // 16, len(K) // 16 + a = np.frombuffer(bytes(raw), dtype=np.uint8).reshape(MT, KC, 2, 16, 8) # [mt, kc, h, r, j] + P8 = a.transpose(0, 3, 1, 2, 4).reshape(16 * MT, 16 * KC) # [16 mt + r, 16 kc + 8 h + j] + M = np.zeros((len(R), len(K)), dtype=np.float64) + M[np.ix_(R, K)] = fp8_decode(P8) + return M + + +def unpack_tile_vector(raw, R, drow): + v = np.frombuffer(bytes(raw), dtype=np.float32) + out = np.empty(len(R), dtype=np.float32) + for mt in range(len(R) // 16): + for h in range(2): + for k in range(8): + out[R[16 * mt + drow[h][k]]] = v[16 * mt + 8 * h + k] + return out + + +def unpack_linear(blob, C_in, C_out, d_row="gfx12"): + """(W [C_out, C_in], b [C_out]) from a linear blob.""" + drow = P.resolve_d_row(d_row) + RL = P.rows_layout_l(C_out, drow) + b = unpack_tile_vector(blob[:4 * C_out], RL, drow) + return unpack_frags(blob[4 * C_out:], RL, P.kord_layout_l(C_in)), b + + +def unpack_project(blob, n_in, n_out, d_row="gfx12"): + drow = P.resolve_d_row(d_row) + RL = P.rows_layout_l(n_out, drow) + b = unpack_tile_vector(blob[:4 * n_out], RL, drow) + return unpack_frags(blob[4 * n_out:], RL, kord_groups32(n_in)), b diff --git a/clean/l/tests/test_l_pack.py b/clean/l/tests/test_l_pack.py new file mode 100644 index 00000000..7a7917ad --- /dev/null +++ b/clean/l/tests/test_l_pack.py @@ -0,0 +1,140 @@ +# SPDX-License-Identifier: MIT +"""Model L weight packing (clean/l/runner/l_pack.py), CPU only, synthetic parameters. + +Run: python -m unittest discover -s clean/l/tests -t . -p test_l_pack.py +""" +import unittest + +import numpy as np + +from clean.l.reference import oracle as L +from clean.l.reference import table as T +from clean.l.runner import l_pack as LP +from clean.reference import encoder as ME +from clean.reference import swin as MS +from clean.reference.fp8 import q8 +from clean.runner import dec0 as D0 +from clean.runner import enc0 as E0 +from clean.runner import packing as P + + +class OrderTest(unittest.TestCase): + def test_groups32_is_dec0_order(self): + self.assertTrue(np.array_equal(LP.kord_groups32(64), D0.kord_decoder())) + + def test_groups32_blocks(self): + K = LP.kord_groups32(128) + self.assertEqual(sorted(K), list(range(128))) + for g in range(4): + self.assertEqual(sorted(K[32 * g:32 * g + 32]), list(range(32 * g, 32 * g + 32))) + with self.assertRaises(ValueError): + LP.kord_groups32(80) + + +class RoundTripTest(unittest.TestCase): + def test_linear(self): + rng = np.random.default_rng(1) + for C_in, C_out, n, lo in ((80, 32, 20, 0), (80, 32, 20, 60), (32, 32, 32, 0), (64, 16, 16, 16)): + W = q8(rng.normal(0, 0.5, (C_out, n))) + b = rng.normal(0, 1, C_out).astype(np.float32) + blob = LP.pack_linear(W, b, C_in, C_out, lo) + self.assertEqual(len(blob), 4 * C_out + C_out * C_in) + Wu, bu = LP.unpack_linear(blob, C_in, C_out) + want = np.zeros((C_out, C_in)) + want[:, lo:lo + n] = W + self.assertTrue(np.array_equal(Wu, want)) + self.assertTrue(np.array_equal(bu, b)) + with self.assertRaises(ValueError): + LP.pack_linear(np.zeros((32, 20)), np.zeros(32), 80, 32, lo=70) + + def test_linear_is_merge_section_format(self): + """The linear blob is the patch-merge section format when the K order is the merge's.""" + rng = np.random.default_rng(2) + W = q8(rng.normal(0, 0.5, (96, 64))) + b = rng.normal(0, 1, 96).astype(np.float32) + drow = P.resolve_d_row("gfx12") + RL = P.rows_layout_l(96, drow) + self.assertEqual(LP.pack_linear(W, b, 64, 96), + P.pack_tile_vector(b, RL, drow) + P.pack_frags(W, RL, P.kord_layout_l(64))) + + def test_project(self): + rng = np.random.default_rng(3) + W = q8(rng.normal(0, 0.3, (64, 128))) + b = rng.normal(0, 1, 64).astype(np.float32) + blob = LP.pack_project(W, b, (32, 32, 32, 32)) + self.assertEqual(len(blob), 4 * 64 + 64 * 128) + Wu, bu = LP.unpack_project(blob, 128, 64) + self.assertTrue(np.array_equal(Wu, W)) + self.assertTrue(np.array_equal(bu, b)) + with self.assertRaises(ValueError): + LP.pack_project(W, b, (20, 20, 20, 20, 48)) + + def test_block_equals_model_m_packer(self): + """The L block packer is packing.pack_block: Model M's stage blobs come out byte for byte, and C = 32 has + the layout's size.""" + rng = np.random.default_rng(4) + for stage in ("b0", "dec1"): + cfg = MS.STAGES[stage] + p = MS.random_params(stage, rng) + want = P.pack_stage(stage, p)[:P.stage_sections(stage)[1]] + got = LP.pack_block({"x." + k: v for k, v in p.items()}, "x.", cfg["C"], cfg["heads"], cfg["mlp"]) + self.assertEqual(got, want, stage) + p = L.random_block_params(rng, 32, 2, 128, "blk.") + blob = LP.pack_block(p, "blk.", 32, 2, 128) + lay = P.block_layout(32, 2, 128) + self.assertEqual(len(blob), lay["SIZE"] + (-lay["SIZE"]) % 256) + self.assertEqual((lay["HPU"], lay["NMLP"], lay["MLP_BYTES"], lay["HEAD_BYTES"]), (8, 1, 8192, 3072)) + + def test_values_blob(self): + rng = np.random.default_rng(5) + enc = L.random_params(rng)["enc0"] + blob = LP.pack_values(enc) + self.assertEqual(len(blob), E0.BLOB_BYTES) + self.assertEqual(blob[:256], bytes(256)) # zero bias + self.assertEqual(blob[E0.OFF_DITHER:E0.OFF_DITHER + 2048], np.asarray(enc["T"]).astype(np.uint8).tobytes()) + + +class ModelTest(unittest.TestCase): + def test_launch_list(self): + ln = LP.encoder_launches() + self.assertEqual([x["kind"] for x in ln], ["values", "linear", "linear", "swin", "concat", "project"]) + self.assertEqual((ln[1]["src"], ln[1]["C_in"], ln[1]["lo"], ln[1]["C_out"]), ("raw", 80, 0, 32)) + self.assertEqual((ln[2]["src"], ln[2]["C_in"]), ("x", 32)) + + def test_pack_model_l(self): + rng = np.random.default_rng(6) + params = L.random_params(rng) + blobs = LP.pack_model_l(params) + self.assertEqual(sorted(blobs), sorted(["enc0.values", "enc0.Wa", "enc0.Wb", "enc0.blk", "enc0.project", + "dec0.blk", "dec0"])) + self.assertEqual(len(blobs["enc0.Wa"]), 4 * 32 + 32 * 80) + self.assertEqual(len(blobs["enc0.Wb"]), 4 * 32 + 32 * 32) + self.assertEqual(len(blobs["dec0"]), D0.BLOB_BYTES) + self.assertEqual(blobs["dec0"], D0.pack({k: params["dec0"][k] for k in ("W", "b", "S", "T")})) + self.assertEqual(blobs, LP.pack_model_l(params)) # deterministic + + def test_unpacked_weights_reproduce_the_oracle(self): + """The weights decoded from the blobs, applied to the oracle's maps the way the kernels apply them (whole + input maps, zero weights outside a select), give the oracle's maps byte for byte.""" + rng = np.random.default_rng(7) + params = L.random_params(rng) + x = ME.random_inputs(rng, rw=36, rh=20) + out = L.encode(x, params["enc0"], parity=0, keep=True) + m = out["maps"] + blobs = LP.pack_model_l(params) + enc = params["enc0"] + Wa, ba = LP.unpack_linear(blobs["enc0.Wa"], 80, 32) + Wb, bb = LP.unpack_linear(blobs["enc0.Wb"], 32, 32) + h1 = q8(m["raw"] @ Wa.T + ba) + self.assertTrue(np.array_equal(h1, q8(m["raw"][..., :20] @ np.asarray(enc["Wa"], np.float64).T + enc["ba"]))) + h2 = q8(h1 @ Wb.T + bb) + bp = {k[4:]: v for k, v in enc.items() if k.startswith("blk.")} + h3 = q8(L.swin_block(h2, bp, T.block_offset(T.TABLE, "first", 0), 2, T.M_BLOCK_CONSTS)) + self.assertTrue(np.array_equal(h3, m["x"])) + Wp, bpj = LP.unpack_project(blobs["enc0.project"], 128, 64) + feats = L.project_groups(m["z"], Wp, bpj, (32, 32, 32, 32)) + self.assertEqual(feats.astype(np.float32).tobytes(), out["features"].tobytes()) + + +if __name__ == "__main__": + unittest.main()