Skip to content
57 changes: 41 additions & 16 deletions clean/l/runner/l_frame_check.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,12 @@
- the ten Swin stages (clean/reference/swin.py run_stage), each output under the per-stage rule;
- dec0: Model L's decoder (oracle decode) or Model M's (clean/reference/decoder.py) on the runtime's dec1 output: the
A, B and latent codes and the C values, each at least 99.5 % identical (l_c32_check's end-to-end bound);
- post (clean/reference/post.py reconstruct): history and display under test_post_emu.py's FP16 acceptance, the
reduced history codes within 1 and 99 % exact; the filter (when the post kernel writes a display image) as
test_post_emu.py;
- post: Model L's reconstruction (l_post_recon) against clean/l/reference/recon.py reconstruct, Model M's against
clean/reference/post.py reconstruct: history and display under test_post_emu.py's FP16 acceptance for Model M, and
for Model L under Model L's post acceptance (clean/l/runner/l_post_check.py, provisional: values more than one ulp
off at most 0.01 % over the run and 0.05 % per frame, for the hardware-log2 reason given there), the reduced
history codes within 1 and 99 % exact; the filter (when
the post kernel writes a display image) as test_post_emu.py, against recon.output_filter / post.output_filter;
- exposure: the runtime's value and the reference's, reported (not a pass condition).
Output: counts only, no timing. The summary gives per stage the values differing, the largest difference (FP8 steps,
FP16 ulps or codes, as the stage's metric has it), the non-finite values on each side and the largest finite magnitude
Expand All @@ -53,6 +56,8 @@
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(HERE)))
sys.path.insert(0, ROOT)

from clean.l.runner import l_post_check as LP # noqa: E402 (Model L's post acceptance)

L_SOURCES = [os.path.join("..", "l", "runtime", "l_model.cpp"), os.path.join("..", "l", "runtime", "l_pack.cpp")]
SEED = 89
MAX_RENDER = (96, 64)
Expand Down Expand Up @@ -147,30 +152,33 @@ def prepare(build, rocm, model=None, map_path=None):

# ---- --run (GPU) ----------------------------------------------------------------------------------------------------

