# tyvirgo/higan architecture

> Architecture diagram of the GitHub repository tyvirgo/higan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tyvirgo/higan
- Repository: https://github.com/tyvirgo/higan

## Overview

1. This repository is a PyTorch-based image super-resolution project centered on the HIGAN family of models. It provides both training and evaluation code, plus pretrained checkpoints for three model sizes: HIGAN-S, HIGAN, and HIGAN-L.

2. The architecture is organized around a single entry point, `src/main.py`, which likely dispatches between training and test-only execution based on command-line options. Configuration is handled through `src/option.py`, with `src/template.py` and `src/utility.py` supporting experiment setup, logging, and run-time orchestration.

3. The core model boundary lives in `src/model/`. This folder contains the HIGAN implementations (`higan_6block.py`, `higan_10block.py`) as well as baseline/reference architectures such as EDSR, VDSR, RFDN, and shared building blocks in `block.py`, `common.py`, `arch_util.py`, and `atten.py`. The repo is therefore not just a single network, but a model zoo with HIGAN as the main target.

4. Data ingestion is isolated in `src/data/`. The repository supports multiple super-resolution datasets and dataset variants, including DIV2K, DF2K, Flickr2K, SR291, benchmark/test datasets, JPEG variants, demo inputs, and video data. `srdata.py` appears to be the common dataset base class, while the other files adapt it to specific sources and evaluation formats.

5. The data flow for training is typical SR supervision: low-resolution inputs and corresponding high-resolution targets are loaded from dataset-specific readers, then cropped into patches and batched through `src/dataloader.py`. The repo’s training commands in the README indicate patch-based training, scale-factor-specific runs, and dataset-path configuration through options.

6. The training loop is concentrated in `src/trainer.py`. This is the main subsystem that likely connects the model, optimizer, learning-rate schedule, loss functions, and periodic evaluation. The repo also includes `src/loss/` with adversarial, discriminator, and VGG-based perceptual losses, indicating support for both plain reconstruction training and GAN/perceptual training variants.

7. Evaluation and reporting are separated from training. The README’s `demo.sh` workflow and the `--test_only` flag suggest that test runs load pretrained checkpoints from `./pretrained/` and write results into experiment-specific output folders. This boundary keeps inference side effects, metrics, and image saving out of the training loop.

8. There is explicit support for benchmark-style testing over standard SR datasets such as Set5, Set14, B100, Urban100, and Manga109. The `src/data/benchmark.py` and `src/data/div2k_test.py` files suggest a distinction between training datasets and standardized test datasets, which is important for architecture diagrams showing separate ingestion paths.

9. Video super-resolution is a separate functional path, not just an afterthought. The presence of `src/videotester.py` and `src/data/video.py` indicates a dedicated inference/testing path for sequential frame inputs, likely sharing the same model backbone but different sampling and I/O logic.

10. The repository depends on CUDA-enabled PyTorch tooling and expects Python 3.8. The README also notes that this code is built on EDSR-PyTorch, which helps explain the overall layout: option parsing, dataset factories, trainer abstraction, and model modules are all in the style of a reusable SR research framework.

11. Pretrained weights are versioned by model family and upscaling factor under `pretrained/`, with separate folders for x2, x3, and x4 checkpoints. This means the deployment boundary is checkpoint-based rather than service-based: the model graph is defined in code, then instantiated with a matching `.pt` file for inference or fine-tuning.

12. For an architecture diagram, the key flow is: command-line options enter `main.py`, configuration selects dataset and model, data loaders feed LR/HR pairs into the HIGAN backbone, losses and optimizer are managed by the trainer during training, and checkpoints/results are emitted to experiment folders during evaluation or demo runs.

