Research digests¶

The site search finds a digest by its title through the title list; digest bodies are not in the search index (ADR-1512). To search their text, use GitHub code search, for example repo:VMAFx/vmafx path:docs/research/ zensical.

Iteration-time research notes for the VMAFx fork. Each digest captures what was investigated and why for a fork-local workstream — source links, alternatives weighed, prior art, dead ends.

These are not ADRs:

• An ADR records a decision and its alternatives at the moment it was made. The body is frozen once Accepted.
• A research digest records the learning behind that decision (and the iterations that followed). It can be amended as new evidence arrives, the same way a lab notebook is.

A typical workstream has one ADR (the decision) and one research digest (the supporting investigation). Some PRs reuse an existing digest by linking; that is fine.

When to write one¶

Required by ADR-0108 on every fork-local PR that makes a non-trivial design choice. PRs without a design choice (e.g., a one-line bug fix in fork-added code) state "no research digest needed: trivial" in the PR description and skip the file. Reuse over duplication: if the workstream already has a digest, link it from the new PR instead of starting a parallel one.

Format¶

Each file is named NNNN-kebab-case-topic.md with a 4-digit zero-padded ID assigned in commit order. The structure mirrors 0000-template.md:

# Research-NNNN: <short, descriptive title>

- **Status**: Active | Superseded by Research-MMMM | Archived
- **Workstream**: <ADR-NNNN, ADR-MMMM, ...>
- **Last updated**: YYYY-MM-DD

## Question         — what was the unknown going in
## Sources          — papers, upstream docs, Netflix issues, prior PRs
## Findings         — what was learned, with citations
## Alternatives explored — what didn't work and why
## Open questions   — what is still unknown
## Related          — ADRs, PRs, issues

Conventions:

• IDs are assigned in commit order and never reused.
• Digests are amendable — update the Last updated date when you add findings. To replace one entirely, add Status: Superseded by Research-MMMM and write a new file.
• Cite sources inline with [link text](URL) so readers can verify.
• Keep one digest per workstream, not per PR. Cross-link from the PR description.

Index¶

| 0053 | Post-merge CPU profile 2026-05-03 — perf top-10 after lusoris/vmaf#310 through lusoris/vmaf#321; surfaces 3 new opt targets (convolve widen, SSIM double reduction, VIF gather elimination) | Active | — | | 0081 | Real-corpus retrain methodology for the fr_regressor_v2 deep ensemble — corpus-size sufficiency (9 ref + 70 dis @ .workingdir2/netflix/), 9-fold LOSO sizing inherited from the deterministic ADR-0291 baseline, seed-diversity hyperparameters, and the Seeking_25fps weak-fold diagnostic for HOLD-on-spread cases. | Active | ADR-0309 | | 0089 | CPU double vs Vulkan float stage bisect on the residual NVIDIA-Vulkan integer_vif_scale2 45/48-frame places=4 mismatch at API 1.4 (T-VK-VIF-1.4-RESIDUAL). Static SPIR-V re-verification confirms only 5 FP-arithmetic ops in vif.comp and all 5 are NoContraction-decorated post-PR #346 — SPIR-V mitigation surface is exhausted. SYCL counter-example (same f32 contract, passes the gate) rules out a pure f32-vs-f64 class issue. Localised root cause: NVIDIA shaderFloatControls2-v2 codegen flip at API 1.4 on a non-IEEE-bound default (reciprocal-multiply, fast-rsq) outside the SPIR-V declarable surface. Phase-2 shader fix not warranted; recommends per-stage NVIDIA dynamic dump or places=3 override ADR. | Active | ADR-0264, ADR-0269 | | 0090 | Per-commit triage of the 41 upstream commits binned SKIP-doc-or-format by the /sync-upstream Pass-2 heuristic on 2026-05-08. Splits into 5 PORT_NOW (motion_v2 mirroring bugfix, motion_v2 option cluster + prev_prev_ref API, two cambi internals), 18 PORT_LATER (python/test MyTestCase migration, blocked on agent-E worktree), 4 DEFER_INDEFINITELY, 1 PORTED_SILENTLY (662fb9ce semaphores → fork commit e5a52e74), 12 MERGE_BOUNDARY. Surfaces the riskiest item: the python/test mass-port is +5 600 LOC and crosses Netflix-golden assertions in feature_extractor_test.py. | Active | — (companion to Research-0089) | | 0135 | Vulkan dispatch overhead characterization — T7-18: startup dominated by uncached vkCreateComputePipelines; per-frame fence/submit overhead ruled out; pipeline-cache fix recommended | Active | T7-18 | | 0091 | CAMBI CUDA integration trade-offs (T3-15a): per-thread 49-read vs shared-memory SAT for the spatial-mask kernel; synchronous vs async ring-buffer DtoH for the 5-scale pipeline; host_pinned slot reuse for score storage; two compile-time bugs found and fixed (cuMemcpyDtoH arg order, VMAF_FEATURE_DISPATCH_SEQUENTIAL non-existence). Predecessor: Research-0032 (Vulkan twin). | Active | ADR-0360 |

| 0734 | CUDA VIF filter1d.cu ncu hotpath profile on RTX 4090 (sm_89). Primary bottleneck: launch-width-limited (0.84 waves) + register pressure (56 regs/thread). Top kernel filter1d_8_horizontal_kernel_2_17_9 = 35 % of VIF filter time. Three optimization candidates: increase val_per_thread 2→4, reduce register live range, add __ldg() for smem loads. | Active | — | (Index seeded by ADR-0108's adoption PR; backfilled digests for the existing major workstreams will be added as their authors revisit the corresponding code.) | 0135 | CAMBI CUDA spatial-mask SLM tile -- design analysis: img-tile correctness bug, 26x read reduction via direct zd_tile load, bank-conflict accepted at uint8 row access | Active | ADR-0464 | | 0751 | Cross-backend 4K (3840x2160) baseline (CPU + CUDA) and PR #79 adm_cm_line_kernel_8 A/B at 4K. RTX 4090 medians: vif CUDA 147 fps, adm CUDA 161 fps. filter1d fully saturated at 4K (253 waves, 69.7% occ). adm_cm __launch_bounds__ win is zero at 4K (-0.3%) vs -9.3% at 1080p (register-bound regime only). ms_ssim_decimate scale 0 saturated at 4K (88.1% occ). | Active | — |