h3-blackwell-runtime/tools/validate_h3_fusion.py

"""Validate fused H3 elementwise kernels on real checkpoint blocks."""

from __future__ import annotations

import argparse
import json
import time
from pathlib import Path

import torch

from h3_blackwell_runtime.adaln import H3CurveAdaLN
from h3_blackwell_runtime.block import H3DiTBlock
from h3_blackwell_runtime.checkpoint import H3Checkpoint
from h3_blackwell_runtime.packing import H3PromptPacker
from h3_blackwell_runtime.rope import h3_rope_rotation
from h3_blackwell_runtime.sampler import _audio_sigma, _model_sigma, beta_sigmas
from h3_blackwell_runtime.t2v import random_av_latents
from profile_h3_block import summarize


def sync() -> None:
    torch.cuda.synchronize()


def timed(fn, warmup: int, iterations: int) -> dict[str, float]:
    with torch.inference_mode():
        for _ in range(warmup):
            fn()
        values = []
        for _ in range(iterations):
            sync()
            started = time.perf_counter()
            fn()
            sync()
            values.append(time.perf_counter() - started)
    return summarize(values)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--model-path", default="/models/minimax_h3_fl2va_pruned_nvfp4.safetensors")
    parser.add_argument("--output", type=Path, required=True)
    parser.add_argument("--width", type=int, default=1344)
    parser.add_argument("--height", type=int, default=768)
    parser.add_argument("--frames", type=int, default=124)
    parser.add_argument("--steps", type=int, default=12)
    parser.add_argument("--sampler-step", type=int, default=1)
    parser.add_argument("--seed", type=int, default=440420)
    parser.add_argument("--text-tokens", type=int, default=100)
    parser.add_argument("--blocks", nargs="+", type=int, default=(0, 24, 49))
    parser.add_argument("--attention", default="sage2")
    parser.add_argument("--warmup", type=int, default=3)
    parser.add_argument("--iterations", type=int, default=10)
    parser.add_argument("--device", default="cuda")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    torch.manual_seed(args.seed)
    checkpoint = H3Checkpoint(args.model_path, device=args.device)
    packer = H3PromptPacker(checkpoint)
    video, audio, aligned_frames = random_av_latents(
        args.width, args.height, args.frames, args.seed, device=args.device,
    )
    sigma = beta_sigmas(args.steps, device=args.device)[args.sampler_step - 1]
    native_audio = audio.to(torch.bfloat16) * (_audio_sigma(sigma) / sigma)
    text = torch.randn(
        1, args.text_tokens, 5376, device=args.device, dtype=torch.bfloat16,
    )
    hidden, timesteps, segments, positions, _, _ = packer(
        text, video, native_audio, _model_sigma(sigma),
    )
    rotation = h3_rope_rotation(
        positions.to(args.device), checkpoint.tensor("rope.inv_freq", dtype=torch.float32), hidden.dtype,
    )

    results = []
    for block_index in args.blocks:
        if not 0 <= block_index < 50:
            raise ValueError("block indices must be in [0, 49]")
        block = H3DiTBlock.from_checkpoint(
            checkpoint, block_index, attention_backend=args.attention,
        ).eval()
        adaln = H3CurveAdaLN.from_checkpoint(
            checkpoint, f"blocks.{block_index}.adaln_proj",
        ).eval()
        modulation = tuple(value.detach() for value in adaln(timesteps))

        with torch.inference_mode():
            block.fused_elementwise = False
            expected = block(hidden.clone(), rotation, *modulation, segments)
            block.fused_elementwise = True
            actual = block(hidden.clone(), rotation, *modulation, segments)
        delta = actual.float() - expected.float()
        parity = {
            "equal": torch.equal(actual, expected),
            "max_abs": delta.abs().max().item(),
            "mean_abs": delta.abs().mean().item(),
            "reference_checksum": expected.float().sum().item(),
            "fused_checksum": actual.float().sum().item(),
        }
        if not parity["equal"]:
            raise RuntimeError(f"block {block_index} fused output is not bit-exact: {parity}")

        block.fused_elementwise = False
        eager_timing = timed(
            lambda: block(hidden.clone(), rotation, *modulation, segments),
            args.warmup,
            args.iterations,
        )
        block.fused_elementwise = True
        fused_timing = timed(
            lambda: block(hidden.clone(), rotation, *modulation, segments),
            args.warmup,
            args.iterations,
        )
        results.append({
            "block": block_index,
            "parity": parity,
            "eager_timing": eager_timing,
            "fused_timing": fused_timing,
            "p50_speedup": eager_timing["p50_s"] / fused_timing["p50_s"],
            "p50_latency_reduction": 1.0 - fused_timing["p50_s"] / eager_timing["p50_s"],
        })
        print(
            f"block {block_index}: exact, eager={eager_timing['p50_s'] * 1000:.3f}ms, "
            f"fused={fused_timing['p50_s'] * 1000:.3f}ms, "
            f"speedup={results[-1]['p50_speedup']:.3f}x",
            flush=True,
        )

    report = {
        "device": torch.cuda.get_device_name(),
        "torch": torch.__version__,
        "resolution": [args.width, args.height],
        "frames": aligned_frames,
        "packed_tokens": hidden.shape[0],
        "steps": args.steps,
        "sampler_step": args.sampler_step,
        "seed": args.seed,
        "attention": args.attention,
        "warmup": args.warmup,
        "iterations": args.iterations,
        "results": results,
    }
    args.output.parent.mkdir(parents=True, exist_ok=True)
    args.output.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")


if __name__ == "__main__":
    main()