How google-research/timesfm works
TimesFM is a pretrained time-series forecasting library with current 3.0 PyTorch and MLX inference, a 2.5 implementation, and archived 1.x/2.x code. The principal workflow configures or loads a forecaster, accepts time-series context (and, for 3.0, covariates), then returns forecasts and optional quantiles. The graph preserves documented model capabilities and major implementation branches; unsampled internals are represented only where the README or source index supports the component or relationship.
Main entry points: torch/model.py Torch model · finetune.py Fine-tuning · mlx/model.py MLX model · timesfm_2p5_base.py 2.5 model definition
Components 23
TimesFM 3.0
- Forecast API
src/timesfm3/torch/timesfm3_forecaster.py - Torch model
src/timesfm3/torch/model.py - Transformer stack
src/timesfm3/torch/transformer.py - CPM RevIN
src/timesfm3/torch/cpm_revin_refine.py - Torch configuration
src/timesfm3/torch/configs.py - MLX forecast API
src/timesfm3/mlx/timesfm3_forecaster.py - MLX model
src/timesfm3/mlx/model.py - MLX transformer
src/timesfm3/mlx/transformer.py - MLX configuration
src/timesfm3/mlx/configs.py
TimesFM 2.5
- 2.5 model definition
src/timesfm/timesfm_2p5/timesfm_2p5_base.py - 2.5 Torch backend
src/timesfm/timesfm_2p5/timesfm_2p5_torch.py - 2.5 Flax backend
src/timesfm/timesfm_2p5/timesfm_2p5_flax.py - 2.5 configuration
src/timesfm/configs.py - 2.5 XReg support
src/timesfm/utils/xreg_lib.py
Archived Models
- Legacy model API
v1/src/timesfm/timesfm_base.py - Legacy data loader
v1/src/timesfm/data_loader.py - Legacy JAX decoder
v1/src/timesfm/patched_decoder.py - Legacy Torch decoder
v1/src/timesfm/pytorch_patched_decoder.py - Legacy XReg
v1/src/timesfm/xreg_lib.py
Adaptation
- Fine-tuning
v1/peft/finetune.py - LoRA layers
v1/src/adapter/lora_layers.py - DoRA layers
v1/src/adapter/dora_layers.py
Other components
- Forecast caller
Connections 19
- Forecast caller → Forecast API: requests forecast
- Forecast API → Torch model: invokes model
src/timesfm3/torch/timesfm3_forecaster.py - Torch model → Transformer stack: uses stack
src/timesfm3/torch/model.py - Torch model → CPM RevIN: uses refinement
src/timesfm3/torch/model.py - Torch model → Torch configuration: reads config
src/timesfm3/torch/model.py - Forecast caller → MLX forecast API: requests forecast
- MLX forecast API → MLX model: uses model
src/timesfm3/mlx/timesfm3_forecaster.py - MLX model → MLX transformer: uses stack
src/timesfm3/mlx/model.py - MLX model → MLX configuration: reads config
src/timesfm3/mlx/model.py - 2.5 Torch backend → 2.5 model definition: uses definition
src/timesfm/timesfm_2p5/timesfm_2p5_torch.py - 2.5 Flax backend → 2.5 model definition: uses definition
src/timesfm/timesfm_2p5/timesfm_2p5_flax.py - 2.5 Torch backend → 2.5 configuration: reads config
src/timesfm/timesfm_2p5/timesfm_2p5_torch.py - 2.5 Flax backend → 2.5 configuration: reads config
src/timesfm/timesfm_2p5/timesfm_2p5_flax.py - 2.5 model definition → 2.5 XReg support: uses covariates
src/timesfm/timesfm_2p5/timesfm_2p5_base.py - Legacy model API → Legacy XReg: uses XReg
v1/src/timesfm/timesfm_base.py - Legacy data loader → Fine-tuning: supplies training data
v1/peft/finetune.py - Fine-tuning → Legacy JAX decoder: uses decoder
v1/peft/finetune.py - Fine-tuning → LoRA layers: uses adapters
v1/peft/finetune.py - Fine-tuning → DoRA layers: optional adapter