Module neuralops.tests.test_huffman_coder

Comprehensive Test Suite for Vectorized Huffman Coder & Huffman Compressor. Tests roundtrip correctness, compression metrics, fallback LoRA freezing, and cross-architecture integration.

Classes

class DummyLoRAModule (in_features=64, out_features=64, r=16)

Expand source code

class DummyLoRAModule(nn.Module):
    def __init__(self, in_features=64, out_features=64, r=16):
        super().__init__()
        self.base_layer = nn.Linear(in_features, out_features, bias=True)
        self.lora_A = nn.Parameter(torch.randn(r, in_features))
        self.lora_B = nn.Parameter(torch.zeros(out_features, r))

Base class for all neural network modules.

Your models should also subclass this class.

Modules can also contain other Modules, allowing them to be nested in a tree structure. You can assign the submodules as regular attributes::

import torch.nn as nn
import torch.nn.functional as F


class Model(nn.Module):
    def __init__(self) -> None:
        super().__init__()
        self.conv1 = nn.Conv2d(1, 20, 5)
        self.conv2 = nn.Conv2d(20, 20, 5)

    def forward(self, x):
        x = F.relu(self.conv1(x))
        return F.relu(self.conv2(x))

Submodules assigned in this way will be registered, and will also have their parameters converted when you call :meth:to, etc.

Note

As per the example above, an __init__() call to the parent class must be made before assignment on the child.

:ivar training: Boolean represents whether this module is in training or evaluation mode. :vartype training: bool

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Ancestors

• torch.nn.modules.module.Module

class DummyTransformerModel (d_model=64, num_layers=2)

Expand source code

class DummyTransformerModel(nn.Module):
    def __init__(self, d_model=64, num_layers=2):
        super().__init__()
        self.word_embeddings = nn.Embedding(100, d_model)
        self.layers = nn.ModuleList([
            nn.ModuleDict({
                "q_proj": nn.Linear(d_model, d_model),
                "k_proj": nn.Linear(d_model, d_model),
                "v_proj": nn.Linear(d_model, d_model),
                "out_proj": nn.Linear(d_model, d_model),
            })
            for _ in range(num_layers)
        ])
        self.classifier = nn.Linear(d_model, 2)

    def forward(self, input_ids=None, attention_mask=None, **kwargs):
        if input_ids is None:
            input_ids = torch.zeros((1, 4), dtype=torch.long)
        x = self.word_embeddings(input_ids)
        for layer in self.layers:
            q = layer["q_proj"](x)
            k = layer["k_proj"](x)
            v = layer["v_proj"](x)
            x = x + layer["out_proj"](v)
        return self.classifier(x[:, 0])

Base class for all neural network modules.

Your models should also subclass this class.

Modules can also contain other Modules, allowing them to be nested in a tree structure. You can assign the submodules as regular attributes::

import torch.nn as nn
import torch.nn.functional as F


class Model(nn.Module):
    def __init__(self) -> None:
        super().__init__()
        self.conv1 = nn.Conv2d(1, 20, 5)
        self.conv2 = nn.Conv2d(20, 20, 5)

    def forward(self, x):
        x = F.relu(self.conv1(x))
        return F.relu(self.conv2(x))

Submodules assigned in this way will be registered, and will also have their parameters converted when you call :meth:to, etc.

Note

As per the example above, an __init__() call to the parent class must be made before assignment on the child.

:ivar training: Boolean represents whether this module is in training or evaluation mode. :vartype training: bool

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Ancestors

• torch.nn.modules.module.Module

Methods

def forward(self, input_ids=None, attention_mask=None, **kwargs) ‑> Callable[..., typing.Any]

Expand source code

def forward(self, input_ids=None, attention_mask=None, **kwargs):
    if input_ids is None:
        input_ids = torch.zeros((1, 4), dtype=torch.long)
    x = self.word_embeddings(input_ids)
    for layer in self.layers:
        q = layer["q_proj"](x)
        k = layer["k_proj"](x)
        v = layer["v_proj"](x)
        x = x + layer["out_proj"](v)
    return self.classifier(x[:, 0])

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the :class:Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class TestHuffmanCoder (methodName='runTest')

Expand source code

