How eruditionherta/arfm works
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 sample.py · train.py train.py · arflow arflow · model.py model.py
Components 11
Entry points
Top-level training, sampling, and evaluation scripts
- train.py · Main training orchestration: data, time field, model, loss, optimization
train.py - sample.py · Inference entry point for checkpointed generation and trajectory capture
sample.py - evaluate.py · Standalone evaluation flow, primarily FID via the sampling stack
evaluate.py
arflow core
Reusable modeling, timing, and sampling components
- arflow · Main library boundary for ARFM modeling and generation
arflow - time_field.py · Converts scalar time into per-pixel heterogeneous time maps and loss weighting
arflow/time_field.py - model.py · Velocity network conditioned on spatial time maps and labels
arflow/model.py - solver.py · Discrete generation-time integrator from learned velocity to images
arflow/solver.py - ema.py · Exponential moving average tracking for stable inference weights
arflow/ema.py - utils.py · Shared library utilities used across core flows
arflow/utils.py
Data
Dataset loading boundary and local dataset storage
- data_loader.py · Single dataset access layer for MNIST, CIFAR-10, and CelebA
data_loader.py - data/ · Local downloaded and raw dataset files
data
Connections 20
- 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