# eruditionherta/arfm architecture

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

- Interactive diagram: https://gitdiagram.com/eruditionherta/arfm
- Repository: https://github.com/eruditionherta/arfm

## Overview

1. **Repo shape**
   - This is a small PyTorch-based generative modeling project centered on one core library, `arflow`, plus three entry-point scripts: `train.py`, `sample.py`, and `evaluate.py`.
   - The architecture is split cleanly between reusable model/sampling components and task-specific orchestration code.

2. **Core library boundary: `arflow/`**
   - `arflow` contains the implementation of the ARFM method itself.
   - The key subsystems are:
     - `time_field.py` for the spatially heterogeneous time map
     - `model.py` for the SPADE U-Net velocity network
     - `solver.py` for ODE-style sampling
     - `ema.py` for exponential moving average weights
     - `utils.py` for shared helpers
   - This package is the main dependency for all training, inference, and evaluation flows.

3. **Data ingestion layer**
   - `data_loader.py` is the single dataset access boundary for MNIST, CIFAR-10, and CelebA.
   - It abstracts resolution, channel count, labels/attributes, and any dataset-specific preprocessing.
   - The `data/` directory is local storage for downloaded/raw dataset assets; for example, MNIST raw files are checked in here.

4. **Time-field subsystem**
   - `time_field.py` is the architectural novelty of the repo: it converts a scalar ODE time into a per-pixel time map.
   - The map is spatially heterogeneous, with pixels near the image center progressing earlier than pixels near the edges.
   - This module also provides the derivative-based weighting used by the loss, which is important because training is not just standard uniform-time flow matching.

5. **Model subsystem**
   - `model.py` implements the SPADE U-Net backbone that predicts the flow/velocity field.
   - Its conditioning path consumes the spatial time map rather than a single global timestep, allowing the network to represent different temporal states across the image simultaneously.
   - For conditional generation, the model also supports label conditioning and classifier-free guidance behavior during training/inference.

6. **Training data path**
   - `train.py` wires together dataset loading, time-field construction, noise/image mixing, model forward passes, loss computation, and optimizer updates.
   - The training objective is flow-matching-style regression toward the image displacement between noise and data.
   - If enabled, label dropout is used to train classifier-free guidance.
   - Optional EMA tracking runs alongside training so inference can use a smoothed copy of the model parameters.

7. **Sampling / inference path**
   - `sample.py` is the inference entry point.
   - It loads a checkpoint, constructs the time field, and repeatedly applies the solver to move from noise toward an image sample.
   - It can run unconditional sampling, label-conditional sampling, CFG-scaled sampling, and trajectory capture for visualizing the center-out progression.

8. **Solver boundary**
   - `solver.py` is the generation-time integration layer.
   - It turns the learned velocity field into a discrete sampling trajectory, likely with Euler-style steps as described in the README.
   - This is the bridge between the continuous-time formulation and actual image synthesis.

9. **EMA subsystem**
   - `ema.py` maintains an exponential moving average of model parameters during training.
   - This is a separate inference-quality path: the training loop updates both live weights and EMA weights, and sampling can prefer the EMA copy for better sample stability.

10. **Evaluation path**
   - `evaluate.py` is a standalone metrics script, primarily for FID.
   - It reuses the checkpoint loading and sampling stack, then compares generated samples against the target dataset distribution.
   - This keeps evaluation aligned with the exact inference code path rather than using a separate implementation.

11. **End-to-end data flow**
   - Training flow: dataset loader → batch preprocessing → spatial time-field generation → model forward pass → flow-matching loss → optimizer/EMA update.
   - Sampling flow: checkpoint → optional EMA weights → solver loop → generated images / optional trajectory output.
   - Evaluation flow: checkpoint → sampler → generated sample set → FID computation.

12. **Primary architectural distinction**
   - The key design boundary is that the repo does not use a traditional autoregressive decoder or masking pipeline.
   - Instead, autoregressive behavior is induced implicitly by the spatial time field plus SPADE-conditioned U-Net dynamics, with the solver producing images in a center-to-edge progression.

