@kernaut/kernaut-resources 0.1.17-beta.1 → 0.1.18

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/compute/warp-divergence/apis.md

@@ -1,120 +0,0 @@
----
-title: Warp Divergence APIs
-status: draft
-source:
-- path: spec
-  anchor: Reference
-apis:
-- func_name: __ballot_sync
-  namespace: cuda-runtime
-  kind: warp-vote
-  signature: unsigned __ballot_sync(unsigned mask, int predicate);
-  notes: Returns a 32-bit mask whose bit i is set iff lane i in mask evaluated predicate non-zero. Full-warp masks should be 0xFFFFFFFFu.
-- func_name: __all_sync
-  namespace: cuda-runtime
-  kind: warp-vote
-  signature: int __all_sync(unsigned mask, int predicate);
-  notes: Returns non-zero iff predicate is non-zero on every lane in mask.
-- func_name: __any_sync
-  namespace: cuda-runtime
-  kind: warp-vote
-  signature: int __any_sync(unsigned mask, int predicate);
-  notes: Returns non-zero iff predicate is non-zero on at least one lane in mask.
-- func_name: __uni_sync
-  namespace: cuda-runtime
-  kind: warp-vote
-  notes: Returns non-zero iff the predicate is uniform (same value) across all lanes in mask.
-- func_name: __syncwarp
-  namespace: cuda-runtime
-  kind: warp-barrier
-  signature: void __syncwarp(unsigned mask = 0xFFFFFFFFu);
-  notes: Forces reconvergence of lanes in mask. Required before warp-synchronous code on CC 7.0+ (ITS).
-- func_name: __activemask
-  namespace: cuda-runtime
-  kind: warp-introspect
-  signature: unsigned __activemask();
-  notes: Returns mask of currently active lanes. Does NOT force convergence; do not use as a synchronization primitive (pitfall P4).
-- func_name: __popc
-  namespace: cuda-runtime
-  kind: intrinsic
-  signature: int __popc(unsigned x);
-  notes: 'Population count. Paired with __ballot_sync for stream compaction: __popc(mask & ((1u << laneId) - 1)) is the per-lane compact offset.'
-- func_name: __ffs
-  namespace: cuda-runtime
-  kind: intrinsic
-  signature: int __ffs(unsigned x);
-  notes: Find first set bit (1-indexed). Paired with ballot to locate the first active lane.
-- func_name: setp.CmpOp.type
-  namespace: ptx
-  kind: ptx-predicate-set
-  signature: setp.{eq,ne,lt,le,gt,ge}.{s32,u32,f32,...} p, a, b;
-  notes: Set predicate register p from comparison. Emitted by nvcc for any simple conditional.
-- func_name: selp.type
-  namespace: ptx
-  kind: ptx-predicate-select
-  signature: selp.type d, a, b, p;
-  notes: 'Select-on-predicate: d = p ? a : b. Branchless conditional move.'
-- func_name: '@{!}p instruction'
-  namespace: ptx
-  kind: ptx-predication
-  notes: Any PTX instruction can be prefixed with a predicate guard. Predicated false instructions are dispatched but produce no side effects (BP §13.2).
-- func_name: bra.uni
-  namespace: ptx
-  kind: ptx-branch
-  notes: Uniform branch — cheap, no divergence. Emitted for conditions the compiler proves are warp-uniform.
-- func_name: vote.sync.{all,any,uni,ballot}.b32
-  namespace: ptx
-  kind: ptx-warp-vote
-  notes: PTX form of the warp-vote intrinsics above.
-id: api-warp-divergence-ref
-type: api-definition
-vendor: nvidia
-architectures:
-- '*'
-func_name: Warp Divergence APIs
-namespace: runtime
-header: cuda_runtime.h
-signature: See documentation
-source_refs:
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-c-best-practices-guide/cuda_cuda-c-best-practices-guide_index.html.md
-  anchor: L1602-L1628
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L3427-L3436
-languages:
-- ptx
-- cuda-cpp
-confidence: inferred
-evidence_level: inferred
-tags:
-- ptx
-- cuda-cpp
----
-## Core APIs
-
-| API / Instruction | Layer | Purpose |
-|-------------------|-------|---------|
-| `__ballot_sync(mask, predicate)` | Runtime | Warp-wide predicate bitmask |
-| `__all_sync(mask, predicate)` | Runtime | All-lanes-true check |
-| `__any_sync(mask, predicate)` | Runtime | Any-lane-true check |
-| `__syncwarp(mask)` | Runtime | Force lane reconvergence (ITS) |
-| `__popc(x)` | Intrinsic | Population count (pairs with ballot) |
-| `__ffs(x)` | Intrinsic | First-set-bit (pairs with ballot) |
-
-## PTX-level
-
-| Instruction | Purpose |
-|-------------|---------|
-| `setp.{CmpOp}.{type}` | Set predicate register from comparison |
-| `selp.{type}` | Branchless conditional move (d = p ? a : b) |
-| `@{!}p INSTR` | Predicate guard on any PTX instruction |
-| `bra.uni LABEL` | Uniform (non-divergent) branch |
-| `vote.sync.{all,any,uni,ballot}` | Warp vote |
-
-## Cross-references
-
-- **`branch-elimination` skill** (pending migration): catalog of C++ rewrites (ternary, `fmax`, masked conditional write) that encourage predication.
-- **`warp-primitives` skill**: warp shuffle + vote used together for divergence-free warp-level algorithms.
-- **`coalescing` skill**: the pitfall P6 caveat — warp-aligning a branch can break stride-1 access.
-- **`memory-ordering` skill**: `__syncwarp` is the warp-scope analog of `__syncthreads`; memory ordering semantics documented there.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/compute/warp-divergence/pitfalls.md

