What problem it solves

Time-series forecasting requires models that can forecast univariate and multivariate series across different context lengths. Forecasters also need to incorporate optional covariates and produce quantile forecasts without requiring per-task tuning.

Key features

• Univariate and multivariate forecasting — Forecast individual time series or multiple target variates from NumPy arrays. Forecasting supports variable context lengths and joint forecasts across target channels.

  Source: README

• Dynamic covariate support — Provide optional past-only or past-and-future covariate channels alongside target series. The forecasting interface supports covariates natively without per-task tuning.

  Source: README

• Quantile predictions — Request point predictions together with nine quantiles from the forecasting interface. Outputs expose separate forecast and quantile arrays for each series.

  Source: README

• PyTorch and MLX backends — Run TimesFM 3.0 with PyTorch or use the MLX-native backend on Apple silicon. The MLX interface supports univariate and multivariate prediction with covariates.

  Source: README, timesfm3-usage

• Examples, tests, and fine-tuning support — The repository includes forecasting examples, unit tests, and a fine-tuning example built with HuggingFace Transformers and PEFT LoRA. Archived model code and documentation are also included for earlier versions.

  Source: README, tests, timesfm-forecasting

Quick start

Copied verbatim from the project's README.

# Install TimesFM with PyTorch
pip install timesfm[torch]

# Or, for MLX-native inference on Apple silicon (no PyTorch required)
pip install timesfm[mlx]

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

# Initialize TimesFM 3.0
config = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=32,
    device="cuda"
)
forecaster = TimesFM3Evaluator(config)

# Two univariate series of different lengths (100 and 72 steps)
ts1 = np.linspace(0, 1, 100).astype(np.float32)
ts2 = np.sin(np.linspace(0, 24, 72)).astype(np.float32)

# Generate forecast (point predictions + 9 quantiles: 0.1 to 0.9)
outputs = list(forecaster.predict_batch([ts1, ts2], horizon=12, return_quantiles=True, use_symmetric_averaging=False))

print("Series 1 forecast shape:", outputs[0].forecast.shape)   # (12,)
print("Series 1 quantiles shape:", outputs[0].quantiles.shape) # (12, 9)

print("Series 2 forecast shape:", outputs[1].forecast.shape)   # (12,)
print("Series 2 quantiles shape:", outputs[1].quantiles.shape) # (12, 9)

Who it may suit

This project may suit researchers and developers building univariate or multivariate forecasting workflows, including workflows that require dynamic covariates or quantile outputs.

Topics to discuss

• Which forecasting domains or datasets would you like to evaluate with TimesFM 3.0?

• How can covariate support be improved for real-world forecasting workflows?

• What examples or fine-tuning workflows would be most useful to add next?

Written by ReadmeX AI from the project's README, source and public GitHub data; it may contain mistakes.

Read the original README https://github.com/google-research/timesfm#readme

ReadmeX opened this community for a trending project; it is not run by the project. Maintainers can claim it from the community page.