Skip to content
SR-Forge

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

Dataset --> [Entry] --> Transforms --> [Entry] --> Model --> [Entry] --> Loss
  1. A Dataset loads raw data and wraps it in an Entry — a dictionary-like container that carries tensors, metadata, and any other fields through the pipeline
  2. Transforms preprocess the data (normalize, augment, reshape)
  3. A Model runs the neural network computation
  4. Results are written back to the Entry
  5. A Loss function evaluates the prediction against the target

Every component reads from and writes to Entry objects. This uniform interface is what makes everything interchangeable — swap any component and the rest of the pipeline doesn't change.

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, losses, and observers work exactly like built-in ones.

Where to Go Next

Read the guide in order — each page builds on the previous one:

  1. Anatomy of a Training — What every training needs and which SR-Forge piece handles it — the "why" behind the framework
  2. Core Concepts — Quick glossary of every SR-Forge term (2 min read)
  3. Entry — The dictionary-like container that carries data through the pipeline
  4. Collation — How single entries become batches (and why it matters)
  5. Datasets — Loading data, caching, and wrapper datasets
  6. Transforms — Preprocessing and augmentation steps
  7. IO Binding — How components connect to Entry fields
  8. Models — Neural network components and pipeline composition
  9. Losses — Evaluation metrics and loss functions
  10. Writing Scripts — Training and test scripts
  11. Trainers & Runners — The training loop and inference orchestration
  12. Configuration — Wire everything together in YAML
  13. Experiment Tracking — W&B, checkpointing, and resume
  14. Hooks — Pluggable training-loop callbacks for losses and metrics
  15. Observers & Events — Legacy monitoring system (deprecated; use Hooks)
  16. Extending SR-Forge — Write custom components that work like built-in ones

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
Losses L1, L2, SSIM, LPIPS, schedulable loss combiners
Observers Checkpointing, W&B logging, image visualization, metric tracking

Contributing

SR-Forge is under active development. Contributions welcome!

  • Report issues on GitLab
  • Submit merge requests
  • Share your models and experiments