@@ -1,193 +0,0 @@
----
-title: Warp Divergence — Pitfalls
-status: draft
-id: pitfall-warp-divergence
-type: pitfall
-vendor: nvidia
-architectures:
-- sm90
-- sm90a
-languages:
-- cuda-cpp
-techniques:
-- pipeline-stages
-- shared-memory-optimization
-- software-exp
-confidence: inferred
-evidence_level: inferred
-tags:
-- pipeline-stages
-- shared-memory-optimization
-- software-exp
-- cuda-cpp
----
-# Warp Divergence — Pitfalls
-
-## P1. Implicit warp-synchronous execution on Volta+ (correctness)
-
-**Symptom**: Warp shuffle or shared-memory exchange produces incorrect results on CC 7.0+ but works on CC 6.x and earlier.
-
-**Root cause**: Independent Thread Scheduling (CC 7.0+) allows diverged lanes to stay diverged after the conditional block ends. Any subsequent code that assumes the warp is "back in lockstep" may operate on the wrong set of lanes.
-
-**Fix**: Always use `_sync` variants of warp intrinsics with explicit masks (`0xFFFFFFFFu` for full warp, `__ballot_sync` for data-dependent masks). Insert `__syncwarp()` after any divergent region followed by warp-synchronous code.
-
-```cuda
-// Bad on Volta+: assumes implicit reconvergence
-if (laneId < 16) { smem[laneId] = val; }
-if (laneId >= 16) { result = smem[laneId - 16]; }       // may see stale data
-
-// Good: explicit __syncwarp() + _sync intrinsics
-if (laneId < 16) { smem[laneId] = val; }
-__syncwarp();
-if (laneId >= 16) { result = smem[laneId - 16]; }
-
-// Also good: use warp shuffle with _sync
-val = __shfl_xor_sync(0xFFFFFFFFu, val, 16);
-```
-
-**Source**: CUDA C++ Programming Guide §3.2.2.1.1 (L3427-L3436). This is a **correctness pitfall**, not a performance one — failure mode is silent data corruption.
-
-## P2. Branching on `threadIdx.x` with sub-warp granularity
-
-**Symptom**: Every warp in the block serializes its two branch bodies. NCU shows `smsp__thread_inst_executed_per_inst_executed.ratio` dropping below 32 (towards 16 for a 50/50 split).
-
-**Root cause**: Condition depends on `threadIdx.x` directly (or `threadIdx.x % k` for some `k < 32`). Every warp straddles the boundary, so every warp diverges.
-
-**Fix**: Restructure to align the condition on warp boundaries — typically by expressing it in terms of `threadIdx.x / 32` (or `>> 5`).
-
-```cuda
-// Bad: 50/50 split within each warp
-if (threadIdx.x % 2 == 0) { /* A */ } else { /* B */ }
-
-// Good: every warp picks one side
-int warpId = threadIdx.x >> 5;
-if ((warpId & 1) == 0) { /* A */ } else { /* B */ }
-```
-
-**Source**: BP Guide §12.1.2 (L1396-L1400).
-
-## P3. Early return in only some lanes of a warp
-
-**Symptom**: Adding an early-return guard (`if (i >= N) return;`) does not actually shrink the warp's runtime — the warp remains active until the last lane finishes.
-
-**Root cause**: A per-lane return does not "release" the warp; the warp's remaining lanes continue executing with the returned lanes masked off. The warp occupies an SM slot until *all* its lanes have exited.
-
-**Fix**: Structure the kernel so entire warps exit together (or the warp leader issues an early-exit vote). Use `__all_sync` to check if the whole warp has no work.
-
-```cuda
-// Ineffective: individual lanes return, warp stays resident
-if (tid >= N) return;
-process(tid);
-
-// Better: warp-wide early exit
-bool done = (tid >= N);
-if (__all_sync(0xFFFFFFFFu, done)) return;   // whole warp exits
-if (!done) process(tid);                      // surviving lanes work
-```
-
-**Source**: CUDA C++ Programming Guide §3.2.2.1 (L3427-L3436; "threads can be inactive for a variety of reasons including having exited earlier than other threads of their warp").
-
-## P4. Using `__activemask()` as a synchronization primitive
-
-**Symptom**: Subtle correctness bugs on Volta+; warp intrinsics called with the `__activemask()` result sometimes include the wrong lanes.
-
-**Root cause**: `__activemask()` reports which lanes are currently active, but makes **no guarantee** about what *will be* active when the next warp-synchronous operation executes. It is an **introspection** primitive, not a synchronization primitive.
-
-**Fix**: Use explicit masks whenever possible. If the mask must be data-dependent, compute it with `__ballot_sync` (which includes a convergence point) rather than `__activemask`.
-
-```cuda
-// Bad: using activemask as a sync primitive
-unsigned mask = __activemask();
-val = __shfl_down_sync(mask, val, 1);     // may include wrong lanes
-
-// Good: ballot has a sync, so the mask is valid at the next op
-unsigned mask = __ballot_sync(0xFFFFFFFFu, isActive);
-if (isActive) {
-    val = __shfl_down_sync(mask, val, 1);  // mask holds all through this op
-}
-```
-
-**Source**: CUDA C++ Programming Guide §5.4.6.1.
-
-## P5. Nested divergent branches causing exponential serialization
-
-**Symptom**: NCU reports warp efficiency well below 50 %; multiple divergence points stack, each roughly halving active lanes.
-
-**Root cause**: Each nested divergent `if/else` multiplies the serialization factor. Three levels of 2-way divergence can serialize to 8× (25 % SIMT efficiency) even if each individual split is 50/50.
-
-**Fix**: Flatten nested branches into a single multi-way dispatch (lookup table / switch compiled to jump table), or use predication for the innermost conditions.
-
-```cuda
-// Bad: 3 levels of nesting, up to 8x serialization
-if (condA) {
-    if (condB) {
-        if (condC) { do_ABC(); } else { do_ABnC(); }
-    }
-}
-
-// Flatten via lookup table (branchless)
-int path = (condA << 2) | (condB << 1) | condC;
-result = lookup_table[path];
-
-// Or flatten via chained predication (works for short bodies)
-float r = condA ? (condB ? (condC ? vABC : vABnC) : 0.f) : 0.f;
-```
-
-**Source**: BP Guide §12.1.2 (L1396-L1400).
-
-## P6. Warp-boundary alignment destroying memory coalescing (measured on legacy)
-
-**Symptom**: After rewriting a branch to align on warp boundaries (pitfall P2 fix), wall-clock regresses. NCU shows coalescing metrics dropping: `l1tex__t_sectors_pipe_lsu_mem_global_op_ld` per warp rises from 4 to 16.
-
-**Root cause**: The two branch bodies access interleaved addresses. When the branch was per-lane, adjacent lanes within a warp hit adjacent memory addresses (coalesced). After warp-alignment, lanes in each warp hit *strided* addresses because they're all executing the same branch body against dispersed data indices.
-
-**Fix**: Before committing to warp-alignment, check memory coalescing. If the two bodies access interleaved addresses, keep the per-lane branch and let predication handle it (S2), or restructure the data layout so the warp-aligned access pattern remains stride-1.
-
-**Measured (legacy L3 sandbox, 2026-04-06)**: warp-aligning a gather-shaped kernel destroyed coalescing and regressed wall-clock by ~15 %. Scheduled for H200 re-measurement in a follow-up probe.
-
-**Source**: KernelPilot legacy L3 sandbox run (2026-04-06). Retained as measured-on-legacy; the principle holds but the exact number needs H200 re-measurement.
-
-## P7. Warp-vote early-exit shifts bottleneck from compute to memory latency
-
-**Symptom**: After adding `if (!__any_sync(...)) return;` the kernel's SM throughput drops from 90.5 % to 44.8 %, and `stall_long_scoreboard` rises from 0.11 % to 32.1 % — making it *look* worse in NCU section view.
-
-**Root cause**: The early exit dramatically reduces total work, so the surviving warps are relatively more memory-latency-bound. Absolute wall-clock is faster, but the NCU metrics show the new bottleneck shape.
-
-**Fix**: Read the absolute duration and memory throughput, not the SOL percentage alone. A drop in SOL accompanied by a larger drop in wall-clock is a win, not a regression.
-
-**Source**: KernelPilot legacy L3 sandbox run (2026-04-06). Retained as anecdotal; the metric-interpretation lesson is general.
-
-## P8. Data compaction overhead exceeds the divergence it was meant to fix
-
-**Symptom**: Sorting / binning / stream-compaction added upstream "to eliminate divergence" makes the pipeline slower overall.
-
-**Root cause**: Compaction has its own memory traffic and launch overhead. For mild divergence (SIMT efficiency > 75 %) or small problem sizes (N < 1e5), the compaction step is pure overhead.
-
-**Fix**: Profile divergence severity before applying S4 compaction. The NCU metric is `smsp__thread_inst_executed_per_inst_executed.ratio`: only pursue compaction when it is < 24 (i.e. average active lanes < 24/32 = 75 %).
-
-**Source**: KernelPilot legacy L3 sandbox run (2026-04-06).
-
-## P10. The SIMT-efficiency NCU metric can stay at 32/32 during actual serialization (measured on H200)
-
-**Symptom**: A branching kernel is obviously paying a divergence cost (wall-clock 1.82× slower at p=0.25 than at p=0), but NCU's `smsp__thread_inst_executed_per_inst_executed.ratio` reports `32` (i.e. "perfect SIMT, no divergence") for every probability. The usual metric-based divergence hunt misses it entirely.
-
-**Root cause**: NCU counts each serialized sub-warp execution as a *distinct* issued instruction. When a warp splits 20/12 into two bodies, NCU sees (issued=2, active-threads-per-issue=32) — not (issued=1, active-threads-per-issue=16). The ratio averages to 32. What actually grew is the **total count** of issued instructions, not their per-issue fill.
-
-**Fix**: Do not rely on `smsp__thread_inst_executed_per_inst_executed.ratio` alone for divergence hunting. The authoritative signal is **wall-clock × Compute(SM) Throughput**:
-
-- If Compute(SM) Throughput is high (≥ 80 %) AND wall-clock rises after adding a branch AND total output is unchanged → divergence serialized the body. Measured on H200: compute-bound branching kernel at 89 % SOL showed 1.82× wall-clock at p ∈ (0, 1), while SIMT efficiency reported 32/32 unchanged.
-- If Compute(SM) Throughput is low → the kernel is memory-bound, divergence may be invisible in wall-clock, and the metric is honestly reporting "nothing to see here" (pitfall P7 / skill §"When NOT to use").
-
-Look at `inst_issued.avg_per_cycle_active` instead to detect doubled-issue-rate from serialization; pair with wall-clock at constant occupancy to confirm.
-
-**Source**: `sources/experience/hw-probes/warp-divergence-cost.md` (measured on H200).
-
-## P9. Mis-categorizing `__syncwarp()` as a latency optimization
-
-**Symptom**: `__syncwarp()` calls deleted from a kernel as "dead code" because they "don't do anything visible"; later, sporadic silent data corruption under heavy load.
-
-**Root cause**: `__syncwarp()` prevents correctness bugs (pitfall P1) rather than accelerating anything. Removing it looks safe in short-run tests but opens a window where ITS permits a scheduling pattern that exposes stale data.
-
-**Fix**: Treat `__syncwarp()` as a correctness primitive. Never remove one without confirming the surrounding code has no warp-synchronous dependency. The performance cost of `__syncwarp()` is one cycle on all lanes — negligible against the correctness it guarantees.
-
-**Source**: KernelPilot legacy L3 sandbox run (2026-04-06).

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/compute/warp-divergence.md

