Promote latest kernel artifacts to main

README.md

@@ -1,9 +1,116 @@
-# flashrt/fp4-gemm
+# fp4-gemm
 
-This repository is a compatibility mirror for older `kernels` clients
-that resolve repositories through the default Hugging Face model repo API.
+FlashRT native Blackwell NVFP4 A4W4 GEMM kernels.
 
-Canonical Kernel Hub repo: https://huggingface.co/kernels/flashrt/fp4-gemm
+This package consumes packed FP4 E2M1 tensors plus CUTLASS Sm1xx SFA/SFB scale
+buffers and produces BF16 output. It is designed to pair with
+`flashrt/fp4-fused-ops` and other static low-bit transformer/diffuser runtime
+paths.
 
-Do not edit this mirror by hand. It is generated from the Kernel Hub
-`vN` branches and contains the same `build/**` artifacts.
+## Available Functions
+
+- `sfa_size_bytes(rows, dim)`
+- `quantize_fp4_sfa_fp16(x, packed=None, sfa=None, is_sfb=False)`
+- `quantize_fp4_sfa_bf16(x, packed=None, sfa=None, is_sfb=False)`
+- `dequantize_fp4_sfa_fp16(packed, sfa, out=None, is_sfb=False)`
+- `nvfp4_gemm_bf16(a_packed, b_packed, sfa, sfb, alpha=1.0, out=None, variant=-1)`
+- `nvfp4_gemm_bias_bf16(a_packed, b_packed, sfa, sfb, bias, out=None)`
+- `nvfp4_gemm_bias_residual_bf16(a_packed, b_packed, sfa, sfb, bias, residual, out=None)`
+- `nvfp4_gemm_residual_bf16(a_packed, b_packed, sfa, sfb, residual, alpha=1.0, out=None)`
+- `nvfp4_gemm_bias_gelu_bf16(a_packed, b_packed, sfa, sfb, bias, alpha=1.0, out=None)`
+- `nvfp4_gemm_bias_gelu_nvfp4(a_packed, b_packed, sfa, sfb, bias, alpha=1.0, out_packed=None, out_sfa=None)`
+- `nvfp4_gemm_streamk_bf16(a_packed, b_packed, sfa, sfb, alpha=1.0, out=None)`
+- `nvfp4_gemm_streamk_bias_bf16(a_packed, b_packed, sfa, sfb, bias, alpha=1.0, out=None)`
+- `fp4_w4a16_linear_bf16(...)` is retained as a compatibility alias
+
+## Tensor Contract
+
+- `a_packed`: `torch.uint8`, shape `(M, K / 2)`.
+- `b_packed`: `torch.uint8`, shape `(N, K / 2)`.
+- `sfa`: `torch.uint8`, CUTLASS SFA layout for `(M, K)`.
+- `sfb`: `torch.uint8`, CUTLASS SFB layout for `(N, K)`.
+- output: `torch.bfloat16`, shape `(M, N)`.
+- `K` must be divisible by 16.
+- Targets: Blackwell `sm_110a` (Jetson AGX Thor, CUDA 13+) and `sm_120a`
+  (RTX Blackwell, CUDA 12.8+).
+
+`variant` selects the CUTLASS schedule:
+
+- `-1`: architecture-aware auto-dispatch (public default).
+- `0`: default `<128,128,256>` cooperative schedule.
+- `1`: widen `<128,256,128>` schedule, intended for very large `N`.
+- `2`: pingpong schedule for A/B testing shape-specific wins.
+
+The canonical linear API and FP4/SFA quantize/dequantize helpers are available
+on both SM110 and SM120. SM110 additionally provides the GROOT N1.7 production
+epilogues `nvfp4_gemm_bias_bf16`, `nvfp4_gemm_bias_residual_bf16`, and
+`nvfp4_gemm_bias_gelu_nvfp4`. The latter emits packed FP4 plus CUTLASS SFA so
+the following projection can consume it without a BF16 materialization and a
+standalone quantization launch. Stream-K and the older BF16 GELU epilogue keep
+their existing SM120 dispatch and reject unsupported architectures explicitly.
+
+The SM110 release gate includes the production `(M,N,K)` shapes
+`(41,4608,1536)`, `(41,6144,1536)`, and `(41,1536,6144)`, plus the legacy
+`M=51` compatibility row. The kernels are the native sources used by FlashRT's
+GROOT N1.7 Thor NVFP4 pipeline.
+
+## Minimal Usage
+
+```python
+from kernels import get_kernel
+import torch
+
+ops = get_kernel("flashrt/fp4-gemm", version=1, trust_remote_code=True)
+
+x = torch.randn((32, 256), device="cuda", dtype=torch.float16)
+w = torch.randn((512, 256), device="cuda", dtype=torch.float16)
+
+a_packed, sfa = ops.quantize_fp4_sfa_fp16(x, is_sfb=False)
+b_packed, sfb = ops.quantize_fp4_sfa_fp16(w, is_sfb=True)
+
+y = ops.nvfp4_gemm_bf16(a_packed, b_packed, sfa, sfb, alpha=1.0)
+```
+
+For BF16 model activations, use the direct producer so the hot path does not
+materialize an intermediate FP16 tensor:
+
+```python
+x_bf16 = torch.randn((1, 5120), device="cuda", dtype=torch.bfloat16)
+a_packed, sfa = ops.quantize_fp4_sfa_bf16(x_bf16)
+```
+
+The BF16 entry writes the same E2M1 bytes and CUTLASS SFA/SFB layout as
+`quantize_fp4_sfa_fp16(x_bf16.to(torch.float16))` for finite FP16-range
+inputs. It is an additive API; the existing FP16 producer remains unchanged.
+
+The quantize/dequantize helpers are included for examples and validation. A
+production runtime should keep weights prepacked and should avoid quantizing in
+the hot path unless that producer kernel is part of the intended low-bit block.
+
+Use the bias/GELU and residual variants to avoid returning to BF16
+elementwise code between low-bit GEMMs. Stream-K variants are selected only
+for the validated large down-projection shapes; unsupported shapes reject
+rather than silently selecting a losing schedule.
+
+## Validation
+
+```bash
+python fp4-gemm/tests/test_fp4_gemm.py --backend source --mode full
+python fp4-gemm/tests/test_fp4_gemm.py --backend installed --mode full \
+  --artifact fp4-gemm/build/torch211-cxx11-cu128-x86_64-linux
+python fp4-gemm/benchmarks/benchmark.py --backend installed --mode headline \
+  --artifact fp4-gemm/build/torch211-cxx11-cu128-x86_64-linux
+
+# Thor model-shape gate
+python fp4-gemm/tests/test_fp4_gemm.py --backend installed \
+  --mode thor-models \
+  --artifact fp4-gemm/build/torch211-cxx11-cu130-aarch64-linux
+```
+
+The correctness reference dequantizes the same FP4/SFA and FP4/SFB inputs used
+by the kernel, then computes the PyTorch GEMM reference from those dequantized
+low-bit values.
+
+The producer gate also checks the BF16 direct entry byte-for-byte against the
+established FP16 compatibility chain at decode widths 5120, 6144 and 17408,
+plus multi-row activation and SFB layouts.

