doc: add nvfp4 tech report

tech_report/NVFP4/figures/nvfp4_diagram1_forward.mmd

@@ -0,0 +1,21 @@
+flowchart TD
+    X["X (BF16, token activations)"]
+    Wlp["W_lp (FP4 stored, E2M1 codes)"]
+    SX["scales_X (E4M3) + pts_X (FP32)"]
+    SW["scales_W (E4M3) + pts_W (FP32)"]
+
+    X --> QF["Block-wise quantize<br/>elem=E2M1, block_scale=E4M3,<br/>tensorwise PTS, rounding=RNE<br/>(no Hadamard on forward path)"]
+    QF --> Xlp["X_lp (FP4 codes)"]
+    Xlp --> DQX["Dequantize X<br/>X_dq = X_lp * block_scale * pts"]
+    DQX --> Xdq["X_dq (BF16)"]
+    SX --> DQX
+
+    Wlp --> DQW["Dequantize W"]
+    SW --> DQW
+    DQW --> Wdq["W_dq (BF16)"]
+
+    Xdq --> GEMM["BF16 GEMM (QDQ emulation path)<br/>Y = X_dq @ W_dq^T"]
+    Wdq --> GEMM
+    GEMM --> Y["Y (BF16) -> next layer"]
+
+    X -. saved for wgrad .-> Save["Hadamard H + block-quantize<br/>(stored on ctx as x_for_wgrad)"]

tech_report/NVFP4/figures/nvfp4_diagram2_backward.mmd

@@ -0,0 +1,25 @@
+flowchart TD
+    dY["dY (BF16) from layer L+1"]
+    Wlp["W_lp (FP4 stored)"]
+    Xsaved["x_for_wgrad (saved BF16 or pre-rotated FP4)"]
+
+    dY --> QDg["SR-block-quantize on dY<br/>elem=E2M1, scale=E4M3, PTS,<br/>rounding=SR (no Hadamard on dgrad)<br/>injects fresh noise eps_d"]
+    QDg --> dYdq["dY_dq (BF16) = true dY + eps_d"]
+    dYdq --> Gd["BF16 GEMM (QDQ emulation)<br/>dX = dY_dq @ W_dq"]
+    Wlp --> DqW1["Dequantize W"]
+    DqW1 --> Gd
+    Gd --> dX["dX (BF16)<br/>flows to layer L-1 as dY_{L-1}<br/>(cross-layer noise carrier)"]
+
+    dY --> HW["Hadamard rotation H<br/>(applied to dY for wgrad only)"]
+    HW --> QWg["SR-block-quantize<br/>(same block params, SR=ON)"]
+    QWg --> dYHdq["dY_H_dq (BF16) = true dY rotated + eps_w"]
+
+    Xsaved --> HX["Hadamard H on saved X"]
+    HX --> QXw["block-quantize"]
+    QXw --> Xhdq["X_H_dq (BF16)"]
+
+    dYHdq --> Gw["BF16 GEMM (QDQ emulation)<br/>dW = dY_H_dq^T @ X_H_dq"]
+    Xhdq --> Gw
+    Gw --> dW["dW (BF16)"]
+    dW --> Opt["AdamW optimizer"]
+    dW --> GN["grad_norm = sqrt(sum over layers ||dW||_2^2)<br/>pre-clip global L2"]

tech_report/NVFP4/figures/nvfp4_diagram3_stacked.mmd

@@ -0,0 +1,13 @@
+flowchart LR
+    dYLp1["dY_{L+1}"]
+    dYLp1 --> N3["layer L+1 dgrad<br/>SR + GEMM, adds eps_{L+1}"]
+    N3 --> dYL["dX_{L+1} = dY_L<br/>variance sigma_{L+1}^2"]
+
+    dYL --> N2["layer L dgrad<br/>SR + GEMM, adds eps_L"]
+    N2 --> dYLm1["dX_L = dY_{L-1}<br/>sigma_L^2 ~ G_L * sigma_{L+1}^2 + eps_L^2"]
+
+    dYLm1 --> N1["layer L-1 dgrad<br/>SR + GEMM, adds eps_{L-1}"]
+    N1 --> dYLm2["dX_{L-1} = dY_{L-2}<br/>sigma_{L-1}^2 ~ G_{L-1} * sigma_L^2 + eps_{L-1}^2"]
+
+    Note["Recurrence (no Hadamard on dgrad):<br/>sigma_d^2 = G_d * sigma_{d+1}^2 + eps_d^2<br/>eps_d^2 ∝ ||grad_output||_inf^2 (Tseng Thm 3.2)"]
+    N2 -.-> Note

tech_report/NVFP4/figures/nvfp4_grad_output_backward_path.mmd

