README.md

---
library_name: granite_tsfm
base_model: ibm-granite/granite-timeseries-ttm-r2
tags:
- ttm4hvac
- tsfm
- digital twin
- hvac
- energy
license: apache-2.0
papers:
- title: "Transfer learning of building dynamics digital twin for HVAC control with Time-series Foundation Model"
  url: https://arxiv.org/abs/XXXX.XXXXX
  authors: "Ferran Aran Domingo"
datasets:
- gft/ttm4hvac-source-all-train
- gft/ttm4hvac-target-heat-test
- gft/ttm4hvac-target-cool-test
pipeline_tag: time-series-forecasting
---

# TTM4HVAC – TinyTimeMixer for HVAC dynamics modeling

This repository contains the **primary and recommended checkpoint** of the **TTM4HVAC** project: a fine-tuned version of IBM's *TinyTimeMixer* designed to serve as a generic digital twin of building dynamics under an HVAC system.

This model corresponds to the **“source-all”** training configuration (all source buildings, full dataset), and it achieves the best overall performance across the TTM4HVAC evaluation benchmarks.

Read more on the paper: [arXiv:XXXX.XXXXX]() (to be released).

---

# 🔧 Installation

The model uses IBM’s Granite Time Series Foundation Model tooling, available from PyPI:

```bash
pip install granite-tsfm==0.3.1
````

This installs the `tsfm_public` package containing:

* `TinyTimeMixerForPrediction`
* `TimeSeriesPreprocessor`
* `TimeSeriesForecastingPipeline`
* dataset utilities

---

# 🚀 Quickstart

This example loads the model directly from Hugging Face and performs:

1. Data preprocessing
2. Zero-shot evaluation
3. Forecast generation

```python
import pandas as pd
import torch

from tsfm_public import (
    TinyTimeMixerForPrediction,
    TimeSeriesPreprocessor,
    TimeSeriesForecastingPipeline,
    get_datasets,
)
from tsfm_public.toolkit.time_series_preprocessor import prepare_data_splits

MODEL_ID = "gft/ttm4hvac"
device = "cuda" if torch.cuda.is_available() else "cpu"

TARGETS = [
    "Room Air Temperature (C)",
    "HVAC Power Consumption (W)"
]
OBSERVABLES = [
    "Outdoor Air Temperature (C)",
    "Outdoor Humidity (%)",
    "Wind Speed (m/s)",
    "Direct Solar Radiation (W/m^2)",
]
CONTROLS = [
    "Heating Setpoint (C)",
    "Cooling Setpoint (C)"
]
ID_COLUMNS = []
TIMESTAMP_COLUMN = "time"

BATCH_SIZE = 32
SPLIT_CONFIG = {"train": 0.35, "test": 0.25}  # val is inferred


def run_inference(df: pd.DataFrame, model_id: str = MODEL_ID):
    # 1) Load the fine-tuned TinyTimeMixer model from Hugging Face
    model = TinyTimeMixerForPrediction.from_pretrained(model_id)
    model.to(device)

    context_length = model.config.context_length
    prediction_length = model.config.prediction_length

    # 2) Build the preprocessor
    tsp = TimeSeriesPreprocessor(
        timestamp_column=TIMESTAMP_COLUMN,
        target_columns=TARGETS,
        control_columns=CONTROLS,
        observable_columns=OBSERVABLES,
        id_columns=ID_COLUMNS,
        context_length=context_length,
        prediction_length=prediction_length,
        scaling=True,
        freq="15min",
        encode_categorical=False,
        scaler_type="standard",
    )

    # 3) Prepare test split
    _, _, df_test = prepare_data_splits(
        df, context_length=context_length, split_config=SPLIT_CONFIG
    )

    # 4) Build the forecasting pipeline
    pipeline = TimeSeriesForecastingPipeline(
        model,
        device=device,
        feature_extractor=tsp,
        batch_size=BATCH_SIZE,
    )

    # 5) Generate forecasts
    df_forecast = pipeline(df_test)

    return df_test, df_forecast

```

## Example using [gft/ttm4hvac-target-heat-test]()

```python
from datasets import load_dataset

ds = load_dataset("gft/ttm4hvac-target-heat-test")
df = ds["test"].to_pandas()
df.head()
```

---

# 📑 Input Schema

Your input `pandas.DataFrame` must contain:

* `time` (timestamp column)
* **Targets:**

  * `Room Air Temperature (C)`
  * `HVAC Power Consumption (W)`
* **Observables:**

  * `Outdoor Air Temperature (C)`
  * `Outdoor Humidity (%)`
  * `Wind Speed (m/s)`
  * `Direct Solar Radiation (W/m^2)`
* **Controls:**

  * `Heating Setpoint (C)`
  * `Cooling Setpoint (C)`

Sampling frequency must be **15 minutes** (`freq="15min"`).

---

# 📦 Related models (TTM4HVAC family)

These models correspond to each experiment documented on the [paper]():

  - `gft/ttm4hvac` - Main model, best performer (this repo)
  - [`gft/ttm4hvac-source-default`](https://huggingface.co/gft/ttm4hvac-source-default)
  - [`gft/ttm4hvac-target-default`](https://huggingface.co/gft/ttm4hvac-target-default)
  - [`gft/ttm4hvac-target-chaotic`](https://huggingface.co/gft/ttm4hvac-target-chaotic)

---

# 📚 Related Datasets

Training and evaluation datasets used for this fine-tune:

* [`gft/ttm4hvac-source-all-train`](https://huggingface.co/datasets/gft/ttm4hvac-source-all-train)
* [`gft/ttm4hvac-target-heat-test`](https://huggingface.co/datasets/gft/ttm4hvac-target-heat-test)
* [`gft/ttm4hvac-target-cool-test`](https://huggingface.co/datasets/gft/ttm4hvac-target-cool-test)

Other datasets:

* [`gft/ttm4hvac-source-default-train`](https://huggingface.co/datasets/gft/ttm4hvac-source-default-train)
* [`gft/ttm4hvac-target-chaotic-train`](https://huggingface.co/datasets/gft/ttm4hvac-target-chaotic-train)
* [`gft/ttm4hvac-target-default-train`](https://huggingface.co/datasets/gft/ttm4hvac-target-default-train)

---

# 📘 Project Overview

**TTM4HVAC** investigates how foundation-model-based time-series architectures (*TinyTimeMixer*, from IBM Granite TSFM) can:

* model complex building thermal dynamics,
* generalize across buildings and climates,
* support transfer from source → target buildings,
* evaluate under diverse behavioral patterns (default schedules vs chaotic occupants).

---

# ✒️ Citation

If you use this model or datasets, please cite:

```
**F. Aran**,  
*Transfer learning of building dynamics digital twin for HVAC control with Time-series Foundation Model*,  
arXiv:XXXX.XXXXX, 2025.  
https://arxiv.org/abs/XXXX.XXXXX
```