class TestHuffmanCoder(unittest.TestCase):

    # 2.1 Roundtrip Correctness
    def test_roundtrip_small_tensor(self):
        x = torch.randn(1000)
        packed, table, meta = HuffmanCoder.encode(x, quantize_bits=8)
        self.assertGreater(len(packed), 0)
        rec = HuffmanCoder.decode(packed, table, meta)
        err = torch.norm(x - rec) / torch.norm(x)
        self.assertLess(err.item(), 0.05, f"Small tensor error {err.item():.4f} too high")

    def test_roundtrip_large_tensor(self):
        x = torch.randn(1, 512, 768)
        t0 = time.time()
        packed, table, meta = HuffmanCoder.encode(x, quantize_bits=8)
        rec = HuffmanCoder.decode(packed, table, meta)
        elapsed = time.time() - t0
        err = torch.norm(x - rec) / torch.norm(x)
        self.assertLess(elapsed, 15.0, f"Encode+decode took {elapsed:.2f}s, expected < 15s")
        self.assertLess(err.item(), 0.05)

    def test_roundtrip_zero_tensor(self):
        x = torch.zeros(100, 100)
        packed, table, meta = HuffmanCoder.encode(x, quantize_bits=8)
        rec = HuffmanCoder.decode(packed, table, meta)
        self.assertEqual(rec.shape, x.shape)
        self.assertTrue(torch.allclose(x, rec, atol=1e-5))

    def test_roundtrip_high_bits(self):
        x = torch.randn(128, 128)
        packed, table, meta = HuffmanCoder.encode(x, quantize_bits=16)
        rec = HuffmanCoder.decode(packed, table, meta)
        self.assertTrue(torch.allclose(x, rec, atol=1e-5), "High-bit quantization must be lossless identity")
        self.assertTrue(meta.get("is_raw", False))

    # 2.2 Compression Metrics
    def test_entropy_calculation(self):
        # 4 symbols with uniform frequency: entropy should be log2(4) = 2.0
        x = torch.tensor([0.0, 1.0, 2.0, 3.0] * 250)
        packed, table, meta = HuffmanCoder.encode(x, quantize_bits=2)
        entropy = meta["entropy"]
        self.assertAlmostEqual(entropy, 2.0, places=1)

    def test_compression_ratio(self):
        # Skewed tensor: mostly zeros
        x = torch.zeros(1000)
        x[0:10] = 5.0
        packed, table, meta = HuffmanCoder.encode(x, quantize_bits=8)
        # Original bytes: 1000 * 4 = 4000
        # Compressed should be much smaller
        orig_bytes = x.numel() * x.element_size()
        self.assertLess(meta["compressed_bytes"], orig_bytes)

    # 2.3 Fallback and LoRA Freezing
    def test_fallback_freezes_only_base(self):
        mod = DummyLoRAModule(64, 64, r=16)
        _freeze_base_only(mod)
        self.assertTrue(mod.lora_A.requires_grad, "lora_A should stay trainable")
        self.assertTrue(mod.lora_B.requires_grad, "lora_B should stay trainable")
        self.assertFalse(mod.base_layer.weight.requires_grad, "base_layer.weight should be frozen")
        if mod.base_layer.bias is not None:
            self.assertFalse(mod.base_layer.bias.requires_grad, "base_layer.bias should be frozen")

    def test_non_lora_fallback_freezes_all(self):
        mod = nn.Linear(64, 64)
        _freeze_base_only(mod)
        self.assertFalse(mod.weight.requires_grad, "Plain linear weight should be frozen")
        self.assertFalse(mod.bias.requires_grad, "Plain linear bias should be frozen")

    # 2.4 Cross-Architecture Integration
    def test_injection_transformer(self):
        model = DummyTransformerModel(d_model=64, num_layers=2)
        comp = HuffmanCompressor(model, quantize_bits=8, max_error=0.20)
        c_model, stats = comp.compress()
        self.assertGreater(stats["num_compressed"], 0)
        self.assertGreater(stats["huffman_compression_ratio"], 1.0)
        self.assertTrue(stats.get("forward_check_success"))

A class whose instances are single test cases.

By default, the test code itself should be placed in a method named 'runTest'.

If the fixture may be used for many test cases, create as many test methods as are needed. When instantiating such a TestCase subclass, specify in the constructor arguments the name of the test method that the instance is to execute.

Test authors should subclass TestCase for their own tests. Construction and deconstruction of the test's environment ('fixture') can be implemented by overriding the 'setUp' and 'tearDown' methods respectively.

If it is necessary to override the init method, the base class init method must always be called. It is important that subclasses should not change the signature of their init method, since instances of the classes are instantiated automatically by parts of the framework in order to be run.

When subclassing TestCase, you can set these attributes: * failureException: determines which exception will be raised when the instance's assertion methods fail; test methods raising this exception will be deemed to have 'failed' rather than 'errored'. * longMessage: determines whether long messages (including repr of objects used in assert methods) will be printed on failure in addition to any explicit message passed. * maxDiff: sets the maximum length of a diff in failure messages by assert methods using difflib. It is looked up as an instance attribute so can be configured by individual tests if required.

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

