amazon-science/thermal-forge

amazon-science/thermal-forge

Language: Python

License: NOASSERTION

Stars: 0

Forks: 0

Open issues: 0

Created: 2026-04-22T19:44:55Z

Pushed: 2026-06-16T21:53:56Z

Default branch: main

Fork: no

Archived: no

README:

ThermalForge

LLM-Powered Agents for Modeling Thermal Dynamics of Buildings

ThermalForge is a framework for automatically generating hybrid neuro-physical thermal dynamics models for residential buildings where modeling decisions are made by a Large Language Model (LLM). Specifically, ThermalForge implements a bi-level optimization approach where an LLM proposes model structures (physics-based equations or neural architectures) and then their parameters are calibrated against smart thermostat data.

This repository contains the source code for ThermalForge and the necessary configurations needed to replicate the experiments in the accompanying paper:

> Exploring LLM-Powered Agents for Modeling Thermal Dynamics of Buildings > in *Proceedings of ACM BuildSys 2026*

---

How It Works

ThermalForge runs a two-phase modeling pipeline for each building:

1. Physics-Based Modeling — The LLM generates grey-box thermal models (RC networks) as PyTorch code. Each candidate is calibrated against observational data, and the LLM receives feedback to improve subsequent proposals.

2. Neural Residual Modeling — The best physics model's rolled-out predictions become input to a neural model that learns to model the residual. The LLM can generate full architectures, modify a U-Net template, or tune hyperparameters.

The framework is implemented as a LangGraph state graph with 7 nodes:

create_phy_dataloader → generate_phy_model ⇄ evaluate_phy_model
↓ (converged)
select_phy_model → generate_nn_model ⇄ evaluate_nn_model
↓ (converged)
select_nn_model → END

Installation

Requires Python ≥ 3.12. From the repository root:

# Option 1: conda + pip
conda create -n thermal_forge python=3.12 -y
conda activate thermal_forge
pip install -e .

# Option 2: venv + pip
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

# Option 3: uv
uv sync

All ThermalForge settings — experiment parameters, LLM options, and infrastructure paths — are controlled through a single YAML config file. See src/thermal_forge/experiments/default.yaml for the full template with all available fields. The [Configuration](#configuration) section has details on priority and overrides.

AWS Setup Prerequisites

AWS Account Setup

In order to leverage AWS services (such as S3 for model input/output storage, or SageMaker for running experiments at scale in the cloud) first configure a personal AWS account as follows. All steps assume you are signed in as the account root user or an existing admin.

1. Choose a region. Pick a single AWS region and use it consistently throughout these instructions. Make sure the region selector in the AWS console (top-right) is set accordingly.

2. Grant permissions for an IAM user. In the IAM console, go to Users → Create user (unless you have one already). On the permissions page of that user, choose Attach policies directly and attach AdministratorAccess. This single policy covers everything the experiments need (Bedrock, S3, SageMaker, ECR, and IAM role passing for the Docker and SageMaker steps below).

3. Install the AWS CLI. Download and install the AWS CLI on your local machine before continuing.

4. Create an access key for CLI use. On the new user's page, go to Security credentials → Create access key and select Command Line Interface (CLI) as the use case. Acknowledge the warning and click Next. Copy the Access Key ID and Secret Access Key since the secret is shown only once. Then run aws configure on your local machine and provide the keys, the region you chose in step 1, and json as the default output format.

SageMaker Execution Role

5. Create an IAM role for SageMaker. When SageMaker runs your training jobs, it assumes a separate IAM role (distinct from your user permissions). To create it: in the IAM console, go to Roles → Create role, select AWS service as the trusted entity type, then choose SageMaker as the use case (SageMaker - Execution, specifically). On the permissions page, AmazonSageMakerFullAccess will be pre-selected, but after creating the role we will need to add one more permission. Name the role (e.g., SageMakerThermalForgeRole) and create it. Note the Role ARN — you will need it when launching jobs. Once done, go back to the role and also attach the AmazonBedrockFullAccess policy (needed for LLM calls from within the training jobs).

S3 Bucket Creation

6. Create an S3 bucket. In the S3 console, click Create bucket, give it a name that contains the string `sagemaker` (e.g., sagemaker-thermalforge-), leave the defaults, and click Create. The SageMaker execution role (created in the previous step) is granted S3 access by default only on buckets whose names contain sagemaker. If you prefer a different name, you will need to attach an inline policy granting the execution role s3:GetObject and s3:PutObject on that bucket once it exists.

Docker Image

7. Build a custom Docker image. The Dockerfile extends an AWS Deep Learning Container (DLC) base image hosted in an AWS-managed ECR registry. You must authenticate Docker to that registry before building so that it can pull the base image. First, run the configuration script to set the correct base image for your region:

# Configure the Dockerfile (prompts for region and DLC account ID)
python scripts/configure_docker.py

# Or specify explicitly (DLC_ACCOUNT is the registry account for your region,
# found at https://docs.aws.amazon.com/sagemaker/latest/dg-ecr-paths/sagemaker-algo-docker-registry-paths.html)
python scripts/configure_docker.py --region REGION --account DLC_ACCOUNT

# Authenticate Docker to the DLC ECR registry (use the same DLC_ACCOUNT and REGION from above)
aws ecr get-login-password --region REGION | \
docker login --username AWS --password-stdin DLC_ACCOUNT.dkr.ecr.REGION.amazonaws.com

# Build the image
cd docker/
docker build -t thermalforge .
cd ..

8. Push to ECR. Authenticate Docker to *your own* account's Amazon Elastic Container Registry (ECR) and push the image. This is a different registry than the DLC one used in step 7, so a separate `docker...