How thuml/openltm works
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.