def frame_inputs(rng, rw, rh, reset):
def frame_inputs(rng, rw, rh, reset, special=True):
from clean.reference import encoder as En
x = En.random_inputs(rng, rw=rw, rh=rh, fw=-(-rw // 32) * 32, fh=-(-rh // 32) * 32)
x = En.random_inputs(rng, rw=rw, rh=rh, fw=-(-rw // 32) * 32, fh=-(-rh // 32) * 32, special=special)
return {"color": x["color"], "depth": x["depth"], "motion": x["motion"], "mv_scale": x["mv_scale"],
"jitter": x["jitter"], "exposure": 1.0, "pre_exposure": PRE_EXPOSURE, "reset": reset}


def run(build, rocm):
def run(build, rocm, special=True):
from clean.runner.hip import clean_process_environment
clean_process_environment(rocm)
from clean.runner.pipeline import Pipeline
d = model_dir(build)
# Model L: HDR colour (its reconstruction kernel l_post_recon is HDR; the runtime refuses Model L without it)
setups = {"L": dict(map_path=l_map(build), check_packing=False, kernels={"options": "model=L"}),
"M": dict(check_packing=True, kernels={"pack": "none"})}
flags = {"L": {"depth_inverted": False, "auto_exposure": True, "hdr": True},
"M": {"depth_inverted": False, "auto_exposure": True}}
for model, kw in setups.items():
# "stages": the bottleneck as six block launches, so that b0 ... b4 are written (the default megakernel writes
# only b5's output); "default": the runtime's default kernels, which must give the same bytes
for config in ("stages", "default"):
k = dict(kw, kernels=dict(kw["kernels"], **({"bneck": "none"} if config == "stages" else {})))
p = Pipeline(build, rocm, d, MAX_RENDER, OUTPUT, {"depth_inverted": False, "auto_exposure": True}, **k)
p = Pipeline(build, rocm, d, MAX_RENDER, OUTPUT, flags[model], **k)
rng = np.random.default_rng(SEED)
frames = []
for (rw, rh), reset in SEQUENCE:
fr = frame_inputs(rng, rw, rh, reset)
fr = frame_inputs(rng, rw, rh, reset, special)
out = p.frame(fr, debug=True)
frames.append({"inputs": fr, "out": out})
rec = {"model": model, "config": config, "kernels": p.kernels(), "notes": p.notes(),
Expand Down Expand Up @@ -230,16 +238,22 @@ def same_values(got, ref):
"max_f16_steps": int(_f16_steps(g[dif], r[dif]).max()) if dif.any() else 0}


def post_fp16(got, ref):
def post_fp16(got, ref, model="M"):
finite = np.isfinite(got)
s = _f16_steps(got, ref)
d = np.abs(np.where(finite, got, 0.0).astype(np.float64) - ref)
m = {"values": int(s.size), "differ": int(np.sum(s > 0)), "max_f16_steps": int(s.max()) if s.size else 0,
"nonfinite": int(np.sum(~finite)), "frac_over_1": float(np.mean(s > 1)), "frac_diff": float(np.mean(s > 0)),
"nonfinite": int(np.sum(~finite)), "frac_over_1": float(np.mean(s > 1)), "over_1": int(np.sum(s > 1)),
"frac_diff": float(np.mean(s > 0)),
"mean_rel_rms": float(d.mean() / max(np.sqrt(np.mean(np.square(ref, dtype=np.float64))), 1e-30))}
m.update(_magnitudes(got, ref))
m["pass"] = (m["nonfinite"] == 0 and m["frac_over_1"] <= 1e-4 and m["mean_rel_rms"] <= 1e-3
and m["frac_diff"] <= 0.01)
if model == "L":
# Model L's post acceptance (clean/l/runner/l_post_check.py, provisional): per frame at most 0.05 % more than
# one ulp off; the run-level 0.01 % is checked in compare()
m["pass"] = LP.l_post_rule(m["values"], m["nonfinite"], m["over_1"], m["differ"], m["mean_rel_rms"])
else:
m["pass"] = (m["nonfinite"] == 0 and m["frac_over_1"] <= 1e-4 and m["mean_rel_rms"] <= 1e-3
and m["frac_diff"] <= 0.01)
return m


Expand All @@ -249,6 +263,7 @@ def compare_model(rec, params):
from clean.reference import decoder as MD
from clean.reference import encoder as ME
from clean.reference import exposure as Ex
from clean.l.reference import recon as R
from clean.reference import post as Po
from clean.reference import swin as S
model = rec["model"]
Expand Down Expand Up @@ -332,17 +347,20 @@ def compare_model(rec, params):
"history": out["state"]["history_prev"] if not eff_reset else np.zeros((D[1], D[0], 3), np.float32),
"m_near": out["enc0"]["m_near"], "m_center": out["enc0"]["m_center"], "m_far": out["enc0"]["m_far"],
"jitter": fr["jitter"], "reset": eff_reset, "recon_size": D}
ref = Po.reconstruct(xp, float(np.asarray(params["post"]["s"]).reshape(-1)[0]))
m["post"] = {"history": post_fp16(out["post"]["history"], ref["history"])}
s_post = float(np.asarray(params["post"]["s"]).reshape(-1)[0])
ref = R.reconstruct(xp, s_post) if model == "L" else Po.reconstruct(xp, s_post)
m["post"] = {"history": post_fp16(out["post"]["history"], ref["history"], model)}
if out["post"]["display"] is not None:
m["post"]["display"] = post_fp16(out["post"]["display"], ref["display"])
m["post"]["display"] = post_fp16(out["post"]["display"], ref["display"], model)
dc = codes(out["post"]["reduced"], ref["reduced"], 1023.0)
dc["pass"] = dc["max_code_diff"] <= 1 and dc["differ"] <= 0.01 * dc["values"]
m["post"]["reduced"] = dc
if out["post"]["display"] is not None:
disp, e = out["post"]["display"], out["exposure"]["e"]
if rec["taps"] is not None:
fo = Po.output_filter_original(disp, e, (rec["ow"], rec["oh"]), rec["taps"])
elif model == "L":
fo = R.output_filter(disp, e, (rec["ow"], rec["oh"]))
else:
fo = Po.output_filter(disp, e, (rec["ow"], rec["oh"]))
fo = (np.asarray(fo, np.float32) * pi).astype(np.float32)
Expand Down Expand Up @@ -434,6 +452,10 @@ def compare(build, json_path):
"default_identical": {"frames": len(same), "identical": sum(not d for d in same),
"differing_outputs": sorted({k for d in same for k in d})},
"pass": all(m["pass"] for m in frames) and not any(same)}
if model == "L": # Model L's run-level limit on post values more than one ulp off (provisional)
res[model]["post_run"] = {k: LP.l_post_run([m["post"][k] for m in frames if k in m["post"]])
for k in ("history", "display")}
res[model]["pass"] = res[model]["pass"] and all(r["pass"] for r in res[model]["post_run"].values())
res["pass"] = res["L"]["pass"] and res["M"]["pass"]
src = os.path.join(model_dir(build), "source.json")
if os.path.exists(src):
Expand All @@ -460,6 +482,9 @@ def main(argv=None):
g.add_argument("--run", action="store_true")
g.add_argument("--compare", action="store_true")
ap.add_argument("--json")
ap.add_argument("--plain", action="store_true",
help="--run: frames without random_inputs' special values (NaN / huge / negative colours, NaN "
"depths, motion leaving the frame)")
ap.add_argument("--model", help="--prepare: a converter-written Model L model.wgcm in place of the synthetic model")
ap.add_argument("--map", help="--prepare with --model: the map it was converted with (default: the shipped "
"data/preset-L.v1.map.json)")
Expand All @@ -472,7 +497,7 @@ def main(argv=None):
prepare(a.build, a.rocm, a.model, a.map)
return 0
if a.run:
run(a.build, a.rocm)
run(a.build, a.rocm, special=not a.plain)
return 0
return compare(a.build, a.json or os.path.join(a.build, "lframe_check.json"))

Expand Down
47 changes: 37 additions & 10 deletions clean/l/runner/l_post_check.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,17 @@
the reduced codes' three 10-bit fields and top 2 bits (must be 0); no byte of any slack may change. A negative
control (the same case with the jitter moved by half a render pixel) must fail the criteria.

Criteria. Values: Model M's acceptance for its own reconstruction kernel (clean/tests/test_post_emu.py
test_matches_reference): no non-finite value, at most 0.01 % of FP16 values more than one ulp off, at most 1 % differ,
mean absolute error at most 0.1 % of the reference RMS; reduced codes at most 1 off, at most 1 % differ. These are
Model M's thresholds (float32 kernel against a float64 oracle); they are to be tightened when a kernel-order model of
the reconstruction exists. The oracle's colour gather runs in the model's precision (confirmed by the spec side), so
Criteria (Model L's post acceptance, l_post_rule; also used by clean/l/runner/l_frame_check.py for Model L). Values:
no non-finite value, at most 1 % differ, mean absolute error at most 0.1 % of the reference RMS; reduced codes at most
1 off, at most 1 % differ (Model M's acceptance for its own reconstruction kernel, clean/tests/test_post_emu.py
test_matches_reference). FP16 values more than one ulp off: at most 0.01 % over the whole run (all cases of all seeds)
and at most 0.05 % in any one case. PROVISIONAL until a kernel-order model of the reconstruction exists (approved by
the coordinator, 2026-11-14; Model M's checks keep their per-case 0.01 %). Why: the kernel's hardware log2
(v_log_f32, not correctly rounded) can put one input feature h(E_in(e c)) on the other side of an FP16 rounding
boundary than the oracle's correctly rounded log; the gather's half accumulators carry that flip forward, to several
FP16 steps where the window mixes a clamped negative colour with positive ones. Forcing that one feature to the
kernel's value in the oracle leaves 0 values more than one ulp off (the failing special case of #137's record, and
frames 8 and 9 of l_frame_check's record). With about 5 such values per case, a per-case 0.01 % turns on one flip. The oracle's colour gather runs in the model's precision (confirmed by the spec side), so
the kernel and the oracle agree on which weights underflow: no pixel is excluded.
Special colours (the encoder's random_inputs special values: NaN, 1e3 ... 1e6, small negatives, +inf): the same
criteria; the ill-conditioned pixels (a large fallback colour cancelled in the blend) are also reported apart.
Expand Down Expand Up @@ -121,6 +127,24 @@ def decode(raw, sizes, dims):
"slack_untouched": all(bool((raw[k][sizes[k]:] == SENTINEL).all()) for k in sizes)}


# Model L's post acceptance (see the module docstring; provisional): FP16 values more than one ulp off, at most this
# fraction of all values of a run, and at most L_OVER1_CASE in any one case or frame.
L_OVER1_RUN = 1e-4
L_OVER1_CASE = 5e-4


def l_post_rule(values, nonfinite, over_1, differ, mean_rel_rms):
"""One case's (or frame's) FP16 output under Model L's post acceptance, the run-level limit aside."""
return (nonfinite == 0 and over_1 <= L_OVER1_CASE * values and differ <= 0.01 * values and mean_rel_rms <= 1e-3)


def l_post_run(items):
"""The run-level limit: items = per-case dicts with "values" and "over_1". Returns {values, over_1, frac, pass}."""
v = sum(int(i["values"]) for i in items)
o = sum(int(i["over_1"]) for i in items)
return {"values": v, "over_1": o, "frac_over_1": o / max(v, 1), "pass": o <= L_OVER1_RUN * v}


def m_rule(got, ref):
res = {}
for k in ("history", "display"):
Expand All @@ -129,10 +153,11 @@ def m_rule(got, ref):
s = C32.f16_steps(np.where(fin, g, 0), r)
d = np.abs(np.where(fin, g, 0.0).astype(np.float64) - r)
res[k] = {"values": int(s.size), "nonfinite": int(np.sum(~fin)), "frac_over_1": float(np.mean(s > 1)),
"differ": int(np.sum(s > 0)), "frac_diff": float(np.mean(s > 0)), "max_steps": int(s.max()),
"over_1": int(np.sum(s > 1)), "differ": int(np.sum(s > 0)), "frac_diff": float(np.mean(s > 0)),
"max_steps": int(s.max()),
"mean_rel_rms": float(d.mean() / max(np.sqrt(np.mean(np.square(r, dtype=np.float64))), 1e-30))}
res[k]["pass"] = (res[k]["nonfinite"] == 0 and res[k]["frac_over_1"] <= 1e-4 and res[k]["frac_diff"] <= 0.01
and res[k]["mean_rel_rms"] <= 1e-3)
res[k]["pass"] = l_post_rule(res[k]["values"], res[k]["nonfinite"], res[k]["over_1"], res[k]["differ"],
res[k]["mean_rel_rms"])
rc = np.rint(np.asarray(ref["reduced"], np.float64) * 1023.0).astype(np.int64)
dc = np.abs(got["reduced_codes"] - rc)
res["reduced"] = {"values": int(dc.size), "differ": int(np.sum(dc > 0)), "max": int(dc.max(initial=0))}
Expand Down Expand Up @@ -197,7 +222,9 @@ def run(build, rocm, seeds=(89,)):
raw, sizes, dims = run_kernel(hip, mod, dict(x, jitter=np.asarray(x["jitter"], np.float32) + 0.5), S)
neg = m_rule(decode(raw, sizes, dims), R.reconstruct(x, S))
res["negative_control_fails"] = not neg["pass"]
res["pass"] = all(c["pass"] for c in res["cases"]) and res["negative_control_fails"]
res["run"] = {k: l_post_run([c[k] for c in res["cases"]]) for k in ("history", "display")}
res["pass"] = (all(c["pass"] for c in res["cases"]) and res["negative_control_fails"]
and all(r["pass"] for r in res["run"].values()))
return res


Expand All @@ -214,7 +241,7 @@ def main(argv=None):
for c in res["cases"]:
print(json.dumps({k: c[k] for k in c if k not in ("history", "display", "reduced")}),
{k: (c[k]["differ"], c[k].get("max_steps", c[k].get("max"))) for k in ("history", "display", "reduced")})
print({"negative_control_fails": res["negative_control_fails"], "pass": res["pass"]})
print({"run": res["run"], "negative_control_fails": res["negative_control_fails"], "pass": res["pass"]})
return 0 if res["pass"] else 1


Expand Down
20 changes: 11 additions & 9 deletions clean/l/runtime/tests/test_l_runtime_abi.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# SPDX-License-Identifier: MIT
"""Model L's code objects against what the runtime launches (#89), without running them: l_enc_values.co, l_ops.co
and l_swin.co are compiled (clean/l/runner/l_c32_check.py compile_kernels; HIP SDK clang, compile only), and each
kernel the runtime frame launches (clean/runtime/runtime.cpp, clean/l/FORMATS.md) must be exported with the arguments
the runtime passes: their number and sizes (a device address 8 bytes, an int 4, the encoder parameters WgEncParams
116, the decoder parameters WgDecParams 56). The kernels' own metadata (the AMDGPU metadata note of each code object,
amdhsa.kernels) is read here; nothing is loaded or executed. The argument kinds are the frame trace's table
"""Model L's code objects against what the runtime launches (#89), without running them: l_enc_values.co, l_ops.co,
l_swin.co and l_post.co are compiled (clean/l/runner/l_c32_check.py compile_kernels; HIP SDK clang, compile only),
and each kernel the runtime frame launches (clean/runtime/runtime.cpp, clean/l/FORMATS.md) must be exported with the
arguments the runtime passes: their number and sizes (a device address 8 bytes, an int 4, the encoder parameters
WgEncParams 116, the decoder parameters WgDecParams 56, the reconstruction parameters WgPostParams 64). The kernels'
own metadata (the AMDGPU metadata note of each code object, amdhsa.kernels) is read here; nothing is loaded or
executed. The argument kinds are the frame trace's table
(clean/tests/runtime_frame_trace.cpp), so the recorder that checks the runtime's arguments and the kernels agree.

Skipped without the HIP SDK (ROCM_PATH or C:\\Program Files\\AMD\\ROCm\\7.2).
Expand All @@ -21,12 +22,13 @@
import unittest

ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))))
SIZES = {"p": 8, "i": 4, "E": 116, "D": 56}
SIZES = {"p": 8, "i": 4, "E": 116, "D": 56, "P": 64}
# the kernels the Model L frame launches, by code object (the lev tag of l_enc_values.co is the runtime's)
LAUNCHED = {"l_enc_values.co": ["input_encoder"],
"l_ops.co": ["l_linear_32_32_relu", "l_linear_32_32_f16", "l_project_gather", "l_dec_project", "l_coef"],
"l_swin.co": ["l_swin_block_c32_enc", "l_swin_block_c32_enc_nc", "l_swin_block_c32_dec",
"l_swin_block_c32_dec_nc"]}
"l_swin_block_c32_dec_nc"],
"l_post.co": ["l_post_recon"]}
_BUILD = None


Expand Down Expand Up @@ -55,7 +57,7 @@ def kinds_table():
"""{kernel name or prefix*: kinds} from the frame trace program's table."""
with open(os.path.join(ROOT, "clean", "tests", "runtime_frame_trace.cpp"), encoding="utf-8") as f:
text = f.read()
return dict(re.findall(r'\{"([A-Za-z0-9_*]+)", "([piED]+)"\}', text))
return dict(re.findall(r'\{"([A-Za-z0-9_*]+)", "([piEDP]+)"\}', text))


def kinds_of(table, kernel):
Expand Down
Loading
Loading