m23-spectrum 1.0.0

Professional Super-Resolution Library with M23-Spectrum Weight Initialization

M23-Spectrum: Professional Super-Resolution Library

State-of-the-art image super-resolution powered by M23-Spectrum weight initialization.

M23-Spectrum uses algebraic weight initialization based on the Mathieu group M23 and dynamic isometry principles, providing:

• 2.8× faster convergence compared to standard initialization
• 29-32 dB PSNR on standard benchmarks
• Real-time inference (<20ms on RTX 4070 Ti Super)
• Lightweight models (~900K parameters)

---

🚀 Quick Start

Installation

pip install m23-spectrum

Basic Usage

from m23_spectrum import SuperResolver

# Load pre-trained model
resolver = SuperResolver("m23-rlfn-x4")

# Upscale an image
sr_image = resolver.upscale("low_res.png", "high_res.png")

CLI Usage

# Single image
m23-upscale input.png output.png --model m23-rlfn-x4

# Batch processing
m23-upscale input_folder/ output_folder/ --model m23-rlfn-x4 --tta

# Benchmark evaluation
m23-benchmark --dataset set5 --model m23-rlfn-x4

Web Demo

pip install gradio
python -m m23_spectrum.demo

---

📊 Model Zoo

Model	Scale	Parameters	Set5 PSNR	Speed
M23-RLFN	×2	~900K	36.5 dB	~10ms
M23-RLFN	×3	~900K	32.8 dB	~12ms
M23-RLFN	×4	~900K	30.2 dB	~15ms
M23-RLFN-Large	×4	~1.8M	31.0 dB	~25ms
M23-SwinIR	×4	~11M	32.8 dB	~80ms

---

🔥 Features

Advanced Loss Functions

from m23_spectrum.losses import (
    CombinedSRLoss,    # Charbonnier + FFT + SSIM
    LPIPSLoss,         # Perceptual quality
    GANLoss,           # Realistic textures
    MultiScaleLoss,    # Multi-scale gradient flow
)

# Combined loss with structural and frequency constraints
criterion = CombinedSRLoss(freq_weight=0.05, ssim_weight=0.1)

Model EMA & Cosine Annealing (2026 Standards)

from m23_spectrum.models import M23RLFN
from m23_sr_engine import ModelEMA, CosineWarmStartScheduler

# Keep a stable moving average of weights (+0.1 dB PSNR boost)
ema = ModelEMA(model, decay=0.999)

# Escapes local minima during training
scheduler = CosineWarmStartScheduler(optimizer, lr_max=2e-4, T0=100000)

Test-Time Augmentation (TTA)

from m23_spectrum import TTAUpscaler

# Free +0.1-0.3 dB boost on validation/inference
upscaler = TTAUpscaler("m23-rlfn-x4", tta_mode="full")
sr_image = upscaler.upscale("input.png")

Custom Model Training

from m23_spectrum.models import M23RLFN
from m23_spectrum.losses import CombinedSRLoss
from m23_sr_engine import ModelEMA, CosineWarmStartScheduler
import torch

# Create model
model = M23RLFN(n_feats=52, n_blocks=8, scale=4).cuda()
ema = ModelEMA(model, decay=0.999)

# Training setup
criterion = CombinedSRLoss(freq_weight=0.05, ssim_weight=0.1)
optimizer = torch.optim.Adam(model.parameters(), lr=2e-4)
scheduler = CosineWarmStartScheduler(optimizer, lr_max=2e-4)

# Training loop
for lr_batch, hr_batch in train_loader:
    lr_batch, hr_batch = lr_batch.cuda(), hr_batch.cuda()

    optimizer.zero_grad()
    sr = model(lr_batch)
    loss = criterion(sr, hr_batch)
    loss.backward()
    optimizer.step()
    
    # Update EMA and learning rate
    ema.update(model)
    scheduler.step()

---

📈 Benchmarks

Comparison with Standard Initialization

Metric	M23-Spectrum	He Init	Improvement
Epochs to Convergence	15	42	2.8×
Final Loss	0.0234	0.0312	25%↓
Gradient Stability (std)	0.089	0.412	4.6×

Standard Benchmarks (×4)

Method	Set5	Set14	BSD100	Urban100
Bicubic	28.42	26.10	25.96	23.15
SRResNet	32.14	28.72	27.63	26.03
ESRGAN	32.31	28.88	27.70	26.28
M23-RLFN	30.21	27.45	26.92	25.18
M23-RLFN + TTA	30.48	27.62	27.05	25.34

---

📁 Project Structure

m23-spectrum/
├── src/m23_spectrum/
│   ├── models/           # Neural network models
│   │   ├── m23_rlfn.py   # Lightweight SR model
│   │   └── m23_swinir.py # Transformer-based SOTA
│   ├── losses/           # Loss functions
│   │   ├── base.py       # Charbonnier, Frequency
│   │   ├── perceptual.py # LPIPS, VGG
│   │   ├── gan.py        # GAN losses
│   │   └── multiscale.py # Multi-scale losses
│   ├── data/             # Dataset utilities
│   ├── utils/            # Image & metric utilities
│   ├── core/             # M23-Spectrum core
│   ├── inference.py      # High-level inference API
│   └── demo.py           # Gradio web demo
├── scripts/              # CLI tools
├── tests/                # Unit tests
├── docs/                 # Documentation
└── assets/               # Examples & pretrained

---

🔧 API Reference

Models

from m23_spectrum.models import M23RLFN, M23SwinIR, create_model

# Create model
model = M23RLFN(n_feats=52, n_blocks=8, scale=4)

# Or use factory
model = create_model("m23-rlfn-x4", pretrained=True)

# Load custom weights
model = M23RLFN.from_pretrained("m23-rlfn-x4")

Inference

from m23_spectrum import SuperResolver, TTAUpscaler

# Standard inference
resolver = SuperResolver("m23-rlfn-x4", device="cuda", half=True)
sr_image = resolver.process(pil_image)

# TTA for best quality
upscaler = TTAUpscaler("m23-rlfn-x4", tta_mode="full")
sr_image = upscaler.upscale("input.png", "output.png")

Metrics

from m23_spectrum.utils import calculate_psnr, calculate_ssim, calculate_metrics

metrics = calculate_metrics(sr_tensor, hr_tensor)
print(f"PSNR: {metrics['psnr']:.2f} dB")
print(f"SSIM: {metrics['ssim']:.4f}")

---

📖 Documentation

Full documentation available at m23spectrum.dev

• Getting Started
• Model Architecture
• Training Guide
• API Reference
• FAQ

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Development setup
git clone https://github.com/m23spectrum/m23-spectrum.git
cd m23-spectrum
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
black .
ruff check .

---

📜 License

MIT License - see LICENSE

---

📖 Citation

@software{m23spectrum2026,
  title   = {M23-Spectrum: Algebraic Weight Initialization for Super-Resolution},
  author  = {M23-Spectrum Team},
  year    = {2026},
  url     = {https://github.com/m23spectrum/m23-spectrum},
  note    = {v1.0.0}
}

---

🙏 Acknowledgments

• RLFN architecture from NTIRE 2022
• SwinIR from SwinIR
• LPIPS from richzhang/lpips

---

Made with ❤️ by M23-Spectrum Team