@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/attention.md

@@ -1,189 +0,0 @@
----
-title: MVP Minimal Flash-Attention Kernel (TMA + wgmma, cutlass-template-free)
-status: verified
-evidence_level: measured
-applies_to_pattern_class:
-- tensor-core
-applies_to_ops:
-- attention
-requires_sm: '>=9.0a'
-requires_features:
-- wgmma
-- tma
-single_kernel_useful: true
-cuda_version_tested: 12.9.86
-driver_version_tested: 570.124.06
-toolchain: nvcc 12.9 + ptxas 12.9
-measured_on: H200-SXM | sm_90a | cuda 12.9.86 | driver 570.124.06
-source:
-- path: sources/experience/hw-probes/wgmma-ptx.md
-  anchor: wgmma PTX inline-asm pattern reused for attention Q@K^T and P@V tiles
-- path: sources/experience/hw-probes/tma-ptx.md
-  anchor: TMA load PTX pattern reused for Q/K/V tile loads
-- path: sources/experience/api-probes/attention.md
-  anchor: flash_attn_tma_wgmma_kernel — TMA+wgmma online-softmax attention
-artifacts:
-  code: artifacts/experience/api-probes/attention/flash_attn_tma_wgmma.cu
-  build: artifacts/experience/api-probes/attention/build.sh
-  introspection: artifacts/experience/api-probes/attention/device.json
-  profile: artifacts/experience/api-probes/attention/tma-wgmma-ncu.csv
-related_apis: []
-related_skills:
-- compute/attention/cutlass-fmha
-upstream_repo: none (hand-built from TMA + wgmma primitives)
-id: skill-attention
-type: skill
-vendor: nvidia
-tags:
-- cuda-cpp
-- wgmma
-- tma
-- shared-memory-optimization
-- swizzling
-- software-exp
-- conditional-rescaling
-- attention
-- gemm
-- flash-attention
-- ptx
-applies_to:
-- general
-source_refs:
-- source_id: source-code/cutlass
-  path: examples/88_hopper_fmha/88_hopper_fmha.cu
-  anchor: Hopper FMHA example — used as algorithmic reference only, not as code dependency
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-hardware_features:
-- wgmma
-- tma
-techniques:
-- shared-memory-optimization
-- swizzling
-- software-exp
-- conditional-rescaling
-kernel_types:
-- attention
-- gemm
-- flash-attention
-confidence: experimental
-artifact_dir: artifacts/experience/api-probes/attention
----
-# MVP Minimal Flash-Attention Kernel
-
-## What it is
-
-A hand-built flash-attention kernel that computes scaled dot-product attention `softmax(QK^T / sqrt(d)) * V` using TMA for tile loads and wgmma for both matmuls, without depending on cutlass FMHA templates. This mirrors the existing "aligned GEMM minimal kernel" pattern but for the attention operator.
-
-**Status**: `verified` / `measured` — the TMA+wgmma kernel (`flash_attn_tma_wgmma.cu`) passes correctness on H200 with `max_abs_err = 0.000061` (well within 1e-2 tolerance), 0 mismatches out of 16384 elements, and `compute-sanitizer memcheck: 0 errors`. Kernel time: 0.024 ms at B=1 H=2 S=128 D=64. Uses canonical CUTLASS smem layout (Layout_K_SW128_Atom with Swizzle<3,4,3> + CU_TENSOR_MAP_SWIZZLE_128B). A thread-level reference kernel (`flash_attn_minimal.cu`) is also provided as a secondary correctness baseline.
-
-The kernel implements the FlashAttention-2 online softmax algorithm:
-1. Load Q tile from HBM via TMA (`cp.async.bulk.tensor.2d`) into smem
-2. For each K/V tile along the sequence dimension:
-   a. Load K tile via TMA into smem
-   b. Compute `S = Q @ K^T` using wgmma m64n16k16 (f16 inputs, f32 accumulator), iterating over K and N groups
-   c. Scatter S from wgmma output registers to smem
-   d. Apply online softmax in smem: track running max and running sum, rescale previous O accumulator
-   e. Load V tile via TMA into smem
-   f. Compute `O += softmax(S) @ V` using wgmma m64n16k16
-3. Final normalization and writeback O to global memory
-
-## Algorithmic skeleton
-
-```
-HOST: create CUtensorMap for Q, K, V (2D: fastest=HD, slow=BH*S)
-
-DEVICE (1 warpgroup = 128 threads):
-for each batch b, head h:
-    for each Q-tile (rows [qStart..qStart+BLOCK_M)):
-        TMA-load Q[b,h,qStart:qStart+BM, :] → Q_smem
-        init: O_acc[4][8] = 0, rmax = -inf, rsum = 0
-
-        for each KV-tile (cols [kvStart..kvStart+BLOCK_N)):
-            TMA-load K[b,h,kvStart:kvStart+BN, :] → KV_smem
-
-            // wgmma: S = Q_smem @ K_smem^T
-            wgmma.fence
-            for ng in 0..3:  // 4 N-groups of 16
-                for k in 0..3:   // 4 K-tiles of 16
-                    descA = Q_smem[:, k*16], descB = K_smem[ng*16:, k*16:]
-                    wgmma.mma_async m64n16k16 S_acc[ng] += A × B  (transA=0, transB=0)
-            wgmma.commit; wgmma.wait
-
-            // scatter S from registers to S_smem (f32)
-            // thread-level softmax in S_smem → P_smem (f16)
-            // rescale O_acc per owned rows
-
-            TMA-load V[b,h,kvStart:kvStart+BN, :] → KV_smem
-
-            // wgmma: O_acc += P_smem @ V_smem
-            wgmma.fence
-            for ng in 0..3:
-                for k in 0..3:
-                    descA = P_smem[:, k*16], descB = V_smem[k*16:, ng*16:]
-                    wgmma.mma_async m64n16k16 O_acc[ng] += A × B  (transA=0, transB=1)
-            wgmma.commit; wgmma.wait
-
-        O_acc /= rsum; global-store O
-```
-
-## Tuning parameters
-
-See `tuning.md` for the full parameter space. Fixed config for MVP:
-- `BLOCK_M` = 64 (matches wgmma M=64)
-- `BLOCK_N` = 64
-- `HEAD_DIM` = 64
-- `NTHREADS` = 128 (1 warpgroup)
-
-## Measured Characteristics
-
-H200-SXM, sm_90a, cuda 12.9.86, driver 570.124.06. fp16 inputs, f32 accumulator.
-
-**Correctness gate**: `max_abs_err = 0.000061` at B=1, H=2, S=128, D=64, 0/16384 mismatches (>1e-2). `compute-sanitizer memcheck: 0 errors`. Disposition: **Passed**.
-
-**Timing**: kernel_ms = 0.024 at B=1, H=2, S=128, D=64 (12.4x faster than thread-level reference at same config: 0.298 ms).
-
-**Throughput**: 0.35 TFLOPS (total_flops = 4×1×2×128²×64 = 8.39M FLOPs). Far below H200 peak (~989 TFLOPS) due to tiny problem size (2 CTAs on 132 SMs).
-
-**ncu profiler metrics** (representative run at B=1 H=2 S=128 D=64):
-
-| Metric | Value | Notes |
-|--------|-------|-------|
-| Throughput | 0.35 TFLOPS | 8.39M FLOPs / 0.024 ms |
-| HBM bandwidth | 5.15 GB/s (0.11% of 4800 GB/s peak) | 123,648 B read / 0.024 ms |
-| SM utilization | 2.75% peak active cycles | Extreme under-utilization at this size |
-| SM throughput | 0.20% peak | |
-| Active warps | 6.25% peak sustained | Single warpgroup per CTA |
-| Tensor ops (hmma) | 1,024 instructions | 32 wgmma calls |
-
-Evidence:
-- Primary probe: 2026-05-08-mvp-attention-tma-wgmma.md
-- ncu CSV: `artifacts/experience/api-probes/attention/tma-wgmma-ncu.csv`
-- Correctness log: `artifacts/experience/api-probes/attention/tma-wgmma-correctness.log`
-- Sanitizer log: `artifacts/experience/api-probes/attention/tma-wgmma-sanitizer.log`
-
-Secondary thread-level reference:
-- Probe record: sources/experience/api-probes/attention.md
-- Tuning sweep: sources/experience/hw-probes/attention-tuning.md
-
-## When to use it
-
-- Learning how flash-attention works at the TMA + wgmma primitive level.
-- As a starting point for custom attention patterns without cutlass templates.
-- Correctness reference for cutlass FMHA or FlashAttention v3.
-
-## When NOT to use it
-
-- Production attention: use cutlass FMHA or FlashAttention v3 for optimized performance.
-- Non-Hopper targets: this kernel requires sm_90a (TMA + wgmma).
-
-## How it connects to the rest of the KB
-
-- Builds on `wiki/nvidia/hardware/wgmma-ptx/` (wgmma PTX patterns) and `wiki/nvidia/hardware/tma-ptx/` (TMA load patterns).
-- Complemented by `wiki/nvidia/foundations/compute/attention/cutlass-fmha/` (cutlass's production FMHA).
-- Compared against FlashAttention v3 at `wiki/nvidia/code-walkthroughs/flash-attention-v3/`.
-- Tuning parameter space: tuning.md.

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

@@ -1,158 +0,0 @@
----
-title: Branch Elimination APIs
-status: draft
-source:
-- path: spec
-  anchor: Reference
-apis:
-- func_name: fmaxf
-  namespace: cuda-runtime
-  kind: fp32-minmax
-  signature: float fmaxf(float x, float y);
-  notes: 'Single-precision max. PTX `max.f32` → SASS `FMNMX` (1 instruction). Measured on H200 sm_9.0a: 14.02 ns/op in the branchless-patterns probe — 1.56x faster than the equivalent `if/else` form which emits FSETP+FSEL (2 SASS ops). The canonical branchless-ReLU implementation.'
-- func_name: fminf
-  namespace: cuda-runtime
-  kind: fp32-minmax
-  signature: float fminf(float x, float y);
-  notes: Single-precision min. PTX `min.f32` → SASS `FMNMX` (with min flag). Same 1-op SASS lowering as `fmaxf`. Use `fminf(fmaxf(x, lo), hi)` for branchless clamp (2 FMNMX ops).
-- func_name: fabsf
-  namespace: cuda-runtime
-  kind: fp32-bitwise
-  signature: float fabsf(float x);
-  notes: 'Single-precision absolute value. PTX `abs.f32` → SASS `LOP3.LUT` (1 instruction, IEEE sign-bit mask). Measured on H200 sm_9.0a: 9.27 ns/op, 2.36x faster than the `if (x<0) x=-x` form and 1.51x faster than explicit bit-trick `b & 0x7FFFFFFF`.'
-- func_name: copysignf
-  namespace: cuda-runtime
-  kind: fp32-bitwise
-  signature: float copysignf(float x, float y);
-  notes: 'Returns `x` with the sign of `y`. Expected to lower to a single LOP3.LUT (bit-level sign transplant); not re-measured by the branchless-patterns probe. The branchless equivalent of `(y < 0) ? -fabsf(x) : fabsf(x)`.'
-- func_name: __fmaxf
-  namespace: cuda-runtime
-  kind: fp32-minmax-intrinsic
-  signature: float __fmaxf(float x, float y);
-  notes: Identical PTX / SASS lowering to `fmaxf` on sm_9.0a (both emit `max.f32` / `FMNMX`). The `__` prefix marks it as the CUDA-intrinsic form; no behavioural difference on modern archs.
-- func_name: __fminf
-  namespace: cuda-runtime
-  kind: fp32-minmax-intrinsic
-  signature: float __fminf(float x, float y);
-  notes: Identical PTX / SASS lowering to `fminf` on sm_9.0a. See `__fmaxf` above.
-- func_name: max
-  namespace: cuda-runtime
-  kind: template-minmax
-  signature: template<typename T> T max(T a, T b);
-  notes: 'CUDA overload resolution: `max(float, float)` lowers to `fmaxf` / `FMNMX`; `max(int, int)` lowers to PTX `max.s32` / SASS `IMNMX`. Avoid implicit conversions that round-trip through fp — call the typed form directly.'
-- func_name: min
-  namespace: cuda-runtime
-  kind: template-minmax
-  signature: template<typename T> T min(T a, T b);
-  notes: As above but min. `min(int, int)` → `IMNMX`; `min(float, float)` → `FMNMX`.
-- func_name: __int_as_float
-  namespace: cuda-runtime
-  kind: bit-cast
-  signature: float __int_as_float(int x);
-  notes: Reinterpret-cast int bit pattern as float. Zero-cost at SASS (no instruction emitted; register alias). Used in hand-coded bit tricks.
-- func_name: __float_as_int
-  namespace: cuda-runtime
-  kind: bit-cast
-  signature: int __float_as_int(float x);
-  notes: Reverse of `__int_as_float`. Also zero-cost. Pair of casts lets you do integer ops on the fp bit pattern; but measured on H200, explicit bit-trick paths emit more SASS ops (LOP3.LUT ×2) than the intrinsic form (LOP3.LUT ×1) — use the intrinsic whenever possible.
-- func_name: max.f32
-  namespace: ptx
-  kind: ptx-fp32-max
-  signature: max.f32 d, a, b;
-  notes: PTX single-precision max. Lowers to SASS `FMNMX` (1 instruction). Emitted from `fmaxf` / `__fmaxf` / `max(float,float)`.
-- func_name: min.f32
-  namespace: ptx
-  kind: ptx-fp32-min
-  notes: PTX fp32 min. SASS `FMNMX` with min flag.
-- func_name: abs.f32
-  namespace: ptx
-  kind: ptx-fp32-abs
-  notes: PTX fp32 absolute value. SASS `LOP3.LUT` (1 instruction, IEEE sign-bit mask). Emitted from `fabsf`.
-- func_name: selp.f32
-  namespace: ptx
-  kind: ptx-predicated-select
-  signature: selp.f32 d, a, b, p;
-  notes: 'Predicated select: `d = p ? a : b`. Emitted from simple-body `if/else` and ternary expressions. SASS `FSEL` (1 instruction). This is why C-source ''branches'' in simple contexts are already branchless at SASS on H200 sm_9.0a.'
-- func_name: selp.b32
-  namespace: ptx
-  kind: ptx-predicated-select-integer
-  notes: Integer variant of `selp`. Same SASS lowering (`SEL` / `FSEL` family).
-- func_name: FMNMX
-  namespace: sass
-  kind: sass-fp32-minmax
-  notes: H200 SASS opcode for fp min / max. Encodes comparison + select in one instruction. Emitted from PTX `max.f32` / `min.f32`.
-- func_name: FSEL
-  namespace: sass
-  kind: sass-predicated-select
-  notes: H200 SASS predicated-select. Emitted from PTX `selp` — the hardware instruction behind `if/else` and ternary rewrites for simple bodies.
-- func_name: FSETP.GEU.AND
-  namespace: sass
-  kind: sass-fp-setp
-  notes: H200 SASS floating-point compare (producing a predicate). Paired with `FSEL` in the 2-op emission from `if (x<0) y = 0;` ReLU form. Not needed when the intrinsic `fmaxf` is used (that's a single FMNMX).
-- func_name: LOP3.LUT
-  namespace: sass
-  kind: sass-3-input-logic
-  notes: H200 SASS 3-input bitwise LUT — can compute any 3-input boolean with an 8-bit truth table. Used by `fabsf` (1 LOP3) for IEEE sign-bit mask; also emitted from explicit bit-tricks (typically ×2 because the round-trip through int registers prevents fusion).
-id: api-branch-elimination-ref
-type: api-definition
-vendor: nvidia
-func_name: Branch Elimination 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-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L25650-L25760
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/parallel-thread-execution/cuda_parallel-thread-execution_index.html.md
-  anchor: L6800-L6950
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-techniques:
-- register-budgeting
-- kernel-fusion
-kernel_types:
-- fused-kernel
-confidence: inferred
-evidence_level: inferred
-tags:
-- register-budgeting
-- kernel-fusion
-- fused-kernel
-- ptx
-- cuda-cpp
----
-## Core rewrite intrinsics (H200 sm_9.0a, measured)
-
-| C-source form | Intrinsic | PTX | SASS | ns/op |
-|---------------|-----------|-----|------|------:|
-| `x < 0 ? 0 : x` | `fmaxf(x, 0)` | `max.f32` | `FMNMX` | 14.0 |
-| `if (x<0) x=-x` | `fabsf(x)` | `abs.f32` | `LOP3.LUT` | 9.3 |
-| `cond ? a : b` | *no intrinsic needed* | `selp.f32` | `FSEL` | ~22 |
-
-## Rewrite-pattern decision table
-
-| C-source pattern | Compiler emits | Right form on H200 |
-|-------------------|----------------|--------------------|
-| `if (x < c) y = 0; else y = x;` | `FSETP + FSEL` (2 ops) | Use `fmaxf(x, c)` for 1 FMNMX |
-| `if (x < 0) x = -x;` | `FSETP + FSEL` (2-3 ops) | Use `fabsf(x)` for 1 LOP3.LUT |
-| `if (cond) acc = v;` | `FSEL` (1 op) | Already optimal — keep as-is |
-| `acc = cond ? a : b;` | `FSEL` (1 op) | Already optimal — keep as-is |
-| `acc * (1-c) + v*c` | `FFMA×2 + FMUL + FADD` (4 ops) | **Anti-pattern** — rewrite as ternary |
-| `b & 0x7FFFFFFF` (bit-abs) | `LOP3.LUT ×2` (2 ops) | Use `fabsf(x)` for 1 LOP3.LUT |
-
-## Cross-references
-
-- **`warp-divergence` skill** (warp-divergence): cost model for *real* divergence when the branch body is non-predicable. The branchless-patterns probe measures the *predicable* regime where the compiler emits `FSEL` automatically; warp-divergence measures what happens when it cannot.
-- **`fast-math` skill**: `-use_fast_math` affects fp32 transcendentals but not min/max/abs. The intrinsics in this skill are always-on regardless of the flag.
-- **`compiler-hints` skill**: `__restrict__` / `__launch_bounds__` interact with predication — tight register budgets can cause the compiler to emit branches where it otherwise would predicate. Measure via `cuobjdump --dump-sass | grep BRA` if performance surprises you.
-
-## Related Probes
-
-- sources/experience/hw-probes/branchless-patterns.md — 10-variant SASS-audited probe. Load-bearing findings: `fmaxf` is 1.56× the `if/else` form, `fabsf` is 2.36×, `cond-arith` is 1.27× *slower* than the ternary form.
-- sources/experience/hw-probes/warp-divergence-cost.md — the real-divergence cost companion measurement.

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

@@ -1,82 +0,0 @@
----
-title: Branch Elimination — Pitfalls
-status: verified
-related_skill: wiki/nvidia/foundations/compute/branch-elimination/skill.md
-source:
-- path: spec
-  anchor: Reference
-experience_refs:
-- sources/experience/hw-probes/branchless-patterns.md
-id: pitfall-branch-elimination
-type: pitfall
-vendor: nvidia
-source_refs:
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/parallel-thread-execution/cuda_parallel-thread-execution_index.html.md
-  anchor: L6800-L6950
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-confidence: inferred
-evidence_level: inferred
-tags:
-- ptx
-- cuda-cpp
----
-All pitfalls below are grounded either in the branchless-patterns probe 2026-04-23 (10-variant SASS audit) or in the PTX ISA documentation cited in the skill's frontmatter. None is anecdotal.
-
-## P1. Arithmetic simulation of select is slower than `if/else` / ternary
-
-**Symptom**: Replacing `if (cond) acc = v;` with `acc = acc * (1 - cond) + v * cond;` (or a similar FMA-based "branchless" rewrite) makes the kernel measurably slower instead of faster.
-**Detection**: On H200 sm_9.0a the measured per-iter cost for `cond-arith` is **28.67 ns/op** vs **22.63 ns/op** for the `if/else` and ternary forms — 1.27× slower. SASS audit confirms the arithmetic form emits `FFMA ×2 + FMUL + FADD` (4 ops) while the `if/else` form already lowers to a single `FSEL`.
-**Fix**: Use the plain `if/else` or ternary form. The compiler pattern-matches simple-body conditionals to `FSEL` automatically; there is no branch to eliminate at the SASS level.
-**Source**: branchless-patterns probe 2026-04-23, SASS audit.
-
-## P2. Bit-trick `abs` / `relu` is not faster than the intrinsic
-
-**Symptom**: Hand-coded bit-twiddling like `__int_as_float(__float_as_int(x) & 0x7FFFFFFF)` for absolute value is not faster — and can be slower — than `fabsf(x)`.
-**Detection**: Measured on H200 sm_9.0a: `fabsf` takes 9.27 ns/op (single `LOP3.LUT`); the explicit bit-trick takes 14.02 ns/op (two `LOP3.LUT`). The bit-trick is 1.51× slower than the intrinsic because the int↔float round-trip through integer registers prevents the compiler from fusing the mask into a single opcode.
-**Fix**: Use `fabsf(x)` / `fmaxf(x, 0.0f)` etc. Modern compilers generate the tightest SASS for the intrinsic; hand bit tricks compete against the compiler's output and typically lose.
-**Source**: branchless-patterns probe 2026-04-23, SASS audit.
-
-## P3. `if/else` with a non-trivial body blocks predication
-
-**Symptom**: The compiler emits a real branch (visible as `BRA` in SASS) instead of `FSEL`, and a divergent warp pays the full serialization cost.
-**Detection**: `cuobjdump --dump-sass <binary> | grep -c BRA` shows more than the expected count (per-kernel epilogue contributes a few BRA; inner-loop BRA is the red flag). If wall-clock regresses when `cond` is made lane-variant, the body is divergence-sensitive.
-**Fix**: Simplify the per-arm body. Move function calls, memory stores, and long expression chains *out* of the branch; compute the value unconditionally in registers, then use a final `FSEL` (ternary or `if` with a register assignment):
-
-```cuda
-// BAD — real branch, divergence-sensitive:
-if (cond) dst[i] = expensive_helper(x, y, z);
-
-// GOOD — one unconditional compute, one FSEL:
-float v = expensive_helper(x, y, z);
-dst[i] = cond ? v : dst[i];
-```
-
-The trade-off is a small amount of wasted compute on lanes that will ignore `v`; usually worth it when the helper is cheap. If the helper is expensive, consider warp-vote (`__any_sync`, `__all_sync`) to short-circuit uniform-false warps — see the `warp-divergence` skill.
-**Source**: PTX ISA §selp / §bra (predication fallback conditions).
-
-## P4. `fmaxf` and `fminf` do not protect against NaN the same way
-
-**Symptom**: `fmaxf(NaN, x)` returns `x` (NaN is "quiet" and the other operand wins); `fminf(NaN, x)` returns `x` too. This differs from C++ `std::max` / `std::min` which are unordered-aware in different ways.
-**Detection**: Kernel output contains unexpected non-NaN values downstream of an op on partially-NaN data.
-**Fix**: If NaN propagation matters, either pre-check with `isnan(x)` or do the compare explicitly. For most ML/kernel workloads with well-defined inputs this is not a concern — but be aware of the semantic.
-**Source**: PG §Standard Math Functions (IEEE 754 behaviour of the `fmax/fmin` family).
-
-## P5. The compiler's if-conversion threshold is version-dependent
-
-**Symptom**: A kernel that emitted `FSEL` under CUDA 12.4 emits `BRA` under CUDA 12.9 (or vice versa), and a performance regression appears in a minor toolkit bump.
-**Detection**: Compare `cuobjdump --dump-sass` output between toolkit versions for the same source; diff the presence/absence of `BRA` in the inner loop.
-**Fix**: If a specific branch MUST be predicated for performance, make the body unambiguously simple (scalar register assignment, no function calls, no store). A body that is 1-2 arithmetic ops is almost always predicated. A body that calls another function will often not be predicated.
-**Source**: Empirical observation; ptxas if-conversion heuristics are not publicly specified. branchless-patterns probe 2026-04-23 verified ptxas 12.9 predicates the 3 simple-body patterns on sm_9.0a.
-
-## P6. "Branchless" is a misleading label
-
-**Symptom**: Code review / tutorials frame rewrites like `acc * mask + v * (1-mask)` as "branchless optimizations" that "avoid the branch penalty". This framing leads developers to rewrite already-fast code into slower code.
-**Detection**: Any time you see a claim that a bitwise / arithmetic form is faster "because it avoids branching", check the SASS. On H200 sm_9.0a with simple bodies, the `if/else` form usually already emits `FSEL` and is byte-identical to the ternary form. A "branchless" rewrite that adds arithmetic ops is a pessimization.
-**Fix**: Think in SASS op counts, not branch counts. The right question is "does my rewrite emit fewer SASS instructions than the compiler's output for the `if/else` form?" — not "does my rewrite eliminate a branch?".
-**Source**: branchless-patterns probe 2026-04-23. The skill body documents the specific op-count relationships.

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

@@ -1,227 +0,0 @@
----
-title: Branch Elimination (predicated patterns + intrinsic-first rewrites)
-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
-- reduction
-- normalization
-applies_to_dtypes:
-- fp32
-- fp16
-- bf16
-- int32
-requires_sm: '>=7.0'
-requires_features:
-- selp
-- fsel
-single_kernel_useful: true
-source:
-- path: spec
-  anchor: Reference
-artifacts:
-  code: artifacts/experience/hw-probes/branchless-patterns/branchless_patterns_probe.cu
-  build: artifacts/experience/hw-probes/branchless-patterns/build.sh
-  introspection: artifacts/experience/hw-probes/branchless-patterns/device.json
-  profile: ''
-related_apis:
-- fmaxf
-- fminf
-- fabsf
-- copysignf
-- __fmaxf
-- __fminf
-- max.f32
-- min.f32
-- abs.f32
-- selp.f32
-- selp.b32
-related_skills:
-- warp-divergence
-- fast-math
-- compiler-hints
-experience_refs:
-- sources/experience/hw-probes/branchless-patterns.md
-id: skill-branch-elimination
-type: skill
-vendor: nvidia
-tags:
-- cuda-cpp
-- kernel-fusion
-- fused-kernel
-- ptx
-applies_to:
-- general
-source_refs:
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L25650-L25760
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/parallel-thread-execution/cuda_parallel-thread-execution_index.html.md
-  anchor: L6800-L6950
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-techniques:
-- kernel-fusion
-kernel_types:
-- fused-kernel
-confidence: experimental
-artifact_dir: artifacts/experience/hw-probes/branchless-patterns
----
-## What
-
-Branch elimination on H200 sm_9.0a is **not what the folklore teaches**. The conventional framing is "rewrite `if/else` as arithmetic to avoid a branch" — but on sm_9.0a the compiler pattern-matches simple-body `if/else` and ternary expressions to `FSEL` (the SASS predicated-select instruction) during codegen. These so-called "branches" are already branchless at the hardware level. The real distinction that matters on H200 is **how many SASS ops** each C-source pattern emits, because wall-clock at compute-bound scales with op count, not branch count.
-
-This skill is therefore a **catalog of rewrites ordered by measured SASS op count**, not a catalog of "branchless" replacements. The three canonical patterns plus their measured op counts on H200 are:
-
-- **ReLU / clamp-to-zero** (`max(x, 0)`): `if/else` and ternary → `FSETP + FSEL` (2 ops); `fmaxf` → `FMNMX` (1 op). Measured **1.56× speedup** from using `fmaxf`.
-- **Absolute value** (`|x|`): `if (x<0) x=-x` → `FSETP + FSEL` (2 ops, with `-x` fused into FSEL); `fabsf` → `LOP3.LUT` (1 op, IEEE sign-bit mask); explicit bit-trick → `LOP3.LUT ×2` (2 ops, inefficient). Measured **2.36× speedup** from using `fabsf`.
-- **Conditional register assignment** (`acc = cond ? a : b`): `if/else` and ternary → `FSEL` (1 op, already optimal); arithmetic simulation `a*(1-c) + b*c` → `FFMA×2 + FMUL + FADD` (4 ops). The arithmetic form is **1.27× slower**.
-
-## Why
-
-Two reasons this skill exists as a pattern catalog rather than a "always use branchless" doctrine:
-
-1. **Intrinsics (`fmaxf`, `fabsf`, `fminf`, `copysignf`) emit fewer SASS ops than the `if/else` form**, and fewer ops at compute-bound scale directly with fewer wall-clock ns. This is the real win — not branch elimination per se, but op-count reduction through hardware-provided primitives.
-2. **Arithmetic simulations of select (`a*(1-c) + b*c`) are strictly worse than the `if/else` form** because FSEL is already a one-op SASS primitive; adding 4 FP ops to "avoid a branch" that doesn't exist at SASS is a net loss. This is a common anti-pattern the skill exists to warn against.
-
-The related but distinct concern — **real branch divergence from non-predicable bodies** (function calls, long compute chains in each arm) — is covered by the sibling `warp-divergence` skill. That cost is real and large (measured 1.82× at compute-bound in that probe). This skill covers only the simple-body rewrites where `FSEL` emission is automatic.
-
-## When to use
-
-### S1. Use `fmaxf` / `fminf` for clamp — 1.56× faster than `if/else`
-
-Any "max against a constant" or "min against a constant" pattern should use the intrinsic, not the ternary or `if/else` form. Measured on H200:
-
-```cuda
-// 2 SASS ops (FSETP + FSEL) — 21.87 ns/op in the probe harness:
-y = (x < 0.0f) ? 0.0f : x;
-y = x < 0.0f ? 0.0f : x;
-if (x < 0.0f) y = 0.0f; else y = x;
-
-// 1 SASS op (FMNMX) — 14.02 ns/op, 1.56× faster:
-y = fmaxf(x, 0.0f);
-```
-
-Same applies for `min(x, upper)` and for full `clamp(x, lo, hi)` built as `fminf(fmaxf(x, lo), hi)` (2 FMNMX ops).
-
-### S2. Use `fabsf` for absolute value — 2.36× faster than `if/else`, 1.51× faster than bit trick
-
-`fabsf` emits a single `LOP3.LUT` doing the IEEE sign-bit mask. The `if (x<0) x=-x` form emits `FSETP + FSEL` (2 ops). The hand-coded bit trick `__int_as_float(__float_as_int(x) & 0x7FFFFFFF)` emits `LOP3.LUT ×2` (2 ops — the round-trip through integer registers is not fused). `fabsf` is strictly best.
-
-```cuda
-// 2-3 SASS ops (FSETP + FSEL, possibly + FNEG) — 21.85 ns/op:
-if (x < 0.0f) x = -x;
-
-// 2 SASS ops (LOP3.LUT ×2) — 14.02 ns/op, 1.56× faster:
-x = __int_as_float(__float_as_int(x) & 0x7FFFFFFF);
-
-// 1 SASS op (LOP3.LUT) — 9.27 ns/op, 2.36× faster than branch, 1.51× faster than bit-trick:
-x = fabsf(x);
-```
-
-### S3. For conditional register assign, use the form that reads clearest — `if/else`, ternary, and `selp` are all 1 SASS op
-
-`FSEL` is already one SASS op. Writing `if (cond) acc = v;` or `acc = cond ? v : acc;` both pattern-match to `FSEL` at codegen. Do **not** replace them with arithmetic (`acc * (1-c) + v * c`) — that form emits 4 FP ops (FFMA ×2 + FMUL + FADD) and measured **1.27× slower** on H200.
-
-```cuda
-// 1 SASS op (FSEL) — 22.63 ns/op. Read-clearest form; pick whichever is cleanest for context:
-if (cond) acc = v;
-acc = cond ? v : acc;
-
-// 4 SASS ops — 28.67 ns/op, 1.27× slower. DO NOT USE:
-float c = static_cast<float>(cond);
-acc = acc * (1.0f - c) + v * c;
-```
-
-The exception is when the body of each arm is **non-trivial** (function call, long chain of ops) — in that case the compiler cannot pattern-match to `FSEL`, a real branch is emitted, and divergence cost applies. See the `warp-divergence` skill for the measurement (1.82× at compute-bound, non-predicable body). But for simple assignments like these three forms above, FSEL emission is reliable and all three are equivalent.
-
-### S4. When the compiler will NOT emit `FSEL` — force it with a simpler body
-
-If the compiler emits a real branch (you can verify via `cuobjdump --dump-sass | grep BRA`), it is usually because the body is too complex — function call, long expression, store to memory, etc. To force predication, rewrite the body to a scalar value:
-
-```cuda
-// Compiler may emit real branch — heavy body blocks predication:
-if (cond) {
-    dst[i] = complicated_helper(x, y, z);
-}
-
-// Predicate-friendly: compute the value unconditionally, select:
-float v = complicated_helper(x, y, z);        // always compute
-dst[i] = cond ? v : dst[i];                   // 1 FSEL
-```
-
-This trades some wasted compute for guaranteed predication. The trade-off is usually worth it when `complicated_helper` is cheap; see pitfall P1.
-
-## When NOT to use
-
-- **When the branch body is non-trivial AND most lanes take the same arm.** If a warp is uniform or near-uniform, the hardware early-exits the inactive arm and divergence cost is minimal. Branchless rewrites with unconditional compute then waste work on the majority of lanes for no win. See pitfall P2.
-- **When the arithmetic rewrite adds ops** — as demonstrated by cond-arith at 1.27× slower, writing `a*(1-c) + b*c` is worse than the `if/else` form the compiler already lowers to `FSEL`. Measure instruction count, not branch count.
-- **When hoping to avoid a divergence penalty that does not exist.** If the body is already predication-friendly, `FSEL` is emitted and there is no divergence penalty to avoid. Re-writing solely for "branchless-ness" is a common no-op.
-
-## Measured Characteristics
-
-Measured on H200-SXM (sm_9.0a, CUDA 12.9, driver 570.124.06) using sources/experience/hw-probes/branchless-patterns/ — 10 variants × 3 pattern families, compute-bound 4-chain ILP × 1024 inner iters harness, lane-variant input so branchful variants would see worst-case 50% divergence if the compiler had actually emitted branches. Full record: sources/experience/hw-probes/branchless-patterns.md.
-
-### Per-iter cost on one SM chain
-
-| Variant | ns / op | vs in-group branch |
-|---------|--------:|-------------------:|
-| relu-branch / relu-ternary | 21.87 | 1.00× |
-| **relu-fmaxf** | **14.02** | **1.56×** |
-| relu-bittrick | 22.34 | 0.98× |
-| abs-branch | 21.85 | 1.00× |
-| **abs-fabsf** | **9.27** | **2.36×** |
-| abs-bittrick | 14.02 | 1.56× |
-| cond-branch / cond-ternary | 22.63 | 1.00× |
-| **cond-arith** | **28.67** | **0.79× (slower)** |
-
-### PTX / SASS emission (verified 2026-04-23)
-
-| Pattern | C-source form | PTX | SASS |
-|---------|---------------|-----|------|
-| ReLU | `if/else` or ternary | `setp.lt.f32 + selp.f32` | `FSETP.GEU.AND + FSEL` |
-| ReLU | `fmaxf(x, 0)` | `max.f32` | `FMNMX` |
-| ReLU | `__int_as_float(b & ~(b>>31))` | `shr.s32 + and.b32 + and.b32` | `SHF.R.S32.HI + LOP3.LUT ×2` |
-| abs  | `if/else -x` | `setp + selp + neg` | `FSETP.GEU.AND + FSEL` (neg fused) |
-| abs  | `fabsf(x)` | `abs.f32` | `LOP3.LUT` |
-| abs  | `b & 0x7FFFFFFF` | `and.b32` | `LOP3.LUT ×2` |
-| cond | `if/else` or ternary | `selp.f32` | `FSEL` |
-| cond | `acc*(1-c) + v*c` | `fma.rn.f32 ×2 + sub + mul` | `FFMA ×2 + FMUL + FADD` |
-
-Key measured findings:
-
-- **"If/else" is NOT a branch at SASS** for simple-body conditionals on sm_9.0a. Compiler emits `FSEL` reliably. C-source style (`if/else` vs ternary) is cosmetic.
-- **`fmaxf` / `fabsf` win by emitting fewer SASS ops, not by "avoiding branches".** Single-op `FMNMX` / `LOP3.LUT` vs 2-3 ops for the `if/else` path.
-- **Bit tricks are equivalent-or-slower than the intrinsic** on H200 — the compiler can synthesise `fabsf` to one LOP3.LUT, while explicit bit code goes through two LOP3s.
-- **Arithmetic simulation of select is a performance anti-pattern** (cond-arith 1.27× slower). Write `if/else` or ternary; the compiler already produces optimal `FSEL`.
-
-## Principles
-
-1. **Count SASS ops, not branches.** The ns/op measured correlates with SASS op count. The word "branchless" is misleading on H200 — most C-source "branches" are already branchless at SASS.
-2. **Prefer single-op intrinsics.** `fmaxf`, `fminf`, `fabsf`, `copysignf` each map to a single SASS instruction. Use them whenever a pattern matches.
-3. **Do not rewrite `if/else` as arithmetic.** `acc*(1-c) + v*c` is slower than `if (c) acc = v;`. FSEL is already a 1-op branchless primitive; arithmetic simulation adds 3-4 extra ops.
-4. **If the compiler emits a real branch, check the body complexity.** Non-predicable bodies (function calls, stores, long chains) block FSEL emission. Simplify the body or move work out of the branch to restore predication.
-5. **Cross-reference `warp-divergence`** for the cost of real (non-predicated) branches. This skill covers the cheap predicable rewrites; real divergence is that skill's domain.
-
-## Open questions
-
-- Q1. Does `fminf`/`fmaxf` scale the same way with fp16 (`__hmax`, `__hmin`) and bf16 inputs? Not measured here. Follow-up probe `sources/experience/hw-probes/half-minmax/` (open).
-- Q2. Does `copysignf` emit a single `LOP3.LUT` like `fabsf`, or a different sequence? Not measured here; SASS inspection sufficient if needed.
-- Q3. When the `if/else` body performs a memory store (not a register update), does the compiler still emit `FSEL` or does it fall back to a real branch? Probe not done; expected answer from PTX documentation is "predicated store". Follow-up if a specific workload exhibits surprising divergence.
-- Q4. How much harder does it become to force predication as the predicated body grows? The `warp-divergence` probe establishes the upper-bound cost (1.82×) when predication fails; the crossover point from "compiler predicates" to "compiler emits branch" is compiler-version-dependent and not measured here.
-
-## Legacy references
-
-The legacy KB at `corpus/nvidia/legacy-advanced/branch-elimination/{branchless-patterns.md, predicated-execution.md, uniform-control-flow.md}` consisted of three empty placeholder files; there is no prior content to import. This skill is a fresh build whose structure and findings come entirely from the branchless-patterns probe and from the PG / PTX ISA citations above. The legacy placeholder path is recorded here solely so future migrations can confirm the "no content to import" state; all pattern recommendations in the body of this skill stand on the probe 2026-04-23 SASS audit and measured wall-clock.