99747c53ba [CUDA] Add Hopper tensor-parallel fused linear cross entropy (#1422)
## Summary

Adds Hopper tensor-parallel fused linear scaled cross entropy
forward/backward with NVLS, direct-peer, and hierarchical two-host
paths.

Production choices:
- zero-spill cluster-2 M-fast dZ handoff with compact precomputed
coefficients;
- zero-spill four-stage combined dX+dW with one reused R24 accumulator;
- H2048 dX split-K2 when the local vocabulary has an even K64 tile
count,
  otherwise split-K1; H4096 uses split-K1;
- N32 FP32 TMA dX publication, N64/S2 dW epilogue, final-only
publication fence;
- post-compute local/hierarchical FP32-to-BF16 finalization;
- device-resident graph-safe launch epochs with one stream-ordered tail
barrier;
- non-RDC WGMMA translation units with remote NVSHMEM code isolated in
RDC sources.

## Tensor-parallel reduction API

Reduction transport is now reusable infrastructure under
`liger_cute::detail`:

- `TpReducePlan` selects the local NVLS or DirectPeer backend on the
host.
- Kernels receive only the selected compact device view; the full host
plan is never passed to device code.
- `RequiresRemote` is a launcher template argument, so the local path
carries no runtime remote branch or remote fields.
- Two-host execution is local NVLS reduce-scatter, explicit
`launch_remote_reduce(...)`, then the common local all-gather/scatter.
- DirectPeer remains supported behind the same local reduction API.

The refactor removes the unused pre-cluster dZ/role framework and old
non-cluster hierarchical implementation. Net change: 1,907 fewer lines
while preserving the validated kernel schedules.

## Kernel structure

### Warp functions and roles

**Forward `forward_gemm_kernel_sm90` (12 warps, cluster-2)**
- Warp 0 is the TMA producer for X and weight panels.
- Warps 1-3 are reserved/inactive.
- Warp groups 1-2 (8 warps) execute the N320 logical GEMM as two N160
accumulator banks, then perform the N80/N40 online-softmax and entropy
fold.
- Cluster peers share the token-side input while owning adjacent
vocabulary work.

**Backward dZ handoff (12 warps, cluster-2)**
- Warp 3 drives the three-stage TMA pipeline for X/W panels.
- Warps 0-2 consume handed-off FP16 logits, apply precomputed row
coefficients, target correction, BF16 conversion, and TMA output stores.
- Warp groups 1-2 execute M128xN256xK64 WGMMA and hand the rounded FP16
logits through shared memory.
- The handoff separates accumulator and epilogue liveness, eliminating
the old dZ spill path.

**Backward combined dX+dW (12 warps, cluster-2)**
- Warp 0 drives the continuous four-stage TMA producer pipeline.
- Two communication warps consume the FP32 dX ring, perform local NVLS
reduction/publication, and overlap with dW.
- Warp groups 1-2 execute dX then dW using one explicitly reused
M128xN256 FP32 accumulator bank at R24.
- dX uses W multicast and N32 FP32 TMA publication. dW uses dZ
multicast, independent X loads, and N64/S2 TMA store/reduce-add.
- H2048 uses split-K2 with atomic accumulation into a stream-cleared
durable
  buffer when its K64 tile count is even; odd tile counts and H4096 use
  split-K1.

### Forward launch sequence

1. `forward_gemm_kernel_sm90`: local GEMM plus online
max/sum/entropy/target partials.
2. `forward_split_reduce_kernel_sm90`: reduce local vocabulary splits.
3. Tensor-parallel MAX reduction.
4. `pack_forward_reduction_kernel`: correct/pack sum fields.
5. Tensor-parallel SUM reduction.
6. `finalize_forward_kernel`: produce log-probability, LSE, and optional
entropy.

### Backward launch sequence

For each token wave:
1. `backward_dz_handoff_wave_kernel_sm90`: logits GEMM, compact dZ math,
BF16 dZ workspace.
2. `backward_dx_cluster2_gemm_wave_kernel_sm90`: continuous four-stage
dX then dW compute with overlapped local communication.

After all waves:
3. Single host: local FP32 reduction result to BF16 scatter.
4. Hierarchical: separate-RDC inter-host reduction, local NVLS
broadcast/all-gather, then BF16 scatter.
5. Direct-peer systems use the post-compute fallback finalizer.
6. One stream-ordered tensor-parallel tail barrier prevents staging
reuse before peers finish.

### Hoisted versus repeated work

**Hoisted**
- Backend capability/team selection, workspace reservation, rank
mapping, and TMA descriptor construction occur once on the host.
- TMA descriptors are prefetched once per CTA role before persistent
tile loops.
- Shape counts, raster bounds, and split-K selection are computed
outside inner K loops.
- dZ stores per-row `exp_bias`, `correction_bias`, and
`correction_slope`; row coefficients/target are hoisted outside the
inner column loop.
- dX and dW share one accumulator object and aliased A/B shared-memory
arenas.
- IB communication and final BF16 materialization remain outside the hot
combined WGMMA kernel.

**Not hoisted**
- Per-wave dZ and combined dX+dW launches.
- Per-tile TMA loads, WGMMA issue, accumulator-to-SMEM conversion, and
dX publication.
- Per-element dZ `exp2`, entropy correction, and target subtraction.
- Per-stage NVLS ring synchronization/reduction and split-K2 atomic
accumulation.
- dW N64 TMA store/reduce-add for each output subtile and wave.

## Validation

- `make checkstyle`
- clean CMake shared-library build
- C++ tests: 8/8 passed
- Python WORLD and strided-subteam forward/backward tests: 2/2 passed,
including two CUDA Graph replays
- backward TP1/2/4/8 selftests: entropy on/off, ragged shapes,
multi-wave/full-grid, TPR1/2/4
- poison staging/dZ and delayed communication warp tests
- forward TP1/2/4/8 selftests: entropy on/off, ragged, temperature,
large split
- hierarchical TP16 forward/backward
- benchmarked kernel schedule before the transport-only API refactor:
92/92 unique matched points passed in both entropy modes; TP1/2/4/8/16
- post-refactor: checkstyle and focused Python facade regression passed;
GPU compilation remains delegated to PR validation

## Benchmark methodology

H200 SXM, CUDA 12.9, 8 warmups and 30 measured iterations, p50 shown
below. TFLOP/s are per GPU unless labeled aggregate. Liger entropy-off
is compared with Verl's no-entropy configuration. Memory factor is `Verl
GiB / Liger GiB`; values above 1 mean Liger uses less memory.
Allocation-free means no hot-path allocation; Liger's reported footprint
includes pre-reserved symmetric communication workspaces. H100 and H200
absolute results are kept separate.

## Overall Liger vs Verl

| Pass | Matched points | Geomean speedup | Range | Slower points |
Geomean mem V/L |
|---|---:|---:|---:|---:|---:|
| backward | 46 | 1.54x | 0.95-1.87x | 1 | 0.82x |
| forward | 46 | 2.11x | 1.69-3.79x | 0 | 0.47x |

Forward is faster at every matched point. Backward is faster at every
matched point except M8192/H2048/V131072 at TP16.

## Strong-scaling efficiency

Efficiency is per-GPU TFLOP/s at TPn divided by TP1 per-GPU TFLOP/s for
the same global workload.

| Pass | M | H | V | TP1 TF/GPU | TP2 eff. | TP4 eff. | TP8 eff. | TP16
eff. |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| backward | 2048 | 4096 | 131072 | 767.9 | 98.1% | 92.7% | 82.5% |
50.1% |
| backward | 8192 | 2048 | 131072 | 694.9 | 91.4% | 82.8% | 68.6% |
37.8% |
| backward | 8192 | 4096 | 131072 | 762.8 | 97.8% | 93.7% | 84.0% |
54.5% |
| backward | 16384 | 4096 | 131072 | 761.1 | 97.3% | 93.8% | 83.7% |
55.3% |
| backward | 2048 | 4096 | 262144 | 783.1 | 98.2% | 97.0% | 91.1% |
66.8% |
| backward | 8192 | 2048 | 262144 | 711.3 | 96.7% | 92.3% | 85.0% |
58.2% |
| backward | 8192 | 4096 | 262144 | 777.4 | 98.4% | 96.6% | 91.8% |
70.6% |
| backward | 16384 | 4096 | 262144 | 775.8 | 98.5% | 95.8% | 91.9% |
71.2% |
| forward | 2048 | 4096 | 131072 | 787.7 | 99.9% | 97.7% | 83.5% | 58.4%
|
| forward | 8192 | 2048 | 131072 | 747.7 | 99.4% | 96.7% | 90.4% | 79.1%
|
| forward | 8192 | 4096 | 131072 | 789.0 | 99.7% | 98.8% | 95.9% | 88.9%
|
| forward | 16384 | 4096 | 131072 | 757.4 | 99.7% | 98.3% | 95.0% |
91.4% |
| forward | 2048 | 4096 | 262144 | 791.1 | 99.0% | 100.0% | 95.4% |
77.0% |
| forward | 8192 | 2048 | 262144 | 747.5 | 99.7% | 99.1% | 95.6% | 86.8%
|
| forward | 8192 | 4096 | 262144 | 788.3 | 99.9% | 100.1% | 98.3% |
94.1% |
| forward | 16384 | 4096 | 262144 | 755.3 | 100.0% | 99.8% | 98.3% |
93.9% |

## Weak-scaling efficiency

Global vocabulary grows with TP while local vocabulary remains 65,536.
Efficiency is per-GPU TFLOP/s relative to TP1.

| Pass | H | TP1 TF/GPU | TP2 eff. | TP4 eff. | TP8 eff. | TP16 eff. |
|---|---:|---:|---:|---:|---:|---:|
| backward | 2048 | 661.4 | 96.1% | 99.2% | 99.2% | 94.7% |
| backward | 4096 | 757.6 | 98.4% | 99.1% | 98.8% | 95.8% |
| forward | 2048 | 748.2 | 99.4% | 99.0% | 98.5% | 97.4% |
| forward | 4096 | 788.5 | 99.7% | 100.1% | 99.3% | 98.4% |

## Full Liger vs Verl results

| Pass | M | H | V | TP | Liger TF/GPU | Verl TF/GPU | Speedup | Liger
GiB | Verl GiB | Mem V/L |
|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
| backward | 8192 | 2048 | 65536 | 1 | 661.4 | 375.2 | 1.76x | 2.26 |
1.15 | 0.51x |
| backward | 8192 | 4096 | 65536 | 1 | 757.6 | 507.3 | 1.49x | 2.82 |
1.99 | 0.71x |
| backward | 2048 | 4096 | 131072 | 1 | 767.9 | 445.2 | 1.72x | 3.85 |
3.14 | 0.82x |
| backward | 2048 | 4096 | 131072 | 2 | 753.3 | 436.4 | 1.73x | 2.72 |
1.65 | 0.61x |
| backward | 2048 | 4096 | 131072 | 4 | 711.6 | 385.0 | 1.85x | 2.16 |
0.88 | 0.41x |
| backward | 2048 | 4096 | 131072 | 8 | 633.3 | 362.6 | 1.75x | 1.88 |
0.52 | 0.28x |
| backward | 2048 | 4096 | 131072 | 16 | 385.0 | 311.3 | 1.24x | 0.17 |
0.33 | 1.94x |
| backward | 8192 | 2048 | 131072 | 1 | 694.9 | 378.9 | 1.83x | 2.88 |
1.89 | 0.66x |
| backward | 8192 | 2048 | 131072 | 2 | 635.4 | 372.0 | 1.71x | 2.26 |
1.15 | 0.51x |
| backward | 8192 | 2048 | 131072 | 4 | 575.2 | 329.3 | 1.75x | 1.94 |
0.71 | 0.37x |
| backward | 8192 | 2048 | 131072 | 8 | 476.9 | 313.8 | 1.52x | 1.79 |
0.56 | 0.31x |
| backward | 8192 | 2048 | 131072 | 16 | 262.4 | 277.1 | 0.95x | 0.14 |
0.49 | 3.50x |
| backward | 8192 | 4096 | 131072 | 1 | 762.8 | 510.6 | 1.49x | 3.94 |
3.48 | 0.88x |
| backward | 8192 | 4096 | 131072 | 2 | 745.7 | 501.2 | 1.49x | 2.82 |
1.99 | 0.71x |
| backward | 8192 | 4096 | 131072 | 4 | 714.7 | 446.2 | 1.60x | 2.26 |
1.18 | 0.52x |
| backward | 8192 | 4096 | 131072 | 8 | 640.6 | 431.4 | 1.48x | 1.97 |
0.84 | 0.43x |
| backward | 8192 | 4096 | 131072 | 16 | 415.7 | 387.3 | 1.07x | 0.27 |
0.68 | 2.52x |
| backward | 16384 | 4096 | 131072 | 1 | 761.1 | 519.8 | 1.46x | 4.07 |
3.93 | 0.97x |
| backward | 16384 | 4096 | 131072 | 2 | 740.2 | 510.8 | 1.45x | 2.94 |
2.46 | 0.84x |
| backward | 16384 | 4096 | 131072 | 4 | 714.1 | 458.3 | 1.56x | 2.38 |
1.58 | 0.66x |
| backward | 16384 | 4096 | 131072 | 8 | 637.1 | 444.4 | 1.43x | 2.10 |
1.28 | 0.61x |
| backward | 16384 | 4096 | 131072 | 16 | 421.0 | 404.6 | 1.04x | 0.39 |
1.13 | 2.90x |
| backward | 2048 | 4096 | 262144 | 1 | 783.1 | 449.4 | 1.74x | 6.10 |
6.14 | 1.01x |
| backward | 2048 | 4096 | 262144 | 2 | 768.8 | 444.1 | 1.73x | 3.85 |
3.14 | 0.82x |
| backward | 2048 | 4096 | 262144 | 4 | 759.7 | 435.4 | 1.74x | 2.72 |
1.65 | 0.61x |
| backward | 2048 | 4096 | 262144 | 8 | 713.6 | 383.2 | 1.86x | 2.16 |
0.88 | 0.41x |
| backward | 2048 | 4096 | 262144 | 16 | 523.4 | 351.2 | 1.49x | 0.31 |
0.52 | 1.68x |
| backward | 8192 | 2048 | 262144 | 1 | 711.3 | 381.3 | 1.87x | 4.13 |
3.35 | 0.81x |
| backward | 8192 | 2048 | 262144 | 2 | 687.8 | 376.7 | 1.83x | 2.88 |
1.89 | 0.66x |
| backward | 8192 | 2048 | 262144 | 4 | 656.4 | 371.3 | 1.77x | 2.26 |
1.15 | 0.51x |
| backward | 8192 | 2048 | 262144 | 8 | 604.6 | 329.0 | 1.84x | 1.94 |
0.71 | 0.37x |
| backward | 8192 | 2048 | 262144 | 16 | 414.0 | 306.1 | 1.35x | 0.22 |
0.56 | 2.55x |
| backward | 8192 | 4096 | 262144 | 1 | 777.4 | 512.1 | 1.52x | 6.19 |
6.45 | 1.04x |
| backward | 8192 | 4096 | 262144 | 2 | 765.1 | 505.7 | 1.51x | 3.94 |
3.48 | 0.88x |
| backward | 8192 | 4096 | 262144 | 4 | 751.1 | 500.6 | 1.50x | 2.82 |
1.99 | 0.71x |
| backward | 8192 | 4096 | 262144 | 8 | 714.0 | 447.2 | 1.60x | 2.26 |
1.18 | 0.52x |
| backward | 8192 | 4096 | 262144 | 16 | 548.6 | 421.2 | 1.30x | 0.41 |
0.84 | 2.05x |
| backward | 16384 | 4096 | 262144 | 1 | 775.8 | 520.5 | 1.49x | 6.32 |
6.87 | 1.09x |
| backward | 16384 | 4096 | 262144 | 2 | 763.9 | 516.4 | 1.48x | 4.07 |
3.93 | 0.97x |
| backward | 16384 | 4096 | 262144 | 4 | 743.2 | 509.9 | 1.46x | 2.94 |
2.46 | 0.84x |
| backward | 16384 | 4096 | 262144 | 8 | 713.2 | 458.0 | 1.56x | 2.38 |
1.58 | 0.66x |
| backward | 16384 | 4096 | 262144 | 16 | 552.6 | 429.2 | 1.29x | 0.53 |
1.28 | 2.42x |
| backward | 8192 | 2048 | 524288 | 8 | 655.9 | 369.7 | 1.77x | 2.26 |
1.15 | 0.51x |
| backward | 8192 | 4096 | 524288 | 8 | 748.4 | 499.0 | 1.50x | 2.82 |
1.99 | 0.71x |
| backward | 8192 | 2048 | 1048576 | 16 | 626.5 | 366.9 | 1.71x | 0.69 |
1.15 | 1.67x |
| backward | 8192 | 4096 | 1048576 | 16 | 726.1 | 494.5 | 1.47x | 1.25 |
1.99 | 1.59x |
| forward | 8192 | 2048 | 65536 | 1 | 748.2 | 361.7 | 2.07x | 0.28 |
0.29 | 1.04x |
| forward | 8192 | 4096 | 65536 | 1 | 788.5 | 417.4 | 1.89x | 0.56 |
0.57 | 1.02x |
| forward | 2048 | 4096 | 131072 | 1 | 787.7 | 460.7 | 1.71x | 1.02 |
1.02 | 1.00x |
| forward | 2048 | 4096 | 131072 | 2 | 786.9 | 439.2 | 1.79x | 0.98 |
0.52 | 0.53x |
| forward | 2048 | 4096 | 131072 | 4 | 769.3 | 408.7 | 1.88x | 0.73 |
0.27 | 0.37x |
| forward | 2048 | 4096 | 131072 | 8 | 657.7 | 351.8 | 1.87x | 0.60 |
0.14 | 0.23x |
| forward | 2048 | 4096 | 131072 | 16 | 460.3 | 253.4 | 1.82x | 0.46 |
0.08 | 0.17x |
| forward | 8192 | 2048 | 131072 | 1 | 747.7 | 226.1 | 3.31x | 0.53 |
0.55 | 1.04x |
| forward | 8192 | 2048 | 131072 | 2 | 743.4 | 199.3 | 3.73x | 0.74 |
0.29 | 0.39x |
| forward | 8192 | 2048 | 131072 | 4 | 722.7 | 343.3 | 2.11x | 0.62 |
0.16 | 0.26x |
| forward | 8192 | 2048 | 131072 | 8 | 676.0 | 321.2 | 2.10x | 0.56 |
0.10 | 0.18x |
| forward | 8192 | 2048 | 131072 | 16 | 591.1 | 251.8 | 2.35x | 0.45 |
0.06 | 0.13x |
| forward | 8192 | 4096 | 131072 | 1 | 789.0 | 224.1 | 3.52x | 1.06 |
1.08 | 1.02x |
| forward | 8192 | 4096 | 131072 | 2 | 786.3 | 411.8 | 1.91x | 1.03 |
0.57 | 0.55x |
| forward | 8192 | 4096 | 131072 | 4 | 779.4 | 401.0 | 1.94x | 0.78 |
0.32 | 0.41x |
| forward | 8192 | 4096 | 131072 | 8 | 756.8 | 388.6 | 1.95x | 0.65 |
0.19 | 0.29x |
| forward | 8192 | 4096 | 131072 | 16 | 701.1 | 333.9 | 2.10x | 0.51 |
0.13 | 0.25x |
| forward | 16384 | 4096 | 131072 | 1 | 757.4 | 372.8 | 2.03x | 1.13 |
1.16 | 1.03x |
| forward | 16384 | 4096 | 131072 | 2 | 754.9 | 365.0 | 2.07x | 1.09 |
0.64 | 0.59x |
| forward | 16384 | 4096 | 131072 | 4 | 744.7 | 358.3 | 2.08x | 0.84 |
0.38 | 0.45x |
| forward | 16384 | 4096 | 131072 | 8 | 719.9 | 331.1 | 2.17x | 0.72 |
0.25 | 0.35x |
| forward | 16384 | 4096 | 131072 | 16 | 692.2 | 327.0 | 2.12x | 0.57 |
0.19 | 0.33x |
| forward | 2048 | 4096 | 262144 | 1 | 791.1 | 468.7 | 1.69x | 2.02 |
2.02 | 1.00x |
| forward | 2048 | 4096 | 262144 | 2 | 783.1 | 422.3 | 1.85x | 1.48 |
1.02 | 0.69x |
| forward | 2048 | 4096 | 262144 | 4 | 790.9 | 437.6 | 1.81x | 0.98 |
0.52 | 0.53x |
| forward | 2048 | 4096 | 262144 | 8 | 754.4 | 404.2 | 1.87x | 0.73 |
0.27 | 0.37x |
| forward | 2048 | 4096 | 262144 | 16 | 609.5 | 327.5 | 1.86x | 0.52 |
0.14 | 0.27x |
| forward | 8192 | 2048 | 262144 | 1 | 747.5 | 372.3 | 2.01x | 1.03 |
1.06 | 1.03x |
| forward | 8192 | 2048 | 262144 | 2 | 745.5 | 360.5 | 2.07x | 0.99 |
0.55 | 0.56x |
| forward | 8192 | 2048 | 262144 | 4 | 740.7 | 353.1 | 2.10x | 0.74 |
0.29 | 0.39x |
| forward | 8192 | 2048 | 262144 | 8 | 714.4 | 341.1 | 2.09x | 0.62 |
0.16 | 0.26x |
| forward | 8192 | 2048 | 262144 | 16 | 648.8 | 309.6 | 2.10x | 0.48 |
0.10 | 0.21x |
| forward | 8192 | 4096 | 262144 | 1 | 788.3 | 208.0 | 3.79x | 2.06 |
2.09 | 1.01x |
| forward | 8192 | 4096 | 262144 | 2 | 787.6 | 233.2 | 3.38x | 1.53 |
1.08 | 0.71x |
| forward | 8192 | 4096 | 262144 | 4 | 789.0 | 411.4 | 1.92x | 1.03 |
0.57 | 0.55x |
| forward | 8192 | 4096 | 262144 | 8 | 775.0 | 401.4 | 1.93x | 0.78 |
0.32 | 0.41x |
| forward | 8192 | 4096 | 262144 | 16 | 741.9 | 379.7 | 1.95x | 0.57 |
0.19 | 0.33x |
| forward | 16384 | 4096 | 262144 | 1 | 755.3 | 374.1 | 2.02x | 2.13 |
2.19 | 1.03x |
| forward | 16384 | 4096 | 262144 | 2 | 755.0 | 367.4 | 2.05x | 1.59 |
1.16 | 0.73x |
| forward | 16384 | 4096 | 262144 | 4 | 753.8 | 364.0 | 2.07x | 1.09 |
0.64 | 0.59x |
| forward | 16384 | 4096 | 262144 | 8 | 742.1 | 357.1 | 2.08x | 0.84 |
0.38 | 0.45x |
| forward | 16384 | 4096 | 262144 | 16 | 709.3 | 344.8 | 2.06x | 0.64 |
0.25 | 0.39x |
| forward | 8192 | 2048 | 524288 | 8 | 736.9 | 351.5 | 2.10x | 0.74 |
0.29 | 0.39x |
| forward | 8192 | 4096 | 524288 | 8 | 782.6 | 410.2 | 1.91x | 1.03 |
0.57 | 0.55x |
| forward | 8192 | 2048 | 1048576 | 16 | 729.1 | 347.2 | 2.10x | 0.66 |
0.29 | 0.44x |
| forward | 8192 | 4096 | 1048576 | 16 | 776.0 | 407.4 | 1.90x | 0.95 |
0.57 | 0.60x |

## Liger entropy-on results

| Pass | M | H | V | TP | p50 ms | TF/GPU | Aggregate TF | GiB | Backend
| split-K |
|---|---:|---:|---:|---:|---:|---:|---:|---:|---|---:|
| backward | 2048 | 4096 | 131072 | 1 | 8.589 | 768.1 | 768.1 | 3.85 |
nvls | 1 |
| backward | 2048 | 4096 | 131072 | 2 | 4.395 | 750.4 | 1500.9 | 2.72 |
nvls | 1 |
| backward | 2048 | 4096 | 131072 | 4 | 2.311 | 713.7 | 2854.6 | 2.16 |
nvls | 1 |
| backward | 2048 | 4096 | 131072 | 8 | 1.291 | 638.5 | 5108.2 | 1.88 |
nvls | 1 |
| backward | 2048 | 4096 | 131072 | 16 | 1.066 | 386.9 | 6190.2 | 0.17 |
hierarchical | 1 |
| backward | 2048 | 4096 | 262144 | 1 | 16.842 | 783.4 | 783.4 | 6.10 |
nvls | 1 |
| backward | 2048 | 4096 | 262144 | 2 | 8.570 | 769.8 | 1539.6 | 3.85 |
nvls | 1 |
| backward | 2048 | 4096 | 262144 | 4 | 4.366 | 755.6 | 3022.2 | 2.72 |
nvls | 1 |
| backward | 2048 | 4096 | 262144 | 8 | 2.306 | 715.1 | 5720.5 | 2.16 |
nvls | 1 |
| backward | 2048 | 4096 | 262144 | 16 | 1.574 | 523.8 | 8380.4 | 0.31 |
hierarchical | 1 |
| backward | 8192 | 2048 | 65536 | 1 | 10.008 | 659.2 | 659.2 | 2.26 |
nvls | 2 |
| backward | 8192 | 2048 | 131072 | 1 | 19.086 | 691.3 | 691.3 | 2.88 |
nvls | 2 |
| backward | 8192 | 2048 | 131072 | 2 | 10.421 | 633.0 | 1266.1 | 2.26 |
nvls | 2 |
| backward | 8192 | 2048 | 131072 | 4 | 5.759 | 572.8 | 2291.2 | 1.94 |
nvls | 2 |
| backward | 8192 | 2048 | 131072 | 8 | 3.467 | 475.7 | 3805.4 | 1.79 |
nvls | 2 |
| backward | 8192 | 2048 | 131072 | 16 | 3.141 | 262.6 | 4201.1 | 0.14 |
hierarchical | 2 |
| backward | 8192 | 2048 | 262144 | 1 | 37.342 | 706.7 | 706.7 | 4.13 |
nvls | 2 |
| backward | 8192 | 2048 | 262144 | 2 | 19.290 | 684.0 | 1368.0 | 2.88 |
nvls | 2 |
| backward | 8192 | 2048 | 262144 | 4 | 10.105 | 652.8 | 2611.3 | 2.26 |
nvls | 2 |
| backward | 8192 | 2048 | 262144 | 8 | 5.454 | 604.8 | 4838.6 | 1.94 |
nvls | 2 |
| backward | 8192 | 2048 | 262144 | 16 | 3.999 | 412.4 | 6598.0 | 0.22 |
hierarchical | 2 |
| backward | 8192 | 2048 | 524288 | 8 | 10.070 | 655.1 | 5241.0 | 2.26 |
nvls | 2 |
| backward | 8192 | 2048 | 1048576 | 16 | 10.573 | 624.0 | 9983.4 | 0.69
| hierarchical | 2 |
| backward | 8192 | 4096 | 65536 | 1 | 17.420 | 757.4 | 757.4 | 2.82 |
nvls | 1 |
| backward | 8192 | 4096 | 131072 | 1 | 34.601 | 762.6 | 762.6 | 3.94 |
nvls | 1 |
| backward | 8192 | 4096 | 131072 | 2 | 17.774 | 742.3 | 1484.7 | 2.82 |
nvls | 1 |
| backward | 8192 | 4096 | 131072 | 4 | 9.214 | 716.0 | 2863.9 | 2.26 |
nvls | 1 |
| backward | 8192 | 4096 | 131072 | 8 | 5.153 | 640.2 | 5121.4 | 1.97 |
nvls | 1 |
| backward | 8192 | 4096 | 131072 | 16 | 3.963 | 416.2 | 6658.9 | 0.27 |
hierarchical | 1 |
| backward | 8192 | 4096 | 262144 | 1 | 67.858 | 777.8 | 777.8 | 6.19 |
nvls | 1 |
| backward | 8192 | 4096 | 262144 | 2 | 34.470 | 765.5 | 1531.1 | 3.94 |
nvls | 1 |
| backward | 8192 | 4096 | 262144 | 4 | 17.560 | 751.4 | 3005.5 | 2.82 |
nvls | 1 |
| backward | 8192 | 4096 | 262144 | 8 | 9.209 | 716.4 | 5731.1 | 2.26 |
nvls | 1 |
| backward | 8192 | 4096 | 262144 | 16 | 6.014 | 548.5 | 8775.6 | 0.41 |
hierarchical | 1 |
| backward | 8192 | 4096 | 524288 | 8 | 17.647 | 747.7 | 5981.2 | 2.82 |
nvls | 1 |
| backward | 8192 | 4096 | 1048576 | 16 | 18.181 | 725.7 | 11611.2 |
1.25 | hierarchical | 1 |
| backward | 16384 | 4096 | 131072 | 1 | 69.235 | 762.3 | 762.3 | 4.07 |
nvls | 1 |
| backward | 16384 | 4096 | 131072 | 2 | 35.679 | 739.6 | 1479.2 | 2.94
| nvls | 1 |
| backward | 16384 | 4096 | 131072 | 4 | 18.499 | 713.2 | 2853.0 | 2.38
| nvls | 1 |
| backward | 16384 | 4096 | 131072 | 8 | 10.382 | 635.4 | 5083.3 | 2.10
| nvls | 1 |
| backward | 16384 | 4096 | 131072 | 16 | 7.832 | 421.1 | 6738.3 | 0.39
| hierarchical | 1 |
| backward | 16384 | 4096 | 262144 | 1 | 136.168 | 775.2 | 775.2 | 6.32
| nvls | 1 |
| backward | 16384 | 4096 | 262144 | 2 | 69.172 | 763.0 | 1526.0 | 4.07
| nvls | 1 |
| backward | 16384 | 4096 | 262144 | 4 | 35.475 | 743.9 | 2975.4 | 2.94
| nvls | 1 |
| backward | 16384 | 4096 | 262144 | 8 | 18.444 | 715.4 | 5722.9 | 2.38
| nvls | 1 |
| backward | 16384 | 4096 | 262144 | 16 | 11.933 | 552.8 | 8845.5 | 0.53
| hierarchical | 1 |
| forward | 2048 | 4096 | 131072 | 1 | 2.842 | 773.9 | 773.9 | 1.02 |
nvls | |
| forward | 2048 | 4096 | 131072 | 2 | 1.392 | 789.8 | 1579.6 | 0.98 |
nvls | |
| forward | 2048 | 4096 | 131072 | 4 | 0.720 | 763.8 | 3055.3 | 0.73 |
nvls | |
| forward | 2048 | 4096 | 131072 | 8 | 0.424 | 648.0 | 5183.8 | 0.60 |
nvls | |
| forward | 2048 | 4096 | 131072 | 16 | 0.303 | 453.9 | 7262.3 | 0.46 |
hierarchical | |
| forward | 2048 | 4096 | 262144 | 1 | 5.612 | 783.6 | 783.6 | 2.02 |
nvls | |
| forward | 2048 | 4096 | 262144 | 2 | 2.820 | 779.7 | 1559.3 | 1.48 |
nvls | |
| forward | 2048 | 4096 | 262144 | 4 | 1.395 | 788.4 | 3153.5 | 0.98 |
nvls | |
| forward | 2048 | 4096 | 262144 | 8 | 0.736 | 746.5 | 5972.1 | 0.73 |
nvls | |
| forward | 2048 | 4096 | 262144 | 16 | 0.456 | 603.4 | 9653.6 | 0.52 |
hierarchical | |
| forward | 8192 | 2048 | 65536 | 1 | 2.957 | 743.6 | 743.6 | 0.28 |
nvls | |
| forward | 8192 | 2048 | 131072 | 1 | 5.899 | 745.5 | 745.5 | 0.53 |
nvls | |
| forward | 8192 | 2048 | 131072 | 2 | 2.973 | 739.7 | 1479.4 | 0.74 |
nvls | |
| forward | 8192 | 2048 | 131072 | 4 | 1.533 | 717.4 | 2869.6 | 0.62 |
nvls | |
| forward | 8192 | 2048 | 131072 | 8 | 0.815 | 674.2 | 5393.4 | 0.56 |
nvls | |
| forward | 8192 | 2048 | 131072 | 16 | 0.473 | 580.9 | 9294.3 | 0.45 |
hierarchical | |
| forward | 8192 | 2048 | 262144 | 1 | 11.777 | 746.9 | 746.9 | 1.03 |
nvls | |
| forward | 8192 | 2048 | 262144 | 2 | 5.918 | 743.1 | 1486.2 | 0.99 |
nvls | |
| forward | 8192 | 2048 | 262144 | 4 | 2.988 | 736.0 | 2944.0 | 0.74 |
nvls | |
| forward | 8192 | 2048 | 262144 | 8 | 1.548 | 710.5 | 5683.6 | 0.62 |
nvls | |
| forward | 8192 | 2048 | 262144 | 16 | 0.854 | 643.8 | 10300.6 | 0.48 |
hierarchical | |
| forward | 8192 | 2048 | 524288 | 8 | 3.002 | 732.6 | 5860.9 | 0.74 |
nvls | |
| forward | 8192 | 2048 | 1048576 | 16 | 3.045 | 722.1 | 11553.5 | 0.66
| hierarchical | |
| forward | 8192 | 4096 | 65536 | 1 | 5.596 | 785.9 | 785.9 | 0.56 |
nvls | |
| forward | 8192 | 4096 | 131072 | 1 | 11.182 | 786.7 | 786.7 | 1.06 |
nvls | |
| forward | 8192 | 4096 | 131072 | 2 | 5.575 | 788.9 | 1577.7 | 1.03 |
nvls | |
| forward | 8192 | 4096 | 131072 | 4 | 2.828 | 777.7 | 3110.7 | 0.78 |
nvls | |
| forward | 8192 | 4096 | 131072 | 8 | 1.458 | 754.1 | 6033.1 | 0.65 |
nvls | |
| forward | 8192 | 4096 | 131072 | 16 | 0.789 | 697.0 | 11151.2 | 0.51 |
hierarchical | |
| forward | 8192 | 4096 | 262144 | 1 | 22.375 | 786.2 | 786.2 | 2.06 |
nvls | |
| forward | 8192 | 4096 | 262144 | 2 | 11.141 | 789.5 | 1579.1 | 1.53 |
nvls | |
| forward | 8192 | 4096 | 262144 | 4 | 5.594 | 786.2 | 3144.9 | 1.03 |
nvls | |
| forward | 8192 | 4096 | 262144 | 8 | 2.833 | 776.2 | 6209.9 | 0.78 |
nvls | |
| forward | 8192 | 4096 | 262144 | 16 | 1.492 | 737.0 | 11791.4 | 0.57 |
hierarchical | |
| forward | 8192 | 4096 | 524288 | 8 | 5.645 | 779.2 | 6233.2 | 1.03 |
nvls | |
| forward | 8192 | 4096 | 1048576 | 16 | 5.677 | 774.7 | 12395.4 | 0.95
| hierarchical | |
| forward | 16384 | 4096 | 131072 | 1 | 23.312 | 754.6 | 754.6 | 1.13 |
nvls | |
| forward | 16384 | 4096 | 131072 | 2 | 11.685 | 752.8 | 1505.6 | 1.09 |
nvls | |
| forward | 16384 | 4096 | 131072 | 4 | 5.932 | 741.4 | 2965.4 | 0.84 |
nvls | |
| forward | 16384 | 4096 | 131072 | 8 | 3.067 | 716.9 | 5735.6 | 0.72 |
nvls | |
| forward | 16384 | 4096 | 131072 | 16 | 1.600 | 687.0 | 10992.6 | 0.57
| hierarchical | |
| forward | 16384 | 4096 | 262144 | 1 | 46.752 | 752.6 | 752.6 | 2.13 |
nvls | |
| forward | 16384 | 4096 | 262144 | 2 | 23.374 | 752.6 | 1505.3 | 1.59 |
nvls | |
| forward | 16384 | 4096 | 262144 | 4 | 11.702 | 751.7 | 3006.6 | 1.09 |
nvls | |
| forward | 16384 | 4096 | 262144 | 8 | 5.946 | 739.6 | 5917.2 | 0.84 |
nvls | |
| forward | 16384 | 4096 | 262144 | 16 | 3.116 | 705.7 | 11291.1 | 0.64
| hierarchical | |

## Resource results

- compact dZ handoff: 168 registers, zero spills, 11 barriers; dZ-only
p50 11.839 ms entropy-off and 11.898 ms entropy-on in the isolated
validation build.
- combined split-K1 and split-K2: 168 registers, zero spills, 7
barriers, 230,400 B dynamic shared memory; TPR1/2/4 validated.
- dX/dW mainloops are within 10% of tuned cuBLASLt; dX exceeds cuBLAS on
multicast-friendly shapes and dW is approximately 4% behind.

---------

Co-authored-by: jkolehma <[email protected]>
Co-authored-by: Copilot <[email protected]>
2026-08-31 20:15:17 +00:00
2024-08-13 11:09:50 -07:00
2025-08-30 08:33:05 -07:00
2024-10-01 21:10:42 +00:00

Liger Kernel: Efficient Triton Kernels for LLM Training

Stable Nightly Discord
Downloads (Stable) PyPI - Version Downloads (Nightly) PyPI - Version Join Our Discord

Installation | Getting Started | Examples | High-level APIs | Low-level APIs | Cite our work

Latest News 🔥

Liger Kernel is a collection of Triton kernels designed specifically for LLM training. It can effectively increase multi-GPU training throughput by 20% and reduces memory usage by 60%. We have implemented Hugging Face Compatible RMSNorm, RoPE, SwiGLU, CrossEntropy, FusedLinearCrossEntropy, and more to come. The kernel works out of the box with Flash Attention, PyTorch FSDP, and Microsoft DeepSpeed. We welcome contributions from the community to gather the best kernels for LLM training.

We've also added optimized Post-Training kernels that deliver up to 80% memory savings for alignment and distillation tasks. We support losses like DPO, CPO, ORPO, SimPO, KTO, JSD, and many more. Check out how we optimize the memory.

You can view the documentation site for additional installation, usage examples, and API references:https://linkedin.github.io/Liger-Kernel/

You can view the Liger Kernel Technical Report: https://openreview.net/forum?id=36SjAIT42G

Supercharge Your Model with Liger Kernel

Banner

With one line of code, Liger Kernel can increase throughput by more than 20% and reduce memory usage by 60%, thereby enabling longer context lengths, larger batch sizes, and massive vocabularies.

Speed Up Memory Reduction
Speed up Memory

Note:

  • Benchmark conditions: LLaMA 3-8B, Batch Size = 8, Data Type = bf16, Optimizer = AdamW, Gradient Checkpointing = True, Distributed Strategy = FSDP1 on 8 A100s.
  • Hugging Face models start to OOM at a 4K context length, whereas Hugging Face + Liger Kernel scales up to 16K.

Optimize Post Training with Liger Kernel

Post Training

We provide optimized post training kernels like DPO, ORPO, SimPO, and more which can reduce memory usage by up to 80%. You can easily use them as python modules.

from liger_kernel.chunked_loss import LigerFusedLinearORPOLoss
orpo_loss = LigerFusedLinearORPOLoss()
y = orpo_loss(lm_head.weight, x, target)

Examples

Use Case Description
Hugging Face Trainer Train LLaMA 3-8B ~20% faster with over 40% memory reduction on Alpaca dataset using 4 A100s with FSDP
Lightning Trainer Increase 15% throughput and reduce memory usage by 40% with LLaMA3-8B on MMLU dataset using 8 A100s with DeepSpeed ZeRO3
Medusa Multi-head LLM (Retraining Phase) Reduce memory usage by 80% with 5 LM heads and improve throughput by 40% using 8 A100s with FSDP
Vision-Language Model SFT Finetune Qwen2-VL on image-text data using 4 A100s with FSDP
Liger ORPO Trainer Align Llama 3.2 using Liger ORPO Trainer with FSDP with 50% memory reduction

Key Features

  • Ease of use: Simply patch your Hugging Face model with one line of code, or compose your own model using our Liger Kernel modules.
  • Time and memory efficient: In the same spirit as Flash-Attn, but for layers like RMSNorm, RoPE, SwiGLU, and CrossEntropy! Increases multi-GPU training throughput by 20% and reduces memory usage by 60% with kernel fusion, in-place replacement, and chunking techniques.
  • Exact: Computation is exact—no approximations! Both forward and backward passes are implemented with rigorous unit tests and undergo convergence testing against training runs without Liger Kernel to ensure accuracy.
  • Lightweight: Liger Kernel has minimal dependencies, requiring only Torch and Triton—no extra libraries needed! Say goodbye to dependency headaches!
  • Multi-GPU supported: Compatible with multi-GPU setups (PyTorch FSDP, DeepSpeed, DDP, etc.).
  • Trainer Framework Integration: Axolotl, LLaMa-Factory, SFTTrainer, Hugging Face Trainer, SWIFT, oumi

Installation

Dependencies

CUDA

  • torch >= 2.1.2
  • triton >= 2.3.0

ROCm

  • torch >= 2.5.0 Install according to the instruction in Pytorch official webpage.
  • triton >= 3.0.0 Install from pypi. (e.g. pip install triton==3.0.0)
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/rocm7.2

Ascend NPU

  • torch == 2.9.0
  • torch_npu == 2.9.0
  • triton-ascend == 3.2.2 Install from the Ascend PyPI mirror (not on default PyPI).
  • CANN == 9.1.0
pip install -e ".[dev]" --extra-index-url https://triton-ascend.osinfra.cn/pypi/simple

Optional Dependencies

  • transformers >= 4.x: Required if you plan to use the transformers models patching APIs. The specific model you are working will dictate the minimum version of transformers.
  • cuda-tile: Required when enabling the optional cuTile backend on CUDA. Use this when your environment already provides CUDA Toolkit 13.1 or newer, or an existing tileiras compiler installation.
  • cuda-tile[tileiras]: Required when enabling the optional cuTile backend with the tileiras compiler installed directly into your Python environment.
  • nvidia-cutlass-dsl >= 4.6.0: Required when enabling the optional CuTe DSL backend on CUDA (the CUDA-only Python DSL shipped with NVIDIA CUTLASS, import cutlass.cute). Targets Hopper (SM90) and Blackwell (SM100/SM110).

Note: Our kernels inherit the full spectrum of hardware compatibility offered by Triton.

To install the stable version:

$ pip install liger-kernel

To install the nightly version:

$ pip install liger-kernel-nightly

To install from source:

git clone https://github.com/linkedin/Liger-Kernel.git
cd Liger-Kernel

# Install Default Dependencies
# Setup.py will detect the local backend and select default dependencies.
# On ROCm, install ROCm PyTorch first from the PyTorch ROCm index.
pip install -e .

# Setup Development Dependencies
pip install -e ".[dev]"

# ROCm source installs
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/rocm7.2
# Then choose one:
pip install -e .
pip install -e ".[dev]"

# Setup cuTile Dependencies
pip install -e ".[cutile]"

# Or install cuTile with the optional tileiras compiler
pip install -e ".[cutile-tileiras]"

# Setup CuTe DSL (NVIDIA CUTLASS Python DSL) Dependencies
pip install -e ".[cutedsl]"

Enable cuTile Backend

cuTile is an optional CUDA-only DSL implementation. After installing the cutile or cutile-tileiras extra, enable it explicitly:

LIGER_KERNEL_IMPL=cutile python your_script.py

LIGER_KERNEL_IMPL selects an opt-in implementation registered with Liger (currently cutile and cutedsl). Selecting one on an unsupported device, or without the required dependencies installed, raises an error.

Enable CuTe DSL Backend

CuTe DSL is the optional, CUDA-only Python DSL shipped with NVIDIA CUTLASS (import cutlass.cute), targeting Hopper (SM90) and Blackwell (SM100/SM110). After installing the cutedsl extra, enable it explicitly:

pip install "liger-kernel[cutedsl]"
LIGER_KERNEL_IMPL=cutedsl python your_script.py

It currently provides genuine cutlass.cute implementations of:

  • RMSNorm
  • RoPE
  • SwiGLU
  • Cross entropy
  • Fused linear cross entropy (with an SM90-specialized variant)
  • Fused scaled cross entropy (SM90)

Ops without a CuTe DSL kernel transparently fall back to the default Triton kernel.

The cutedsl extra also pulls in apache-tvm-ffi, which lets compiled kernels take PyTorch tensors directly rather than marshalling each one per call. It is optional — every kernel falls back to the marshalling launch without it — but short kernels are dominated by that per-call cost, so installing it is strongly recommended.

Fused Scaled Cross Entropy

LigerFusedLinearScaledCrossEntropyFunction is an additional per-token operator, not a replacement for the reduction-oriented Triton LigerFusedLinearCrossEntropyFunction. It takes input[M, H], weight[V, H], and target[M], applies logits / temperature, and returns FP32 negative log-likelihood [M] plus optional differentiable vocabulary entropy [M] in the input dtype. Reductions remain in PyTorch, and rows whose target equals ignore_index contribute zero outputs and gradients.

from liger_kernel.ops import LigerFusedLinearScaledCrossEntropyFunction

nll, entropy = LigerFusedLinearScaledCrossEntropyFunction.apply(
    x, weight, target, 1.0, -100, 1, True
)  # [M], [M]
loss = nll.sum() / (target != -100).sum().clamp_min(1)

The implementations share this public contract but use different schedules:

  • cuTile (LIGER_KERNEL_IMPL=cutile) supports matching floating-point input and weight tensors on CUDA and a finite positive scalar temperature. The portable temporary-logits budget is 256 MiB. Large FP16/BF16 Blackwell workloads (M >= 4096, V >= 131072) automatically use 512 MiB to improve GEMM utilization. Set LIGER_CUTILE_SCALED_CE_WORKSPACE_MB to another positive MiB value for workload-specific tuning; for example, 1024 can help large combined NLL-plus-entropy workloads but is not universally faster. Backward reuses one workspace and writes dX and accumulates dW directly into their final tensors. m_tiles_per_cluster is accepted for API compatibility but does not change the cuTile schedule.
  • CuTe SM90 uses LigerFusedScaledCrossEntropySM90Function for BF16 inputs on Hopper. Its sole forward uses the fixed cluster-M2 N160 fragment kernel, with a measured split-N lookup for profiled long-sequence shapes, and never writes logits to HBM; m_tiles_per_cluster remains accepted for API compatibility but does not change that schedule. Backward runs dZ, dX, and dW in one persistent cluster kernel with a reusable 1024-token dZ workspace.
  • Fallback uses a 512-token chunked PyTorch implementation adapted from Verl's fused PPO formulas when the default frontend cannot use the SM90 kernel.

H100 BF16 forward medians from 60 interleaved samples per provider at H=4096, V=131072. Effective TFLOPS count the common projection work, 2*M*H*V:

M Entropy CuTe SM90 cuTile Verl Torch fallback
2048 No 3.12 ms / 706 TFLOPS 3.19 ms / 690 TFLOPS 11.36 ms / 194 TFLOPS
2048 Yes 3.13 ms / 703 TFLOPS 3.25 ms / 676 TFLOPS 11.37 ms / 193 TFLOPS
4096 No 6.05 ms / 727 TFLOPS 6.28 ms / 701 TFLOPS 22.62 ms / 194 TFLOPS
4096 Yes 6.11 ms / 720 TFLOPS 6.39 ms / 688 TFLOPS 22.68 ms / 194 TFLOPS
8192 No 12.25 ms / 718 TFLOPS 12.41 ms / 709 TFLOPS 45.35 ms / 194 TFLOPS
8192 Yes 12.30 ms / 715 TFLOPS 12.70 ms / 693 TFLOPS 45.59 ms / 193 TFLOPS
16384 No 23.84 ms / 738 TFLOPS 25.11 ms / 700 TFLOPS 90.81 ms / 194 TFLOPS
16384 Yes 24.09 ms / 730 TFLOPS 26.10 ms / 674 TFLOPS 90.97 ms / 193 TFLOPS
32768 No 49.69 ms / 708 TFLOPS 54.31 ms / 648 TFLOPS 180.01 ms / 195 TFLOPS
32768 Yes 49.85 ms / 706 TFLOPS 55.69 ms / 632 TFLOPS 179.85 ms / 196 TFLOPS

Backward medians use 30 interleaved samples per provider. Effective TFLOPS count 6*M*H*V:

M Entropy CuTe SM90 cuTile Verl Torch fallback
8192 No 37.93 ms / 696 TFLOPS 42.55 ms / 620 TFLOPS 85.17 ms / 310 TFLOPS
8192 Yes 37.89 ms / 696 TFLOPS 41.43 ms / 637 TFLOPS 121.00 ms / 218 TFLOPS
16384 No 79.42 ms / 665 TFLOPS 83.78 ms / 630 TFLOPS 166.85 ms / 316 TFLOPS
16384 Yes 78.20 ms / 675 TFLOPS 84.12 ms / 627 TFLOPS 239.39 ms / 220 TFLOPS
32768 No 163.34 ms / 646 TFLOPS 163.21 ms / 647 TFLOPS 331.08 ms / 319 TFLOPS
32768 Yes 160.64 ms / 657 TFLOPS 161.73 ms / 653 TFLOPS 477.51 ms / 221 TFLOPS

Full forward-and-backward effective TFLOPS count 8*M*H*V:

M Entropy CuTe SM90 cuTile Verl Torch fallback
8192 No 50.39 ms / 698 TFLOPS 57.15 ms / 616 TFLOPS 128.76 ms / 273 TFLOPS
8192 Yes 50.22 ms / 701 TFLOPS 56.86 ms / 619 TFLOPS 165.63 ms / 212 TFLOPS
16384 No 104.77 ms / 672 TFLOPS 112.03 ms / 628 TFLOPS 254.91 ms / 276 TFLOPS
16384 Yes 103.65 ms / 679 TFLOPS 111.21 ms / 633 TFLOPS 328.37 ms / 214 TFLOPS
32768 No 211.30 ms / 666 TFLOPS 221.34 ms / 636 TFLOPS 508.33 ms / 277 TFLOPS
32768 Yes 210.60 ms / 668 TFLOPS 221.39 ms / 636 TFLOPS 655.89 ms / 215 TFLOPS

B200 measurements for the same shape, using automatic cuTile workspace selection:

Implementation Forward Backward Full Peak full memory
cuTile 2.97 ms 8.35 ms 11.36 ms 2.64 GiB
Torch 5.24 ms 7.15 ms 12.85 ms 7.22 GiB

Getting Started

There are a couple of ways to apply Liger kernels, depending on the level of customization required.

1. Use AutoLigerKernelForCausalLM

Using the AutoLigerKernelForCausalLM is the simplest approach, as you don't have to import a model-specific patching API. If the model type is supported, the modeling code will be automatically patched using the default settings.

from liger_kernel.transformers import AutoLigerKernelForCausalLM

# This AutoModel wrapper class automatically monkey-patches the
# model with the optimized Liger kernels if the model is supported.
model = AutoLigerKernelForCausalLM.from_pretrained("path/to/some/model")

2. Apply Model-Specific Patching APIs

Using the patching APIs, you can swap Hugging Face models with optimized Liger Kernels.

import transformers
from liger_kernel.transformers import apply_liger_kernel_to_llama

# 1a. Adding this line automatically monkey-patches the model with the optimized Liger kernels
apply_liger_kernel_to_llama()

# 1b. You could alternatively specify exactly which kernels are applied
apply_liger_kernel_to_llama(
  rope=True,
  swiglu=True,
  cross_entropy=True,
  fused_linear_cross_entropy=False,
  rms_norm=False
)

# 2. Instantiate patched model
model = transformers.AutoModelForCausalLM("path/to/llama/model")

3. Compose Your Own Model

You can take individual kernels to compose your models.

from liger_kernel.transformers import LigerFusedLinearCrossEntropyLoss
import torch.nn as nn
import torch

model = nn.Linear(128, 256).cuda()

# fuses linear + cross entropy layers together and performs chunk-by-chunk computation to reduce memory
loss_fn = LigerFusedLinearCrossEntropyLoss()

input = torch.randn(4, 128, requires_grad=True, device="cuda")
target = torch.randint(256, (4, ), device="cuda")

loss = loss_fn(model.weight, input, target)
loss.backward()

High-level APIs

AutoModel

AutoModel Variant API
AutoModelForCausalLM liger_kernel.transformers.AutoLigerKernelForCausalLM

Patching

Model API Supported Operations
Llama4 (Text) & (Multimodal) liger_kernel.transformers.apply_liger_kernel_to_llama4 RMSNorm, LayerNorm, GeGLU, CrossEntropyLoss, FusedLinearCrossEntropy
LLaMA 2 & 3 liger_kernel.transformers.apply_liger_kernel_to_llama RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
LLaMA 3.2-Vision liger_kernel.transformers.apply_liger_kernel_to_mllama RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Ministral liger_kernel.transformers.apply_liger_kernel_to_ministral RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Mistral liger_kernel.transformers.apply_liger_kernel_to_mistral RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Mixtral liger_kernel.transformers.apply_liger_kernel_to_mixtral RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Nemotron liger_kernel.transformers.apply_liger_kernel_to_nemotron ReLUSquared, CrossEntropyLoss, FusedLinearCrossEntropy
Pixtral liger_kernel.transformers.apply_liger_kernel_to_pixtral RoPE, RMSNorm, SwiGLU
Gemma1 liger_kernel.transformers.apply_liger_kernel_to_gemma RoPE, RMSNorm, GeGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Gemma2 liger_kernel.transformers.apply_liger_kernel_to_gemma2 RoPE, RMSNorm, GeGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Gemma3 (Text) liger_kernel.transformers.apply_liger_kernel_to_gemma3_text RoPE, RMSNorm, GeGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Gemma3 (Multimodal) liger_kernel.transformers.apply_liger_kernel_to_gemma3 LayerNorm, RoPE, RMSNorm, GeGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Gemma4 (Text) liger_kernel.transformers.apply_liger_kernel_to_gemma4_text RMSNorm, GeGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Gemma4 (Multimodal) liger_kernel.transformers.apply_liger_kernel_to_gemma4 RMSNorm, GeGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Paligemma, Paligemma2, & Paligemma2 Mix liger_kernel.transformers.apply_liger_kernel_to_paligemma LayerNorm, RoPE, RMSNorm, GeGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Qwen2, Qwen2.5, & QwQ liger_kernel.transformers.apply_liger_kernel_to_qwen2 RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Qwen2-VL, & QVQ liger_kernel.transformers.apply_liger_kernel_to_qwen2_vl RMSNorm, LayerNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Qwen2.5-VL liger_kernel.transformers.apply_liger_kernel_to_qwen2_5_vl RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Qwen3 liger_kernel.transformers.apply_liger_kernel_to_qwen3 RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Qwen3 MoE liger_kernel.transformers.apply_liger_kernel_to_qwen3_moe RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Qwen3.5 liger_kernel.transformers.apply_liger_kernel_to_qwen3_5 RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Qwen3.5 MoE (Text) & (Multimodal) liger_kernel.transformers.apply_liger_kernel_to_qwen3_5_moe RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Phi3 & Phi3.5 liger_kernel.transformers.apply_liger_kernel_to_phi3 RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Granite 3.0 & 3.1 liger_kernel.transformers.apply_liger_kernel_to_granite RoPE, RMSNorm, SwiGLU, CrossEntropyLoss
OLMo2 liger_kernel.transformers.apply_liger_kernel_to_olmo2 RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
Olmo3 liger_kernel.transformers.apply_liger_kernel_to_olmo3 RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
GLM-4 liger_kernel.transformers.apply_liger_kernel_to_glm4 RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
DeepSeek-V4 liger_kernel.transformers.apply_liger_kernel_to_deepseek_v4 RMSNorm, CrossEntropyLoss, FusedLinearCrossEntropy
GPT-OSS liger_kernel.transformers.apply_liger_kernel_to_gpt_oss RoPE, RMSNorm, CrossEntropyLoss, FusedLinearCrossEntropy
InternVL3 liger_kernel.transformers.apply_liger_kernel_to_internvl RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
HunyuanV1 liger_kernel.transformers.apply_liger_kernel_to_hunyuan_v1_dense RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy
HunyuanV1 MoE liger_kernel.transformers.apply_liger_kernel_to_hunyuan_v1_moe RoPE, RMSNorm, SwiGLU, CrossEntropyLoss, FusedLinearCrossEntropy

Low-level APIs

  • Fused Linear kernels combine linear layers with losses, reducing memory usage by up to 80% - ideal for HBM-constrained workloads.
  • Other kernels use fusion and in-place techniques for memory and performance optimization.

Model Kernels

Kernel API
RMSNorm liger_kernel.transformers.LigerRMSNorm
Modulated RMSNorm liger_kernel.transformers.LigerModulatedRMSNorm
LayerNorm liger_kernel.transformers.LigerLayerNorm
RoPE liger_kernel.transformers.liger_rotary_pos_emb
SwiGLU liger_kernel.transformers.LigerSwiGLUMLP
GeGLU liger_kernel.transformers.LigerGEGLUMLP
CrossEntropy liger_kernel.transformers.LigerCrossEntropyLoss
Fused Linear CrossEntropy liger_kernel.transformers.LigerFusedLinearCrossEntropyLoss
Multi Token Attention liger_kernel.transformers.LigerMultiTokenAttention
Softmax liger_kernel.transformers.LigerSoftmax
Sparsemax liger_kernel.transformers.LigerSparsemax
mHC (Hyper-Connections) liger_kernel.transformers.LigerMHC

Alignment Kernels

Kernel API
Fused Linear CPO Loss liger_kernel.chunked_loss.LigerFusedLinearCPOLoss
Fused Linear DPO Loss liger_kernel.chunked_loss.LigerFusedLinearDPOLoss
Fused Linear ORPO Loss liger_kernel.chunked_loss.LigerFusedLinearORPOLoss
Fused Linear SimPO Loss liger_kernel.chunked_loss.LigerFusedLinearSimPOLoss
Fused Linear KTO Loss liger_kernel.chunked_loss.LigerFusedLinearKTOLoss

Distillation Kernels

Kernel API
KLDivergence liger_kernel.transformers.LigerKLDIVLoss
JSD liger_kernel.transformers.LigerJSD
Fused Linear JSD liger_kernel.transformers.LigerFusedLinearJSD
TVD liger_kernel.transformers.LigerTVDLoss

Experimental Kernels

Kernel API
Embedding liger_kernel.transformers.experimental.LigerEmbedding
Matmul int2xint8 liger_kernel.transformers.experimental.matmul

Contributing, Acknowledgements, and License

Sponsorship and Collaboration

  • Glows.ai: Sponsoring NVIDIA GPUs for our open source developers.
  • AMD: Providing AMD GPUs for our AMD CI.
  • Intel: Providing Intel GPUs for our Intel CI.
  • Modal: Free 3000 credits from GPU MODE IRL for our NVIDIA CI.
  • EmbeddedLLM: Making Liger Kernel run fast and stable on AMD.
  • HuggingFace: Integrating Liger Kernel into Hugging Face Transformers and TRL.
  • Lightning AI: Integrating Liger Kernel into Lightning Thunder.
  • Axolotl: Integrating Liger Kernel into Axolotl.
  • Llama-Factory: Integrating Liger Kernel into Llama-Factory.

CI status

Platform Build
NVIDIA GPU NVIDIA GPU Build
AMD GPU AMD GPU Build
Intel GPU Intel GPU Build
Ascend NPU Ascend NPU Build

Contact

Cite this work

Biblatex entry:

@inproceedings{
hsu2025ligerkernel,
title={Liger-Kernel: Efficient Triton Kernels for {LLM} Training},
author={Pin-Lun Hsu and Yun Dai and Vignesh Kothapalli and Qingquan Song and Shao Tang and Siyu Zhu and Steven Shimizu and Shivam Sahni and Haowen Ning and Yanning Chen and Zhipeng Wang},
booktitle={Championing Open-source DEvelopment in ML Workshop @ ICML25},
year={2025},
url={https://openreview.net/forum?id=36SjAIT42G}
}

Star History

Star History Chart

↑ Back to Top ↑

Languages
Python 62.4%
Cuda 31.7%
NASL 3.9%
C++ 1.3%
CMake 0.6%
Other 0.1%