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:

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

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

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
• gft/ttm4hvac-target-default
• gft/ttm4hvac-target-chaotic

---

📚 Related Datasets

Training and evaluation datasets used for this fine-tune:

• gft/ttm4hvac-source-all-train
• gft/ttm4hvac-target-heat-test
• gft/ttm4hvac-target-cool-test

Other datasets:

• gft/ttm4hvac-source-default-train
• gft/ttm4hvac-target-chaotic-train
• 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