# lucidrains/rectified-flow-pytorch architecture

> Architecture diagram of the GitHub repository lucidrains/rectified-flow-pytorch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucidrains/rectified-flow-pytorch
- Repository: https://github.com/lucidrains/rectified-flow-pytorch

## Overview

##### Project type and purpose
- From the file tree and README, this is an open-source Python library (“rectified-flow-pytorch”) implementing rectified flow generative modeling and follow-ups in PyTorch.
- It provides core modules (RectifiedFlow, Reflow, mean/nano flows), training scripts, a Trainer abstraction, and packaging/test workflows.

##### File structure
- Top-level:
- .github/workflows → CI/CD for testing and publishing
- pyproject.toml → packaging and dependencies
- README.md, LICENSE → documentation and licensing
- train_*.py → example/CLI training scripts
- images/ → sample output images
- rectified_flow_pytorch/ → core library modules
- tests/ → automated test suite
- Core library modules follow a logical separation:
- mean_flow.py, nano_flow.py → specific flow implementations
- rectified_flow.py → base RectifiedFlow class
- reflow.py → Reflow extension logic
- __init__.py → public API
- There’s also ImageDataset and a Trainer class (referenced in README but not shown in file tree, likely under rectified_flow_pytorch).

##### README for additional insights
- Describes key classes: Unet (model), RectifiedFlow, Reflow, ImageDataset, Trainer
- Shows usage patterns:
- loss calculation and backward pass
- sampling workflow
- integration with accelerate through Trainer
- Mentions external dependencies: PyTorch, accelerate

a. Main components
- Core library package (“rectified_flow_pytorch”)
– Model sub-component: Unet
– Flow engines: RectifiedFlow, Reflow
– Utilities: ImageDataset, Trainer
- Training scripts (train_oxford.py, train_mean_flow.py, train_nano_rf.py)
- External systems
– PyTorch
– accelerate (for distributed/multi-GPU training)
– Filesystem (datasets, results_folder)
– GitHub Actions (CI/CD)
b. Relationships and interactions
- Training scripts import core library → instantiate Unet → wrap in RectifiedFlow → feed data via ImageDataset → train via Trainer → write outputs to disk
- Core library calls PyTorch APIs (torch.nn, torch.optim, autograd)
- Trainer optionally invokes accelerate launch for distributed execution
- tests/test_flow.py import core classes → validate forward/backward and sample operations
- GitHub workflows run tests and publish package to PyPI
c. Architectural patterns/design principles
- Modular design: separation of model definition (Unet), flow logic (RectifiedFlow, Reflow), data handling (ImageDataset), training orchestration (Trainer)
- Dependency inversion: core library depends only on PyTorch and standard Python; user scripts orchestrate high-level tasks
- Extensibility: new flow types or datasets can be plugged in by extending base classes
d. Key technologies/frameworks/libraries
- Python 3.x, PyTorch
- accelerate (from Hugging Face) for distributed training
- pytest for tests
- GitHub Actions for CI/CD
- pyproject.toml/poetry or setuptools for packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Package
    subgraph "Core Library (rectified_flow_pytorch)"
        direction TB
        CoreLib["rectified_flow_pytorch/"]:::package
        Unet["Unet Model"]:::core
        RectifiedFlow["RectifiedFlow"]:::core
        Reflow["Reflow"]:::core
        MeanFlow["MeanFlow"]:::core
        NanoFlow["NanoFlow"]:::core
        ImageDataset["ImageDataset"]:::core
        Trainer["Trainer"]:::core
    end

    %% Training Scripts
    subgraph "Training Scripts"
        direction TB
        TMF["train_mean_flow.py"]:::script
        TNRF["train_nano_rf.py"]:::script
        TOX["train_oxford.py"]:::script
    end

    %% External Dependencies & Systems
    PyTorch["PyTorch"]:::external
    Accelerate["Accelerate"]:::external
    Filesystem["Filesystem (datasets/results)"]:::data
    GitHubActions["GitHub Actions"]:::external
    PyPI["PyPI"]:::external

    %% Tests & CI/CD
    TestFlow["tests/test_flow.py"]:::test
    TestCI["Test Workflow"]:::ci
    PublishCI["Publish Workflow"]:::ci

    %% Project Config & Docs
    PyProject["pyproject.toml"]:::config
    Readme["README.md"]:::doc
    License["LICENSE"]:::doc
    Images["images/"]:::data

    %% Relationships
    TMF -->|imports| Unet
    TMF -->|wraps in| RectifiedFlow
    TMF -->|uses| ImageDataset
    TMF -->|orchestrates via| Trainer

    TNRF -->|imports| Unet
    TNRF -->|wraps in| NanoFlow
    TNRF -->|uses| ImageDataset
    TNRF -->|orchestrates via| Trainer

    TOX -->|imports| Unet
    TOX -->|wraps in| RectifiedFlow
    TOX -->|uses| ImageDataset
    TOX -->|orchestrates via| Trainer

    RectifiedFlow -->|calls| PyTorch
    Reflow -->|calls| PyTorch
    MeanFlow -->|calls| PyTorch
    NanoFlow -->|calls| PyTorch
    Trainer -->|invokes| Accelerate
    Trainer -->|writes to| Filesystem

    GitHubActions -->|triggers| TestCI
    GitHubActions -->|triggers| PublishCI
    TestCI -->|runs| TestFlow
    TestFlow -->|validates| RectifiedFlow
    TestFlow -->|validates| Reflow
    TestCI -->|reads| PyProject
    PublishCI -->|publishes to| PyPI

    %% Documentation & Config
    GitHubActions -->|reads| Readme
    GitHubActions -->|reads| License
    TMF -.->|outputs to| Images
    TOX -.->|outputs to| Images

    %% Click Events
    click CoreLib "https://github.com/lucidrains/rectified-flow-pytorch/tree/main/rectified_flow_pytorch/"
    click RectifiedFlow "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/rectified_flow_pytorch/rectified_flow.py"
    click Reflow "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/rectified_flow_pytorch/reflow.py"
    click MeanFlow "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/rectified_flow_pytorch/mean_flow.py"
    click NanoFlow "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/rectified_flow_pytorch/nano_flow.py"
    click TMF "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/train_mean_flow.py"
    click TNRF "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/train_nano_rf.py"
    click TOX "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/train_oxford.py"
    click TestFlow "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/tests/test_flow.py"
    click TestCI "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/.github/workflows/test.yml"
    click PublishCI "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/.github/workflows/python-publish.yml"
    click PyProject "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/pyproject.toml"
    click Readme "https://github.com/lucidrains/rectified-flow-pytorch/blob/main/README.md"
    click License "https://github.com/lucidrains/rectified-flow-pytorch/tree/main/LICENSE"
    click Images "https://github.com/lucidrains/rectified-flow-pytorch/tree/main/images/"

    %% Styles
    classDef package fill:#E8F1F2,stroke:#0B6E99,color:#0B6E99,stroke-width:2px
    classDef core fill:#FFF3C4,stroke:#D4A017,color:#8C6500
    classDef script fill:#E2F0CB,stroke:#6B8E23,color:#4F772D
    classDef external fill:#FDE2E4,stroke:#D1495B,color:#9E2A2B
    classDef data fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef test fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef ci fill:#E8DAEF,stroke:#8E44AD,color:#4A235A
    classDef config fill:#D5F5E3,stroke:#27AE60,color:#186A3B
    classDef doc fill:#FADBD8,stroke:#C0392B,color:#78281F
```
