SR-Forge¶
Structured Research Framework for Organized Research & Guided Experiments
SR-Forge is a modular, config-driven PyTorch framework for deep learning research. It handles the repetitive plumbing — data routing, component wiring, configuration management — so you can focus on what matters: your models, your data, and your experiments.
The Problem SR-Forge Solves¶
A typical deep learning experiment has many moving parts: datasets, preprocessing transforms, models, postprocessing, loss functions, optimizers, logging, checkpointing. In most projects, these parts become tangled together. Changing one component means rewriting glue code everywhere else.
SR-Forge solves this by making every component self-contained and configurable. Each component declares what data it needs and what it produces. The framework handles all the wiring — extracting the right fields from data, passing them to the right component, and storing results back. You define your experiment in a YAML file, and SR-Forge builds and connects everything automatically.
The result: you can swap models, change preprocessing, or adjust training strategies by editing a config file — no Python changes needed.
How It Works¶
Every component reads from and writes to Entry objects — dictionary-like containers that carry your data through the pipeline. That one uniform interface is what makes components interchangeable: swap any of them and the rest of the pipeline doesn't change.
That's the whole idea in one line. Anatomy of a Training explains why each piece exists; Core Concepts names and shows the code for each one.
A Taste of SR-Forge¶
Define a model, call it on data:
from srforge.models import Model
from srforge.data import Entry
import torch
class Upscaler(Model):
def __init__(self):
super().__init__()
self.net = torch.nn.Conv2d(3, 3, 3, padding=1)
def _forward(self, image):
return self.net(image)
model = Upscaler()
# Connect parameter names to Entry field names
model.set_io({"inputs": {"image": "input"}, "outputs": "prediction"})
entry = Entry(input=torch.randn(1, 3, 64, 64))
result = model(entry)
print(result.prediction.shape) # torch.Size([1, 3, 64, 64])
That's a complete working example. The model reads from entry["input"], runs the network, and stores the result in entry["prediction"].
What Makes SR-Forge Different¶
Entry + IO binding — All data flows through Entry objects — dictionary-like containers with named fields. Components declare what they need ("image") and IO binding maps that to actual data (entry["input_rgb"]). Write a component once, reuse it with any data layout. Swap any component and the rest of the pipeline doesn't change.
Configuration over code — Define entire experiments in YAML. The framework instantiates all objects, wires them together, and handles training. Reproduce any experiment by sharing a config file.
Easy to extend — Every component follows the same pattern: subclass, implement one method, use from Python or YAML. Your custom models, transforms, metrics, and hooks work exactly like built-in ones.
Where to Go Next¶
New here? Follow the path — it runs why → what → how:
- Anatomy of a Training — what every training needs, and which SR-Forge piece handles each part. The "why" behind the design — start here. (~5 min)
- Core Concepts — the precise vocabulary, Python/YAML code for each piece, and the one big-picture diagram every other page uses.
- The Guide — each piece in depth, grouped by priority: the Essentials (Entry, Datasets, Transforms, IO Binding, Models, Metrics, Code or Config?, Configuration, Writing Scripts), then running real experiments (Tracking, Hooks, Runners) and advanced & scaling (SequentialModel, GANModel, Distributed, Collation, Extending).
Keep these within reach:
- FAQ — "How do I…?", answered in one line each with a link into the guide.
- Cheatsheet — the syntax you'll reach for daily, on one page.
- Architecture — the internals (class hierarchy, runtime wiring, sequence diagrams) for the curious and for contributors.
Built-in Components¶
SR-Forge ships with ready-to-use components for common tasks:
| Category | Examples |
|---|---|
| Models | FSRCNN, DSen2, RAMS, TR-MISR, MagNAt, Interpolation |
| Transforms | Normalization, augmentation, band selection, field manipulation |
| Datasets | Lazy-loading multispectral, patch extraction, flexible collation |
| Metrics | L1, MSE, SSIM, LPIPS, Charbonnier, uncertainty + shift-corrected wrappers, schedulable combiners |
| Hooks | Checkpointing, W&B logging, image previews, gradient clipping, progress bars |
Contributing¶
SR-Forge is under active development. Contributions welcome!
- Report issues on GitLab
- Submit merge requests
- Share your models and experiments