Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

16.4 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""ConvRot: offline and online halves must cancel exactly, and every mismatch must be refused."""

from __future__ import annotations

import contextlib
import sys
import types

import pytest

torch = pytest.importorskip("torch")
nn = torch.nn

import core.inference.diffusion_prequant as pq  # noqa: E402
from core.inference.diffusion_convrot import (  # noqa: E402
    CONVROT_ATTR,
    CONVROT_KIND,
    DEFAULT_CONVROT_GROUPSIZE,
    ROTATION_FQNS_KEY,
    ROTATION_GROUP_KEY,
    ROTATION_KEY,
    apply_activation_rotation,
    build_convrot_hadamard,
    declares_rotation,
    is_power_of_four,
    is_rotated_linear,
    rotatable_fqns,
    rotate_convrot_weight_,
    rotate_linears_,
    rotation_metadata,
    rotation_metadata_error,
)


@pytest.fixture(autouse = True)
def _pin_prequant_safe_globals(real_prequant_safe_globals):
    """Apply the shared stand-in allowlist (see conftest) to every test in this module."""
    return real_prequant_safe_globals


GROUP = 16  # a power of 4, small enough to keep the test model tiny


class _Model(nn.Module):
    """Three Linears: two the group divides, one it does not."""

    def __init__(self, group: int = GROUP) -> None:
        super().__init__()
        self.a = nn.Linear(4 * group, 8)
        self.b = nn.Linear(2 * group, 8)
        self.odd = nn.Linear(group + 1, 8)


def _meta(
    fqns,
    group = GROUP,
    kind = CONVROT_KIND,
):
    return {
        ROTATION_KEY: kind,
        ROTATION_GROUP_KEY: group,
        ROTATION_FQNS_KEY: list(fqns),
    }


def test_power_of_four_gate():
    assert [n for n in (1, 2, 4, 8, 16, 32, 64, 256, 1024) if is_power_of_four(n)] == [
        4,
        16,
        64,
        256,
        1024,
    ]
    assert not is_power_of_four(0)
    assert not is_power_of_four(-4)
    assert not is_power_of_four("256")
    assert not is_power_of_four(None)


def test_hadamard_is_symmetric_and_orthogonal():
    # Symmetry (H.T is H) and orthogonality make the offline/online pair an identity.
    for size in (4, 16, 64, 256):
        h = build_convrot_hadamard(size, device = "cpu", dtype = torch.float32)
        assert h.shape == (size, size)
        assert torch.equal(h, h.T)
        assert torch.allclose(h @ h, torch.eye(size), atol = 1e-5)


_H4 = ((1, 1, 1, -1), (1, 1, -1, 1), (1, -1, 1, 1), (-1, 1, 1, 1))
_SIZES = (4, 16, 64, 256, 1024)
_DTYPES = (torch.float32, torch.float16, torch.bfloat16)
_DEVICES = ("cpu",) + (("cuda",) if torch.cuda.is_available() else ())


def _reference_hadamard(size, dtype):
    # the kron definition the hosted checkpoints were rotated with; exact in float64
    h4 = torch.tensor(_H4, dtype = torch.float64)
    h = h4
    while h.shape[0] < size:
        h = torch.kron(h, h4)
    return (h / size**0.5).to(dtype)


def _bits(t):
    return t.view(torch.int32 if t.dtype == torch.float32 else torch.int16)


@pytest.mark.parametrize("device", _DEVICES)
@pytest.mark.parametrize("dtype", _DTYPES)
@pytest.mark.parametrize("size", _SIZES)
def test_hadamard_is_bit_identical_to_the_kron_definition(size, dtype, device):
    h = build_convrot_hadamard(size, device = device, dtype = dtype)
    ref = _reference_hadamard(size, dtype).to(device)
    assert h.dtype == dtype and h.device.type == torch.device(device).type
    assert h.shape == (size, size)
    assert torch.equal(_bits(h), _bits(ref))


@pytest.mark.parametrize("size", _SIZES)
def test_hadamard_is_orthogonal_in_float64_exactly(size):
    h = build_convrot_hadamard(size, dtype = torch.float64)
    assert torch.equal(h, h.T)
    assert torch.equal(h @ h.T, torch.eye(size, dtype = torch.float64))


@pytest.mark.parametrize("device", _DEVICES)
@pytest.mark.parametrize("size", (4, 16, 256))
def test_rotations_match_an_explicit_block_diagonal(size, device):
    from core.inference.diffusion_convrot import rotate_convrot_activation

    torch.manual_seed(0)
    groups = 3
    ref = _reference_hadamard(size, torch.float64).to(device)
    block = torch.block_diag(*([ref] * groups))
    x = torch.randn(2, 5, groups * size, dtype = torch.float64, device = device)
    h = build_convrot_hadamard(size, device = device, dtype = torch.float64)
    assert torch.allclose(rotate_convrot_activation(x, h, size), x @ block, atol = 1e-12)

    linear = nn.Linear(groups * size, 6, dtype = torch.float32, device = device)
    dense = linear.weight.detach().double().clone()
    rotate_convrot_weight_(linear, size)
    expected = (dense @ block.T).float()
    assert torch.allclose(linear.weight, expected, atol = 1e-6)


def test_hadamard_rejects_a_non_power_of_four():
    with pytest.raises(ValueError):
        build_convrot_hadamard(32)


def test_denoiser_and_conditioner_share_one_hadamard():
    # conditioner (PR 8283) and denoiser must share one Hadamard; fails on a future copy-paste
    from core.inference import video_minimax_h3_te as te

    from core.inference import diffusion_convrot as cr

    assert te.build_convrot_hadamard is cr.build_convrot_hadamard
    assert te.rotate_convrot_activation is cr.rotate_convrot_activation


def test_rotate_then_unrotate_is_the_identity():
    # Offline weight rotation plus online activation rotation leaves the float result unchanged.
    torch.manual_seed(0)
    linear = nn.Linear(1024, 512, dtype = torch.float32)
    x = torch.randn(37, 1024)
    reference = linear(x)

    rotate_convrot_weight_(linear, DEFAULT_CONVROT_GROUPSIZE)
    assert not torch.allclose(linear(x), reference)
    linear.convrot_groupsize = DEFAULT_CONVROT_GROUPSIZE
    from core.inference.diffusion_convrot import convrot_linear_class

    linear.__class__ = convrot_linear_class()

    got = linear(x)
    assert ((got - reference).norm() / reference.norm()).item() < 1e-5


def test_rotation_survives_extra_leading_dims():
    torch.manual_seed(1)
    model = _Model()
    x = torch.randn(2, 5, 4 * GROUP)
    reference = model.a(x)
    rotate_linears_(model, ["a"], GROUP)
    assert torch.allclose(model.a(x), reference, atol = 1e-5)


def test_rotate_weight_refuses_an_indivisible_input_axis():
    with pytest.raises(ValueError):
        rotate_convrot_weight_(nn.Linear(GROUP + 1, 8), GROUP)


def test_rotatable_fqns_splits_on_divisibility():
    model = _Model()
    rotatable, not_divisible = rotatable_fqns(model, lambda m, fqn: True, GROUP)
    assert rotatable == ("a", "b")
    assert not_divisible == ("odd",)
    rotatable, not_divisible = rotatable_fqns(model, lambda m, fqn: fqn != "b", GROUP)
    assert rotatable == ("a",) and not_divisible == ("odd",)


def test_offline_rotation_records_only_what_it_applied():
    model = _Model()
    rotated = rotate_linears_(model, ["a", "b"], GROUP)
    meta = rotation_metadata(GROUP, rotated)
    assert meta[ROTATION_KEY] == CONVROT_KIND
    assert meta[ROTATION_GROUP_KEY] == GROUP
    assert meta[ROTATION_FQNS_KEY] == ["a", "b"]
    assert rotation_metadata_error(meta) is None


def test_offline_rotation_raises_rather_than_over_recording():
    model = _Model()
    with pytest.raises(ValueError):
        rotate_linears_(model, ["a", "nope"], GROUP)
    with pytest.raises(ValueError):
        rotate_linears_(model, ["a"], 32)


def test_apply_rotates_exactly_the_recorded_fqns():
    model = _Model()
    assert apply_activation_rotation(model, _meta(["a"])) == ("a",)
    assert is_rotated_linear(model.a)
    # The recorded list is the contract; "everything divisible" can drift from what was baked.
    assert not is_rotated_linear(model.b)
    assert not is_rotated_linear(model.odd)
    assert getattr(model, CONVROT_ATTR)["linears"] == 1
    assert getattr(model, CONVROT_ATTR)["group"] == GROUP


def test_apply_is_inert_without_a_declared_rotation():
    model = _Model()
    for metadata in ({}, None, {"scheme": "int8"}, {ROTATION_KEY: None}, {ROTATION_KEY: ""}):
        assert apply_activation_rotation(model, metadata) == ()
    assert not any(is_rotated_linear(m) for m in (model.a, model.b, model.odd))


def test_rotated_linear_keeps_the_state_dict_unchanged():
    # The swap must not add, rename or drop a key: the hosted checkpoint loads under strict=True.
    before = sorted(_Model().state_dict())
    model = _Model()
    apply_activation_rotation(model, _meta(["a", "b"]))
    assert sorted(model.state_dict()) == before
    assert isinstance(model.a, nn.Linear)


@pytest.mark.parametrize(
    "metadata",
    [
        _meta(["a"], kind = "convrot_hadamard_v2"),
        _meta(["a"], kind = True),
        _meta(["a"], group = 32),
        _meta(["a"], group = "256"),
        _meta([]),
        {ROTATION_KEY: CONVROT_KIND, ROTATION_GROUP_KEY: GROUP},
        _meta(["a", "a"]),
        _meta(["a", 7]),
    ],
)
def test_apply_refuses_an_unusable_contract(metadata):
    assert declares_rotation(metadata)
    assert rotation_metadata_error(metadata)
    model = _Model()
    with pytest.raises(ValueError):
        apply_activation_rotation(model, metadata)
    assert not any(is_rotated_linear(m) for m in (model.a, model.b, model.odd))


def test_apply_refuses_an_fqn_this_model_does_not_have():
    model = _Model()
    with pytest.raises(ValueError, match = "does not have"):
        apply_activation_rotation(model, _meta(["a", "missing.linear"]))


def test_apply_refuses_a_target_that_is_not_a_linear():
    model = _Model()
    model.not_a_linear = nn.LayerNorm(GROUP)
    with pytest.raises(ValueError, match = "not an nn.Linear"):
        apply_activation_rotation(model, _meta(["not_a_linear"]))


def test_apply_refuses_an_indivisible_target():
    model = _Model()
    with pytest.raises(ValueError, match = "does not divide"):
        apply_activation_rotation(model, _meta(["odd"]))


def test_apply_refuses_to_rotate_twice():
    model = _Model()
    apply_activation_rotation(model, _meta(["a"]))
    with pytest.raises(ValueError, match = "already rotated"):
        apply_activation_rotation(model, _meta(["a"]))


def test_a_refused_apply_rotates_nothing_at_all():
    # A partial install renders wrongly without failing, so validate every target before swapping.
    model = _Model()
    with pytest.raises(ValueError):
        apply_activation_rotation(model, _meta(["a", "b", "odd"]))
    assert not any(is_rotated_linear(m) for m in (model.a, model.b, model.odd))


def test_format_tag_follows_the_rotation():
    assert pq.prequant_format_for({"scheme": "int8"}) == pq.PREQUANT_FORMAT
    assert pq.prequant_format_for(_meta(["a"])) == pq.PREQUANT_FORMAT_ROTATED
    assert pq.PREQUANT_FORMAT_ROTATED != pq.PREQUANT_FORMAT
    assert set(pq.PREQUANT_FORMATS) == {
        pq.PREQUANT_FORMAT,
        pq.PREQUANT_FORMAT_ROTATED,
        pq.PREQUANT_FORMAT_POLICY,
    }


@pytest.mark.parametrize(
    ("fmt", "metadata", "ok"),
    [
        (pq.PREQUANT_FORMAT, {}, True),
        (pq.PREQUANT_FORMAT_ROTATED, _meta(["a"]), True),
        # A rotated artifact tagged v1 must be refused: older Unsloth loads it and renders wrong pixels.
        (pq.PREQUANT_FORMAT, _meta(["a"]), False),
        (pq.PREQUANT_FORMAT_ROTATED, {}, False),
        (pq.PREQUANT_FORMAT_ROTATED, _meta(["a"], kind = "something_else"), False),
        (pq.PREQUANT_FORMAT_ROTATED, _meta(["a"], group = 32), False),
        (pq.PREQUANT_FORMAT_ROTATED, _meta([]), False),
    ],
)
def test_validator_enforces_the_format_rotation_biconditional(fmt, metadata, ok):
    assert pq._validate_activation_rotation(fmt, metadata, "int8", None) is ok


def test_h3_int8_resolves_to_the_rotated_artifact_with_the_plain_one_behind_it():
    # The derived name stays the fallback so older installs get the plain checkpoint, not 66.3 GB dense.
    from core.inference.video_families import detect_video_family

    fam = detect_video_family("MiniMaxAI/MiniMax-H3")
    src = pq.resolve_prequant_source(fam, "int8")
    assert src.location == "unsloth/MiniMax-H3-FP8"
    # the declared .pt's safetensors twin goes first; the .pt stays right behind it
    assert src.filename == "MiniMax-H3-INT8-ConvRot.safetensors"
    assert src.fallback_filenames[0] == "MiniMax-H3-INT8-ConvRot.pt"
    assert "MiniMax-H3-INT8.pt" in src.fallback_filenames
    assert pq.resolve_prequant_source(fam, "fp8").filename == "MiniMax-H3-FP8.safetensors"


class _FakeTransformer(nn.Module):
    """Just enough of a diffusers transformer for ``load_prequantized_transformer``."""

    calls: dict = {}

    def __init__(self) -> None:
        super().__init__()
        self.a = nn.Linear(4 * GROUP, 8)
        self.b = nn.Linear(2 * GROUP, 8)

    @classmethod
    def load_config(cls, base, **kw):
        return {"cfg": True}

    @classmethod
    def from_config(cls, config):
        return cls()

    def load_state_dict(
        self,
        sd,
        strict = True,
        assign = False,
    ):
        _FakeTransformer.calls["load_state_dict"] = {"strict": strict, "assign": assign}


def _load_rotated(monkeypatch, tmp_path, ckpt):
    """Drive ``load_prequantized_transformer`` over ``ckpt`` with real torch."""
    _FakeTransformer.calls = {}
    monkeypatch.setattr(torch, "load", lambda *a, **k: ckpt)
    accelerate = types.ModuleType("accelerate")
    accelerate.init_empty_weights = lambda: contextlib.nullcontext()
    monkeypatch.setitem(sys.modules, "accelerate", accelerate)
    monkeypatch.setenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, str(tmp_path))
    path = tmp_path / "ckpt.pt"
    path.write_bytes(b"x")
    return pq.load_prequantized_transformer(
        _FakeTransformer,
        "Tongyi-MAI/Z-Image-Turbo",
        pq.PrequantSource(kind = "path", location = str(path), filename = None),
        device = "cpu",
        dtype = "bfloat16",
        hf_token = None,
        scheme = "int8",
        logger = None,
    )


def _ckpt(fmt, metadata):
    meta = {"scheme": "int8", "base_model_id": "Tongyi-MAI/Z-Image-Turbo"}
    meta.update(metadata)
    return {"format": fmt, "metadata": meta, "state_dict": {}}


def test_loader_installs_the_rotation_the_checkpoint_records(monkeypatch, tmp_path):
    loaded = _load_rotated(monkeypatch, tmp_path, _ckpt(pq.PREQUANT_FORMAT_ROTATED, _meta(["a"])))
    assert loaded is not None
    assert is_rotated_linear(loaded.a) and not is_rotated_linear(loaded.b)


def test_loader_leaves_a_plain_checkpoint_alone(monkeypatch, tmp_path):
    loaded = _load_rotated(monkeypatch, tmp_path, _ckpt(pq.PREQUANT_FORMAT, {}))
    assert loaded is not None
    assert not is_rotated_linear(loaded.a) and not is_rotated_linear(loaded.b)


@pytest.mark.parametrize(
    ("fmt", "metadata"),
    [
        (pq.PREQUANT_FORMAT_ROTATED, _meta(["a"], kind = "convrot_hadamard_v99")),
        (pq.PREQUANT_FORMAT_ROTATED, _meta(["a"], group = 32)),
        (pq.PREQUANT_FORMAT_ROTATED, _meta(["not_on_this_model"])),
        (pq.PREQUANT_FORMAT_ROTATED, _meta([])),
        (pq.PREQUANT_FORMAT, _meta(["a"])),
    ],
)
def test_loader_refuses_a_rotation_it_cannot_apply(monkeypatch, tmp_path, fmt, metadata):
    # None means fall back to the dense download: slower, never wrong.
    assert _load_rotated(monkeypatch, tmp_path, _ckpt(fmt, metadata)) is None


def test_every_rotated_projection_shares_one_class():
    """Rotated projections must share one class, or torch.compile retraces the block per projection."""
    import torch
    from torch import nn

    from core.inference.diffusion_convrot import _install_rotation, convrot_linear_class

    first, second = nn.Linear(256, 8, bias = False), nn.Linear(256, 8, bias = False)
    _install_rotation(first, 256)
    _install_rotation(second, 256)
    assert type(first) is type(second)
    assert type(first) is convrot_linear_class()
    assert isinstance(first, nn.Linear)
    assert is_rotated_linear(first) and is_rotated_linear(second)
    # And the swap is per instance, so a shared class must not leak one module's group to another.
    third = nn.Linear(512, 8, bias = False)
    _install_rotation(third, 128)
    assert (first.convrot_groupsize, third.convrot_groupsize) == (256, 128)
    assert torch.is_tensor(first.weight)


def test_rotated_forward_traces_fullgraph_on_a_cold_cache(monkeypatch):
    """Denoiser blocks compile with fullgraph=True; a cold Hadamard build must not graph-break."""
    import torch
    from torch import nn

    import core.inference.diffusion_convrot as dc

    torch._dynamo.reset()
    monkeypatch.setattr(dc, "_HADAMARD_CACHE", {})
    linear = nn.Linear(256, 8, bias = False)
    dc._install_rotation(linear, 64)
    x = torch.randn(3, 256)
    expected = linear(x)
    dc._HADAMARD_CACHE.clear()
    compiled = torch.compile(linear, fullgraph = True, backend = "eager")
    assert torch.equal(compiled(x), expected)
    torch._dynamo.reset()