build/torch213-cxx11-cu130-aarch64-linux/__init__.py

@@ -42,6 +42,16 @@ def _linear_fp16_fake(a_packed, b_packed, sfa, sfb, out, alpha: float = 1.0, var
     return None
 
 
+@torch.library.register_fake(add_op_namespace_prefix("nvfp4_gemm_variant_bf16"))
+def _linear_variant_bf16_fake(a, b, sfa, sfb, out, alpha: float = 1.0, variant: int = 7) -> None:
+    return None
+
+
+@torch.library.register_fake(add_op_namespace_prefix("nvfp4_gemm_nvfp4"))
+def _linear_fp4out_fake(a, b, sfa, sfb, out_packed, out_sfa) -> None:
+    return None
+
+
 @torch.library.register_fake(add_op_namespace_prefix("nvfp4_gemm_geglu_nvfp4_fp16"))
 def _geglu_fp4_fake(a, b, sfa, sfb, scratch, out_packed, out_sfa, skinny: bool = False) -> None:
     return None
@@ -94,6 +104,11 @@ def _quant_fake(x: torch.Tensor, packed: torch.Tensor, sfa: torch.Tensor, is_sfb
     return None
 
 
+@torch.library.register_fake(add_op_namespace_prefix("quantize_fp4_sfa_mse_fp16"))
+def _quant_mse_fake(x, packed, sfa, is_sfb: bool = False) -> None:
+    return None
+
+
 @torch.library.register_fake(add_op_namespace_prefix("quantize_e0m3_sfa_fp16"))
 def _quant_e0m3_fake(x, packed, sfa, is_sfb: bool = False) -> None:
     return None
@@ -158,6 +173,19 @@ def quantize_fp4_sfa_fp16(
     return packed, sfa
 
 
+def quantize_fp4_sfa_mse_fp16(
+    x: torch.Tensor,
+    packed: torch.Tensor | None = None,
+    sfa: torch.Tensor | None = None,
+    is_sfb: bool = False,
+):
+    """Pack FP16 weights using per-block reconstruction-MSE scale search."""
+    if packed is None or sfa is None:
+        packed, sfa = _alloc_fp4(x.shape[0], x.shape[1], x.device)
+    ops.quantize_fp4_sfa_mse_fp16(x, packed, sfa, bool(is_sfb))
+    return packed, sfa
+
+
 def quantize_e0m3_sfa_fp16(
     x: torch.Tensor,
     packed: torch.Tensor | None = None,
@@ -276,6 +304,52 @@ def nvfp4_gemm_fp16(
     return out
 
 
+def nvfp4_gemm_variant_bf16(
+    a_packed: torch.Tensor,
+    b_packed: torch.Tensor,
+    sfa: torch.Tensor,
+    sfb: torch.Tensor,
+    alpha: float = 1.0,
+    out: torch.Tensor | None = None,
+    variant: int = 7,
+) -> torch.Tensor:
+    """SM110 native NVFP4 GEMM with BF16 output.
+
+    ``variant=7`` serves large-M encoder/SigLIP shapes; ``variant=10`` is
+    the narrow-N PI0.5 decoder tile. The indices match FlashRT native.
+    """
+    if out is None:
+        out = torch.empty(
+            (a_packed.shape[0], b_packed.shape[0]),
+            device=a_packed.device,
+            dtype=torch.bfloat16,
+        )
+    ops.nvfp4_gemm_variant_bf16(
+        a_packed, b_packed, sfa, sfb, out, float(alpha), int(variant)
+    )
+    return out
+
+
+def nvfp4_gemm_nvfp4(
+    a_packed: torch.Tensor,
+    b_packed: torch.Tensor,
+    sfa: torch.Tensor,
+    sfb: torch.Tensor,
+    *,
+    out_packed: torch.Tensor | None = None,
+    out_sfa: torch.Tensor | None = None,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """SM110 NVFP4 GEMM with an NVFP4 output and CUTLASS SFA layout."""
+    if out_packed is None or out_sfa is None:
+        out_packed, out_sfa = _alloc_fp4(
+            a_packed.shape[0], b_packed.shape[0], a_packed.device
+        )
+    ops.nvfp4_gemm_nvfp4(
+        a_packed, b_packed, sfa, sfb, out_packed, out_sfa
+    )
+    return out_packed, out_sfa
+
+
 def nvfp4_gemm_geglu_nvfp4_fp16(
     a_packed: torch.Tensor,
     b_interleaved_packed: torch.Tensor,
@@ -533,6 +607,8 @@ __all__ = [
     "fp4_w4a4_gemv_warpsplit_bf16",
     "nvfp4_gemm_bf16",
     "nvfp4_gemm_fp16",
+    "nvfp4_gemm_variant_bf16",
+    "nvfp4_gemm_nvfp4",
     "nvfp4_gemm_geglu_nvfp4_fp16",
     "nvfp4_gemm_bias_gelu_nvfp4_fp16",
     "nvfp4_gemm_bias_residual_fp16",
@@ -545,6 +621,7 @@ __all__ = [
     "nvfp4_gemm_streamk_bf16",
     "nvfp4_gemm_streamk_bias_bf16",
     "quantize_fp4_sfa_fp16",
+    "quantize_fp4_sfa_mse_fp16",
     "quantize_e0m3_sfa_fp16",
     "quantize_fp4_sfa_bf16",
     "sfa_size_bytes",

build/torch213-cxx11-cu130-aarch64-linux/_ops.py

@@ -1,6 +1,6 @@
 import torch
-from . import _fp4_gemm_cuda_230e467
-ops = torch.ops._fp4_gemm_cuda_230e467
+from . import fp4_gemm_source_test
+ops = torch.ops.fp4_gemm_source_test
 
 def add_op_namespace_prefix(op_name: str):
-    return f"_fp4_gemm_cuda_230e467::{op_name}"
+    return f"fp4_gemm_source_test::{op_name}"

build/torch213-cxx11-cu130-aarch64-linux/{_fp4_gemm_cuda_230e467.abi3.so → fp4_gemm_source_test.abi3.so}

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:54da8e4f3b0c728c6309dcb434fb608cf50085dfbf3051381ff6b1687316103c
-size 5530648
+oid sha256:73b4cbcb15d13cc6452007e59961f3b217d21771f0c0937cc121cc8e0e6b1e12
+size 6529016

build/torch213-cxx11-cu130-aarch64-linux/metadata.json

@@ -1,28 +1,32 @@
 {
   "name": "fp4-gemm",
-  "id": "_fp4_gemm_cuda_230e467",
+  "id": "fp4_gemm_source_test",
   "version": 1,
   "license": "Apache-2.0",
   "python-depends": [],
   "backend": {
     "type": "cuda",
     "archs": [
-      "11.0a"
+      "11.0"
     ]
   },
   "digest": {
     "algorithm": "sha256",
     "files": {
-      "__init__.py": "Qfdvg/9EedWLGh34xAalDfC0IsAHCOL44L4ShaP/w5Y=",
-      "_fp4_gemm_cuda_230e467.abi3.so": "VNqOTzsMcoxjCdy0NPtgjPUAhd+/MFE4H/axaHMWEDw=",
-      "_ops.py": "IfU2iMVrWYRnoe6q8HI3hU8TPnAlLrXDerlv117PcXI=",
+      "__init__.py": "Fb/FDYOpDw+YGlevblUsv4AkILDQCJdB807qdDUDI1c=",
+      "fp4_gemm_source_test.abi3.so": "c7TLyxXRPMZFIAflmWHzshfSF3HwwJN8wSHMjg5rHhI=",
+      "_ops.py": "ZPjRxrYk7lCA0ZHoCjg8BaJyFY7a5i4NC3jIL6VMRJ4=",
       "fp4_gemm/__init__.py": "v6p5XMfQzddhi1fLSAw4HX9CyS0rQsidvu9VsT01xi4="
     }
   },
   "provenance": {
     "kernel": {
-      "sha": "230e467",
+      "sha": "b6588aa59dd4f8c646f90b58312a0a66886e061f",
       "dirty": false
+    },
+    "validation": {
+      "torch": "2.13.0+cu130",
+      "cuda": "13.0"
     }
   }
 }