Ancestors

• unittest.case.TestCase

Methods

def test_compression_ratio(self)

Expand source code

def test_compression_ratio(self):
    # Skewed tensor: mostly zeros
    x = torch.zeros(1000)
    x[0:10] = 5.0
    packed, table, meta = HuffmanCoder.encode(x, quantize_bits=8)
    # Original bytes: 1000 * 4 = 4000
    # Compressed should be much smaller
    orig_bytes = x.numel() * x.element_size()
    self.assertLess(meta["compressed_bytes"], orig_bytes)

def test_entropy_calculation(self)

Expand source code

def test_entropy_calculation(self):
    # 4 symbols with uniform frequency: entropy should be log2(4) = 2.0
    x = torch.tensor([0.0, 1.0, 2.0, 3.0] * 250)
    packed, table, meta = HuffmanCoder.encode(x, quantize_bits=2)
    entropy = meta["entropy"]
    self.assertAlmostEqual(entropy, 2.0, places=1)

def test_fallback_freezes_only_base(self)

Expand source code

def test_fallback_freezes_only_base(self):
    mod = DummyLoRAModule(64, 64, r=16)
    _freeze_base_only(mod)
    self.assertTrue(mod.lora_A.requires_grad, "lora_A should stay trainable")
    self.assertTrue(mod.lora_B.requires_grad, "lora_B should stay trainable")
    self.assertFalse(mod.base_layer.weight.requires_grad, "base_layer.weight should be frozen")
    if mod.base_layer.bias is not None:
        self.assertFalse(mod.base_layer.bias.requires_grad, "base_layer.bias should be frozen")

def test_injection_transformer(self)

Expand source code

def test_injection_transformer(self):
    model = DummyTransformerModel(d_model=64, num_layers=2)
    comp = HuffmanCompressor(model, quantize_bits=8, max_error=0.20)
    c_model, stats = comp.compress()
    self.assertGreater(stats["num_compressed"], 0)
    self.assertGreater(stats["huffman_compression_ratio"], 1.0)
    self.assertTrue(stats.get("forward_check_success"))

def test_non_lora_fallback_freezes_all(self)

Expand source code

def test_non_lora_fallback_freezes_all(self):
    mod = nn.Linear(64, 64)
    _freeze_base_only(mod)
    self.assertFalse(mod.weight.requires_grad, "Plain linear weight should be frozen")
    self.assertFalse(mod.bias.requires_grad, "Plain linear bias should be frozen")

def test_roundtrip_high_bits(self)

Expand source code

def test_roundtrip_high_bits(self):
    x = torch.randn(128, 128)
    packed, table, meta = HuffmanCoder.encode(x, quantize_bits=16)
    rec = HuffmanCoder.decode(packed, table, meta)
    self.assertTrue(torch.allclose(x, rec, atol=1e-5), "High-bit quantization must be lossless identity")
    self.assertTrue(meta.get("is_raw", False))

def test_roundtrip_large_tensor(self)

Expand source code

def test_roundtrip_large_tensor(self):
    x = torch.randn(1, 512, 768)
    t0 = time.time()
    packed, table, meta = HuffmanCoder.encode(x, quantize_bits=8)
    rec = HuffmanCoder.decode(packed, table, meta)
    elapsed = time.time() - t0
    err = torch.norm(x - rec) / torch.norm(x)
    self.assertLess(elapsed, 15.0, f"Encode+decode took {elapsed:.2f}s, expected < 15s")
    self.assertLess(err.item(), 0.05)

def test_roundtrip_small_tensor(self)

Expand source code

def test_roundtrip_small_tensor(self):
    x = torch.randn(1000)
    packed, table, meta = HuffmanCoder.encode(x, quantize_bits=8)
    self.assertGreater(len(packed), 0)
    rec = HuffmanCoder.decode(packed, table, meta)
    err = torch.norm(x - rec) / torch.norm(x)
    self.assertLess(err.item(), 0.05, f"Small tensor error {err.item():.4f} too high")

def test_roundtrip_zero_tensor(self)

Expand source code

def test_roundtrip_zero_tensor(self):
    x = torch.zeros(100, 100)
    packed, table, meta = HuffmanCoder.encode(x, quantize_bits=8)
    rec = HuffmanCoder.decode(packed, table, meta)
    self.assertEqual(rec.shape, x.shape)
    self.assertTrue(torch.allclose(x, rec, atol=1e-5))