# thuml/autoformer architecture

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

- Interactive diagram: https://gitdiagram.com/thuml/autoformer
- Repository: https://github.com/thuml/autoformer

## Overview

The project is a research/engineering repository for long-term time series forecasting. Its primary purpose is to implement and evaluate the Autoformer model – a Transformer variant that uses series decomposition and an auto-correlation mechanism for forecasting. In addition to Autoformer, the repo includes implementations of similarly themed models such as Informer, Transformer, and Reformer, and it provides extensive scripts for running experiments on multiple real-world datasets (e.g., energy, traffic, economics, weather, disease).

##### Main Components
a. Data Processing:
- Directory: data_provider
- Role: Contains routines to load and preprocess time series data (data_factory.py, data_loader.py), ensuring that datasets are pre-processed and structured for experiments.
b. Model Building:
- Directories: models and layers
- Role:
- models: Implements different time series forecasting models (Autoformer, Informer, Reformer, Transformer).
- layers: Provides the foundational layers and building blocks (e.g., AutoCorrelation for the series-wise mechanism, embedding modules, self-attention families) that support the models.
c. Experimentation and Execution:
- Directory: exp
- Role: Houses modules that set up and run model experiments (exp_basic.py, exp_main.py).
d. Script-based Experimentation:
- Directory: scripts (with subdirectories such as ETT_script, ECL_script, etc.)
- Role: Contains shell scripts that drive training experiments for various benchmarks across different domains (traffic, weather, exchange, etc.).
e. Utilities:
- Directory: utils
- Role: Helper functions for metrics, time features, data downloading, masking, and general tools to support other components.
f. Infrastructure and Deployment:
- Files: Dockerfile, Makefile, environment.yml, requirements.txt, run.py
- Role: Provide configuration for containerized execution (Docker), dependency management, reproducibility (Makefile commands), and a unified entry-point for running experiments.

##### Interactions and Relationships
- Data Flow:
- Data is then fed into the experimental workflow in exp/ (or triggered via scripts) which calls run.py to orchestrate model training and evaluation.
- Model Pipeline:
- Within the training/inference flow, models (from the models directory) are assembled using core layers (from layers) that encapsulate essential components such as the auto-correlation mechanism.
- Utilities provide supporting functionalities (e.g., metrics for evaluation, time features extraction) that are used during training and evaluation.
- Deployment:
- A Docker container (defined in Dockerfile), conda environment (environment.yml), and Makefile tasks ensure that the experiment scripts can be reliably executed in different environments.
- Script Execution:
- Multiple bash scripts under scripts/ directories allow the model to be run over different datasets/applications. They initiate the experiment process and ensure appropriate configuration is applied.

##### Architectural Patterns and Design Principles
- Modularity: The separation into data handling, model layers, experiment scripts, and utilities exemplifies a modular design.
- Experimentation-driven Design: The exp and scripts directories indicate a design geared towards conducting and reproducing experiments, reflecting the research focus.
- Container-based Deployment: Dockerfile and Makefile ensure the environment can be reproduced and experiments reliably executed, emphasizing reproducibility and deployment best practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        dp["Data Provider (data_factory, data_loader)"] 
        ut["Utilities (download_data, masking, metrics, timefeatures, tools)"]
    end

    %% Experimentation Layer
    subgraph "Experimentation Layer"
        exp["Experiment Engine (exp_basic, exp_main)"]
    end

    %% Model Building
    subgraph "Model Building"
        mb_models["Models (Autoformer, Informer, Reformer, Transformer)"]
        mb_layers["Layers (AutoCorrelation, Autoformer_EncDec, Embed, SelfAttention_Family, Transformer_EncDec)"]
    end

    %% Script-based Experimentation
    subgraph "Script-based Experimentation"
        scr_ECL["ECL Script"]
        scr_ETT["ETT Script"]
        scr_Exchange["Exchange Script"]
        scr_ILI["ILI Script"]
        scr_Traffic["Traffic Script"]
        scr_Weather["Weather Script"]
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        dep_Dockerfile["Dockerfile"]
        dep_Makefile["Makefile"]
        dep_env["environment.yml"]
        dep_require["requirements.txt"]
        dep_run["run.py"]
    end

    %% Connections between components
    dp -->|"providesData"| exp
    ut -->|"supports"| exp
    exp -->|"trainsUsing"| mb_models
    exp -->|"utilizes"| mb_layers
    scr_ECL -->|"triggers"| dep_run
    scr_ETT -->|"triggers"| dep_run
    scr_Exchange -->|"triggers"| dep_run
    scr_ILI -->|"triggers"| dep_run
    scr_Traffic -->|"triggers"| dep_run
    scr_Weather -->|"triggers"| dep_run
    dep_run -->|"orchestrates"| exp
    dep_Dockerfile -->|"containerizes"| dep_run
    dep_Makefile -->|"builds"| dep_run
    dep_env -->|"configures"| dep_run
    dep_require -->|"installs"| dep_run

    %% Styles
    classDef dataClass fill:#ccf,stroke:#333,stroke-width:2px;
    classDef experimentClass fill:#cfc,stroke:#333,stroke-width:2px;
    classDef modelClass fill:#fcf,stroke:#333,stroke-width:2px;
    classDef scriptClass fill:#ff9,stroke:#333,stroke-width:2px;
    classDef deployClass fill:#ddd,stroke:#333,stroke-width:2px;

    class dp,ut dataClass;
    class exp experimentClass;
    class mb_models,mb_layers modelClass;
    class scr_ECL,scr_ETT,scr_Exchange,scr_ILI,scr_Traffic,scr_Weather scriptClass;
    class dep_Dockerfile,dep_Makefile,dep_env,dep_require,dep_run deployClass;

    %% Click Events
    click dp "https://github.com/thuml/autoformer/blob/main/data_provider/data_factory.py"
    click ut "https://github.com/thuml/autoformer/blob/main/utils/download_data.py"
    click exp "https://github.com/thuml/autoformer/blob/main/exp/exp_basic.py"
    click mb_models "https://github.com/thuml/autoformer/blob/main/models/Autoformer.py"
    click mb_layers "https://github.com/thuml/autoformer/blob/main/layers/AutoCorrelation.py"
    click scr_ECL "https://github.com/thuml/autoformer/tree/main/scripts/ECL_script"
    click scr_ETT "https://github.com/thuml/autoformer/tree/main/scripts/ETT_script"
    click scr_Exchange "https://github.com/thuml/autoformer/tree/main/scripts/Exchange_script"
    click scr_ILI "https://github.com/thuml/autoformer/tree/main/scripts/ILI_script"
    click scr_Traffic "https://github.com/thuml/autoformer/tree/main/scripts/Traffic_script"
    click scr_Weather "https://github.com/thuml/autoformer/tree/main/scripts/Weather_script"
    click dep_Dockerfile "https://github.com/thuml/autoformer/tree/main/Dockerfile"
    click dep_Makefile "https://github.com/thuml/autoformer/tree/main/Makefile"
    click dep_env "https://github.com/thuml/autoformer/blob/main/environment.yml"
    click dep_require "https://github.com/thuml/autoformer/blob/main/requirements.txt"
    click dep_run "https://github.com/thuml/autoformer/blob/main/run.py"
```
