Using sigularty

This is a quick reference for calling sigularty as a library: how to import it, the two ways to get a model in, and what every compress() argument does. For the theory behind each technique — why pruning runs before LRF, what CQI means, why quantization is always last — see README.md.

Install

git clone https://github.com/<you>/sigularty.git
cd sigularty
pip install -e .

Quickstart

Fastest path — a registry model + its paired dataset in one call:

from sigularty import load_from_registry, compress

r = load_from_registry('resnet18', device='cuda')

result = compress(
    r.model,
    r.train_loader,
    num_classes=r.num_classes,
    use_pruning=True,
    use_lrf=True,
)

print(result)
# CompressionResult(ratio=3.42x, accuracy_retention=96.1%, size=42.7->12.5 MB, speedup=1.8x, cqi=2.113)

compressed_model = result.model

Bring your own model:

from sigularty import compress

result = compress(model, train_loader, num_classes=num_classes)
compressed_model = result.model

model can be any nn.Module. dataloader (positional, second argument) is used for calibration, fine-tuning, and evaluation throughout the pipeline — it's never optional. The original model is never modified; compress() always works on a deep copy.

Other entry points

from sigularty import (
    compress,               # run the full compression pipeline
    analyze,                # inspect a model, get technique recommendations
    load_from_registry,     # pull a registry model + its dataset together
    load_model_and_data,    # older form of the above, returns a plain tuple
    finetune,                # fine-tune a model before compressing it
    find_best_lr,            # LR range test — run before finetune()/pretrain_*
    plot_compression_report,
    plot_pruning_report,
    plot_epsilon_landscape,
)

Registry model names (pass as model_name): resnet18, resnet50, resnext50_32x4d, wide_resnet50_2, vgg16, densenet121, convnext_tiny, regnet_y_400mf, shufflenet_v2_x1_0, squeezenet1_1, mobilenet_v3_large, efficientnet_b0, inception_v3, vit_b_16, swin_t, bert_base, distilbert, roberta_base, albert_base, distilgpt2, custom_cnn.

What compress() returns

result.model                   # nn.Module — the compressed model, ready to use
result.compression_ratio       # size_original / size_compressed, e.g. 3.8 = 3.8x smaller
result.accuracy_retention      # (compressed_acc / original_acc) * 100
result.size_original_mb
result.size_compressed_mb
result.original_accuracy
result.compressed_accuracy
result.original_latency_ms
result.compressed_latency_ms
result.latency_speedup         # original_lat / compressed_lat, >1.0 = faster
result.cqi                     # Compression Quality Index — see README.md
result.techniques_applied      # list[str], only techniques that actually ran/survived
result.report_path             # path to the saved PNG report, or None
result.pruning_report          # dict of per-layer pruning detail, or None

analyze() returns an AnalysisResult: size_mb, num_parameters, architecture_type ('cnn' / 'transformer' / 'hybrid' / 'unknown'), recommended_techniques, per_layer_signals (a LayerSignal per eligible layer: name, layer_type, lrf_epsilon, prunable, size_kb), and accuracy if you passed a dataloader.

load_from_registry() returns a RegistryResult: model, train_loader, test_loader, num_classes, model_name, dataset_name.

compress() hyperparameters

Every argument after model and dataloader is keyword-only. Grouped the same way the function itself groups them.

Device

Model metadata

Pre-training

Use these when the model hasn't been trained on your target dataset yet (e.g. fresh ImageNet weights with an untrained head).

Hyperparameter search (optional, adds evaluations before the pipeline runs)

Technique enable flags

Pruning hyperparameters

Low-Rank Factorization (LRF) hyperparameters

Weight clustering hyperparameters

Knowledge distillation fine-tuning hyperparameters

The final recovery step, run after quantization/GPTQ so it can recover accuracy lost from every prior step at once.

Quantization hyperparameters

GPTQ hyperparameters

CQI scoring weights

Each is an exponent applied to that factor's ratio in the Compression Quality Index — raise one to make the search/report weight that factor more heavily.

Report