# gnobitab/rectifiedflow architecture

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

- Interactive diagram: https://gitdiagram.com/gnobitab/rectifiedflow
- Repository: https://github.com/gnobitab/rectifiedflow

## Overview

1. **Repository purpose**
   This repo is the official implementation of **Rectified Flow** for image generation and reflow-based distillation. The architecture is centered on learning an ODE-based velocity field that transports noise to data, then iteratively “reflowing” trajectories to make sampling progressively straighter and faster.

2. **Top-level execution boundary**
   The main entry point is `ImageGeneration/main.py`. It acts as a mode dispatcher for three workflows: **training**, **evaluation/sampling**, and **reflow**. Most behavior is driven by config files under `ImageGeneration/configs`, so the architecture is primarily **configuration-driven rather than hardcoded**.

3. **Configuration layer**
   The `configs/` tree defines dataset- and experiment-specific setups:
   - CIFAR-10 defaults and rectified-flow variants
   - high-resolution setups for LSUN Bedroom/Church, CelebA-HQ, and AFHQ-Cat
   - specialized reflow configs for data generation, online reflow, and distillation  
   This layer determines model choice, training schedule, sampling method, checkpoint paths, and reflow behavior.

4. **Training / evaluation orchestration**
   The `run_lib.py`, `run_lib_pytorch.py`, and `run_lib_reflow.py` files are the main orchestration boundary. They connect configs to concrete workflows:
   - dataset construction
   - model instantiation
   - optimizer/training loop
   - checkpointing
   - sampling/evaluation
   - reflow pair generation and teacher-student style distillation  
   The separation suggests standard training/eval logic is shared, while reflow gets its own orchestration path.

5. **Data subsystem**
   Data handling is split between `datasets.py` and `pytorch_datasets.py`. This repo supports both the generic dataset pipeline used in the score-based framework and PyTorch-specific dataset loading. The data boundary feeds either:
   - standard supervised-like image batches for training
   - generated trajectory pairs `(Z0, Z1)` for reflow/distillation  
   Reflow data can be generated offline into `assets/reflow_data/...` or online during training.

6. **Model subsystem**
   The `models/` directory contains the neural velocity/score architectures:
   - `ddpm.py` for DDPM++-style models
   - `ncsnpp.py` / `ncsnv2.py` for score-based U-Net variants
   - `layers.py`, `layerspp.py`, `normalization.py`, `up_or_down_sampling.py`, and `utils.py` for reusable building blocks
   - `ema.py` for exponential moving average parameter tracking  
   Architecturally, these models are the learnable core that predicts the vector field used by the flow/ODE samplers.

7. **Flow and SDE abstraction**
   `sde_lib.py` provides the stochastic/ODE process abstraction used by the broader score-based framework. In this project, it supports the rectified-flow formulation by defining how the model is interpreted during training and sampling. This is the conceptual boundary between the neural network and the continuous-time generative process.

8. **Losses, likelihood, and sampling**
   - `losses.py` defines the training objective for the flow/score model.
   - `sampling.py` contains ODE-based generation routines, including Euler-style sampling used for fast one-step or few-step generation.
   - `likelihood.py` supports probability/likelihood-related evaluation paths.
   - `evaluation.py` covers sample generation and metric computation, including FID/IS-style evaluation.  
   These modules form the inference side of the system: once a checkpoint exists, they determine how images are produced and scored.

9. **Reflow pipeline**
   Reflow is a first-class workflow in this repo, not just a training trick. The architecture supports:
   - generating paired trajectories from a teacher model
   - saving those pairs to disk for offline training
   - using the generated pairs to train a stronger student flow
   - optional online generation to reduce storage cost  
   This creates a multi-stage teacher → data-pair generation → student refinement loop.

10. **Custom CUDA / PyTorch ops**
   The `op/` directory contains fused low-level operations (`fused_act`, `fused_bias_act`, `upfirdn2d`) implemented in C++/CUDA with Python bindings. These are performance-critical primitives used by the model backbones, especially for high-resolution image generation. This is the main systems-level boundary in the repo.

