README.md

---
license: apache-2.0
library_name: granite-tsfm
pipeline_tag: time-series-forecasting
base_model: ibm-granite/granite-timeseries-ttm-r2
tags:
  - time-series
  - forecasting
  - volatility
  - quantitative-finance
  - tinytimemixer
  - granite-tsfm
  - foundation-models
  - arxiv:2401.03955
  - arxiv:2602.19732
  - arxiv:2607.05291
model-index:
  - name: VolaTTM
    results:
      - task:
          type: time-series-forecasting
          name: Realized volatility forecasting
        dataset:
          name: VOLARE realized-variance archives
          type: external
        metrics:
          - type: rmse
            name: Macro RMSE at 1 session
            value: 0.085053
          - type: qlike
            name: Macro QLIKE at 1 session
            value: 0.214835
          - type: rmse
            name: Macro RMSE at 5 sessions
            value: 0.099955
          - type: qlike
            name: Macro QLIKE at 5 sessions
            value: 0.310544
          - type: rmse
            name: Macro RMSE at 22 sessions
            value: 0.102618
          - type: qlike
            name: Macro QLIKE at 22 sessions
            value: 0.346820
---

# VolaTTM

![VolaTTM](volattm-hero.png)

VolaTTM is a compact time series foundation model adapted for cross-asset
realized-volatility forecasting. It is a single fine-tuned IBM Granite Tiny Time
Mixer R2.1 model. It is not an ensemble and does not use a mixture-of-experts
architecture.

