fix(gpu): mirror the CPU integer_adm option table on the CUDA, SYCL and HIP twins

[lusoris]

Summary

The CUDA, SYCL and HIP integer_adm twins declared only a drifted subset of the CPU option table — no adm_csf_mode, no adm_p_norm, aliases that disagreed with core/src/feature/integer_adm.c (cs/cds/ss0/sai instead of scf/scfd/ssz). That is not a cosmetic gap: vmaf_feature_name_from_options() builds the emitted feature key from the extractor's own options[], so a twin missing one VMAF_OPT_FLAG_FEATURE_PARAM entry answers under a shorter key than the CPU twin for the same opts dict and the model lookup finds nothing — silently. The fork's default model vmaf_v1.0.16_3d0h asks for VMAF_integer_feature_adm3_score under integer_adm3_csf_2_dlmw_0.7_egl_1_min_0.5_nw_0.02, so adm_csf_mode=2 was both ignored arithmetically and absent from the key. All four CSF models and adm_p_norm are now implemented on all three twins and every option table is an entry-for-entry mirror of the CPU table; three further CPU-parity defects found while verifying it are fixed too (adm_min_val clamped adm2 where the CPU floors adm3 alone, numden_limit used the scale-3 area instead of the full-frame area, and the SYCL/HIP twins emitted aim_score/adm3_score from a hard-coded aim_num = 0.0). Measured CPU-vs-GPU pooled means on the 576x324 Netflix pair over adm2 + aim + adm3 + scale0..3: CUDA max |delta| 0.0e+00 at defaults, 0.0e+00 at csf_mode=2, 1.0e-06 at csf_mode=3, 1.0e-06 at p_norm=2.0, 0.0e+00 under the full model dict; SYCL (adm2 + scale0..3) 1.0e-06 / 0.0e+00 / 1.0e-06 / 5.0e-06 / 1.0e-06. Netflix golden gate 271 passed, 12 skipped, 0 failed. Deferred and recorded as Open rows in docs/state.md, not silently dropped: the SYCL/HIP AIM device pass (T-GPU-ADM-AIM-DEVICE-PASS-MISSING-SYCL-HIP-2026-09-05 — both features now fall back to the CPU twin rather than being fabricated), the pre-existing HIP integer_adm GPU page fault that blocks hardware verification of the HIP half (T-HIP-INTEGER-ADM-GPU-PAGE-FAULT-2026-09-05), the meson fatbin header-dependency gap (T-CUDA-FATBIN-NO-HEADER-DEP-2026-09-05), the pre-existing Arc A380 adm2 parity gap (T-SYCL-ARC-ADM2-PARITY-1.1E-4-2026-09-05), the degenerate adm_csf_mode=1 on the CPU reference itself (T-ADM-CSF-MODE-1-BARTEN-DEGENERATE-2026-09-05), and the icx golden-gate trap found while gating this branch (T-GOLDEN-GATE-ICX-FP-DRIFT-2026-09-05).

Type

• fix — GPU integer_adm twins now honour the CPU option table and the feature-name key it produces.

Checklist

• Commits follow Conventional Commits.
• make format && make lint is green locally (pre-commit on every touched file: pre-commit run --files ./CHANGELOG.md ./changelog.d/fixed/gpu-adm-csf-mode-parity.md ./core/src/feature/AGENTS.md ./core/src/feature/cuda/integer_adm_cuda.{c,h} ./core/src/feature/hip/integer_adm_hip.{c,h} ./core/src/feature/sycl/integer_adm_sycl.cpp ./core/test/test_{cuda,sycl,hip}_adm_parity.c ./docs/backends/{cuda,sycl,hip}/overview.md ./docs/metrics/features.md ./docs/rebase-notes.md ./docs/state.md ./python/test/gpu_default_model_test.py — all hooks Passed; scripts/ci/twin-drift-check.sh, scripts/ci/assertion-density.sh and scripts/ci/check-copyright.sh all PASS).
• Unit tests: meson test -C core/build test_cuda_adm_parity test_adm_csf test_barten_csf test_adm_csf_tools_coverage → 4 OK / 0 Fail. ./core/build/test/test_cuda_adm_parity 4/4 pass; ./core/build/test/test_sycl_adm_parity 5 run, 1 failed — the pre-existing Arc A380 test_adm_cpu_sycl_parity gap, reproduced unchanged against origin/master's integer_adm_sycl.cpp; ./core/build/test/test_hip_adm_parity 2 structural tests pass and the device test faults the GPU on origin/master too. python3 -m pytest python/test/gpu_default_model_test.py → 3 passed, 2 skipped (HIP), 3 subtests passed.
• Docs in the same PR: docs/metrics/features.md, docs/backends/cuda/overview.md, docs/backends/sycl/overview.md, docs/backends/hip/overview.md.
• SIMD/GPU, twins, new C sources, breaking change, ADR — GPU: all three integer_adm twins changed and cross-checked against the CPU reference on real content (table above) plus the C parity tests; twins: every twin of this extractor is updated in this PR, and the two that cannot compute AIM declare that instead of faking it; new C sources: none (one new Python test file, python/test/gpu_default_model_test.py, carries the Lusoris header); breaking change: none — every delta at default options is 0.0e+00 and the Netflix golden gate is unchanged; ADR: n/a, this restores conformance to decisions ADR-0487 / ADR-0530 / ADR-0746 already own rather than making a new one.