@@ -0,0 +1,48 @@
+flowchart LR
+    IN["grad_output (dY, BF16)<br/>from layer L+1 autograd<br/>(upstream chain rule)"]
+
+    HAD["Hadamard rotate H<br/>left_mul=True<br/>(wgrad path only;<br/>dgrad path does NOT rotate)"]
+
+    DGRAD_QDQ["<b>SR-QDQ #1  (root cause)</b><br/>_qdq(grad_output,<br/>  axis=-1, use_sr=True)<br/><br/>autograd.py:200-203"]
+
+    WGRAD_QDQ["<b>SR-QDQ #2  (root cause)</b><br/>_qdq(grad_output_H,<br/>  axis=0, use_sr=True)<br/><br/>cg_backward.py:108-119<br/>(inside _nvfp4_grouped_wgrad)"]
+
+    GD["_nvfp4_grouped_dgrad<br/>dX = g_dq @ w_bwd<br/>(BF16 GEMM, QDQ emulation)"]
+
+    GW["_nvfp4_grouped_wgrad<br/>dW = g_m_dq^T @ x_bwd<br/>(BF16 GEMM, QDQ emulation)"]
+
+    W_BWD["w_bwd  (saved from forward)<br/>_qdq(W, axis=-2)<br/><br/>ABL.2 D2: innocent"]
+
+    X_BWD["x_bwd  (saved from forward)<br/>_qdq(Hadamard(X), axis=0)<br/><br/>ABL.2 D4: innocent"]
+
+    DX["dX (BF16)<br/>-> layer L-1's grad_output<br/><br/><b>This carries SR noise upstream;<br/>cross-layer ε² accumulates here</b>"]
+
+    DW["dW (BF16)<br/>-> AdamW optimizer<br/>-> contributes to global grad_norm"]
+
+    IN -->|"dgrad path<br/>(no Hadamard)"| DGRAD_QDQ
+    IN -->|"wgrad path"| HAD
+    HAD --> WGRAD_QDQ
+
+    DGRAD_QDQ --> GD
+    W_BWD --> GD
+
+    WGRAD_QDQ --> GW
+    X_BWD --> GW
+
+    GD --> DX
+    GW --> DW
+
+    classDef incoming fill:#cce5ff,stroke:#0056b3,color:#000,stroke-width:2px
+    classDef rootcause fill:#f8d7da,stroke:#dc3545,color:#000,stroke-width:3px
+    classDef safe fill:#d4edda,stroke:#28a745,color:#000,stroke-width:2px
+    classDef gemm fill:#fff3cd,stroke:#ffc107,color:#000,stroke-width:2px
+    classDef output fill:#e2e3e5,stroke:#383d41,color:#000,stroke-width:2px
+    classDef neutral fill:#ffffff,stroke:#6c757d,color:#000,stroke-width:2px
+
+    class IN incoming
+    class HAD neutral
+    class DGRAD_QDQ,WGRAD_QDQ rootcause
+    class W_BWD,X_BWD safe
+    class GD,GW gemm
+    class DX output
+    class DW output

tech_report/NVFP4/figures/phase_b_ablation_summary_lr.mmd

@@ -0,0 +1,23 @@
+flowchart LR
+    P["<b>Problem</b><br/>NVFP4 cumulative grad_norm<br/>explodes 100x-2000x<br/>MXFP4 same SR does not"]
+
+    A["<b>B-ABL.1</b>  fwd vs bwd  (24 runs)<br/>━━━━━━━━━━━━━<br/><b>Backward = 100% the source</b>"]
+
+    B["<b>B-ABL.2</b>  bwd tensor bypass  (36 runs)<br/>━━━━━━━━━━━━━<br/><b>Root op = 2x _qdq(grad_output, SR)</b><br/>stride / non-contig hypothesis killed"]
+
+    C["<b>B-ABL.5</b>  op-internal bisect  (S1+S7+F.2)<br/>━━━━━━━━━━━━━<br/><b>Noise = SR randomness only</b><br/>NVFP4 single-op quieter than MXFP4 (paradox)"]
+
+    D["<b>PENDING</b><br/>━━━━━━━━━━━━━<br/><b>S3: block_size 16 -&gt; 32</b><br/>answers: does it explain<br/>'MXFP4 doesn't explode'?"]
+
+    P -->|switch to precision-ablation| A
+    A -->|bwd locked| B
+    B -->|op locked, H1 dead| C
+    C -.->|cross-layer propagation open| D
+
+    classDef problem fill:#cce5ff,stroke:#0056b3,color:#000,stroke-width:2px
+    classDef confirmed fill:#d4edda,stroke:#28a745,color:#000,stroke-width:2px
+    classDef pending fill:#fff3cd,stroke:#ffc107,stroke-width:2px,stroke-dasharray:5 5,color:#000
+
+    class P problem
+    class A,B,C confirmed
+    class D pending