diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..925b79d --- /dev/null +++ b/README.en.md @@ -0,0 +1,143 @@ +# TimesFM + +TimesFM (Time Series Foundation Model) is a pretrained time-series foundation +model developed by Google Research for time-series forecasting. + +* Paper: + [A decoder-only foundation model for time-series forecasting](https://arxiv.org/abs/2310.10688), + ICML 2024. +* All checkpoints: + [TimesFM Hugging Face Collection](https://huggingface.co/collections/google/timesfm-release-66e4be5fdb56e960c1e482a6). +* [Google Research blog](https://research.google/blog/a-decoder-only-foundation-model-for-time-series-forecasting/). +* TimesFM in Google 1P Products: + * [BigQuery ML](https://cloud.google.com/bigquery/docs/timesfm-model): Enterprise level SQL queries for scalability and reliability. + * [Google Sheets](https://workspaceupdates.googleblog.com/2026/02/forecast-data-in-connected-sheets-BigQueryML-TimesFM.html): For your daily spreadsheet. + * [Vertex Model Garden](https://pantheon.corp.google.com/vertex-ai/publishers/google/model-garden/timesfm): Dockerized endpoint for agentic calling. + +This open version is not an officially supported Google product. + +**Latest Model Version:** TimesFM 2.5 + +**Archived Model Versions:** + +- 1.0 and 2.0: relevant code archived in the sub directory `v1`. You can `pip + install timesfm==1.3.0` to install an older version of this package to load + them. +## Update - July 2, 2026 + +Updated PyPI to `timesfm=2.0.2`. See [Install](https://github.com/google-research/timesfm#from-pypi). + +## Update - Apr. 9, 2026 + +Added fine-tuning example using HuggingFace Transformers + PEFT (LoRA) — see +[`timesfm-forecasting/examples/finetuning/`](timesfm-forecasting/examples/finetuning/). +Also added unit tests (`tests/`) and incorporated several community fixes. + +Shoutout to [@kashif](https://github.com/kashif) and [@darkpowerxo](https://github.com/darkpowerxo). + +## Update - Mar. 19, 2026 + +Huge shoutout to [@borealBytes](https://github.com/borealBytes) for adding the support for [AGENTS](https://github.com/google-research/timesfm/blob/master/AGENTS.md)! TimesFM [SKILL.md](https://github.com/google-research/timesfm/tree/master/timesfm-forecasting) is out. + +## Update - Oct. 29, 2025 + +Added back the covariate support through XReg for TimesFM 2.5. + + +## Update - Sept. 15, 2025 + +TimesFM 2.5 is out! + +Comparing to TimesFM 2.0, this new 2.5 model: + +- uses 200M parameters, down from 500M. +- supports up to 16k context length, up from 2048. +- supports continuous quantile forecast up to 1k horizon via an optional 30M + quantile head. +- gets rid of the `frequency` indicator. +- has a couple of new forecasting flags. + +Since the Sept. 2025 launch, the following improvements have been completed: + +1. ✅ Flax version of the model for faster inference. +2. ✅ Covariate support via XReg (see Oct. 2025 update). +3. ✅ Documentation, examples, and agent skill (see `timesfm-forecasting/`). +4. ✅ Fine-tuning example with LoRA via HuggingFace Transformers + PEFT (see `timesfm-forecasting/examples/finetuning/`). +5. ✅ Unit tests for core layers, configs, and utilities (see `tests/`). + +### Install + +#### From `PyPI` + +```shell +# Install the package with torch +pip install timesfm[torch] +# Or with Flax +pip install timesfm[flax] +# And when XReg is needed +pip install timesfm[xreg] +``` + +#### Local Install + +1. Clone the repository: + ```shell + git clone https://github.com/google-research/timesfm.git + cd timesfm + ``` + +2. Create a virtual environment and install dependencies using `uv`: + ```shell + # Create a virtual environment + uv venv + + # Activate the environment + source .venv/bin/activate + + # Install the package in editable mode with torch + uv pip install -e .[torch] + # Or with flax + uv pip install -e .[flax] + # And when XReg is needed + uv pip install -e .[xreg] + ``` + +3. [Optional] Install your preferred `torch` / `jax` backend based on your OS and accelerators +(CPU, GPU, TPU or Apple Silicon).: + +- [Install PyTorch](https://pytorch.org/get-started/locally/). +- [Install Jax](https://docs.jax.dev/en/latest/installation.html#installation) + for Flax. + +### Code Example + +```python +import torch +import numpy as np +import timesfm + +torch.set_float32_matmul_precision("high") + +model = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch") + +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, + ) +) +point_forecast, quantile_forecast = model.forecast( + horizon=12, + inputs=[ + np.linspace(0, 1, 100), + np.sin(np.linspace(0, 20, 67)), + ], # Two dummy inputs +) +point_forecast.shape # (2, 12) +quantile_forecast.shape # (2, 12, 10): mean, then 10th to 90th quantiles. +```