Skip to content

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.

Python

feat(timesfm3/mlx): cap context at global_context before decode

rachittshahf40faab9c7cd
diff --git a/src/timesfm3/mlx/timesfm3_forecaster.py b/src/timesfm3/mlx/timesfm3_forecaster.py
index bbfb5b7..f88038f 100644
--- a/src/timesfm3/mlx/timesfm3_forecaster.py
+++ b/src/timesfm3/mlx/timesfm3_forecaster.py
@@ -42,6 +42,10 @@ class _ModelConfig:
median_quantile_index: int = 4
# mx.compile the forward pass (fuses kernels, cuts dispatch overhead).
compile: bool = True
+ # Longest context fed to the model. Contexts beyond this are truncated to
+ # their most recent `max_context_length` points before decode, matching the
+ # torch backend's `global_context` cap (`_MAX_CONTEXT_LENGTH`).
+ max_context_length: int = 15360
# Hugging Face download options.
cache_dir: str | None = None
revision: str | None = None
@@ -101,6 +105,11 @@ class TimesFM3Forecaster:
def context_length(self) -> int:
return self.model.config.input_patch_len
+ @property
+ def global_context(self) -> int:
+ """Longest context the model runs on; longer inputs are truncated to it."""
+ return self.config.max_context_length
+
def predict(
self,
context: np.ndarray,
@@ -176,7 +185,8 @@ class TimesFM3Forecaster:
# Group same-length contexts so each group runs through a single batched forward pass.
# decode() is per-series independent (running stats, RevIN, detrending are per-batch-row), so
# batching is numerically identical to looping but scales throughput near-linearly.
- arrs = [np.asarray(c, dtype=np.float32).reshape(-1) for c in contexts]
+ cap = self.config.max_context_length
+ arrs = [np.asarray(c, dtype=np.float32).reshape(-1)[-cap:] for c in contexts]
groups: dict[int, list[int]] = {}
for i, a in enumerate(arrs):
groups.setdefault(a.shape[0], []).append(i)
diff --git a/src/timesfm3/mlx/timesfm3_forecaster_test.py b/src/timesfm3/mlx/timesfm3_forecaster_test.py
index 193ebee..b5c1fe1 100644
--- a/src/timesfm3/mlx/timesfm3_forecaster_test.py
+++ b/src/timesfm3/mlx/timesfm3_forecaster_test.py
@@ -102,6 +102,27 @@ class TimesFM3MlxRealWeightsTest(unittest.TestCase):
self.assertEqual(np.asarray(out.forecast).shape, (64,))
self.assertEqual(np.asarray(out.quantiles).shape, (64, 9))
+ def test_global_context_default_matches_torch(self):
+ # The MLX backend must expose the same 15,360-step context cap as the torch
+ # backend so the two are backend-equivalent for very long contexts.
+ forecaster = timesfm3_forecaster.TimesFM3Forecaster.from_pretrained(_CHECKPOINT)
+ self.assertEqual(forecaster.global_context, 15360)
+
+ def test_context_truncated_to_global_context(self):
+ # A context longer than the cap must be truncated to its last
+ # `global_context` points before decode, so forecasting the full series
+ # equals forecasting only that tail.
+ cap = 256
+ forecaster = timesfm3_forecaster.TimesFM3Forecaster.from_pretrained(
+ _CHECKPOINT, max_context_length=cap
+ )
+ self.assertEqual(forecaster.global_context, cap)
+ ctx = np.sin(np.linspace(0, 60, 512)).astype(np.float32)
+ out_full = forecaster.predict(ctx, horizon=32, return_quantiles=True)
+ out_tail = forecaster.predict(ctx[-cap:], horizon=32, return_quantiles=True)
+ np.testing.assert_allclose(out_full.forecast, out_tail.forecast, atol=1e-5)
+ np.testing.assert_allclose(out_full.quantiles, out_tail.quantiles, atol=1e-5)
+
@unittest.skipUnless(_torch_available(), "requires torch as the parity oracle")
def test_parity_with_torch_backend(self):
from ..torch import timesfm3_forecaster as torch_forecaster