11. **Runtime and ecosystem**
   The project is primarily **PyTorch-based**, but the README also references TensorFlow, JAX, and TensorFlow Probability because the broader score-based ecosystem and evaluation stack historically depended on them. For architecture purposes, the runtime center of gravity here is still PyTorch plus CUDA extensions for speed.

12. **Artifacts and external dependencies**
   Important external inputs/outputs include:
   - pretrained checkpoints from Google Drive
   - dataset statistics files such as `assets/stats/cifar10_stats.npz` for FID evaluation
   - generated reflow datasets stored under `assets/reflow_data/...`
   - training/eval outputs stored under `logs/...`  
   These artifacts are part of the operational architecture because training, reflow, and evaluation all depend on them.

13. **Repository structure in one line**
   Overall, the architecture is: **config-driven experiment setup → dataset loading → model + SDE/ODE flow definition → training or reflow orchestration → sampling/evaluation → optional offline/online reflow distillation**, with custom CUDA ops accelerating the model backbone.

Main entry points: [`ImageGeneration/run_lib.py`](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/run_lib.py) (run_lib.py), [`ImageGeneration/run_lib_reflow.py`](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/run_lib_reflow.py) (run_lib_reflow.py), [`ImageGeneration/models/layers.py`](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/layers.py) (layers*.py), [`ImageGeneration/main.py`](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/main.py) (main.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Execution"]
  node_main["main.py<br/>mode dispatcher<br/>[main.py]"]
end

subgraph group_config["Configs"]
  node_cfg_cifar["CIFAR configs<br/>base config"]
  node_cfg_lsun["LSUN configs<br/>base config"]
  node_cfg_rf["RF configs<br/>experiment configs"]
end

subgraph group_core["Core flow"]
  node_run_lib["run_lib.py<br/>orchestration<br/>[run_lib.py]"]
  node_run_lib_pt["run_lib_pytorch.py<br/>orch. backend<br/>[run_lib_pytorch.py]"]
  node_run_lib_reflow["run_lib_reflow.py<br/>reflow orchestration<br/>[run_lib_reflow.py]"]
  node_losses["losses.py<br/>training objective<br/>[losses.py]"]
  node_sampling["sampling.py<br/>ODE sampling<br/>[sampling.py]"]
  node_eval["evaluation.py<br/>metrics<br/>[evaluation.py]"]
  node_likelihood["likelihood.py<br/>likelihood eval<br/>[likelihood.py]"]
  node_sde["sde_lib.py<br/>flow process<br/>[sde_lib.py]"]
end

subgraph group_data["Data"]
  node_datasets["datasets.py<br/>dataset pipeline<br/>[datasets.py]"]
  node_pt_datasets["pytorch_datasets.py<br/>PyTorch loading"]
end

subgraph group_models["Models"]
  node_ddpm["ddpm.py<br/>model arch<br/>[ddpm.py]"]
  node_ncsnpp["ncsnpp.py<br/>model arch<br/>[ncsnpp.py]"]
  node_ncsnv2["ncsnv2.py<br/>model arch<br/>[ncsnv2.py]"]
  node_layers["layers*.py<br/>building blocks<br/>[layers.py]"]
  node_ema["ema.py<br/>parameter tracking<br/>[ema.py]"]
end

subgraph group_systems["Systems"]
  node_ops["op/<br/>CUDA ops"]
  node_assets[("assets<br/>artifacts")]
end

node_main -->|"loads"| node_cfg_rf
node_main -->|"dispatches"| node_run_lib
node_main -->|"dispatches"| node_run_lib_reflow
node_run_lib -->|"uses"| node_datasets
node_run_lib -->|"uses"| node_pt_datasets
node_run_lib -->|"trains with"| node_losses
node_run_lib -->|"samples with"| node_sampling
node_run_lib -->|"evaluates with"| node_eval
node_run_lib -->|"evaluates with"| node_likelihood
node_run_lib -->|"interprets via"| node_sde
node_run_lib_pt -->|"instantiates"| node_ddpm
node_run_lib_pt -->|"instantiates"| node_ncsnpp
node_run_lib_pt -->|"instantiates"| node_ncsnv2
node_ddpm -->|"builds from"| node_layers
node_ncsnpp -->|"builds from"| node_layers
node_ncsnv2 -->|"builds from"| node_layers
node_layers -->|"accelerated by"| node_ops
node_run_lib_reflow -->|"reads/writes"| node_assets
node_run_lib_reflow -->|"generates pairs with"| node_sampling
node_run_lib_reflow -->|"optimizes with"| node_losses
node_eval -->|"reads"| node_assets
node_sampling -->|"writes"| node_assets

click node_main "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/main.py"
click node_cfg_cifar "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/configs/default_cifar10_configs.py"
click node_cfg_lsun "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/configs/default_lsun_configs.py"
click node_cfg_rf "https://github.com/gnobitab/rectifiedflow/tree/main/ImageGeneration/configs/rectified_flow"
click node_run_lib "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/run_lib.py"
click node_run_lib_pt "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/run_lib_pytorch.py"
click node_run_lib_reflow "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/run_lib_reflow.py"
click node_losses "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/losses.py"
click node_sampling "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/sampling.py"
click node_eval "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/evaluation.py"
click node_likelihood "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/likelihood.py"
click node_sde "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/sde_lib.py"
click node_datasets "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/datasets.py"
click node_pt_datasets "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/pytorch_datasets.py"
click node_ddpm "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/ddpm.py"
click node_ncsnpp "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/ncsnpp.py"
click node_ncsnv2 "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/ncsnv2.py"
click node_layers "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/layers.py"
click node_ema "https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/ema.py"
click node_ops "https://github.com/gnobitab/rectifiedflow/tree/main/ImageGeneration/op"

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_main toneBlue
class node_cfg_cifar,node_cfg_lsun,node_cfg_rf toneAmber
class node_run_lib,node_run_lib_pt,node_run_lib_reflow,node_losses,node_sampling,node_eval,node_likelihood,node_sde toneMint
class node_datasets,node_pt_datasets toneRose
class node_ddpm,node_ncsnpp,node_ncsnv2,node_layers,node_ema toneIndigo
class node_ops,node_assets toneTeal
```

## Components

### Execution

Top-level dispatch and workflow entrypoints

- [main.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/main.py): mode dispatcher · Dispatches training, evaluation, sampling, and reflow workflows from config. · `ImageGeneration/main.py`

### Configs

Experiment and dataset configuration layer

- [CIFAR configs](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/configs/default_cifar10_configs.py): base config · Default CIFAR-10 experiment settings reused by rectified-flow variants. · `ImageGeneration/configs/default_cifar10_configs.py`
- [LSUN configs](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/configs/default_lsun_configs.py): base config · Default LSUN experiment settings reused by higher-resolution variants. · `ImageGeneration/configs/default_lsun_configs.py`
- [RF configs](https://github.com/gnobitab/rectifiedflow/tree/main/ImageGeneration/configs/rectified_flow): experiment configs · Dataset-specific rectified-flow and reflow experiment definitions. · `ImageGeneration/configs/rectified_flow`

### Core flow

Training, sampling, loss, and process abstractions

- [run_lib.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/run_lib.py): orchestration · Shared training and evaluation orchestration for the score-based pipeline. · `ImageGeneration/run_lib.py`
- [run_lib_pytorch.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/run_lib_pytorch.py): orch. backend · PyTorch-specific training and evaluation orchestration layer. · `ImageGeneration/run_lib_pytorch.py`
- [run_lib_reflow.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/run_lib_reflow.py): reflow orchestration · Coordinates teacher-generated pairs, offline/online reflow, and student refinement. · `ImageGeneration/run_lib_reflow.py`
- [losses.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/losses.py): training objective · Defines the rectified-flow and score-model loss functions. · `ImageGeneration/losses.py`
- [sampling.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/sampling.py): ODE sampling · Implements ODE/Euler-style sampling routines for generation. · `ImageGeneration/sampling.py`
- [evaluation.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/evaluation.py): metrics · Runs sample generation and evaluation metrics such as FID and IS. · `ImageGeneration/evaluation.py`
- [likelihood.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/likelihood.py): likelihood eval · Supports probability and likelihood-related evaluation paths. · `ImageGeneration/likelihood.py`
- [sde_lib.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/sde_lib.py): flow process · Continuous-time process abstraction for training and sampling interpretation. · `ImageGeneration/sde_lib.py`

### Data

Dataset loading and reflow data handling

- [datasets.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/datasets.py): dataset pipeline · Generic dataset pipeline used by the score-based framework. · `ImageGeneration/datasets.py`
- [pytorch_datasets.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/pytorch_datasets.py): PyTorch loading · PyTorch-specific dataset loading and preprocessing paths. · `ImageGeneration/pytorch_datasets.py`

### Models

Velocity/score network architectures and shared layers

- [ddpm.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/ddpm.py): model arch · DDPM++-style network used as a velocity/score backbone. · `ImageGeneration/models/ddpm.py`
- [ncsnpp.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/ncsnpp.py): model arch · NCSN++ U-Net variant for score/velocity prediction. · `ImageGeneration/models/ncsnpp.py`
- [ncsnv2.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/ncsnv2.py): model arch · NCSNv2 U-Net variant for score-based modeling. · `ImageGeneration/models/ncsnv2.py`
- [layers*.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/layers.py): building blocks · Reusable layers, normalization, sampling, and utility blocks. · `ImageGeneration/models/layers.py`
- [ema.py](https://github.com/gnobitab/rectifiedflow/blob/main/ImageGeneration/models/ema.py): parameter tracking · Exponential moving average helper for model parameters. · `ImageGeneration/models/ema.py`

### Systems

Performance-critical custom ops and runtime artifacts

- [op/](https://github.com/gnobitab/rectifiedflow/tree/main/ImageGeneration/op): CUDA ops · Fused custom C++/CUDA primitives for model performance. · `ImageGeneration/op`
- **assets**: artifacts · External artifacts such as stats files, generated reflow data, and checkpoints.

## Connections

- main.py → RF configs: loads · Selects workflow and experiment settings from configuration modules.
- main.py → run_lib.py: dispatches · Routes execution into the shared orchestration layer.
- main.py → run_lib_reflow.py: dispatches · Routes reflow-specific workflows to the reflow orchestrator.
- run_lib.py → datasets.py: uses · Builds the standard dataset pipeline for training and evaluation.
- run_lib.py → pytorch_datasets.py: uses · Can bind to PyTorch-native dataset loading paths.
- run_lib.py → losses.py: trains with · Connects configs and models to the training objective.
- run_lib.py → sampling.py: samples with · Uses ODE sampling for generation and evaluation.
- run_lib.py → evaluation.py: evaluates with · Runs metric computation and sample evaluation.
- run_lib.py → likelihood.py: evaluates with · Supports likelihood-oriented evaluation workflows.
- run_lib.py → sde_lib.py: interprets via · Uses the continuous-time flow abstraction during training and sampling.
- run_lib_pytorch.py → ddpm.py: instantiates · Constructs the PyTorch model backbone for rectified flow.
- run_lib_pytorch.py → ncsnpp.py: instantiates · Alternative backbone for score/velocity prediction.
- run_lib_pytorch.py → ncsnv2.py: instantiates · Alternative backbone for score/velocity prediction.
- ddpm.py → layers*.py: builds from · Composes reusable neural network blocks.
- ncsnpp.py → layers*.py: builds from · Composes reusable neural network blocks.
- ncsnv2.py → layers*.py: builds from · Composes reusable neural network blocks.
- layers*.py → op/: accelerated by · Uses fused custom kernels for performance-critical operations.
- run_lib_reflow.py → assets: reads/writes · Consumes and produces reflow trajectory pairs and related artifacts.
- run_lib_reflow.py → sampling.py: generates pairs with · Uses the teacher sampler to create trajectory pairs for distillation.
- run_lib_reflow.py → losses.py: optimizes with · Trains student flows on generated or online reflow pairs.
- evaluation.py → assets: reads · Consumes dataset statistics and stored checkpoints for evaluation.
- sampling.py → assets: writes · Can emit generated samples or trajectory data for later use.
