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()