# Recommended ForecastConfig for TimesFM: Production-Ready Settings Explained

> Discover the recommended ForecastConfig for TimesFM production settings. Learn how these parameters optimize memory, speed, and accuracy for your forecasting needs.

- Repository: [Google Research/timesfm](https://github.com/google-research/timesfm)
- Tags: best-practices
- Published: 2026-04-02

---

**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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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:

```python
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:

```python
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`](https://github.com/google-research/timesfm/blob/main/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:

```bash
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`](https://github.com/google-research/timesfm/blob/main/src/timesfm/configs.py)** and consumed by the **`compile()`** method in **[`src/timesfm/timesfm_2p5/timesfm_2p5_torch.py`](https://github.com/google-research/timesfm/blob/main/src/timesfm/timesfm_2p5/timesfm_2p5_torch.py)**.
- Reference the **[`timesfm-forecasting/scripts/forecast_csv.py`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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.