fix(gpu): honour adm_p_norm, adm_bypass_cm and adm_skip_scale0 in the float-ADM twins

[lusoris]

Summary

Three VMAF_OPT_FLAG_FEATURE_PARAM options that the GPU float_adm twins
declare with the CPU's names, aliases, defaults and ranges — and did not
implement. The framework accepts each, range-checks it, and folds it into the
derived feature name (ADR-1183), so a score filed under adm2_apn_2 asserted
a setting that was never applied.

1. adm_p_norm — four application points, one honoured (all four twins)

adm_tools.c applies the p-norm in four places:

/* 1. DLM numerator sum, 2. CSF denominator sum — both branch on p == 3 */
if (c->adm_p_norm == 3.0) { inner[0] += (xh * xh * xh); }
else                      { inner[0] += powf(xh, c->adm_p_norm); }

/* 3. pooling root, 4. the noise constant */
powf(accum[0], 1.0f / adm_p_norm) + get_noise_constant(w, h, weight, adm_p_norm)

All four twins hardcoded the cube in the kernel and 1.0f / 3.0f in the host
pooling, and used adm_p_norm for the AIM exponent alone — producing a sum
of cubes raised to 1/p, with adm2 and every adm_scaleN left at p = 3.

2. adm_bypass_cm — declared, stored, read by nothing (CUDA + Metal)

grep -n adm_bypass_cm over either twin returns exactly two hits: the state
field and the option-table entry. The 3x3 masking threshold was always
subtracted. It now gates both the DLM and the AIM CM kernel, as adm.c
passes it to both adm_cm() calls. SYCL and HIP do not declare it and reject
it — unchanged.

3. adm_skip_scale0 — a pooling rule mistaken for a reporting rule (Metal)

adm.c sets num_scale = 0, den_scale = 1e-10 for scale 0, so it drops out
of the pooled adm2 / aim. The Metal twin zeroed only the reported
adm_scale0 sub-score while still folding the full scale-0 numerator and
denominator into the pooled score. No kernel change was needed: adm_dwt2_lo_s
writes only band_a, which adm_dwt2 computes identically.

Reproducer

meson setup build-cuda core -Denable_cuda=true -Denable_sycl=false -Db_lto=false
ninja -C build-cuda
meson test -C build-cuda test_cuda_float_adm_parity --print-errorlogs -v

Revert core/src/feature/cuda/ and the new variants fail. Measured at
adm_p_norm = 2.0, against the 1e-4 ADR-0214 gate:

Backend	key	CPU	GPU	delta
CUDA (RTX 4090)	adm2_apn_2	0.43097075	0.45416959	2.32e-02
SYCL (Arc A380)	adm_scale0_apn_2	0.90092957	0.89784085	3.09e-03
HIP (gfx1030)	adm2_apn_2	0.99818595	0.99833104	1.45e-04

Each variant fails with the fix reverted and passes with it applied, on all
three local devices. SYCL and HIP legs:

source /opt/intel/oneapi/setvars.sh --force
CC=icx CXX=icpx meson setup build-sycl core -Denable_sycl=true -Denable_cuda=false -Db_lto=false
ninja -C build-sycl && meson test -C build-sycl test_sycl_float_adm_parity

meson setup build-hip core -Denable_hip=true -Denable_hipcc=true -Denable_cuda=false -Denable_sycl=false -Db_lto=false
ninja -C build-hip && meson test -C build-hip test_hip_float_adm_parity

The default path does not move

The kernels keep the CPU's own p == 3 literal-cube fast path
(fadm_pnorm_term). Device powf(x, 3.0f) is not guaranteed to equal
x * x * x, and p = 3 is what every shipped model uses. The pre-existing
default-options test_cuda_float_adm_parity and test_cuda_adm_parity stay
green as the proof.

Why no test caught it

Every float_adm parity test ran with NULL options, where p = 3 is the
hardcoded exponent and bypass = 0 is the hardcoded behaviour.

The SYCL test also had to be widened from adm2 alone to all five ADM features:
on its fixture the aggregate never moves past the gate, and the variant passed
against the unfixed code until adm_scale0 was added. The per-scale
sub-scores are where a kernel-vs-CPU divergence surfaces first — the CUDA test's
own comment says so, and the SYCL one had not followed it.

Scope

Metal gets all three fixes by construction — there is no Apple hardware here to
measure on, and that is stated in the ADR rather than implied. Its CM uniform's
two former padding slots now carry p_norm and bypass_cm, so FadmCsf and
FadmCsfHost keep the same size and alignment.

Deep-dive deliverables (ADR-0108)

• Research digest — docs/research/2037-advertised-but-unimplemented-gpu-options.md: the third instance of this pattern in a week, the one-grep mechanical check that finds it, and why an aggregate-only parity test could not see it.
• Decision matrix — docs/adr/1220-gpu-float-adm-options-reach-kernels.md ## Alternatives considered (five options; the runner-up "always call powf, no p == 3 branch" would move the default path for every shipped model).
• AGENTS.md invariant note — new canonical note in core/src/feature/cuda/AGENTS.md, cross-referenced from core/src/feature/sycl/AGENTS.md, with full sections in core/src/feature/hip/AGENTS.md and core/src/feature/metal/AGENTS.md.
• Reproducer / smoke-test command — see the Reproducer section above.
• CHANGELOG fragment — changelog.d/fixed/1220-gpu-float-adm-options.md.
• Rebase note in docs/rebase-notes.md — entry ADR-1220 — float-ADM options must reach the GPU kernels (2026-09-07).

Docs (rule 10)

docs/metrics/features.md: the adm_p_norm and
adm_skip_scale0 rows now state which backends honour them and what the
pre-fix behaviour was, and adm_bypass_cm gains a row it never had — including
that SYCL and HIP reject it.

Bug status (rule 13 / ADR-0165)

• docs/state.md — closes T-GPU-FLOAT-ADM-OPTIONS-IGNORED-2026-09-07, and opens T-GAP-FLOAT-ADM-BYPASS-CM-SYCL-HIP-2026-09-07 for the option SYCL and HIP still do not declare.

🤖 Generated with Claude Code