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, >1.0 = better tradeoff than the original; can be negative — see "CQI scoring" below
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, CQI accuracy formula, or latency settings produced them. Delete the cache files (.sigularty_cache/ by default) after changing any cqi_w_* argument, after changing accuracy_drop_threshold (it now shapes every cached score, not just the final selection), or after upgrading from a release whose CQI used the plain accuracy ratio — those cached scores sit on a different scale and would be mixed with current ones under the same keys.

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

The Compression Quality Index combines accuracy, size, latency, and (for pruning) output-distribution drift into one number. Both hyperparameter searches rank every trial by it, and it's the cqi value on CompressionResult and in the report.

CQI = accuracy_factor
    × (baseline_size / size)^cqi_w_size
    × (baseline_latency / latency)^cqi_w_latency
    × (1 / (1 + KL))^cqi_w_kl                       [pruning only]

Reading it: 1.0 means no better than the original model; 2.5 means the combined accuracy/size/speed tradeoff is 2.5x better.

The accuracy factor is a function of the accuracy drop measured against accuracy_drop_threshold. Let x = drop / accuracy_drop_threshold, where drop = original_accuracy - compressed_accuracy in percentage points. x = 1 means the drop exactly equals the budget, the same point at which the pipeline's own gate would revert a technique.

The three pieces join continuously, so there are no gaps or jumps in the score. Worked example at accuracy_drop_threshold=10:

The point of the last piece is that a size or latency ratio can't buy back an accuracy drop at or past your budget: the factor falls faster than any compression ratio can grow. Because of that, CQI can be negative, and a negative value is meaningful: the accuracy loss alone already makes that configuration worse than doing nothing, regardless of how small or fast the model got. The searches treat any winner scoring below 1.0 as non-viable and disable that technique for the run.

accuracy_drop_threshold is what drives all of this. compress() always passes it through, so every trial score inside both searches and the final result.cqi use this accuracy factor. Its shape constants (the 2.0 reward ceiling, 0.1 in-budget slope, and 25 post-budget steepness) are fixed defaults and not exposed as compress() arguments; the one knob you control is the threshold itself.

The size, latency, and KL factors are plain ratios raised to their weight. Both searches 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 by these weights: it only checks accuracy, and no technique is reverted for being slower.

Report