# thuml/openltm architecture

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

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

## Overview

##### Project Type and Purpose
- OpenLTM is an open-source research pipeline for developing and evaluating large time-series models (LTM).
- It provides data ingestion, model implementations, experiment definitions, and shell scripts to launch pre-training, supervised training, and adaptation.

##### File Structure Analysis
- Top-level scripts:
- run.py – general CLI entrypoint for experiments.
- scripts/ – bash scripts organized by `pretrain/`, `supervised/`, `adaptation/`, each with domain- and model-specific job launchers.
- Core Python modules:
- data_provider/ – factories and loaders that fetch/prepare time-series data.
- layers/ – low-level building blocks (attention, embeddings, MLPs, Transformers).
- models/ – full LTM architectures (Timer, Timer-XL, Moirai, GPT4TS, etc.).
- exp/ – experiment definitions (`exp_basic.py`, `exp_forecast.py`) that tie data, model, training loop, and evaluation.
- utils/ – shared utilities for masking, metrics, logging.
- Configuration:
- requirements.txt – Python dependencies.
- LICENSE, README.md – project metadata.

##### Key Insights from README
- Emphasis on large-scale pre-training and fine-tuning workflows.
- Extensibility: add new models under `models/`, register them in `Exp_Basic.model_dict`, and add shell scripts in `scripts/`.
- External dependencies: Hugging Face datasets (UTSD, ERA5), external model repos for evaluation.