Main entry points: [`src/main.py`](https://github.com/tyvirgo/higan/blob/main/src/main.py) (main), [`src/videotester.py`](https://github.com/tyvirgo/higan/blob/main/src/videotester.py) (tester), [`src/data/srdata.py`](https://github.com/tyvirgo/higan/blob/main/src/data/srdata.py) (srdata), [`src/trainer.py`](https://github.com/tyvirgo/higan/blob/main/src/trainer.py) (trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_entry["Entry & orchestration"]
  node_n_main(("main<br/>entrypoint<br/>[main.py]"))
  node_n_option["options<br/>cli config<br/>[option.py]"]
  node_n_template["template<br/>run setup<br/>[template.py]"]
  node_n_utility["utility<br/>runtime utils<br/>[utility.py]"]
end

subgraph group_g_data["Data pipeline"]
  node_n_loader["dataloader<br/>batching<br/>[dataloader.py]"]
  node_n_srdata["srdata<br/>dataset base<br/>[srdata.py]"]
  node_n_trainsets["train sets<br/>training datasets<br/>[div2k.py]"]
  node_n_testsets["test sets<br/>benchmark datasets<br/>[benchmark.py]"]
  node_n_demo_video["demo/video<br/>specialized input<br/>[demo.py]"]
end

subgraph group_g_model["Model zoo"]
  node_n_higan["HIGAN<br/>sr backbone<br/>[higan_6block.py]"]
  node_n_baselines["baselines<br/>sr models<br/>[edsr.py]"]
  node_n_blocks["building blocks<br/>shared modules<br/>[block.py]"]
end

subgraph group_g_train["Training & loss"]
  node_n_trainer["trainer<br/>train loop<br/>[trainer.py]"]
  node_n_losses["losses<br/>objective suite<br/>[adversarial.py]"]
end

subgraph group_g_eval["Inference & demo"]
  node_n_test["tester<br/>inference loop<br/>[videotester.py]"]
  node_n_video["video tester<br/>video inference<br/>[videotester.py]"]
end

subgraph group_g_weights["Weights"]
  node_n_pre_higan_s[("HIGAN-S<br/>checkpoint family<br/>[higans_x2.pt]")]
  node_n_pre_higan[("HIGAN<br/>checkpoint family<br/>[higan_x2.pt]")]
  node_n_pre_higan_l[("HIGAN-L<br/>checkpoint family<br/>[higanl_x2.pt]")]
end

node_n_main -->|"reads args"| node_n_option
node_n_main -->|"builds run"| node_n_template
node_n_main -->|"uses helpers"| node_n_utility
node_n_main -->|"creates loaders"| node_n_loader
node_n_loader -->|"extends"| node_n_srdata
node_n_srdata -->|"loads"| node_n_trainsets
node_n_srdata -->|"loads"| node_n_testsets
node_n_srdata -->|"loads"| node_n_demo_video
node_n_main -->|"selects model"| node_n_higan
node_n_main -.->|"selects model"| node_n_baselines
node_n_higan -->|"reuses"| node_n_blocks
node_n_baselines -->|"reuses"| node_n_blocks
node_n_main -->|"trains"| node_n_trainer
node_n_trainer -->|"optimizes with"| node_n_losses
node_n_trainer -->|"updates"| node_n_higan
node_n_trainer -->|"consumes batches"| node_n_loader
node_n_main -->|"test only"| node_n_test
node_n_test -->|"loads"| node_n_pre_higan
node_n_test -->|"loads"| node_n_pre_higan_s
node_n_test -->|"loads"| node_n_pre_higan_l
node_n_test -->|"evaluates on"| node_n_testsets
node_n_video -->|"streams"| node_n_demo_video
node_n_video -.->|"loads"| node_n_pre_higan

click node_n_main "https://github.com/tyvirgo/higan/blob/main/src/main.py"
click node_n_option "https://github.com/tyvirgo/higan/blob/main/src/option.py"
click node_n_template "https://github.com/tyvirgo/higan/blob/main/src/template.py"
click node_n_utility "https://github.com/tyvirgo/higan/blob/main/src/utility.py"
click node_n_loader "https://github.com/tyvirgo/higan/blob/main/src/dataloader.py"
click node_n_srdata "https://github.com/tyvirgo/higan/blob/main/src/data/srdata.py"
click node_n_trainsets "https://github.com/tyvirgo/higan/blob/main/src/data/div2k.py"
click node_n_testsets "https://github.com/tyvirgo/higan/blob/main/src/data/benchmark.py"
click node_n_demo_video "https://github.com/tyvirgo/higan/blob/main/src/data/demo.py"
click node_n_higan "https://github.com/tyvirgo/higan/blob/main/src/model/higan_6block.py"
click node_n_baselines "https://github.com/tyvirgo/higan/blob/main/src/model/edsr.py"
click node_n_blocks "https://github.com/tyvirgo/higan/blob/main/src/model/block.py"
click node_n_trainer "https://github.com/tyvirgo/higan/blob/main/src/trainer.py"
click node_n_losses "https://github.com/tyvirgo/higan/blob/main/src/loss/adversarial.py"
click node_n_test "https://github.com/tyvirgo/higan/blob/main/src/videotester.py"
click node_n_video "https://github.com/tyvirgo/higan/blob/main/src/videotester.py"
click node_n_pre_higan_s "https://github.com/tyvirgo/higan/blob/main/pretrained/HIGAN-S_Div2k/higans_x2.pt"
click node_n_pre_higan "https://github.com/tyvirgo/higan/blob/main/pretrained/HIGAN_Div2K/higan_x2.pt"
click node_n_pre_higan_l "https://github.com/tyvirgo/higan/blob/main/pretrained/HIGAN-L_Div2k/higanl_x2.pt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_main,node_n_option,node_n_template,node_n_utility toneBlue
class node_n_loader,node_n_srdata,node_n_trainsets,node_n_testsets,node_n_demo_video toneAmber
class node_n_higan,node_n_baselines,node_n_blocks toneMint
class node_n_trainer,node_n_losses toneRose
class node_n_test,node_n_video toneIndigo
class node_n_pre_higan_s,node_n_pre_higan,node_n_pre_higan_l toneTeal
```

## Components

### Entry & orchestration

CLI entrypoint, option parsing, and run setup.

- [main](https://github.com/tyvirgo/higan/blob/main/src/main.py): entrypoint · Single command entry for train or test execution. · `src/main.py`
- [options](https://github.com/tyvirgo/higan/blob/main/src/option.py): cli config · Parses command-line flags and experiment settings. · `src/option.py`
- [template](https://github.com/tyvirgo/higan/blob/main/src/template.py): run setup · Builds experiment templates and runtime structure. · `src/template.py`
- [utility](https://github.com/tyvirgo/higan/blob/main/src/utility.py): runtime utils · Shared helpers for logging, filesystem, and orchestration. · `src/utility.py`

### Data pipeline

Training and evaluation dataset loading.

- [dataloader](https://github.com/tyvirgo/higan/blob/main/src/dataloader.py): batching · Creates loaders and batches for SR datasets. · `src/dataloader.py`
- [srdata](https://github.com/tyvirgo/higan/blob/main/src/data/srdata.py): dataset base · Common dataset base class used by SR datasets. · `src/data/srdata.py`
- [train sets](https://github.com/tyvirgo/higan/blob/main/src/data/div2k.py): training datasets · DIV2K, DF2K, Flickr2K, SR291, and JPEG variants. · `src/data/div2k.py`
- [test sets](https://github.com/tyvirgo/higan/blob/main/src/data/benchmark.py): benchmark datasets · Benchmark and DIV2K test readers for standard SR evaluation. · `src/data/benchmark.py`
- [demo/video](https://github.com/tyvirgo/higan/blob/main/src/data/demo.py): specialized input · Demo inputs and video frame loading for sequential inference. · `src/data/demo.py`

### Model zoo

HIGAN and baseline SR architectures.

- [HIGAN](https://github.com/tyvirgo/higan/blob/main/src/model/higan_6block.py): sr backbone · Main HIGAN family implementations for 6-block and 10-block variants. · `src/model/higan_6block.py`
- [baselines](https://github.com/tyvirgo/higan/blob/main/src/model/edsr.py): sr models · Reference SR architectures such as EDSR, VDSR, and RFDN. · `src/model/edsr.py`
- [building blocks](https://github.com/tyvirgo/higan/blob/main/src/model/block.py): shared modules · Common layers, attention, and architecture utilities reused by models. · `src/model/block.py`

### Training & loss

Optimization loop and training objectives.

- [trainer](https://github.com/tyvirgo/higan/blob/main/src/trainer.py): train loop · Coordinates model updates, evaluation cadence, and checkpoints. · `src/trainer.py`
- [losses](https://github.com/tyvirgo/higan/blob/main/src/loss/adversarial.py): objective suite · Adversarial, discriminator, and perceptual loss components. · `src/loss/adversarial.py`

### Inference & demo

Test-only and video/demo execution paths.

- [tester](https://github.com/tyvirgo/higan/blob/main/src/videotester.py): inference loop · Test-only execution path for loading checkpoints and reporting results. · `src/videotester.py`
- [video tester](https://github.com/tyvirgo/higan/blob/main/src/videotester.py): video inference · Specialized sequential-frame evaluation for video SR. · `src/videotester.py`

### Weights

Pretrained checkpoints grouped by model family.

- [HIGAN-S](https://github.com/tyvirgo/higan/blob/main/pretrained/HIGAN-S_Div2k/higans_x2.pt): checkpoint family · Pretrained weights for the small HIGAN model across x2, x3, x4. · `pretrained/HIGAN-S_Div2k/higans_x2.pt`
- [HIGAN](https://github.com/tyvirgo/higan/blob/main/pretrained/HIGAN_Div2K/higan_x2.pt): checkpoint family · Pretrained weights for the base HIGAN model across x2, x3, x4. · `pretrained/HIGAN_Div2K/higan_x2.pt`
- [HIGAN-L](https://github.com/tyvirgo/higan/blob/main/pretrained/HIGAN-L_Div2k/higanl_x2.pt): checkpoint family · Pretrained weights for the large HIGAN model across x2, x3, x4. · `pretrained/HIGAN-L_Div2k/higanl_x2.pt`

## Connections

- main → options: reads args · CLI options determine mode, dataset, scale, and paths.
- main → template: builds run · Experiment naming and folder layout are prepared early.
- main → utility: uses helpers · Main flow relies on common runtime utilities.
- main → dataloader: creates loaders · Dispatches into training or evaluation data pipelines.
- dataloader → srdata: extends · Dataset wrappers share the common SR dataset base.
- srdata → train sets: loads · Training data readers provide LR/HR supervision pairs.
- srdata → test sets: loads · Benchmark readers provide standardized evaluation samples.
- srdata → demo/video: loads · Demo and video inputs follow specialized read paths.
- main → HIGAN: selects model · Configured model family is instantiated from the model zoo.
- main → baselines: selects model · Alternative SR backbones are available through the same boundary.
- HIGAN → building blocks: reuses · HIGAN variants are composed from shared architectural blocks.
- baselines → building blocks: reuses · Baseline architectures also depend on shared modules.
- main → trainer: trains · Training mode hands off control to the trainer loop.
- trainer → losses: optimizes with · Trainer combines reconstruction, adversarial, and perceptual losses.
- trainer → HIGAN: updates · Backpropagation targets the selected super-resolution model.
- trainer → dataloader: consumes batches · Mini-batches from the loader feed the optimization loop.
- main → tester: test only · Evaluation mode bypasses training and runs inference/reporting.
- tester → HIGAN: loads · Test runs use matching pretrained checkpoints when available.
- tester → HIGAN-S: loads · Small-model checkpoints support inference and demo workflows.
- tester → HIGAN-L: loads · Large-model checkpoints support inference and demo workflows.
- tester → test sets: evaluates on · Standard benchmark datasets are used for reported results.
- video tester → demo/video: streams · Video SR uses frame-sequence input rather than image batches.
- video tester → HIGAN: loads · Video inference reuses pretrained backbone checkpoints.