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

pip install sigularty

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
    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): custom_cnn, 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.

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 their accuracy gate — see "Accuracy-drop gating" below
result.report_path             # path to the saved PNG report, or None
result.pruning_report          # dict of per-layer pruning detail, or None (also None if pruning ran but was reverted by the gate)

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, straight out of load_from_registry() with no existing checkpoint).

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

Accuracy-drop gating is always active in Phase A (new behaviour). Structured Pruning, Low-Rank Factorization, Weight Clustering, and the in-pipeline KD step are each measured before/after and reverted to their pre-technique state if that ONE technique's own marginal drop exceeds accuracy_drop_threshold. Each technique gets an independent budget — an earlier costly technique does not eat into a later technique's allowance. A reverted technique will not appear in result.techniques_applied — check the console output for a ❌ [TechniqueName] SKIPPED — accuracy dropped ... line if a technique you enabled seems to be missing. Phase B (standard Quantization, GPTQ) is not gated — those two run after Phase A completes and always apply once enabled; see README.md for why they're handled differently.

Search result caching (fixed — was previously a silent correctness bug). Each search caches trial results to disk purely by hyperparameter value, with no reference to which model produced them. Earlier versions of compress() always used the same two hardcoded filenames (epsilon_cache.json, pruning_search_cache.json) for every call — so compressing two different models from the same working directory could silently reuse one model's cached trial results for the other, producing search output that looked plausible but was measuring the wrong model entirely. epsilon_cache_path/pruning_cache_path now default to a filename derived from the model's class name + parameter count + num_classes, so different models get separate cache files automatically. Pass an explicit path yourself for a stronger guarantee (e.g. distinct caches per dataset too, not just per model/class-count). If you have epsilon_cache.json / pruning_search_cache.json left over from an older version in your working directory, they're now orphaned — safe to delete.

Technique enable flags

Pruning hyperparameters

Note: find_optimal_pruning=True now correctly forwards pruning_max_ratio (and pruning_residual_max_ratio) into the search itself, and correctly reads the search's winning max-ratio back out afterward. In earlier versions, the pruning search always ran uncapped regardless of pruning_max_ratio, and even when the search picked a safe config, its chosen max-ratio was silently discarded on the way back into the real pipeline — the pipeline always fell back to whatever pruning_max_ratio default was in effect (0.95 unless you changed it). Combined with gating being off (see above), this could let pruning collapse the residual-critical layers at every stage boundary with nothing to catch or revert it. Both are fixed now; if you were relying on find_optimal_pruning before this fix, re-run — the pruning config it actually applies may now be meaningfully different (and safer).

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