##### Main Components
A. Data Sources (external)
- Raw datasets: UTSD, ERA5, TSLib datasets → placed under `./dataset`.
B. Data Provider Module
- `data_provider/data_factory.py`, `data_provider/data_loader.py`
- Responsibility: transform raw files into training/evaluation tensors.
C. Model Library
- `layers/` (attention, transformer layers) → low-level.
- `models/` (Timer, Timer-XL, Moirai, GPT4TS, etc.) → high-level architectures built atop layers.
D. Experiment Engine
- `exp/exp_basic.py`, `exp/exp_forecast.py`
- Orchestrates:
- Instantiating data provider → DataLoader
- Selecting model from `model_dict`
- Training loop (forward, backward, metrics)
- Saving checkpoints, metrics, figures.
E. CLI & Orchestration
- run.py: parses arguments (experiment type, model, dataset, hyperparams) → invokes Experiment Engine.
- scripts/…/*.sh: job-specific wrappers that call run.py with proper flags and environment.
F. Utilities & Logging
- `utils/metrics.py`, `utils/tools.py`, `utils/masking.py` provide helper functions for evaluation and data processing.

##### Component Interactions
- run.py sits at the top of Experiment Engine; scripts invoke run.py.
- Utilities are horizontally shared by Data Provider, Experiment Engine, and Models.

##### Architectural Patterns & Design Principles
- Modular layering:
- Separation of concerns between data ingestion, model definitions, and experiment orchestration.
- Plugin-style extensibility:
- New models under `models/` and registration in `exp_basic.py`.
- New scripts in scripts/ to launch experiments without code changes.
- Reusability:
- Shared `layers/` across all model implementations.
- Common `utils/` for metrics and data masking.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data
    External_Data["External Data Sources\n(UTSD, ERA5, TSLib)"]:::data

    %% Users & Operations
    subgraph "Users & Ops"
        direction TB
        Scripts["Orchestration Scripts"]:::orchestration
        RunCLI["run.py"]:::orchestration
    end

    %% Codebase
    subgraph "Codebase"
        direction TB

        subgraph "Data Provider Module" 
            direction TB
            DataFactory["data_factory.py"]:::data
            DataLoader["data_loader.py"]:::data
        end

        subgraph "Model Library - Layers"
            direction TB
            Attn_Bias["Attn_Bias.py"]:::ml
            Attn_Projection["Attn_Projection.py"]:::ml
            Embed["Embed.py"]:::ml
            MLP["MLP.py"]:::ml
            SelfAttention["SelfAttention_Family.py"]:::ml
            Transformer["Transformer_EncDec.py"]:::ml
        end

        subgraph "Model Library - Architectures"
            direction TB
            Timer["timer.py"]:::ml
            Timer_XL["timer_xl.py"]:::ml
            Moirai["moirai.py"]:::ml
            GPT4TS["gpt4ts.py"]:::ml
            AutoTimes["autotimes.py"]:::ml
            Moment["moment.py"]:::ml
            TimeLLM["time_llm.py"]:::ml
            TTM["ttm.py"]:::ml
        end

        subgraph "Experiment Engine"
            direction TB
            ExpBasic["exp_basic.py"]:::orchestration
            ExpForecast["exp_forecast.py"]:::orchestration
        end

        subgraph "Utilities & Logging"
            direction TB
            Masking["masking.py"]:::utils
            Metrics["metrics.py"]:::utils
            Tools["tools.py"]:::utils
        end
    end

    %% Outputs
    subgraph "Outputs"
        direction TB
        Checkpoints["Checkpoints"]:::external
        Logs["Logs & Metrics"]:::external
        Figures["Figures"]:::external
    end

    %% Flows
    Scripts -->|launch| RunCLI
    RunCLI -->|invoke| ExpBasic
    RunCLI -->|invoke| ExpForecast
    ExpBasic -->|load data| DataFactory
    ExpForecast -->|load data| DataLoader
    DataFactory -->|prepare tensors| ExpBasic
    DataLoader -->|prepare tensors| ExpForecast
    ExpBasic -->|select model| Timer
    ExpBasic -->|select model| Timer_XL
    ExpBasic -->|select model| Moirai
    ExpBasic -->|select model| GPT4TS
    ExpBasic -->|select model| AutoTimes
    ExpBasic -->|select model| Moment
    ExpBasic -->|select model| TimeLLM
    ExpBasic -->|select model| TTM
    ExpBasic -->|forward/backward| Attn_Bias
    ExpBasic -->|forward/backward| Attn_Projection
    ExpBasic -->|forward/backward| Embed
    ExpBasic -->|forward/backward| MLP
    ExpBasic -->|forward/backward| SelfAttention
    ExpBasic -->|forward/backward| Transformer
    ExpForecast -->|training loop| Metrics
    ExpForecast -->|training loop| Tools
    ExpForecast -->|training loop| Masking
    ExpBasic -->|save| Checkpoints
    ExpBasic -->|log| Logs
    ExpBasic -->|plot| Figures

    %% Shared Utilities
    DataFactory ---|uses| Masking
    DataLoader ---|uses| Metrics
    Timer ---|depends on| Embed
    Moirai ---|depends on| SelfAttention
    GPT4TS ---|depends on| Transformer

    %% Click Events
    click DataFactory "https://github.com/thuml/openltm/blob/main/data_provider/data_factory.py"
    click DataLoader "https://github.com/thuml/openltm/blob/main/data_provider/data_loader.py"
    click Attn_Bias "https://github.com/thuml/openltm/blob/main/layers/Attn_Bias.py"
    click Attn_Projection "https://github.com/thuml/openltm/blob/main/layers/Attn_Projection.py"
    click Embed "https://github.com/thuml/openltm/blob/main/layers/Embed.py"
    click MLP "https://github.com/thuml/openltm/blob/main/layers/MLP.py"
    click SelfAttention "https://github.com/thuml/openltm/blob/main/layers/SelfAttention_Family.py"
    click Transformer "https://github.com/thuml/openltm/blob/main/layers/Transformer_EncDec.py"
    click Timer "https://github.com/thuml/openltm/blob/main/models/timer.py"
    click Timer_XL "https://github.com/thuml/openltm/blob/main/models/timer_xl.py"
    click Moirai "https://github.com/thuml/openltm/blob/main/models/moirai.py"
    click GPT4TS "https://github.com/thuml/openltm/blob/main/models/gpt4ts.py"
    click AutoTimes "https://github.com/thuml/openltm/blob/main/models/autotimes.py"
    click Moment "https://github.com/thuml/openltm/blob/main/models/moment.py"
    click TimeLLM "https://github.com/thuml/openltm/blob/main/models/time_llm.py"
    click TTM "https://github.com/thuml/openltm/blob/main/models/ttm.py"
    click ExpBasic "https://github.com/thuml/openltm/blob/main/exp/exp_basic.py"
    click ExpForecast "https://github.com/thuml/openltm/blob/main/exp/exp_forecast.py"
    click RunCLI "https://github.com/thuml/openltm/blob/main/run.py"
    click Scripts "https://github.com/thuml/openltm/tree/main/scripts/pretrain/"
    click Scripts "https://github.com/thuml/openltm/tree/main/scripts/supervised/forecast/"
    click Scripts "https://github.com/thuml/openltm/tree/main/scripts/supervised/rolling_forecast/"
    click Scripts "https://github.com/thuml/openltm/tree/main/scripts/adaptation/few_shot/"
    click Scripts "https://github.com/thuml/openltm/tree/main/scripts/adaptation/full_shot/"
    click Masking "https://github.com/thuml/openltm/blob/main/utils/masking.py"
    click Metrics "https://github.com/thuml/openltm/blob/main/utils/metrics.py"
    click Tools "https://github.com/thuml/openltm/blob/main/utils/tools.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#000;
    classDef ml fill:#ccffcc,stroke:#000;
    classDef orchestration fill:#ffe5cc,stroke:#000;
    classDef utils fill:#e0e0e0,stroke:#000;
    classDef external fill:#f2f2f2,stroke:#000;
```
