Skip to content
SR-Forge

Getting Started

Installation

Prerequisites

Install PyTorch before installing SR-Forge. Follow the official instructions at pytorch.org to pick the right build for your OS, package manager, and GPU.

# Example: CUDA 12.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

# Example: CPU only
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

Install SR-Forge

pip install srforge

This installs the core framework with everything you need for tensor-based super-resolution: models, transforms, datasets, losses, training loops, and configuration.

Graph neural network support

If you work with graph-based models (e.g., MagNAt), you need PyTorch Geometric and its compiled extensions. Just like PyTorch itself, these must be installed with the correct CUDA version before installing SR-Forge's graph extra.

Follow the PyG installation guide to pick the right wheels for your PyTorch version, then install the graph extra:

# Example: PyG packages for PyTorch 2.7 + CUDA 12.8
pip install torch-geometric
pip install pyg-lib torch-scatter torch-sparse torch-cluster torch-spline-conv \
    -f https://data.pyg.org/whl/torch-2.7.0+cu128.html

# Then install the graph extra
pip install srforge[graph]

Scaffold a new project

After installing SR-Forge, create a ready-to-run training project:

mkdir my-experiment && cd my-experiment
srforge init

This generates:

my-experiment/
├── train.py              # Training script
├── benchmark.py          # Benchmark/inference script
└── configs/
    ├── train-cfg.yaml    # Training config
    └── benchmark-cfg.yaml # Benchmark config

Edit configs/train-cfg.yaml to point at your data and adjust training settings, then run:

python train.py

No data yet? Run the bundled example first

The repository ships a complete, zero-setup experiment at examples/minimal_sr/ — synthetic data, a tiny model, and a fully-commented config. python examples/minimal_sr/train.py runs in seconds on CPU and shows you the whole pipeline working before you wire up your own data.

What the scaffold contains

The generated benchmark.py follows the same structure as train.py but runs inference on a test dataset using the BenchmarkRunner.

The generated train.py follows a 6-step pattern:

  1. init(cfg) — framework setup, returns a config resolver
  2. Resolve training objects — model, loss, optimizer, scheduler from YAML
  3. Datasets & device — load data, set up GPU/multi-GPU
  4. Trainer & sanity check — resolve the trainer and validate the pipeline once
  5. Tracker + resume — experiment logging (W&B or null) + optional checkpoint restore
  6. Train — run the epoch loop

Hooks (progress bars, loss logging, checkpoint saving, image previews) are attached to the trainer and runners via their hooks: YAML lists — no separate subscription step in the Python script. See Hooks for how to add your own; the legacy observers: mechanism still works but is scheduled for removal in v0.16.0.

The generated train-cfg.yaml has sections for: system (device, caching), tracker, training (epochs, batch size), model, optimizer, lr_scheduler, loss, dataset, preprocessing/postprocessing, training_runner/validation_runner, and trainer (with hooks attached inside these last three). The benchmark-cfg.yaml mirrors the training config but without training-specific sections (optimizer, scheduler, trainer).

The rest of the guide explains each piece in detail.

The generated files are a starting point, not a rigid template. They include common features out of the box (multi-GPU, mixed precision, dataset caching, W&B tracking, loss scheduling, checkpointing), but you're expected to modify both files to fit your workflow.

The config file is especially flexible — add any fields you need. The YAML config is a plain Hydra/OmegaConf file, so you can add custom sections for your own training script logic, experiment metadata, or grouping in W&B, MLflow, or any other tracking tool. For example:

# Custom fields — use them however you like in train.py
experiment:
  description: "Ablation study on loss weights"
  tags: [ablation, l1-ssim]

my_custom_setting: 42

See the Configuration guide for details on built-in settings.

IDE support

SR-Forge Assistant is a plugin for PyCharm and other JetBrains IDEs that adds first-class support for SR-Forge projects.

  • Target intelligence — resolve _target_ references, navigate to class definitions
  • Config interpolation — live preview of ${ref:...} and OmegaConf expressions
  • Pipeline probe — visualize SequentialModel flow as a graph
  • Tensor shape inspector — inspect tensor dimensions at breakpoints
  • Debugger integration — Entry and tensor visualizations in the debug panel
Source & Documentation github.com/ttarasiewicz/SR-Forge-Assistant

What's 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 (start here if you're new to training loops)
  2. Core Concepts — Quick glossary of every SR-Forge term
  3. Entry — The data container that flows through the pipeline
  4. Collation — How single entries become batches
  5. Datasets — Loading data and caching
  6. Transforms — Preprocessing and augmentation
  7. IO Binding — How components connect to Entry fields
  8. Models — Neural networks and pipeline composition
  9. Losses — Evaluation metrics and loss functions
  10. Writing Scripts — Training and test scripts
  11. Trainers & Runners — Inside the training loop
  12. Configuration — Wire everything together in YAML
  13. Experiment Tracking — Logging, checkpointing, and resume
  14. Hooks — Progress bars, logging, checkpointing, and custom training-loop plugins
  15. Observers & Events — Legacy monitoring (deprecated — use Hooks)
  16. Extending SR-Forge — Custom components

For developers

Install PyTorch and PyG with CUDA wheels first (see Prerequisites and Graph support above), then clone and install in editable mode:

git clone https://gitlab.com/tarasiewicztomasz/sr-forge.git
cd sr-forge
pip install -e ".[dev,graph]"

This gives you:

  • Editable install — code changes take effect immediately, no reinstall needed
  • Dev tools — pytest, mkdocs, mkdocstrings
  • Graph support — full access to all components including graph models

Run the test suite:

pytest tests/ -v

Build and serve the docs locally:

mkdocs serve

Then open the local URL shown in the terminal.