Bug-status hygiene (ADR-0165)

• docs/state.md — Recently closed: T-GPU-ADM-CSF-MODE-NOT-PORTED-2026-09-05 with the per-twin delta table. Open: T-GPU-ADM-AIM-DEVICE-PASS-MISSING-SYCL-HIP-2026-09-05, T-HIP-INTEGER-ADM-GPU-PAGE-FAULT-2026-09-05, T-CUDA-FATBIN-NO-HEADER-DEP-2026-09-05, T-SYCL-ARC-ADM2-PARITY-1.1E-4-2026-09-05, T-ADM-CSF-MODE-1-BARTEN-DEGENERATE-2026-09-05, T-GOLDEN-GATE-ICX-FP-DRIFT-2026-09-05.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: trivial — core/src/feature/integer_adm.c is the normative reference and the whole change is conformance to it.
• Decision matrix — no alternatives: only-one-way fix — the twins either mirror the CPU option table and its arithmetic or they emit the wrong key and the wrong value.
• AGENTS.md invariant note — core/src/feature/AGENTS.md, section "GPU-twin VmafOption tables mirror the CPU table (2026-09-05)".
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/fixed/gpu-adm-csf-mode-parity.md
• Rebase note — docs/rebase-notes.md entry

Reproducer

# 1. Feature-name-key identity + value parity, CPU vs each GPU twin, on the
#    default model's ADM option dict. This is the failure the PR fixes: before
#    it, the GPU twins answered under a key without `_csf_2`.
Y=python/test/resource/yuv
O='adm_csf_mode=2:adm_dlm_weight=0.7:adm_enhn_gain_limit=1.0:adm_min_val=0.5:adm_noise_weight=0.02'
for pair in "adm|--no_cuda --no_sycl --no_hip" "adm_cuda|--backend cuda" "adm_sycl|--backend sycl"; do
  fex=${pair%%|*}; flags=${pair#*|}
  ./core/build/tools/vmaf -r $Y/src01_hrc00_576x324.yuv -d $Y/src01_hrc01_576x324.yuv \
      -w 576 -h 324 -p 420 -b 8 --feature "$fex=$O" --no_prediction $flags \
      --json -o /tmp/$fex.json
done
python3 - <<'PY'
import json
cpu = json.load(open('/tmp/adm.json'))['pooled_metrics']
for be in ('adm_cuda', 'adm_sycl'):
    gpu = json.load(open(f'/tmp/{be}.json'))['pooled_metrics']
    for k in sorted(cpu):
        print(f'{be:9s} {k:60s} cpu={cpu[k]["mean"]!r} gpu={gpu.get(k, {}).get("mean")!r}')
PY
# Expected: every CPU key carries the `_csf_2_dlmw_0.7_egl_1_min_0.5_nw_0.02`
# suffix and starts with `integer_adm3` / `integer_adm2` / `integer_aim` /
# `integer_adm_scale0..3`. adm_cuda reproduces all seven bit-for-bit at the
# emitted precision (max |delta| 0.0e+00). adm_sycl reproduces the five it
# provides (max |delta| 1.0e-06) and prints `gpu=None` for
# `integer_aim_...` / `integer_adm3_...` — it has no AIM device pass, so those
# two route to the CPU twin through the ADR-0530 fallback instead of being
# fabricated.

# 2. C parity + option-table-mirror tests.
meson test -C core/build test_cuda_adm_parity   # 1/1 OK
./core/build/test/test_cuda_adm_parity          # 4 tests run, 4 passed
./core/build/test/test_hip_adm_parity           # first 2 (device-free) pass
source /opt/intel/oneapi/setvars.sh
./core/build/test/test_sycl_adm_parity          # 5 run, 1 failed: the
                                                # pre-existing Arc A380 gap

# 3. The GPU default-model key test (probes each backend, skips what is absent).
PYTHONPATH=$PWD/python python3 -m pytest python/test/gpu_default_model_test.py -v
# Expected: 3 passed, 2 skipped, 3 subtests passed

# 4. Netflix golden gate. MUST be run against a gcc build dir: a `core/build`
#    configured with oneAPI reports 11 unrelated float-motion FP-contraction
#    failures for any branch (T-GOLDEN-GATE-ICX-FP-DRIFT-2026-09-05).
CC=gcc CXX=g++ meson setup core/build-golden core \
    -Denable_cuda=false -Denable_sycl=false -Denable_hip=false -Denable_dnn=disabled
ninja -C core/build-golden
printf 'VMAFEXEC_PATH = "%s/core/build-golden/tools/vmaf"\n' "$PWD" > compat/python-vmaf/externals.py
CUDA_VISIBLE_DEVICES="" VMAF_FORCE_BACKEND=cpu PYTHONPATH=$PWD/python python3 -m pytest \
    python/test/quality_runner_test.py python/test/feature_extractor_test.py \
    python/test/vmafexec_test.py python/test/vmafexec_feature_extractor_test.py \
    python/test/result_test.py -m "not slow" --tb=short -q
rm -f compat/python-vmaf/externals.py
# Expected: 271 passed, 12 skipped

🤖 Generated with Claude Code