Resources: [source and audit](https://github.com/Aurelien7877/volattm) and
[public research article](https://huggingface.co/spaces/AurelPx/volattm-article).

## Model description

| Property | Value |
|---|---|
| Base model | [`ibm-granite/granite-timeseries-ttm-r2`](https://huggingface.co/ibm-granite/granite-timeseries-ttm-r2) |
| Base branch selected during training | `512-48-ft-l1-r2.1` |
| Parameters | approximately 805,000 |
| Input context | 512 observed trading sessions |
| Output used | first 22 forecast steps |
| Reported horizons | 1, 5, and 22 sessions |
| Target channel | log 5-minute realized variance |
| Input channels | 12 |
| Evaluation period | 2025-01-01 to 2026-06-30 |

The model enables TTM's forecast-channel-mixing decoder and predicts the target
channel from the twelve-channel end-of-day context.

## Data

Fine-tuning used official realized-variance archives from
[VOLARE](https://volare.unime.it/), downloaded on 2026-07-13. The files contain
158,887 daily observations for 40 equities, 5 foreign-exchange rates, and 5
futures through 2026-06-30. The prediction target is `rv5`, realized variance
computed from 5-minute returns.

The VOLARE data are not included in this model repository. Raw archives,
processed tables, row-level predictions, and data caches are intentionally
excluded. Users must obtain the archives from VOLARE and follow the provider's
usage terms. The data construction is described by
[Cipollini et al.](https://arxiv.org/abs/2602.19732).

The twelve input channels, in order, are:

```text
log_rv5
log_rv5_ss
log_rk
log_bv5
jump_share
downside_share
log_rq5
intraday_return
overnight_return
log_range
log_volume
log_trades
```

All channels are observable after the forecast-origin session closes. This is
an end-of-day model and should not be interpreted as an intraday nowcaster.

## Training

Eligible training targets end before 2024-01-01. Calendar year 2024 is used for
early stopping and seed selection. The final checkpoint is seed 17 at epoch 3.
The 2025 to June 2026 period is used only for evaluation of the released run.

The objective is a weighted combination of Smooth L1 loss and QLIKE in
log-variance space over the 22-step path. Training uses AdamW, OneCycle
scheduling, gradient clipping, mixed precision, asset-balanced sampling, and
three random seeds. The TTM configuration retains internal standard scaling.

## Evaluation results

HAR-RV and Log-HAR are direct horizon models re-estimated at every forecast
origin on a rolling 1,000-session window. Scores are macro averages across 50
assets. MAE and RMSE are measured on annualized volatility. QLIKE is measured on
variance. Lower values are better.

| Horizon | Model | MAE | RMSE | QLIKE |
|---:|---|---:|---:|---:|
| 1 | HAR-RV | 0.05164 | 0.08592 | 0.22188 |
| 1 | Log-HAR | **0.04958** | 0.08610 | 0.23887 |
| 1 | **VolaTTM** | 0.05192 | **0.08505** | **0.21483** |
| 5 | HAR-RV | 0.06134 | 0.10099 | 0.33504 |
| 5 | Log-HAR | **0.05832** | 0.10030 | 0.36285 |
| 5 | **VolaTTM** | 0.06173 | **0.09996** | **0.31054** |
| 22 | HAR-RV | 0.06686 | 0.10678 | 0.39199 |
| 22 | Log-HAR | **0.06433** | 0.10644 | 0.43810 |
| 22 | **VolaTTM** | 0.06466 | **0.10262** | **0.34682** |

VolaTTM improves macro RMSE and QLIKE at all three horizons. It does not improve
MAE relative to Log-HAR. Against Log-HAR, VolaTTM has lower QLIKE on 50 of 50
assets at one session, 49 of 50 at five sessions, and 47 of 50 at 22 sessions.

## Loading the checkpoint

Install the same major model implementation used for training:

```bash
pip install "granite-tsfm==0.3.6" "torch>=2.10,<2.11"
```

```python
import torch
from tsfm_public.models.tinytimemixer import TinyTimeMixerForPrediction

model = TinyTimeMixerForPrediction.from_pretrained("AurelPx/VolaTTM")
model.eval()

# Shape: batch, 512 sessions, 12 channels in the documented order.
past_values = torch.as_tensor(features, dtype=torch.float32)
freq_token = torch.full((past_values.shape[0],), 8, dtype=torch.long)

with torch.inference_mode():
    log_variance_path = model(
        past_values=past_values,
        freq_token=freq_token,
        return_loss=False,
    ).prediction_outputs[..., 0]

annualized_volatility = torch.sqrt(252.0 * torch.exp(log_variance_path))
forecasts = annualized_volatility[:, [0, 4, 21]]
```

`features` must be reconstructed with the transformations documented in the
[source repository](https://github.com/Aurelien7877/volattm). A different channel
order or target scale is not compatible with this checkpoint.

## Intended use

The model is intended for research on end-of-day volatility forecasting,
time-series foundation-model adaptation, and econometric benchmarking. It is
not designed for order execution, automated risk limits, or investment advice.

## Limitations

- The test period is isolated from checkpoint selection, but it is not a fully
  project-blind holdout. Earlier proxy-based experiments had identified 2026 as
  a difficult regime before this model was trained.
- The fixed VOLARE universe can contain selection and survivorship effects.
- Trading calendars differ across asset classes.
- Diebold-Mariano p-values are not corrected for multiple testing.
- Forecast accuracy has not been translated into a transaction-cost-aware
  strategy or economic utility result.
- Future data may differ materially from the evaluation period.

The full protocol and leakage assessment are documented in the
[audit](https://github.com/Aurelien7877/volattm/blob/main/AUDIT.md).

## Base-model and data attribution

VolaTTM is an independent research fine-tune and is not an IBM product. The
base TTM checkpoint is released by IBM under Apache 2.0. The IBM model card lists
the base pretraining sources and does not list VOLARE.

Please cite the original model and data work when using this checkpoint:

```bibtex
@inproceedings{ekambaram2024tinytimemixers,
  title     = {Tiny Time Mixers: Fast Pre-trained Models for Enhanced Zero/Few-Shot Forecasting of Multivariate Time Series},
  author    = {Ekambaram, Vijay and Jati, Arindam and Dayama, Pankaj and Mukherjee, Sumanta and Nguyen, Nam H. and Gifford, Wesley M. and Reddy, Chandra and Kalagnanam, Jayant},
  booktitle = {Advances in Neural Information Processing Systems},
  year      = {2024}
}

@article{cipollini2026volare,
  title   = {VOLatility Archive for Realized Estimates},
  author  = {Cipollini, Fabrizio and Cruciani, Giulia and Gallo, Giampiero M. and Insana, Alessandra and Otranto, Edoardo and Spagnolo, Fabio},
  journal = {arXiv preprint arXiv:2602.19732},
  year    = {2026}
}
```

## License

The fine-tuned weights and project code are released under Apache 2.0. VOLARE
data are not redistributed and remain subject to the source provider's terms.