# prs-eth/thera architecture

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

- Interactive diagram: https://gitdiagram.com/prs-eth/thera
- Repository: https://github.com/prs-eth/thera

## Overview

Thera is a JAX/Flax arbitrary-scale image super-resolution system. Its main workflow takes an image and requested scale, builds a model from a checkpoint, and predicts and saves an upscaled image; separate workflows train models and evaluate them across datasets and scales. The graph also shows the model’s hypernetwork/heat-field design and the documented EDSR and RDN backbones. Relationships for unsampled inference code follow the README and SOURCE INDEX; uncertain implementation details are omitted.

Main entry points: [`run_train.py`](https://github.com/prs-eth/thera/blob/main/run_train.py) (Training loop), [`model/thera.py`](https://github.com/prs-eth/thera/blob/main/model/thera.py) (Thera builder and fields), [`run_eval.py`](https://github.com/prs-eth/thera/blob/main/run_eval.py) (Evaluation runner), [`super_resolve.py`](https://github.com/prs-eth/thera/blob/main/super_resolve.py) (Super-resolve CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["User workflows"]
  node_superresolve["Super-resolve CLI<br/>[super_resolve.py]"]
  node_train_eval["Train/eval runner"]
end

subgraph group_data_eval["Data and evaluation"]
  node_data["Image datasets<br/>[data.py]"]
  node_utils["Image utilities<br/>[utils.py]"]
  node_eval_args["Evaluation options<br/>[eval.py]"]
  node_eval["Evaluation runner<br/>[run_eval.py]"]
end

subgraph group_model["Thera model"]
  node_thera["Thera builder and fields<br/>[thera.py]"]
  node_hyper["Hypernetwork<br/>[hyper.py]"]
  node_edsr["EDSR backbone<br/>[edsr.py]"]
  node_rdn["RDN backbone<br/>[rdn.py]"]
  node_tail["Backbone tails<br/>[tail.py]"]
  node_convnext["ConvNeXt blocks<br/>[convnext.py]"]
  node_swin["SwinIR blocks<br/>[swin_ir.py]"]
end

subgraph group_training["Training"]
  node_train_args["Training options<br/>[train.py]"]
  node_train["Training loop<br/>[run_train.py]"]
end

node_user(("Image user"))
node_trainer(("Model trainer"))
node_dataset[("Image dataset")]
node_checkpoint["Model checkpoint"]
node_wandb["Weights &amp; Biases"]

node_user -->|"requests upscale"| node_superresolve
node_superresolve -->|"builds model"| node_thera
node_superresolve -.->|"loads parameters"| node_checkpoint
node_superresolve -->|"uses helpers"| node_utils
node_superresolve -.->|"saves result"| node_user
node_trainer -->|"starts training"| node_train_eval
node_train_eval -->|"runs training"| node_train
node_train_eval -->|"runs evaluation"| node_eval
node_train -->|"reads options"| node_train_args
node_train -->|"loads samples"| node_data
node_train -->|"builds model"| node_thera
node_train -->|"uses metrics"| node_utils
node_train -->|"writes parameters"| node_checkpoint
node_train -->|"logs metrics"| node_wandb
node_data -.->|"reads images"| node_dataset
node_data -->|"uses grid and resize"| node_utils
node_eval -->|"reads options"| node_eval_args
node_eval -->|"loads evaluation images"| node_data
node_eval -->|"loads parameters"| node_checkpoint
node_eval -->|"builds model"| node_thera
node_eval -->|"computes metrics"| node_utils
node_thera -->|"constructs hypernetwork"| node_hyper
node_thera -->|"selects backbone"| node_edsr
node_thera -->|"selects backbone"| node_rdn
node_thera -->|"builds tail"| node_tail
node_hyper -->|"interpolates grid"| node_utils
node_tail -->|"uses blocks"| node_convnext
node_tail -->|"uses blocks"| node_swin

click node_superresolve "https://github.com/prs-eth/thera/blob/main/super_resolve.py"
click node_train_eval "https://github.com/prs-eth/thera/blob/main/run_train_and_eval.py"
click node_train_args "https://github.com/prs-eth/thera/blob/main/args/train.py"
click node_train "https://github.com/prs-eth/thera/blob/main/run_train.py"
click node_data "https://github.com/prs-eth/thera/blob/main/data.py"
click node_utils "https://github.com/prs-eth/thera/blob/main/utils.py"
click node_eval_args "https://github.com/prs-eth/thera/blob/main/args/eval.py"
click node_eval "https://github.com/prs-eth/thera/blob/main/run_eval.py"
click node_thera "https://github.com/prs-eth/thera/blob/main/model/thera.py"
click node_hyper "https://github.com/prs-eth/thera/blob/main/model/hyper.py"
click node_edsr "https://github.com/prs-eth/thera/blob/main/model/edsr.py"
click node_rdn "https://github.com/prs-eth/thera/blob/main/model/rdn.py"
click node_tail "https://github.com/prs-eth/thera/blob/main/model/tail.py"
click node_convnext "https://github.com/prs-eth/thera/blob/main/model/convnext.py"
click node_swin "https://github.com/prs-eth/thera/blob/main/model/swin_ir.py"

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_superresolve,node_train_eval,node_user toneBlue
class node_data,node_utils,node_eval_args,node_eval,node_dataset toneAmber
class node_thera,node_hyper,node_edsr,node_rdn,node_tail,node_convnext,node_swin toneMint
class node_train_args,node_train toneRose
class node_trainer,node_checkpoint,node_wandb toneIndigo
```

## Components

### User workflows

- [Super-resolve CLI](https://github.com/prs-eth/thera/blob/main/super_resolve.py): `super_resolve.py`
- [Train/eval runner](https://github.com/prs-eth/thera/blob/main/run_train_and_eval.py): `run_train_and_eval.py`

### Data and evaluation

- [Image datasets](https://github.com/prs-eth/thera/blob/main/data.py): `data.py`
- [Image utilities](https://github.com/prs-eth/thera/blob/main/utils.py): `utils.py`
- [Evaluation options](https://github.com/prs-eth/thera/blob/main/args/eval.py): `args/eval.py`
- [Evaluation runner](https://github.com/prs-eth/thera/blob/main/run_eval.py): `run_eval.py`

### Thera model

- [Thera builder and fields](https://github.com/prs-eth/thera/blob/main/model/thera.py): `model/thera.py`
- [Hypernetwork](https://github.com/prs-eth/thera/blob/main/model/hyper.py): `model/hyper.py`
- [EDSR backbone](https://github.com/prs-eth/thera/blob/main/model/edsr.py): `model/edsr.py`
- [RDN backbone](https://github.com/prs-eth/thera/blob/main/model/rdn.py): `model/rdn.py`
- [Backbone tails](https://github.com/prs-eth/thera/blob/main/model/tail.py): `model/tail.py`
- [ConvNeXt blocks](https://github.com/prs-eth/thera/blob/main/model/convnext.py): `model/convnext.py`
- [SwinIR blocks](https://github.com/prs-eth/thera/blob/main/model/swin_ir.py): `model/swin_ir.py`

### Training

- [Training options](https://github.com/prs-eth/thera/blob/main/args/train.py): `args/train.py`
- [Training loop](https://github.com/prs-eth/thera/blob/main/run_train.py): `run_train.py`

### Other components

- **Image user**
- **Model trainer**
- **Image dataset**
- **Model checkpoint**
- **Weights & Biases**

## Connections

- Image user → Super-resolve CLI: requests upscale (evidence: `README.md`)
- Super-resolve CLI → Thera builder and fields: builds model (evidence: `super_resolve.py`)
- Super-resolve CLI → Model checkpoint: loads parameters
- Super-resolve CLI → Image utilities: uses helpers (evidence: `super_resolve.py`)
- Super-resolve CLI → Image user: saves result (evidence: `README.md`)
- Model trainer → Train/eval runner: starts training (evidence: `README.md`)
- Train/eval runner → Training loop: runs training (evidence: `run_train_and_eval.py`)
- Train/eval runner → Evaluation runner: runs evaluation (evidence: `run_train_and_eval.py`)
- Training loop → Training options: reads options (evidence: `run_train.py`)
- Training loop → Image datasets: loads samples (evidence: `run_train.py`)
- Training loop → Thera builder and fields: builds model (evidence: `run_train.py`)
- Training loop → Image utilities: uses metrics (evidence: `run_train.py`)
- Training loop → Model checkpoint: writes parameters (evidence: `run_train.py`)
- Training loop → Weights & Biases: logs metrics (evidence: `run_train.py`)
- Image datasets → Image dataset: reads images
- Image datasets → Image utilities: uses grid and resize (evidence: `data.py`)
- Evaluation runner → Evaluation options: reads options (evidence: `run_eval.py`)
- Evaluation runner → Image datasets: loads evaluation images (evidence: `run_eval.py`)
- Evaluation runner → Model checkpoint: loads parameters (evidence: `run_eval.py`)
- Evaluation runner → Thera builder and fields: builds model (evidence: `run_eval.py`)
- Evaluation runner → Image utilities: computes metrics (evidence: `run_eval.py`)
- Thera builder and fields → Hypernetwork: constructs hypernetwork (evidence: `model/thera.py`)
- Thera builder and fields → EDSR backbone: selects backbone (evidence: `model/thera.py`)
- Thera builder and fields → RDN backbone: selects backbone (evidence: `model/thera.py`)
- Thera builder and fields → Backbone tails: builds tail (evidence: `model/thera.py`)
- Hypernetwork → Image utilities: interpolates grid (evidence: `model/hyper.py`)
- Backbone tails → ConvNeXt blocks: uses blocks (evidence: `model/tail.py`)
- Backbone tails → SwinIR blocks: uses blocks (evidence: `model/tail.py`)
