TimesFM API Reference

Model Classes

timesfm.TimesFM_2p5_200M_torch

The primary model class for TimesFM 2.5 (200M parameters, PyTorch backend).

from_pretrained()

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch",
    cache_dir=None,         # Optional: custom cache directory
    force_download=True,    # Re-download even if cached
)

Returns: Initialized TimesFM_2p5_200M_torch instance (not yet compiled).

compile()

Compiles the model with the given forecast configuration. Must be called before forecast().

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

Raises: Nothing (but forecast() will raise RuntimeError if not compiled).

forecast()

Run inference on one or more time series.

point_forecast, quantile_forecast = model.forecast(
    horizon=24,
    inputs=[array1, array2, ...],
)

Returns: tuple[np.ndarray, np.ndarray]

• point_forecast: shape (batch_size, horizon) — median (0.5 quantile)
• quantile_forecast: shape (batch_size, horizon, 10) — [mean, q10, q20, ..., q90]

Raises: RuntimeError if model is not compiled.

Key behaviors:

• Leading NaN values are stripped automatically
• Internal NaN values are linearly interpolated
• Series longer than max_context are truncated (last max_context points used)
• Series shorter than max_context are padded

forecast_with_covariates()

Run inference with exogenous variables (requires timesfm[xreg]).

point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"temp": [temp_array1, temp_array2]},
    dynamic_categorical_covariates={"dow": [dow_array1, dow_array2]},
    static_categorical_covariates={"region": ["east", "west"]},
    xreg_mode="xreg + timesfm",
)

Note: Dynamic covariates must have length context + horizon for each series.

timesfm.ForecastConfig

Immutable dataclass controlling all forecast behavior.

@dataclasses.dataclass(frozen=True)
class ForecastConfig:
    max_context: int = 0
    max_horizon: int = 0
    normalize_inputs: bool = False
    per_core_batch_size: int = 1
    use_continuous_quantile_head: bool = False
    force_flip_invariance: bool = True
    infer_is_positive: bool = True
    fix_quantile_crossing: bool = False
    return_backcast: bool = False
    quantiles: list[float] = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
    decode_index: int = 5

Parameter Details

max_context (int, default=0)

Maximum number of historical time points to use as context.

• 0: Use the model's maximum supported context (16,384 for v2.5)
• N: Truncate series to last N points
• Best practice: Set to the length of your longest series, or 512–2048 for speed

max_horizon (int, default=0)

Maximum forecast horizon.

• 0: Use the model's maximum
• N: Forecasts up to N steps (can still call forecast(horizon=M) where M ≤ N)
• Best practice: Set to your expected maximum forecast length

normalize_inputs (bool, default=False)

Whether to z-normalize each series before feeding to the model.

• True (RECOMMENDED): Normalizes each series to zero mean, unit variance
• False: Raw values are passed directly
• When False is OK: Only if your series are already normalized or very close to scale 1.0

per_core_batch_size (int, default=1)

Number of series processed per device in each batch.

• Increase for throughput, decrease if OOM
• See references/system_requirements.md for recommended values by hardware

use_continuous_quantile_head (bool, default=False)

Use the 30M-parameter continuous quantile head for better interval calibration.

• True (RECOMMENDED): More accurate prediction intervals, especially for longer horizons
• False: Uses fixed quantile buckets (faster but less accurate intervals)

force_flip_invariance (bool, default=True)

Ensures the model satisfies f(-x) = -f(x).

• True (RECOMMENDED): Mathematical consistency — forecasts are invariant to sign flip
• False: Slightly faster but may produce asymmetric forecasts

infer_is_positive (bool, default=True)

Automatically detect if all input values are positive and clamp forecasts ≥ 0.

• True: Safe for sales, demand, counts, prices, volumes
• False: Required for temperature, returns, PnL, any series that can be negative

fix_quantile_crossing (bool, default=False)

Post-process quantiles to ensure monotonicity (q10 ≤ q20 ≤ ... ≤ q90).

• True (RECOMMENDED): Guarantees well-ordered quantiles
• False: Slightly faster but quantiles may occasionally cross

return_backcast (bool, default=False)

Return the model's reconstruction of the input (backcast) in addition to forecast.

• True: Used for covariate workflows and diagnostics
• False: Only return forecast

Available Model Checkpoints

Output Shape Reference

Where B = batch size (number of input series), H = forecast horizon.

Error Handling