vilhess commited on
Commit
f9ac6eb
·
verified ·
1 Parent(s): 4c1fa8d

Push model using huggingface_hub.

Browse files
Files changed (3) hide show
  1. README.md +6 -129
  2. config.json +4 -4
  3. model.safetensors +1 -1
README.md CHANGED
@@ -1,133 +1,10 @@
1
  ---
2
  tags:
3
- - timeseries
4
- - forecasting
5
- - zero-shot
6
- - transormers
7
- pipeline_tag: time-series-forecasting
8
  ---
9
- # A tutorial on how to build a Foundation Model for Univariate Time Series Forecasting
10
 
11
- A concise, reproducible recipe for training a transformer-based, patch-to-patch forecasting model for univariate time series. The approach mirrors Large Language Model (LLM) practices (next-token → next-patch) while remaining lightweight compared to a classic LLM and practical.
12
- [Original GitHub](https://github.com/vilhess/PatchFM)
13
-
14
- ## Highlights
15
- - Next-patch prediction objective (autoregressive, causal)
16
- - Patch-based representation of time series (tokens ↔ patches)
17
- - Causal masking self-attention with RoPE (relative positions)
18
- - RevIN (Reversible Instance Normalization) with causal statistics
19
- - SwiGLU feed-forward networks
20
- - Multi-quantile outputs (median + uncertainty bands)
21
- - Efficient rollout with KV caching
22
-
23
- ## Installation
24
- ```bash
25
- git clone https://github.com/vilhess/PatchFM
26
- cd PatchFM
27
- pip install -r requirements.txt
28
- ```
29
-
30
- ## Quick Start
31
-
32
- ```python
33
- import torch
34
- from model import Forecaster
35
- from configs import PatchFMConfig
36
-
37
- # --- Instantiate model ---
38
- config = PatchFMConfig(load_from _hub=True)
39
- model = Forecaster(config)
40
-
41
- # --- Inference ---
42
- forecast_horizon = 64
43
- seq = torch.randn(1, 1024) # (batch, time)
44
- pred_median, pred_quantiles = model(seq, forecast_horizon=forecast_horizon, quantiles=[0.1, 0.5, 0.9]) # (batch, time, quantiles)
45
- ```
46
-
47
- We provide an extended quick start example in [notebooks/tutorial.ipynb](./notebooks/tutorial.ipynb).
48
- If you dont have suitable hardware you can run the the extended quick start example example also in Google Colab:
49
-
50
- <a target="_blank" href="https://colab.research.google.com/drive/17sdf-7luCkv5TaeLj3Z6kIaTDkwkz3VR?usp=share_link">
51
- <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open Quick Start In Colab"/>
52
- </a>
53
-
54
- ## Method (TL;DR)
55
- - Patching: Split a context signal of length $w$ into $P_{num} = w / P_{len}$ patches of length $P_{len}$.
56
- - RevIN: Normalize patches using causal running mean/variance over past patches, and denormalize outputs to the original scale.
57
- - Architecture: Input residual MLP → stacked Transformer blocks (MHA + SwiGLU FFN, pre-norm, residual) → $|\mathcal{Q}|$ output heads mapping back to patch space.
58
- - Positional encoding: Rotary Position Embeddings (RoPE) applied to queries/keys.
59
- - Training: Multi-quantile (pinball) loss across positions, elements, and quantiles $\mathcal{Q}$.
60
- - Inference: Predict next patch; roll out autoregressively with KV caching for long horizons.
61
-
62
- ## Problem Formulation
63
- Given context patches $x_{p_1}, \ldots, x_{p_n}$, predict the next patch $x_{p_{i+1}}$ for each position $i$ using only past patches (causality). The model outputs quantiles $\{\hat{x}_{p_{i+1}}^{(q)}: q \in \mathcal{Q}\}$ with median (q=0.5) as the point forecast.
64
-
65
- ## Loss: Multi-Quantile (Pinball)
66
- For residual $u = x - \hat{x}^{(q)}$:
67
- $$\rho_q(u) = \begin{cases} q\,u, & u \ge 0,\\ (q-1)\,u, & u < 0. \end{cases}$$
68
- Aggregate over positions, patch elements, and quantiles.
69
-
70
- ## Architecture
71
- - Input MLP: $\mathbb{R}^{P_{len}} \to \mathbb{R}^{dim}$ residual 2-layer MLP (ReLU)
72
- - Multi-Head Attention: causal mask, RoPE; queries/keys/values per head
73
- - FFN: SwiGLU (SiLU-gated), pre-norm + residual
74
- - Output heads: |Q| linear maps $\mathbb{R}^{dim} \to \mathbb{R}^{P_{len}}$ (one per quantile)
75
-
76
- ### Model Details
77
- - Patch size: 32
78
- - Max context: 32 patches (1024 steps)
79
- - Forecast horizon: 32 steps per forward pass
80
- - Quantiles $\mathcal{Q}$: {0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9}
81
- - Layers: 6
82
- - Attention heads: 64 (head dim 32)
83
- - Model dim: 2048
84
- - Parameters: ~300M
85
-
86
- ## Inference
87
- - Single step: predict next patch ($P_{len}$ values)
88
- - Long-horizon: append prediction to context and repeat (optionally drop oldest patch to keep window fixed)
89
- - KV caching: reuse cached keys/values for past patches; compute new Q/K/V only for the appended patch
90
-
91
- ## Datasets
92
- - UTSD (Unified Time Series Dataset) [UTSD]: seven domains (Energy, IoT, Nature, Web, Health, Transport, Environment). We start with UTSD-1G (~55M series after preprocessing).
93
- - Artificial: ~1M synthetic series (sinusoidal, linear, polynomial, logarithmic) plus mixtures via TSMixup [Chronos]; Gaussian Process samples via KernelSynth (mixtures of RBF/periodic/linear kernels with swept hyperparameters).
94
-
95
- ## Repository Layout
96
-
97
- - `model/training/` — main PatchFM model class
98
-
99
- - `modules.py` - core modules (Residual Layers, MHA, SwiGLU, RoPE, Transformer Encoder, ...)
100
- - `revin.py` — causal RevIN
101
- - `loss.py` — multi-quantile (pinball) loss
102
- - `trainer.py` — PyTorch Lightning trainer class
103
-
104
- - `model/inference/` — main PatchFM model class for inference with KV caching
105
- - `modules.py` — core modules with caching support
106
- - `forecaster.py` — Forecasting model with KV caching and rollout logic
107
-
108
- - `dataset/` — data loading and preprocessing
109
- - `artificial.py` — synthetic dataset : artificial signals + TSMixup + KernelSynth
110
- - `utsd.py` — Unified Time Series Dataset (UTSD) loading and preprocessing
111
- - `get_data.py` — utility to fetch and preprocess datasets
112
- - `generate_data.py` — utility to generate and save the KernelSynth dataset (long to generate)
113
-
114
- - `configs/` — model and training configurations
115
- - `notebooks/inference` — how to load a trained model and generate forecasts
116
- - `training.py` — training script using PyTorch Lightning
117
-
118
- ## Acknowledgements
119
- We thank the authors of the following repositories for inspiration and code snippets:
120
- - [TiRex](https://github.com/NX-AI/tirex)
121
-
122
- ## Incoming Works
123
-
124
- - [ ] Improve performance: extend training duration, tune schedules, and explore larger effective batch sizes.
125
- - [ ] Data scaling: train on larger corpora (e.g., UTSD-12G) and expand synthetic generators to broaden dynamics and scales.
126
- - [ ] Benchmarking: evaluate on standard SOTA datasets with common metrics (e.g., MAE/MSE and quantile coverage) to compare against baselines.
127
- - [ ] Ablations: gradually increase context length, RevIN (on/off and causal variants).
128
- - [ ] Mixture of Experts: test sparse MoE in FFNs with routing.
129
- - [ ] Implement LoRA for finetuning.
130
-
131
-
132
- ## Citation
133
- If you use this work, please cite the paper ...
 
1
  ---
2
  tags:
3
+ - model_hub_mixin
4
+ - pytorch_model_hub_mixin
 
 
 
5
  ---
 
6
 
7
+ This model has been pushed to the Hub using the [PytorchModelHubMixin](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) integration:
8
+ - Code: [More Information Needed]
9
+ - Paper: [More Information Needed]
10
+ - Docs: [More Information Needed]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
config.json CHANGED
@@ -1,5 +1,5 @@
1
  {
2
- "ckpt_path": "ckpts/huge_v3.pth",
3
  "compile": false,
4
  "d_model": 2048,
5
  "load_from_hub": false,
@@ -9,11 +9,11 @@
9
  "quantiles": [
10
  0.1,
11
  0.2,
12
- 0.30000000000000004,
13
  0.4,
14
  0.5,
15
- 0.6000000000000001,
16
- 0.7000000000000001,
17
  0.8,
18
  0.9
19
  ]
 
1
  {
2
+ "ckpt_path": "ckpts/huge_v4.pth",
3
  "compile": false,
4
  "d_model": 2048,
5
  "load_from_hub": false,
 
9
  "quantiles": [
10
  0.1,
11
  0.2,
12
+ 0.3,
13
  0.4,
14
  0.5,
15
+ 0.6,
16
+ 0.7,
17
  0.8,
18
  0.9
19
  ]
model.safetensors CHANGED
@@ -1,3 +1,3 @@
1
  version https://git-lfs.github.com/spec/v1
2
- oid sha256:4c3a0dfd86ed6ffa4a2078803dff6d007f3115996039d70c4f8e23a9342f7edd
3
  size 1275009880
 
1
  version https://git-lfs.github.com/spec/v1
2
+ oid sha256:9a90e71072ecb82579eb3eaadc88262ecd271057ce555954e4cc1f6a8970b5ba
3
  size 1275009880