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 runs before the final recovery step, 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,
    test_loader=r.test_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, test_loader=test_loader, num_classes=num_classes)
compressed_model = result.model

model can be any nn.Module. dataloader (positional, second argument) is used for calibration and fine-tuning throughout the pipeline: it's never optional. test_loader is a genuine held-out set used for every accuracy measurement — baseline, both hyperparameter searches, every technique's gate, the final report. If you omit it, compress() auto-splits dataloader's dataset 70/30 and prints a warning when it does; passing your own is always preferable, since the auto-split both reduces how much data your model actually gets fine-tuned on and can't guarantee class balance in the held-out portion. 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)

Every accuracy value on this object — original_accuracy, compressed_accuracy, and everything derived from them (accuracy_retention, cqi's accuracy factor, every gate's keep/revert decision along the way) — is measured against test_loader, never against dataloader.

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.

Evaluation data

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). This step always runs before test_loader is resolved via auto-split — pretrain trains on dataloader's 70% share, never on the held-out portion.

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

Accuracy-drop gating is always active. Structured Pruning, Low-Rank Factorization, Weight Clustering, GPTQ, standard Quantization, and the final KD recovery fine-tune 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.

GPTQ uses a QAT-aware (straight-through estimator) path whenever use_kd_finetune=True, so the final KD fine-tune can actually update GPTQ-quantized weights instead of finding them frozen — collapsed back to compact storage automatically once KD finishes. If the final KD step's cumulative recovery still falls short of accuracy_drop_threshold after its own gate passes, one bounded, LR-adjusted retry runs automatically before the result is accepted as-is. KD always runs after GPTQ and standard quantization, never before, so it recovers accuracy lost to every prior step at once, including quantization/GPTQ's own damage. fp16 is not skipped when GPTQ is absent or reverted — fp16-only stays a fully independent, always-available configuration.

Search result caching. Each search caches trial results to disk purely by hyperparameter value, with no reference to which model produced them. epsilon_cache_path/pruning_cache_path 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).

Cached scores don't record which CQI weights or latency settings produced them. Delete the cache files (.sigularty_cache/ by default) after changing any cqi_w_* argument, or old scores will be mixed with new ones.

If you have .sigularty_cache/ files from before test_loader existed, delete them. Those cached accuracy numbers were measured against dataloader (effectively training data, since compress() had no other option at the time) rather than a genuine held-out set — reusing them now would silently mix pre-fix and post-fix numbers under the same cache keys, and the cached values would understate real accuracy drop.

Technique enable flags

Pruning hyperparameters

Note: find_optimal_pruning=True forwards pruning_max_ratio (and pruning_residual_max_ratio) into the search itself, and reads the search's winning max-ratio back out afterward — the config the search recommends is the config the real pipeline actually applies.

Low-Rank Factorization (LRF) hyperparameters

Weight clustering hyperparameters

Knowledge distillation fine-tuning hyperparameters

The final recovery step. KD always runs after quantization/GPTQ, never before, so it recovers accuracy lost from every prior step at once — including quantization/GPTQ's own damage, since those are gated too (see "Accuracy-drop gating" above). If GPTQ is enabled, it uses a QAT-aware path specifically so this step can update GPTQ-quantized weights rather than finding them frozen.

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.

Both hyperparameter searches (find_optimal_epsilon and find_optimal_pruning) measure latency on every trial, so cqi_w_latency affects which epsilon or pruning config wins, not just the final report. A technique that shrinks the model but makes it slower is scored accordingly; raise cqi_w_latency to make the searches stricter about speed. Latency is a ratio like size, so a large size reduction can still outweigh a moderate slowdown. The per-technique accuracy gate is unaffected: it only checks accuracy, and no technique is reverted for being slower.

Report