Recommended ForecastConfig for TimesFM: Production-Ready Settings Explained

The recommended ForecastConfig for TimesFM sets max_context=1024, max_horizon=256, normalize_inputs=True, use_continuous_quantile_head=True, force_flip_invariance=True, infer_is_positive=True, and fix_quantile_crossing=True to balance memory efficiency, inference speed, and forecast accuracy.

The ForecastConfig dataclass in google-research/timesfm controls how the compiled decoder processes input time series and generates predictions. While the library ships with conservative defaults where most features are disabled, the official examples and production scripts use a specific configuration optimized for real-world forecasting. These settings are implemented in timesfm-forecasting/scripts/forecast_csv.py and represent the configuration referenced throughout the TimesFM 2.5 release documentation.

Understanding the ForecastConfig Dataclass

In src/timesfm/configs.py, ForecastConfig is defined as an immutable dataclass that governs inference behavior. The configuration is consumed by the compile() method in src/timesfm/timesfm_2p5/timesfm_2p5_torch.py (for the PyTorch backend) before executing forecasts.

The dataclass is re-exported at the top level via src/timesfm/__init__.py, making it accessible as timesfm.ForecastConfig after importing the library.

Recommended ForecastConfig Values

The following parameters constitute the production-ready configuration used throughout the official TimesFM codebase. These values strike a balance between memory usage, computational efficiency, and prediction quality.

• max_context=1024: Maximum length of the input context that the compiled decoder will accept. Shorter series are zero-padded, while longer series are truncated to this length.

• max_horizon=256: Maximum number of future steps the compiled decoder will forecast in a single pass. For horizons exceeding this value, the model uses iterative forecasting.

• normalize_inputs=True: Scales each input series to roughly zero-mean and unit-variance, improving numerical stability when dealing with very large or tiny values.

• use_continuous_quantile_head=True: Enables a continuous quantile head that produces smooth prediction intervals and prevents quantile collapsing.

• force_flip_invariance=True: Guarantees that scaling the input by a negative factor also flips the forecast, extending the model's invariance beyond the default assumption that the scaling factor satisfies a ≥ 0.

• infer_is_positive=True: Enforces non-negativity of the output when the input series contains only non-negative values, preventing predictions below zero for metrics like sales or population counts.

• fix_quantile_crossing=True: Post-processes quantile predictions to ensure they remain properly ordered, preventing scenarios where the 90th percentile prediction falls below the 10th percentile.

• per_core_batch_size=32: Batch size per device core used during compiled batched inference. This value is typically auto-detected from system pre-flight checks, with 32 serving as the standard default.

• return_backcast=False: Optional parameter controlling whether the model returns a back-cast (reconstruction of the input window); left disabled to reduce memory overhead.

Implementing the Recommended Configuration

Compiling the Model with Recommended Settings

To apply the recommended configuration using the TimesFM 2.5 PyTorch backend, instantiate ForecastConfig with the parameters above and pass it to the compile() method:

import timesfm

# Load the 200M parameter TimesFM-2.5 checkpoint

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch"
)

# Compile with recommended ForecastConfig

model.compile(
    timesfm.ForecastConfig(
        max_context=1024,
        max_horizon=256,
        normalize_inputs=True,
        use_continuous_quantile_head=True,
        force_flip_invariance=True,
        infer_is_positive=True,
        fix_quantile_crossing=True,
        per_core_batch_size=32,
    )
)

Forecasting Multiple Time Series

After compiling with the recommended configuration, forecast multiple series simultaneously by providing a list of NumPy arrays. The following example demonstrates forecasting 24 steps ahead for sales and revenue columns:

import numpy as np
import pandas as pd

# Assume df is a pandas DataFrame with numeric columns

value_columns = ["sales", "revenue"]
inputs = [df[col].dropna().values.astype(np.float32) for col in value_columns]

# Forecast 24 steps ahead

point, quantiles = model.forecast(horizon=24, inputs=inputs)

# Convert to structured output

forecasts = {
    col: {
        "point": point[i].tolist(),
        "median": quantiles[i, :, 5].tolist(),
        "lower_90": quantiles[i, :, 1].tolist(),
        "upper_90": quantiles[i, :, 9].tolist(),
    }
    for i, col in enumerate(value_columns)
}

Using the CLI Script

The bundled forecast_csv.py script automatically applies the recommended configuration. Running the following executes a system pre-flight check to detect the optimal per_core_batch_size and compiles the model with the exact settings shown above:

python timesfm-forecasting/scripts/forecast_csv.py data.csv \
    --horizon 48 \
    --date-col date \
    --value-cols sales,revenue \
    --output forecasts.json \
    --format json

Summary

• The recommended ForecastConfig for TimesFM uses max_context=1024 and max_horizon=256 to balance memory constraints with modeling capacity.
• Enable normalize_inputs=True, use_continuous_quantile_head=True, force_flip_invariance=True, infer_is_positive=True, and fix_quantile_crossing=True for production-quality forecasts with valid uncertainty intervals.
• The configuration is defined in src/timesfm/configs.py and consumed by the compile() method in src/timesfm/timesfm_2p5/timesfm_2p5_torch.py.
• Reference the timesfm-forecasting/scripts/forecast_csv.py script for the complete implementation of these settings in end-to-end pipelines.

Frequently Asked Questions

What is the default max_context for TimesFM?

The recommended default is 1024, representing the maximum number of historical timesteps the compiled decoder processes. This value is implemented in the official examples as the standard context window, with shorter series being zero-padded and longer series truncated to fit this length.

Should I enable normalize_inputs for small datasets?

Yes, normalize_inputs=True is recommended regardless of dataset size. This setting scales each series to zero-mean and unit-variance, which improves numerical stability and prevents gradient issues when values are extremely large or small. The normalization is applied per-series, so it benefits both small and large datasets.

How does fix_quantile_crossing improve forecasts?

fix_quantile_crossing=True ensures that predicted quantiles maintain proper ordering (e.g., the 10th percentile is always less than the 90th percentile). Without this post-processing step, the model might predict overlapping or inverted intervals, producing logically impossible prediction intervals where the optimistic scenario shows lower values than the pessimistic one.

Can I override per_core_batch_size manually?

Yes, while per_core_batch_size is typically auto-detected through system pre-flight checks in forecast_csv.py, you can manually set it in the ForecastConfig initialization. The default value of 32 works well for most hardware configurations, but you may increase it for larger GPUs or decrease it if encountering out-of-memory errors during batched inference.

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