How to Load the TimesFM 2.5 Model with PyTorch: A Complete Guide

Load the TimesFM 2.5 model by importing TimesFM_2p5_200M_torch from src/timesfm/timesfm_2p5/timesfm_2p5_torch.py and calling from_pretrained() to download the 200M‑parameter checkpoint from Hugging Face, then compile it with a ForecastConfig before running inference.

The google-research/timesfm repository provides a native PyTorch implementation of TimesFM 2.5, a 200‑million‑parameter foundation model for time‑series forecasting. Unlike the JAX implementation, the PyTorch version inherits from PyTorchModelHubMixin, enabling seamless weight loading via the Hugging Face Hub using Safetensors format. This guide demonstrates how to load the TimesFM 2.5 model with PyTorch, configure inference parameters, and execute forecasts on your data.

Importing the PyTorch Wrapper Class

The PyTorch interface resides in src/timesfm/timesfm_2p5/timesfm_2p5_torch.py. The primary class TimesFM_2p5_200M_torch wraps the low‑level transformer implementation and adds Hugging Face Hub integration.

from timesfm.timesfm_2p5.timesfm_2p5_torch import TimesFM_2p5_200M_torch
from timesfm.configs import ForecastConfig
import numpy as np

This wrapper bundles the underlying TimesFM_2p5_200M_torch_module and exposes high‑level methods for checkpoint loading and batched decoding.

Loading Pre‑Trained Weights

Downloading from Hugging Face Hub (Default)

The class inherits from_pretrained() from PyTorchModelHubMixin. Calling this method with no arguments automatically pulls the default google/timesfm-2.5-200m-pytorch repository (~1 GB download) and caches the weights locally.

# Auto-detects CUDA and moves model to GPU if available

model = TimesFM_2p5_200M_torch.from_pretrained()

The loader specifically looks for model.safetensors (referenced internally via TimesFM_2p5_200M_torch.WEIGHTS_FILENAME) and deserializes it into the PyTorch module. The underlying TimesFM_2p5_200M_torch_module.load_checkpoint automatically detects CUDA availability via torch.cuda.is_available() and moves parameters to the GPU without manual device mapping.

Loading a Local Safetensors Checkpoint

If you have pre‑downloaded the weights, point from_pretrained() to the local directory containing model.safetensors:

model = TimesFM_2p5_200M_torch.from_pretrained(model_id="/path/to/local/dir")

The wrapper resolves the path and loads the Safetensors file directly from disk, bypassing the Hugging Face download.

Configuring and Compiling the Model

Before inference, you must compile the model with a ForecastConfig that defines memory constraints and decoding behavior. This step builds an optimized decode function based on your specific context length, horizon, and batch size.

forecast_cfg = ForecastConfig(
    max_context=4096,          # Maximum input time steps the model observes

    max_horizon=128,           # Maximum prediction steps per forward pass

    per_core_batch_size=1,     # Batch size per GPU/CPU core for decoding

    normalize_inputs=True,     # Enable reversible normalization (recommended)

    return_backcast=False,     # Set True to receive backcast outputs

)

model.compile(forecast_cfg)

The compile() method configures internal caches and JIT‑compatible decoding paths according to the TransformerConfig embedded in the forecast configuration. Skipping this step results in uninitialized inference graphs.

Executing Inference

Input Data Format

The forecast() method expects a list of 1‑D NumPy arrays. Each series represents a univariate time series of arbitrary length (up to max_context).

# Example: two synthetic series of 300 points each

series_a = np.sin(np.linspace(0, 20, 300))
series_b = np.cos(np.linspace(0, 20, 300))
inputs = [series_a, series_b]

Running the forecast() Method

Call forecast() with the desired prediction horizon and the prepared inputs. The method returns a tuple containing point forecasts and quantile forecasts.

# Forecast 96 steps ahead

points, quantiles = model.forecast(horizon=96, inputs=inputs)

print("Point forecasts shape:", points.shape)        # (2, 96)

print("Quantile forecasts shape:", quantiles.shape)  # (2, 96, 10)

The output shapes correspond to (batch_size, horizon) for point predictions and (batch_size, horizon, num_quantiles) for the full distribution, where the model outputs 10 quantile levels by default.

Accessing the Underlying PyTorch Module

For fine‑tuning or architectural inspection, access the raw PyTorch module via the model attribute:

torch_mod = model.model
print(torch_mod)          # Displays layer architecture

print(torch_mod.device)   # Confirms 'cuda' or 'cpu'

This exposes the complete transformer stack defined in src/timesfm/torch/transformer.py, allowing you to manipulate parameters, freeze layers, or integrate the model into custom training loops.

Summary

• Import TimesFM_2p5_200M_torch from src/timesfm/timesfm_2p5/timesfm_2p5_torch.py to access the PyTorch interface.
• Call from_pretrained() to load the google/timesfm-2.5-200m-pytorch checkpoint from Hugging Face Hub or a local Safetensors file.
• Compile the model using a ForecastConfig to set context length, horizon, and batch size constraints before forecasting.
• Pass a list of 1‑D NumPy arrays to forecast() to generate point and quantile predictions.
• Access the raw module via model.model for advanced modifications; CUDA detection is automatic.

Frequently Asked Questions

What is the default model repository for TimesFM 2.5 PyTorch?

When calling from_pretrained() without arguments, the class automatically pulls google/timesfm-2.5-200m-pytorch from the Hugging Face Hub. This repository contains the 200M‑parameter checkpoint stored as model.safetensors, totaling approximately 1 GB in size.

Do I need to manually move the model to CUDA?

No. The internal TimesFM_2p5_200M_torch_module.load_checkpoint method automatically checks torch.cuda.is_available() and transfers the model weights to the GPU when detected. You do not need to call .to('cuda') or .cuda() manually on the wrapper instance.

Why must I compile the model before forecasting?

The compile() method instantiates the decoding cache and builds the inference graph based on your ForecastConfig parameters (max_context, max_horizon, batch size). Without compilation, the model lacks the initialized state necessary for batched decoding and will raise runtime errors when forecast() is called.

Can I fine-tune the TimesFM 2.5 PyTorch implementation?

Yes. Access the raw PyTorch module through the model.model attribute to obtain a standard nn.Module object compatible with PyTorch optimizers and loss functions. You can then implement custom training loops using the transformer architecture defined in src/timesfm/torch/transformer.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}