13. **External/runtime dependencies that matter**
   - The project is Python 3.10+ / PyTorch 2.7+ oriented, with CUDA support called out as recommended for training.
   - torchvision-style dataset handling is implied by the supported datasets, and the README indicates metric/plotting tooling for evaluation and visualization.

14. **What to draw in a diagram**
   - Show `train.py`, `sample.py`, and `evaluate.py` as separate entry points feeding into the shared `arflow` core.
   - Put `data_loader.py` on the left as the dataset boundary.
   - Inside `arflow`, show `time_field` and `model` feeding the training loss and the solver.
   - Show `ema` as a parallel weight-tracking path attached to training but consumed by sampling/evaluation.

Main entry points: [`sample.py`](https://github.com/eruditionherta/arfm/blob/main/sample.py) (sample.py), [`train.py`](https://github.com/eruditionherta/arfm/blob/main/train.py) (train.py), [`arflow`](https://github.com/eruditionherta/arfm/tree/main/arflow) (arflow), [`arflow/model.py`](https://github.com/eruditionherta/arfm/blob/main/arflow/model.py) (model.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry points"]
  node_train_py["train.py<br/>trainer<br/>[train.py]"]
  node_sample_py["sample.py<br/>sampler<br/>[sample.py]"]
  node_evaluate_py["evaluate.py<br/>metrics<br/>[evaluate.py]"]
end

subgraph group_core["arflow core"]
  node_arflow_pkg{{"arflow<br/>core package"}}
  node_time_field_py["time_field.py<br/>spatial time map<br/>[time_field.py]"]
  node_model_py["model.py<br/>SPADE U-Net<br/>[model.py]"]
  node_solver_py["solver.py<br/>ODE sampler<br/>[solver.py]"]
  node_ema_py["ema.py<br/>EMA weights<br/>[ema.py]"]
  node_utils_py["utils.py<br/>helpers<br/>[utils.py]"]
end

subgraph group_data["Data"]
  node_data_loader_py["data_loader.py<br/>dataset boundary<br/>[data_loader.py]"]
  node_data_store[("data/<br/>dataset assets")]
end

node_train_py -->|"loads data"| node_data_loader_py
node_train_py -->|"builds time"| node_time_field_py
node_train_py -->|"trains"| node_model_py
node_train_py -.->|"updates"| node_ema_py
node_train_py -.->|"uses"| node_utils_py
node_sample_py -->|"integrates"| node_solver_py
node_sample_py -->|"queries"| node_model_py
node_sample_py -->|"builds time"| node_time_field_py
node_sample_py -.->|"prefers"| node_ema_py
node_sample_py -.->|"uses"| node_utils_py
node_evaluate_py -.->|"reuses"| node_sample_py
node_evaluate_py -.->|"compares to"| node_data_loader_py
node_data_loader_py -->|"reads"| node_data_store
node_arflow_pkg -->|"contains"| node_time_field_py
node_arflow_pkg -->|"contains"| node_model_py
node_arflow_pkg -->|"contains"| node_solver_py
node_arflow_pkg -->|"contains"| node_ema_py
node_arflow_pkg -->|"contains"| node_utils_py
node_time_field_py -->|"conditions"| node_model_py
node_model_py -->|"drives"| node_solver_py

click node_train_py "https://github.com/eruditionherta/arfm/blob/main/train.py"
click node_sample_py "https://github.com/eruditionherta/arfm/blob/main/sample.py"
click node_evaluate_py "https://github.com/eruditionherta/arfm/blob/main/evaluate.py"
click node_data_loader_py "https://github.com/eruditionherta/arfm/blob/main/data_loader.py"
click node_data_store "https://github.com/eruditionherta/arfm/tree/main/data"
click node_arflow_pkg "https://github.com/eruditionherta/arfm/tree/main/arflow"
click node_time_field_py "https://github.com/eruditionherta/arfm/blob/main/arflow/time_field.py"
click node_model_py "https://github.com/eruditionherta/arfm/blob/main/arflow/model.py"
click node_solver_py "https://github.com/eruditionherta/arfm/blob/main/arflow/solver.py"
click node_ema_py "https://github.com/eruditionherta/arfm/blob/main/arflow/ema.py"
click node_utils_py "https://github.com/eruditionherta/arfm/blob/main/arflow/utils.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_train_py,node_sample_py,node_evaluate_py toneBlue
class node_arflow_pkg,node_time_field_py,node_model_py,node_solver_py,node_ema_py,node_utils_py toneAmber
class node_data_loader_py,node_data_store toneMint
```

## Components

### Entry points

Top-level training, sampling, and evaluation scripts

- [train.py](https://github.com/eruditionherta/arfm/blob/main/train.py): trainer · Main training orchestration: data, time field, model, loss, optimization · `train.py`
- [sample.py](https://github.com/eruditionherta/arfm/blob/main/sample.py): sampler · Inference entry point for checkpointed generation and trajectory capture · `sample.py`
- [evaluate.py](https://github.com/eruditionherta/arfm/blob/main/evaluate.py): metrics · Standalone evaluation flow, primarily FID via the sampling stack · `evaluate.py`

### arflow core

Reusable modeling, timing, and sampling components

- [arflow](https://github.com/eruditionherta/arfm/tree/main/arflow): core package · Main library boundary for ARFM modeling and generation · `arflow`
- [time_field.py](https://github.com/eruditionherta/arfm/blob/main/arflow/time_field.py): spatial time map · Converts scalar time into per-pixel heterogeneous time maps and loss weighting · `arflow/time_field.py`
- [model.py](https://github.com/eruditionherta/arfm/blob/main/arflow/model.py): SPADE U-Net · Velocity network conditioned on spatial time maps and labels · `arflow/model.py`
- [solver.py](https://github.com/eruditionherta/arfm/blob/main/arflow/solver.py): ODE sampler · Discrete generation-time integrator from learned velocity to images · `arflow/solver.py`
- [ema.py](https://github.com/eruditionherta/arfm/blob/main/arflow/ema.py): EMA weights · Exponential moving average tracking for stable inference weights · `arflow/ema.py`
- [utils.py](https://github.com/eruditionherta/arfm/blob/main/arflow/utils.py): helpers · Shared library utilities used across core flows · `arflow/utils.py`

### Data

Dataset loading boundary and local dataset storage

- [data_loader.py](https://github.com/eruditionherta/arfm/blob/main/data_loader.py): dataset boundary · Single dataset access layer for MNIST, CIFAR-10, and CelebA · `data_loader.py`
- [data/](https://github.com/eruditionherta/arfm/tree/main/data): dataset assets · Local downloaded and raw dataset files · `data`

## Connections

- train.py → data_loader.py: loads data · Training reads batches through the dataset boundary
- train.py → time_field.py: builds time · Training constructs spatial time maps and loss weights
- train.py → model.py: trains · Model predicts velocity during flow-matching regression
- train.py → ema.py: updates · Training maintains an exponential moving average copy
- train.py → utils.py: uses · Shared helpers support training orchestration
- sample.py → solver.py: integrates · Sampling uses the solver to step from noise to images
- sample.py → model.py: queries · The sampler repeatedly evaluates the velocity network
- sample.py → time_field.py: builds time · Inference constructs the same spatial time mapping
- sample.py → ema.py: prefers · Sampling can load EMA-smoothed parameters
- sample.py → utils.py: uses · Shared helpers support checkpoint and output handling
- evaluate.py → sample.py: reuses · Evaluation follows the exact sampling path
- evaluate.py → data_loader.py: compares to · Metrics are computed against the target dataset distribution
- data_loader.py → data/: reads · Loader accesses local raw dataset assets
- arflow → time_field.py: contains · Core package includes the spatial time-field subsystem
- arflow → model.py: contains · Core package includes the SPADE U-Net backbone
- arflow → solver.py: contains · Core package includes the generation-time integrator
- arflow → ema.py: contains · Core package includes EMA parameter tracking
- arflow → utils.py: contains · Core package includes shared helpers
- time_field.py → model.py: conditions · Spatial time maps are consumed by the network conditioning path
- model.py → solver.py: drives · Solver advances images using predicted velocities
