Skip to content

Model K: k_approx opt-in (A1 + A2) - #257

Merged
phantoslayer21 merged 4 commits into
mainfrom
clean/k-approx
Nov 16, 2026
Merged

phantoslayer21 merged 4 commits into
mainfrom
clean/k-approx

Conversation

@phantoslayer21

@phantoslayer21 phantoslayer21 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Based on main after #254 (25429c5) and #264 (32ed000, the direct route's legacy input intermediates).

What

A runtime option for Model K, k_approx. It is opt-in: nothing set stays the exact path, which remains the default and the reference. It selects close approximations of two stages on the native D3D12 device. They are judged by image quality against the exact path, not byte for byte.

  • a1, the tiled input stage (kx/k_in_tiled*__a1, k_in_common.hlsli KI_HWMATH): the correctly rounded log2, 2^x and divisions (FP32 double-word arithmetic with a Ziv test and a binary64 fallback) become v_log_f32, v_exp_f32 and v_rcp_f32 times the dividend (scaled for |b| >= 2^126). Fast-close where the stage supports it: frames that take the legacy input kernels (a render size above 0.68 x the output, a jitter outside [-0.5, 0.5], or input_tiled=0) run the exact input stage. That is never refused (exact is always within quality); the first such frame of a context logs one line ("k_approx=a1 applies to the tiled input stage only; ...", through wg_rt_take_frame_note and the D3D12 executor's log), and the option's create note and clean/k/README.md say so.
  • a2, the output stage (k_out_color*__a2, k_out_pixel_c*__a2, k_out.hlsli KO_APPROX): the exact divisions become v_rcp_f32 times the dividend plus one correction of the quotient from its exact residual, and ko_div_axis and ko_rcp_refined drop their Newton step. ko_rcp_output_bounded and every opaque barrier stay.

Taking one adds one note of create (logged by the executor), k_approx=... in the kernels line, and ;k_approx=... with "an approximation (not bit-exact)" in the executor's mode line.

Refused at create, each in one line: HIP and the hybrid D3D12 device (k_approx runs on the native D3D12 device only); an empty value (k_approx=), an empty list item (a1,, ,a2, a1,,a2) and an unknown tag (control characters shown as ?); a1 without the exact input kernels; a2 with k_fast=1; a2 with k_head=full (the full head's k_out_pixel has no a2 form, so every accepted combination runs the same kernels on every frame).

Prepared only when selected: native create prepares exactly the kernels the context can select, the __a1 / __a2 forms only when they are selected, and checks each shader against the manifest digest. The D3D12 executor no longer runs its own warm-up for model K (that warm-up compiled every kernel of the build, the unselected forms too), so an unusable approximate shader cannot affect a context that does not select it; one that is selected refuses create, naming it.

Speed

Model K, 1440p Quality, harness direct route, interleaved 4+4, rt-k3 build (K-MIX): frame 1.5815 -> 1.3685 ms with k_approx=a1,a2 (main 1.5955)

Path Frame (ms) Input stage (ms) Output stage (ms)
exact (nothing set) 1.5815 0.394 0.473
k_approx=a1,a2 1.3685 0.193 0.456

Record: k-approx-speed.json in the lane folder; runs k3t-*.

The seven __a1 / __a2 shaders rebuilt from this branch are byte-identical (DXIL SHA-256) to those of the build that was timed and scored. Record: k-approx-dxil-257.json.

Image quality (spec side's scoring, Q11-C metrics; two sets of the game's frames)

The test sets are S1 (40 frames) and S2 (thin lines, 64 frames). The bars are a tenth of the Q11-C band against exact, and no worse than exact against the RTX 3060 natives.

Variant Set PSNR vs exact, median / min (dB) ΔPSNR vs native, variant − exact (bar 0.02 dB) Frame-to-frame ratio (bar 1 ± 0.001) Thin-line flicker ratio (bar 1 ± 0.002) Brightness ratio (bar 1 ± 0.0002) Result
a1 S1 80.4 / 76.0 +0.0075 1.000010 — 0.9999965 met
a1 S2 86.3 / 81.2 -0.0019 1.000000 1.00004 0.9999999 met
a1 + a2 S1 80.5 / 76.2 +0.0064 0.999984 — 0.9999949 met
a1 + a2 S2 86.4 / 81.2 -0.0019 0.999999 1.00011 0.9999998 met

There is no drift over 64 frames: the vs-exact PSNR rises from the first window to the last, and the variant − exact ΔPSNR vs native stays within 0.02 dB in the last window. The spec side's verdict for both is "very very close: every bar met on S1 and S2, no drift".

Tests

test_k_runtime_d3d12.py and test_k_approx_executor.py, 35 / 35 on a developer build, each create in its own process; synthetic model only:

  • test_k_approx_refusals: HIP and the hybrid device refused; the empty value, empty items, an unknown tag, a control-character tag and a2;k_head=full refused, each in one line; nothing set: no note, no k_approx in the kernels line.
  • test_k_approx_each_tag: a1, a2 and a1,a2 each create with one note and their kernels-line field; with the self-check's fallback forced, a1,a2 still applies (two notes); with both softmax forms failed, create refuses.
  • test_k_approx_shaders_prepared_only_when_selected: a copy of the build with one byte changed in k_out_pixel_c__a2 or kx/k_in_tiled__a1: nothing set creates; selecting that form refuses, naming it.
  • test_native_k_approx_a1_legacy_note: tiled, legacy, legacy, tiled, legacy, tiled, legacy frames (legacy = a jitter outside the guard; the launch trace confirms each frame's path): with k_approx=a1 exactly one line, at the first legacy frame, and a second a1 context gets its own; no line with nothing set or k_approx=a2. Legacy frames run no __a1 kernel.
  • test_native_k_approx_frames: frame by frame at 1440p Quality (a reset, a steady frame, a smaller render size): every approximate frame launches the __a1 tiled input and k_out_pixel_c__a2 and no exact counterpart, every default frame none of them; the approximate output differs from exact and stays within loose bounds (at most 35 % of values differ, tone-mapped luma PSNR above 45 dB; measured 1.3 / 12.2 / 17.4 % and 55.7 / 55.5 / 54.7 dB). Negative controls: the variant check fails on a default frame, the closeness check on identical and on perturbed outputs.
  • Every exact-path test is unchanged and passes.

test_k_direct_legacy.py (from #264) gains two cases: k_approx=a1 on the direct context (DLAA, and a jitter outside the guard) keeps every legacy frame byte-identical to the exact reference on all 6 frames (the input stage runs exact), and the context logs its one a1 line.

test_k_approx_executor.py (new; test_interop_d3d12.exe matrix at 1080p, 20 contexts each):

  • test_selected_form_runs: the unchanged build takes k_approx=a2 in every context, and each mode line names it.
  • test_unselected_form_is_not_prepared: with one byte changed in both k_out_pixel_c__a2 forms and nothing set, every context runs the exact path. Negative control: the same test against a build with the executor's warm-up restored fails, 20 of 20 contexts refused with "shader integrity mismatch: k_out_pixel_c__a2" (record executor-negctl-257.json).
  • test_a1_legacy_line_once_per_context: k_approx=a1: each DLAA context (render size = output: the legacy input path) logs the line exactly once and its frame runs; the 16 other contexts (tiled) never log it.
  • test_selected_changed_form_is_refused: the same copy with k_approx=a2: every context refused, naming k_out_pixel_c_direct__a2.

… (output stage), D3D12 only

Runtime option k_approx (opt-in; nothing set stays the exact path, the default and the reference). The variants are
judged by image quality against the exact path, not byte for byte. D3D12 devices only: HIP refuses the option, and an
unknown tag is refused. Taking one adds a note of create and " k_approx=..." to the kernels line.

- a1, the tiled input stage (kx/k_in_tiled*__a1; k_in_common.hlsli KI_HWMATH): the correctly rounded log2, 2^x and
  divisions (FP32 double-word arithmetic with a Ziv test and a binary64 fallback) become v_log_f32, v_exp_f32 and
  v_rcp_f32 times the dividend (scaled for |b| >= 2^126). Needs the exact input kernels.
- a2, the output stage (k_out_color*__a2, k_out_pixel_c*__a2; k_out.hlsli KO_APPROX): the exact divisions become
  v_rcp_f32 times the dividend plus one correction of the quotient from its exact residual, and ko_div_axis and
  ko_rcp_refined drop their Newton step; ko_rcp_output_bounded and every opaque barrier stay. Excludes k_fast.

Tests (test_k_runtime_d3d12.py): the refusals (HIP, unknown tag), the note, the __a1 / __a2 kernels in the launch
trace, and loose closeness bounds against the exact path on the synthetic model (tone-mapped luma PSNR).

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…tent a2, one-line refusals

- Native create already prepares (and digest-checks) exactly the kernels the context can select, the __a1 / __a2
  forms only when selected. The D3D12 executor now skips its own warm-up for a runtime that did
  (runtime_prepared_kernels): that warm-up compiled every kernel of the build, so an unusable unselected approximate
  shader refused every default context.
- k_approx runs on the native D3D12 device only; the hybrid device (backend 2) is refused as HIP is.
- a2 needs the compact head: with k_head=full, k_out_pixel has no a2 form, so the combination is refused at create
  instead of running a mixed output stage.
- An empty value (k_approx=) and an empty list item are refused; values in refusals are shown on one line (control
  characters as '?').
- The executor's mode line names k_approx and calls the mode an approximation.

Tests: test_k_runtime_d3d12.py k_approx tests rewritten (refusals on both other devices and every malformed value,
each tag's note and kernels-line field, the self-check fallback with k_approx, per-frame kernel selection with
negative controls, closeness with differ > 0, a changed approximate shader selected and not);
test_k_approx_executor.py (new): the interop matrix with a changed a2 shader, selected and not, and the mode line.
README: the k_approx section matches (no figures without a record).

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
Base automatically changed from clean/k-mix-softmax to main November 16, 2026 09:28
…mes run exact, logged once per context

The a1 contract: a frame on the legacy input path (a render size above 0.68 x the output, a jitter outside
[-0.5, 0.5], input_tiled=0) runs the exact input stage, never refused (exact is always within quality). The first such
frame of a context produces one line for the log: KRuntime::take_frame_note, runtime_take_frame_note and the C export
wg_rt_take_frame_note; the D3D12 executor logs it after the frame. The option's create note, its comment,
clean/k/README.md and clean/k/dx12/README.md say so.

Tests: test_native_k_approx_a1_legacy_note (tiled / legacy switches over seven frames, path confirmed by the launch
trace: exactly one line at the first legacy frame per a1 context, none with nothing set or a2);
test_a1_legacy_line_once_per_context (interop matrix: each DLAA context logs it once, tiled contexts never).

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…ames exact

With k_approx=a1 on the direct context (WG_TEST_DX12_OPTIONS), DLAA and jitter-outside-the-guard frames run the exact
input stage: every output byte equals the exact reference on all 6 frames, and the context logs its one a1 line.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
@phantoslayer21
phantoslayer21 marked this pull request as ready for review November 16, 2026 10:26
@phantoslayer21
phantoslayer21 merged commit a819430 into main Nov 16, 2026
10 checks passed
@phantoslayer21
phantoslayer21 deleted the clean/k-approx branch November 16, 2026 10:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant