{
"cells": [
{
"cell_type": "markdown",
"id": "da55dd6c",
"metadata": {},
"source": [
"# Foundation Models\n",
"In this notebook, we will show how to use time series foundation models in Darts. If you are new to Darts, please check out the [Quickstart Guide](https://unit8co.github.io/darts/quickstart/00-quickstart.html) before proceeding.\n",
"\n",
"Foundation models are pre-trained on large-scale time series data and can be used for **zero-shot forecasting** -- that means they can produce forecasts **without any training or fine-tuning**. Darts currently supports the following foundation models:\n",
"\n",
"- [Chronos2Model](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.chronos2_model.html) -- Amazon's Chronos-2 ([paper](https://arxiv.org/abs/2510.15821), [blog](https://www.amazon.science/blog/introducing-chronos-2-from-univariate-to-universal-forecasting))\n",
"- [TimesFM2p5Model](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.timesfm2p5_model.html) -- Google's TimesFM 2.5 ([paper](https://arxiv.org/abs/2310.10688))\n",
"- [TiRexModel](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.tirex_model.html) -- NX-AI's TiRex ([paper](https://arxiv.org/abs/2505.23719))\n",
"\n",
"All models support the following:\n",
"\n",
"- uni- and multivariate time series\n",
"- single and multiple time series\n",
"- deterministic and probabilistic forecasting\n",
"- zero-shot forecasting\n",
"- fine-tuning\n",
"\n",
"They differ in covariate support and installation requirements:\n",
"\n",
"| Model | Past Covariates | Future Covariates | Static Covariates | Extra Dependency |\n",
"|-------------------|:---------------:|:-----------------:|:-----------------:|-------------------|\n",
"| `Chronos2Model` | ✅ | ✅ | 🔴 | - |\n",
"| `TimesFM2p5Model` | 🔴 | 🔴 | 🔴 | - |\n",
"| `TiRexModel` | 🔴 | 🔴 | 🔴 | `tirex-ts>=1.4.0` |\n",
"\n",
"This notebook demonstrates common usage patterns with `Chronos2Model`. Other foundation models can be used in exactly the same way -- the only differences are covariate support (see table above) and installation requirements."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "310fa52a",
"metadata": {},
"outputs": [],
"source": [
"# fix python path if working locally\n",
"from utils import fix_pythonpath_if_working_locally\n",
"\n",
"fix_pythonpath_if_working_locally()\n",
"%matplotlib inline"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "bfa59f65",
"metadata": {},
"outputs": [],
"source": [
"%load_ext autoreload\n",
"%autoreload 2\n",
"%matplotlib inline"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8368a3a294566cff",
"metadata": {},
"outputs": [],
"source": [
"# use darts plotting style\n",
"from darts import set_option\n",
"\n",
"set_option(\"plotting.use_darts_style\", True)"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "d510b54b",
"metadata": {},
"outputs": [],
"source": [
"import warnings\n",
"\n",
"import numpy as np\n",
"\n",
"from darts.datasets import ElectricityConsumptionZurichDataset\n",
"from darts.metrics import mae, mic, miw\n",
"from darts.models import Chronos2Model\n",
"\n",
"# Other foundation models can be imported in the same way:\n",
"# from darts.models import TimesFM2p5Model\n",
"# from darts.models import TiRexModel # requires: pip install tirex-ts>=1.4.0\n",
"from darts.utils.likelihood_models import QuantileRegression\n",
"\n",
"warnings.filterwarnings(\"ignore\")\n",
"import logging\n",
"\n",
"logging.disable(logging.CRITICAL)"
]
},
{
"cell_type": "markdown",
"id": "6b82a07a",
"metadata": {},
"source": [
"## Data Preparation"
]
},
{
"cell_type": "markdown",
"id": "70d7e392",
"metadata": {},
"source": [
"Here, we will use the [Electricity Consumption Zurich Dataset](https://unit8co.github.io/darts/generated_api/darts.datasets.datasets.html#darts.datasets.datasets.ElectricityConsumptionZurichDataset), which records the electricity consumption of households & SMEs (`\"Value_NE5\"` column) and business & services (`\"Value_NE7\"`) in Zurich, Switzerland, along with weather covariates such as temperature (`\"T [°C]\"`) and humidity (`\"Hr [%Hr]\"`).\n",
"Values are recorded every 15 minutes between January 2015 and August 2022.\n",
"\n",
"\n",
"\n",
"Train-Test Split\n",
"\n",
"Even though foundation models are pre-trained already, we still need to split the data into training and test sets. That is because they follow the Darts unified interface and will require calling the `fit()` method before forecasting. However, no training or fine-tuning will be performed during the `fit()` call.\n",
"\n",
"\n",
"\n",
"\n",
"\n",
"Data Scaling\n",
"\n",
"Unlike other deep learning models in Darts, foundation models do not require data scaling since they have their own internal data normalization mechanism. Therefore, we will skip the scaling step in this notebook.\n",
"\n",
""
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2f87bcc5",
"metadata": {},
"outputs": [],
"source": [
"# convert to float32\n",
"data = ElectricityConsumptionZurichDataset().load().astype(np.float32)\n",
"# extract households energy consumption\n",
"ts_energy = data[\"Value_NE5\"]\n",
"# extract temperature, solar irradiation and rain duration\n",
"ts_weather = data[[\"T [°C]\", \"StrGlo [W/m2]\", \"RainDur [min]\"]]\n",
"# split into train and validation sets by last 7 days\n",
"train_energy, val_energy = ts_energy.split_before(len(ts_energy) - 7 * 24 * 4)"
]
},
{
"cell_type": "markdown",
"id": "a3887f37",
"metadata": {},
"source": [
"Let's quickly visualize the last 7 days of the electricity consumption data."
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "3b43a60a",
"metadata": {},
"outputs": [
{
"data": {
"image/png": "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++3iueeeE48++mge1xWFDiHBQaFDCCEFpGrVqs42LDq33HKLc/vxxx+X/+m6IiQcKHQIIcTDNPNly5aJDRs2OLd3794t9uzZkyB0VKYWIcR/KHSI9aAIGwqPffbZZ2HvCokputCZOHFiwmP/+c9/xBNPPOHU2UHbiEMOOSTwfSQkrrAFBLGKLl26iF9++UXGQChQSn/btm0JfYcICRK9ncM333yT5/Gbb77Z2a5Vq1Zg+0UIoUWHRIBChQqJY489lt2PSWiULFlSHHDAAXnuP+WUU/Lcd+qppwa0V4QQQKFjKX///bdMX61QoYIoWrSoNJ3fd9998rHPP/9cNG3aVBx00EGiRIkSomfPnmLnzp0JVpE2bdqIhx56SMYK4DnXXnutjCNQPP3006JixYriwAMPlIN4+/btncdQvl5lkuir1AEDBji34UoaMWKEuOCCC8TBBx8sKleuLD788EOxbt060bhxY2m6P/vss8X69eud1+D1eB+8DitkvK5jx46yEJt6/IUXXhBTp06V74+/efPmJXVdzZ8/X9SpU0ceG3xHdEj+66+/nMexDzfccIO47bbbRPHixaVQ0vefkGzYf//981Q7LlOmjOjdu3ee55522mkB7hkhhELHUu644w4xdOhQ0b9/f1mN9ZVXXpGCZNeuXaJ58+biyCOPFJ988omYNGmSmD17trjuuusSXj937lwpMvAf4mHs2LHyT5Wyhwj497//LdauXStmzpwpGjZsmPU+Dho0SFx55ZVSgGBle9lll8m6Ith3VS7fvV8QQohxmDZtmvxcBHaqyQKZLBA+LVq0kK4q/EEsuUEab8uWLcUZZ5whli9fLp555hkxevRoMXjw4ITn4XtDcH388cdSNOL7vvvuu1l/T0LccTrgrLPOSigmCGB1rF+/fsB7Rki8oa3fBQam7777LvDPhUUBk38m/P777+Kxxx4TTz75pLjqqqvkfeXLl5cD6MiRI2Xw44svvugEPOJ5F154oRg2bJgUQwBCCPfD7QMR0qpVK1nsrEePHjI9Fq+FNeawww6TK9NczO1du3aVwgSgpggGfggzCDFVRRbP0VH7rtJvEcSJfXv44YflMYKVClks2E4FrFGwCOH7wdKD74eMF+zDPffcI1ffoEaNGuLee++V27Be4fk4Bueee27W35UQt9CBCIeFslixYuK3336T98GyyD5X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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"val_energy.plot(label=\"consumption\");"
]
},
{
"cell_type": "markdown",
"id": "46c1c07f",
"metadata": {},
"source": [
"## Model Creation"
]
},
{
"cell_type": "markdown",
"id": "30825d45",
"metadata": {},
"source": [
"In the following, we demonstrate model creation using `Chronos2Model`. The same pattern applies to other foundation models -- simply swap the model class.\n",
"\n",
"All foundation models support two types of forecasting outputs:\n",
"- **Deterministic** forecasts (**default**): single point estimates for each future time step.\n",
"- **Probabilistic** forecasts: multiple samples for each future time step, which can be used to estimate prediction intervals. To enable probabilistic forecasting, set `likelihood=QuantileRegression([...])` when creating the model. The list of quantiles used here must be a subset of the model's supported quantiles. For Chronos-2: `[0.01, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 0.99]`.\n",
"\n",
"\n",
"\n",
"Lookback and Forward Windows\n",
"\n",
"Under the hood, foundation models are no different from other [Torch Forecasting Models (TFMs)](https://unit8co.github.io/darts/userguide/torch_forecasting_models.html) in Darts and most hyperparameters from TFMs can be applied here as well. In particular, you can control the length of the lookback window and the forward window using the `input_chunk_length` and `output_chunk_length` parameters, respectively.\n",
"\n",
"- `input_chunk_length`: the number of time steps of history the model takes as input when making a forecast. Maximum is **8192** for Chronos-2.\n",
"- `output_chunk_length`: the number of time steps the model outputs in one forward pass. If the forecast horizon is longer than this value, the model consumes its own previous predictions to produce further forecasts. This is known as the autoregressive forecasting. Maximum is **1024** for Chronos-2.\n",
"\n",
"\n",
"\n",
"See the [Torch Forecasting Models User Guide](https://unit8co.github.io/darts/userguide/torch_forecasting_models.html) for more details.\n",
"\n",
"\n",
"\n",
"\n",
"\n",
"Model Downloading and Caching\n",
"\n",
"When creating a foundation model instance for the first time, the pre-trained model checkpoint will be automatically downloaded from Hugging Face Hub and cached locally. Subsequent usage will NOT re-download the files but use the cached version instead.\n",
"\n",
"If you would like to download or load the model checkpoint to a custom directory, set `local_dir` argument when creating the model. For example:\n",
"\n",
"```python\n",
"model = Chronos2Model(\n",
" input_chunk_length=168,\n",
" output_chunk_length=24,\n",
" local_dir=\"path/to/your/directory\"\n",
")\n",
"```\n",
"\n",
"\n",
"\n",
"\n",
"\n",
"Using Smaller or Synthetic Variants (Chronos-2)\n",
"\n",
"Two variants of Chronos-2 are available on HuggingFace Hub:\n",
"- [autogluon/chronos-2-small](https://huggingface.co/autogluon/chronos-2-small) : a smaller 28M parameter Chronos-2 model.\n",
"- [autogluon/chronos-2-synth](https://huggingface.co/autogluon/chronos-2-synth) : a 120M parameter Chronos-2 model trained on synthetic data only.\n",
"\n",
"To use either of those variants, specify the `hub_model_name` parameter to the desired model ID. For example, to use the synthetic data variant:\n",
"\n",
"```python\n",
"model = Chronos2Model(\n",
" input_chunk_length=168,\n",
" output_chunk_length=24,\n",
" hub_model_name=\"autogluon/chronos-2-small\",\n",
" hub_model_revision=None, # e.g., branch, tag, or commit ID\n",
")\n",
"```\n",
"\n",
""
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "045aa20c",
"metadata": {},
"outputs": [],
"source": [
"# use last 30 days of data to predict next 7 days\n",
"model = Chronos2Model(\n",
" input_chunk_length=30 * 24 * 4,\n",
" output_chunk_length=7 * 24 * 4,\n",
")"
]
},
{
"cell_type": "markdown",
"id": "a6607bf5",
"metadata": {},
"source": [
"## Model Training\n",
"Here, we will call the `fit()` method to \"train\" the model on the training set. Note that no actual training or fine-tuning will be performed since foundation models are already pre-trained."
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "a447aec7",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"Chronos2Model(output_chunk_shift=0, likelihood=None, hub_model_name=amazon/chronos-2, hub_model_revision=None, local_dir=None, input_chunk_length=2880, output_chunk_length=672)"
]
},
"execution_count": null,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"model.fit(\n",
" series=train_energy,\n",
" verbose=True,\n",
")"
]
},
{
"cell_type": "markdown",
"id": "ea528f34",
"metadata": {},
"source": [
"## Forecasting\n",
"We now perform a one-shot forecast for the next 7 days. We then compare the forecast against the actual values from the validation set."
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "b076cafe",
"metadata": {},
"outputs": [
{
"data": {
"application/vnd.jupyter.widget-view+json": {
"model_id": "32756a350f8942ee884acebddebbfdf3",
"version_major": 2,
"version_minor": 0
},
"text/plain": [
"Predicting: | | 0/? [00:00"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"pred = model.predict(\n",
" n=7 * 24 * 4,\n",
" series=train_energy,\n",
")\n",
"val_energy.plot(label=\"actual\")\n",
"pred.plot(label=\"forecast\");"
]
},
{
"cell_type": "markdown",
"id": "c0a0144c",
"metadata": {},
"source": [
"You can see that the model is able to produce qualitatively accurate forecasts without any training or fine-tuning! Let's evaluate the forecast accuracy using the [Mean Absolute Error (MAE)](https://unit8co.github.io/darts/generated_api/darts.metrics.metrics.html#darts.metrics.metrics.mae) metric."
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "c4e7e695",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"MAE on validation set: 653.57\n"
]
}
],
"source": [
"mae_val = mae(val_energy, pred)\n",
"print(f\"MAE on validation set: {mae_val:.2f}\")"
]
},
{
"cell_type": "markdown",
"id": "379b094e",
"metadata": {},
"source": [
"## Model Fine Tuning\n",
"\n",
"Fine-tuning can be enabled via the `enable_finetuning` model creation parameter. You can find detailed examples in our [fine-tuning examples](https://unit8co.github.io/darts/examples/27-Torch-and-Foundation-Model-Fine-Tuning-examples.html).\n"
]
},
{
"cell_type": "markdown",
"id": "d511f0d0",
"metadata": {},
"source": [
"## Forecasting with Covariates\n",
"\n",
"
\n",
"\n",
" This section only applies to foundation models that support covariates (such as `Chronos2Model`).\n",
"\n",
"
\n",
"\n",
"Recall that Chronos-2 supports forecasting with covariates (exogenous variables). Since no training is required, we do not worry about hyperparameter tuning for covariates. Forecasting with covariates is as simple as passing the covariate series to the `fit()` and `predict()` methods!\n",
"\n",
"We use weather variables as future covariates to help forecast the electricity consumption. We then compare the forecast (with and without covariates) against the actual values from the validation set.\n",
"\n",
"
\n",
" The weather variables here are actual measurements from a weather station and not forecasts (not actual future covariates). The results shown here for demonstration purposes only. In practice, you should supply weather forecasts as future covariates to get realistic results.\n",
"
"
]
},
{
"cell_type": "code",
"execution_count": 10,
"id": "addc0b08",
"metadata": {},
"outputs": [
{
"data": {
"application/vnd.jupyter.widget-view+json": {
"model_id": "407106836a2146c28fe8d7f7544cffd2",
"version_major": 2,
"version_minor": 0
},
"text/plain": [
"Predicting: | | 0/? [00:00"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"model = Chronos2Model(\n",
" input_chunk_length=30 * 24 * 4,\n",
" output_chunk_length=7 * 24 * 4,\n",
")\n",
"model.fit(\n",
" series=train_energy,\n",
" future_covariates=ts_weather,\n",
" verbose=True,\n",
")\n",
"pred_cov = model.predict(\n",
" n=7 * 24 * 4,\n",
" series=train_energy,\n",
" future_covariates=ts_weather,\n",
")\n",
"val_energy.plot(label=\"actual\")\n",
"pred_cov.plot(label=\"forecast with covariates\")\n",
"pred.plot(label=\"forecast without covariates\");"
]
},
{
"cell_type": "markdown",
"id": "5e3d38ca",
"metadata": {},
"source": [
"With future covariates such as weather, we see that the forecast accuracy has improved on the 7-day horizon! Covariate support from Chronos-2 can be very useful when exogenous variables have a strong influence on the target series."
]
},
{
"cell_type": "code",
"execution_count": 11,
"id": "c8fe6715",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"MAE on validation set with covariates: 466.05\n"
]
}
],
"source": [
"mae_cov = mae(val_energy, pred_cov)\n",
"print(f\"MAE on validation set with covariates: {mae_cov:.2f}\")"
]
},
{
"cell_type": "markdown",
"id": "9591d946",
"metadata": {},
"source": [
"## Probabilistic Forecasting\n",
"All foundation models support probabilistic forecasting. Here, we show how to perform probabilistic forecasting using [QuantileRegression](https://unit8co.github.io/darts/generated_api/darts.utils.likelihood_models.torch.html#darts.utils.likelihood_models.torch.QuantileRegression) likelihood. The quantiles passed to `QuantileRegression` must be a subset of the model's pre-trained quantiles (see \"Model Creation\" section above for Chronos-2).\n",
"\n",
"Because sampling with large foundation models can be computationally expensive, we here call `predict()` with `predict_likelihood_parameters=True` to obtain quantile estimates directly without sampling. However, if the forecast horizon is longer than `output_chunk_length` (i.e., auto-regressive forecasting is required), you must call `predict()` with a large enough `num_samples` value (e.g., 1000) to generate probabilistic forecasts via Monte Carlo sampling."
]
},
{
"cell_type": "code",
"execution_count": 12,
"id": "14a424fc",
"metadata": {},
"outputs": [
{
"data": {
"application/vnd.jupyter.widget-view+json": {
"model_id": "fff6dd69ddea481097232ea71176c65e",
"version_major": 2,
"version_minor": 0
},
"text/plain": [
"Predicting: | | 0/? [00:00"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"model = Chronos2Model(\n",
" input_chunk_length=30 * 24 * 4,\n",
" output_chunk_length=7 * 24 * 4,\n",
" likelihood=QuantileRegression(quantiles=[0.1, 0.5, 0.9]),\n",
")\n",
"model.fit(\n",
" series=train_energy,\n",
" future_covariates=ts_weather,\n",
" verbose=True,\n",
")\n",
"pred_prob = model.predict(\n",
" n=7 * 24 * 4,\n",
" series=train_energy,\n",
" future_covariates=ts_weather,\n",
" predict_likelihood_parameters=True,\n",
")\n",
"val_energy.plot(label=\"actual\")\n",
"pred_prob.plot(label=\"forecast\");"
]
},
{
"cell_type": "markdown",
"id": "a570c81c",
"metadata": {},
"source": [
"For probabilistic forecasts, we can evaluate the forecast quality by computing the [Mean Interval Coverage (MIC)](https://unit8co.github.io/darts/generated_api/darts.metrics.metrics.html#darts.metrics.metrics.mic) (the share of actuals inside the prediction intervals) and [Mean Interval Width (MIW)](https://unit8co.github.io/darts/generated_api/darts.metrics.metrics.html#darts.metrics.metrics.miw) (the width of the prediction intervals) metrics to evaluate the quality of the prediction intervals.\n",
"\n",
"For MIC, we expect a value close to the nominal coverage of the prediction intervals (i.e., 80% for the (0.1, 0.9) interval). For MIW, lower values indicate narrower prediction intervals and thus better forecast quality when MIC is satisfactory."
]
},
{
"cell_type": "code",
"execution_count": 13,
"id": "70e28256",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"MIC on validation set with covariates: 82.74%\n",
"MIW on validation set with covariates: 1719.57\n"
]
}
],
"source": [
"mic_prob = mic(val_energy, pred_prob, q_interval=(0.1, 0.9))\n",
"miw_prob = miw(val_energy, pred_prob, q_interval=(0.1, 0.9))\n",
"print(f\"MIC on validation set with covariates: {mic_prob:.2%}\")\n",
"print(f\"MIW on validation set with covariates: {miw_prob:.2f}\")"
]
},
{
"cell_type": "markdown",
"id": "d8f08fb4",
"metadata": {},
"source": [
"## Final Remarks\n",
"Just like other Torch Forecasting Models in Darts, foundation models support historical forecasting (`historical_forecasts()`), backtesting (`backtest()`), residual computation (`residuals()`), custom PyTorch Lightning arguments (`pl_trainer_kwargs`), and more. Check out the following resources to learn more about those topics:\n",
"- [Torch Forecasting Models User Guide](https://unit8co.github.io/darts/userguide/torch_forecasting_models.html)\n",
"- [Fine Tuning Examples](https://unit8co.github.io/darts/examples/27-Torch-and-Foundation-Model-Fine-Tuning-examples.html)\n",
"- [Using Torch Models with GPUs and TPUs](https://unit8co.github.io/darts/userguide/gpu_and_tpu_usage.html)\n",
"- [Backtesting: simulate historical forecasting](https://unit8co.github.io/darts/quickstart/00-quickstart.html#Backtesting:-simulate-historical-forecasting)\n",
"- [Chronos2Model API](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.chronos2_model.html)\n",
"- [TimesFM2p5Model API](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.timesfm2p5_model.html)\n",
"- [TiRexModel API](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.tirex_model.html)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c6b18c34",
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "darts",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.13.12"
}
},
"nbformat": 4,
"nbformat_minor": 5
}