@@ -1,267 +0,0 @@
----
-title: Warp Divergence Cost & Mitigation
-status: verified
-evidence_level: measured
-cuda_version_tested: '12.9'
-driver_version_tested: 570.124.06
-toolchain: nvcc 12.9.86 + ptxas 12.9
-measured_on: H200-SXM
-applies_to_pattern_class:
-- cuda-core
-applies_to_ops:
-- elementwise
-- indexing
-- pooling
-- reduction
-- scan
-requires_sm: '>=7.0'
-requires_features:
-- independent-thread-scheduling
-single_kernel_useful: true
-source:
-- path: spec
-  anchor: Reference
-artifacts:
-  code: artifacts/experience/hw-probes/warp-divergence-cost/divergence_cost_probe.cu
-  build: artifacts/experience/hw-probes/warp-divergence-cost/build.sh
-  introspection: artifacts/experience/hw-probes/warp-divergence-cost/device.json
-  profile: ''
-related_apis:
-- __ballot_sync
-- __all_sync
-- __any_sync
-- __syncwarp
-- __activemask
-related_skills:
-- branch-elimination
-- warp-primitives
-- coalescing
-id: skill-warp-divergence
-type: skill
-vendor: nvidia
-tags:
-- cuda-cpp
-- cluster
-- kernel-fusion
-- shared-memory-optimization
-- fused-kernel
-- quantization
-applies_to:
-- general
-source_refs:
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-c-best-practices-guide/cuda_cuda-c-best-practices-guide_index.html.md
-  anchor: L1602-L1612
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-c-best-practices-guide/cuda_cuda-c-best-practices-guide_index.html.md
-  anchor: L1396-L1400
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-c-best-practices-guide/cuda_cuda-c-best-practices-guide_index.html.md
-  anchor: L1614-L1628
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L3427-L3436
-architectures:
-- sm90
-- sm90a
-languages:
-- cuda-cpp
-hardware_features:
-- cluster
-techniques:
-- kernel-fusion
-- shared-memory-optimization
-kernel_types:
-- fused-kernel
-- quantization
-confidence: experimental
-artifact_dir: artifacts/experience/hw-probes/warp-divergence-cost
----
-## What
-
-**Warp divergence** is what happens when threads of the same 32-lane warp need to execute different instructions because a branch condition evaluated differently across those threads. The hardware handles this by executing **each path serially** — lanes that take path A run while the lanes that took path B are masked off, then the paths swap. Both paths count toward instruction cost, so a fully-divergent branch costs up to the **sum** of both paths.
-
-**The bound, stated as a number:** a two-way branch costs up to 2x. The worst case
-is a warp whose 32 lanes each take a *different* path -- a `switch` on
-`threadIdx.x % 32`, or a data-dependent branch with 32 distinct outcomes. The
-hardware then walks 32 paths with one lane active in each, and SIMT efficiency
-degrades to **1/32**. That is the floor, not a typical value: real kernels almost
-never hit it, and quoting it as the cost of "having a branch" overstates the
-problem by an order of magnitude. ⚠️ *The 1/32 figure is the architectural bound
-transcribed from a guideline document, not a measurement; the measured two-path
-costs on this page are the reliable numbers.*
-
-BP §13.1 (L1602-L1612) states the rule bluntly: "Avoid different execution paths within the same warp." The quantifier that matters is **how much of the warp's work each path actually represents** — the serialization cost scales with the number of instructions in the longer path, multiplied by the number of distinct paths the warp must walk.
-
-Divergence has three relevant sub-cases, each with a different mitigation:
-
-1. **ThreadIdx-aligned divergence** — the condition depends on `threadIdx.x` and not `threadIdx.x / 32`; both paths live in the same warp. Fix: **restructure the branch to align on warp boundaries** (S1).
-2. **Short-body divergence** — both paths are small (few instructions). Fix: **let the compiler predicate it** (S2). Often happens automatically, but hostile C++ patterns (function calls inside the branch, volatile writes, `printf`) block predication — rewrite for branch-free expressions.
-3. **Data-dependent divergence** — the condition depends on input data that cannot be grouped at compile time (sparse data, graph traversal). Fix: **compact / sort / bin the data before the kernel** so each warp sees homogeneous work, or use **warp vote** for early-exit when entire warps have no work (S3 + S4).
-
-Plus one correctness wrinkle since Volta (sm_70):
-
-4. **Independent Thread Scheduling (ITS)** — diverged threads may stay diverged after the conditional block ends. Any subsequent warp-synchronous code (shuffle, smem exchange without a barrier) must use `_sync` intrinsics with explicit masks, and must call `__syncwarp()` explicitly after the divergent region (PG §3.2.2.1.1, L3427-L3436). This is a **correctness** issue, not a performance one — but failure mode is silent data corruption on CC 7.0+.
-
-## Why
-
-Divergence is cheap to detect and almost always cheap to fix; the reason it persists in real kernels is that the cost is **not visible from wall-clock alone** for kernels that are also memory-bound. The warp is often waiting on memory anyway, so a doubled instruction count on the compute side gets hidden.
-
-The cost *becomes* visible when:
-
-- The kernel is compute-bound (elementwise math, fused activations).
-- Both branch paths together exceed the memory-wait window.
-- Nested divergence multiplies: two 2-way divergent conditions can halve throughput twice, to 25 % SIMT efficiency (pitfall P5).
-
-BP §13.2 (L1614-L1628) documents the compiler's own escape hatch: predication. The compiler converts branches to predicated instructions when both paths are short enough; the hardware then runs both paths **as predicated NOPs** instead of serializing them. Predicated instructions still occupy issue slots but don't split the warp, so the warp stays at full SIMT efficiency. Understanding predication is the core of this skill — most of the time, "fix the divergence" means "let the compiler predicate it."
-
-## When to use
-
-### S1. Align branches on warp boundaries when the condition depends on threadIdx
-
-When a branch condition is `threadIdx.x < K` for some `K < blockDim.x`, and K is not a multiple of 32, every warp straddling the boundary diverges. BP §12.1.2 (L1396-L1400) gives the canonical pattern: **make the condition depend on `threadIdx.x / warpSize` instead**.
-
-```cuda
-// Bad: warp at threadIdx.x 0-31 splits 16/16
-if (threadIdx.x < blockDim.x / 2) {
-    produce(data);
-} else {
-    consume(data);
-}
-
-// Good: warp boundary aligned — every warp takes one branch cleanly
-int warpId = threadIdx.x >> 5;           // threadIdx.x / 32
-int numWarps = blockDim.x >> 5;
-if (warpId < (numWarps >> 1)) {
-    produce(data);
-} else {
-    consume(data);
-}
-```
-
-**Caveat** (pitfall P6, measured in legacy sandbox): reorganizing threads into warps by role can unalign their memory accesses. If the two branch bodies access interleaved addresses, the warp-aligned version may kill coalescing. Measure before committing.
-
-### S2. Keep short divergent bodies short so the compiler predicates them
-
-When both bodies of an `if/else` are a few instructions, prefer branch-free idioms. The compiler then emits `selp` / `@p` predicated instructions with zero divergence overhead (BP §13.2, L1614-L1628).
-
-```cuda
-// Predication-friendly: no real branch generated
-float y = (x > 0.0f) ? x : 0.0f;           // ReLU
-float z = fmaxf(x, 0.0f);                   // same, even better
-float c = condition ? a : b;                // scalar selp
-
-// Hostile to predication: forces a real branch
-if (condition) {
-    do_expensive_thing_A();                 // function call blocks predication
-} else {
-    do_expensive_thing_B();
-}
-```
-
-The threshold is documented as "a certain threshold" (BP §13.2) — empirically around 7 instructions in modern nvcc. Function calls, volatile memory ops, and side-effectful intrinsics block predication entirely. **When in doubt, inspect SASS**; `ptxas -v` reports predicated-vs-branched stats.
-
-For the pattern-level rewrite library (ReLU / clamp / abs / conditional write / masked gather), see the sibling `branch-elimination` skill — this skill covers the *why and how much it costs*; that skill covers *the catalog of rewrites*.
-
-### S3. Use warp vote functions for lane-uniform conditions
-
-If every lane in a warp is likely to agree (a per-warp-uniform condition that *might* still diverge at some warps), `__any_sync` / `__all_sync` / `__ballot_sync` turn the check into a per-warp decision at one instruction:
-
-```cuda
-// Early-exit an entire warp if no lane has work
-bool has_work = (work_indicator[tid] != 0);
-if (!__any_sync(0xFFFFFFFFu, has_work)) {
-    return;     // every lane returns together; no divergence
-}
-
-// Cheap bounds check for a multi-element-per-thread loop
-if (__all_sync(0xFFFFFFFFu, tid + n_per_thread <= N)) {
-    process_unchecked();   // full coalesced fast path
-} else {
-    process_with_bounds_checks();   // slow tail path
-}
-```
-
-`__ballot_sync` returns the full 32-bit mask, enabling warp-local work counts (`__popc`) and lane-compaction (`__popc(mask & ((1u << laneId) - 1))`).
-
-### S4. Data compaction / sorting for input-driven divergence
-
-When divergence is caused by input heterogeneity that the kernel cannot control at launch time (sparse input, irregular graph nodes, variable-length work per thread), the mitigation lives **outside the kernel**:
-
-- Sort the input so similar items land in the same warp.
-- Bin by work-class and launch one kernel per bin.
-- Run a compaction pass (`__ballot_sync` + `__popc` + stream compaction) to produce a dense homogeneous array, then launch the actual kernel on the dense array.
-
-Pitfall P8 (legacy, measured): the compaction overhead itself can dominate if the original divergence is small or the problem size is small. Always **profile divergence severity first**: `smsp__thread_inst_executed_per_inst_executed.ratio` (average active lanes per warp execution) is the NCU metric — if it's near 32, no compaction is needed.
-
-## When NOT to use
-
-- **When the kernel is memory-bound and divergence is already hidden by memory latency.** Rewriting for predication is pure churn with no wall-clock benefit. Profile first — if `stall_long_scoreboard` dominates and SIMT efficiency is >50 %, the divergence is not the bottleneck.
-- **When "fixing" divergence breaks coalescing.** Re-grouping lanes by branch role can unalign adjacent threads' memory addresses. Pitfall P6 (measured on legacy): aligning branches to warp boundaries destroyed coalescing in a gather-shaped kernel and regressed wall-clock by ~15 %.
-- **When the branch is on a truly warp-uniform scalar.** If the condition is a kernel argument or a block-wide broadcast that never differs across lanes, there is no divergence — the branch emits a `bra.uni` and costs a single instruction. Leave it alone.
-- **When pursuing predication removes side effects that matter.** Predicated loads/stores never evaluate addresses or read operands (BP §13.2), which is correct for pure-arithmetic predication but matters when the "other branch" had a memory read whose address computation had to happen. Check SASS for the actual shape.
-
-## Measured Characteristics
-
-Measured on H200-SXM (sm_90a, CUDA 12.9, driver 570.124.06) using sources/experience/hw-probes/warp-divergence-cost/ — per-lane predicate with probability `p` of taking path B; compute-bound workload (~1024 FMAs per lane per kernel, 1 M lanes, Compute SM throughput ~89 %). Unlocked clock logged at 1980 MHz. Full record: sources/experience/hw-probes/warp-divergence-cost.md.
-
-| Kernel               | p=0.00 | p=0.25 | p=0.50 | p=0.75 | p=1.00 | Slowdown vs own p=0 |
-| -------------------- | -----: | -----: | -----: | -----: | -----: | ------------------: |
-| `branch_variant`     | 0.0418 | 0.0760 | 0.0760 | 0.0760 | 0.0416 |        **1.82×**    |
-| `predicated_variant` | 0.0766 | 0.0819 | 0.0820 | 0.0819 | 0.0766 |              1.07×  |
-| `warp_uniform`       | 0.0409 | 0.0415 | 0.0415 | 0.0415 | 0.0408 |              1.01×  |
-
-Units: median ms across 20 iterations (5 warmup).
-
-Key measured findings:
-
-- **Divergence cost kicks in at ANY p ∈ (0, 1), not just p=0.5.** With 32-lane warps, the probability any single warp avoids divergence at p=0.25 is (0.75)³² ≈ 0.01 %; essentially every warp diverges and pays the full **1.82× slowdown**. The "cost curve" folklore (smooth ramp from 1× at p=0 to 2× at p=0.5) is a per-warp-averaged measure, not what wall-clock shows.
-- **Predication is flat across p** (1.00×–1.07×) but always pays the "both bodies execute" cost (absolute 0.0766 ms vs the branch's 0.0418 ms at p=0). Trade: predication eliminates p-dependence at a fixed ~1.83× compute cost. Use when p is unpredictable per-lane.
-- **`warp_uniform` (S3) at 1.01× is the upper bound** on this technique's benefit — achievable only when the "pessimistic body" cost equals the optimistic body cost. In production kernels where path B is materially heavier than path A, `warp_uniform` pays the full path-B cost on every warp that has any lane needing it.
-- **NCU `smsp__thread_inst_executed_per_inst_executed.ratio` stays at 32 across all p** for the branching kernel — this is a new pitfall (P10): the SIMT-efficiency metric that pedagogy recommends for divergence hunting can look perfect at 32/32 even when the warp is actually serializing. The authoritative signal is wall-clock at constant Compute(SM) Throughput (~89 %) — doubled wall-clock at unchanged throughput means doubled total instructions issued.
-- **Divergence cost is invisible in memory-bound kernels.** A parallel run of the same probe at N=16 M and only 64 FMAs per path showed zero slowdown across p on all three variants (memory latency hiding it). This is the empirical basis for skill §"When NOT to use" item 1.
-
-See probe record for NCU breakdown, the memory-bound vs compute-bound comparison, and the full interpretation.
-
-## Principles
-
-1. **Divergence cost is proportional to the LONGER path × the number of distinct paths taken.** A 2-way 50/50 branch doubles the cost of one side; a 4-way branch can quadruple it.
-2. **Predication is the compiler's escape hatch; stay short and side-effect-free inside branches.** Function calls, volatile writes, and printf block predication entirely.
-3. **Sub-warp branching is always worse than no branching; warp- aligned branching is usually better than sub-warp branching but not always.** Check the memory coalescing side before committing to S1 (pitfall P6).
-4. **ITS (Volta+) requires explicit `__syncwarp()` after any divergent region followed by warp-synchronous code.** This is a correctness rule, not a performance one, but the performance cost is negligible — always include the barrier.
-5. **Profile first.** If SIMT efficiency > 75 % and the kernel is memory-bound, divergence is not the bottleneck; rewriting it produces churn without wall-clock win.
-
-## Open questions
-
-- Q1. What is the exact predication threshold for `nvcc 12.9` on sm_90a? Legacy guidance says "approximately 7 instructions"; the probe opens with a compile-time sweep to land the modern number.
-- Q2. How does divergence cost interact with Hopper's thread-block- cluster scheduling? Currently no data; follow-up probe blocked on `wiki/nvidia/hardware/thread-block-cluster/` bootstrap (bucket F).
-- Q3. For the "early-exit via warp vote" idiom (S3), what fraction of warps-with-zero-work is needed for the vote-early-exit to pay back its own `__any_sync` cost? Open follow-up: `sources/experience/hw-probes/warp-vote-early-exit-amortization/`.
-
-## Legacy references
-
-- `legacy_sandbox_path`: `KernelPilot/optimization/latency/warp-divergence/skill.md`. Legacy kept five sub-skills (S1-S5); this port collapses S1+S4 of the legacy version into the measured quadrant (S1 warp-align, S4 data-compaction), keeps S2 predication / S3 warp-vote, and promotes S5 `__syncwarp()` from "skill" to a pitfall (P1 in the sibling pitfalls file) because it is a **correctness** fix, not a throughput optimization.
-- Legacy L3 sandbox findings P6-P9 are retained in `pitfalls.md` pending H200 re-measurement.
-- **Related but distinct**: `wiki/nvidia/foundations/compute/branch-elimination/` (pending migration) covers the catalog of branch-rewriting patterns; this skill covers the divergence cost model and measurement. Cross-ref is one-line in each skill's body.
-
-## Health thresholds
-
-Two numbers describe the same thing from opposite ends.
-
-```
-smsp__thread_inst_executed_per_inst_executed.ratio
-```
-
-**32 is the ceiling and it is definitional**, not measured: it is the warp
-width. A value at 32 means every lane was active on every issued instruction;
-the ratio divided by 32 is branch efficiency.
-
-| Ratio | Branch efficiency | Reads as |
-|---|---|---|
-| ~32 | ~100% | no divergence worth chasing |
-| ~29 | ~90% | the usual "acceptable" line ⚠️ **unverified** |
-| ~1 | ~3% | the 1/32 floor described above |
-
-⚠️ *The 90% line is transcribed from a guideline document and has not been
-reproduced on our own hardware. It is a convention for deciding when to stop,
-not a property of the architecture. The two numbers that are properties — 32 as
-the width and 1/32 as the floor — are marked as such above.*