README.md

---
language:
- en
license: cc-by-nc-4.0
base_model:
- google/flan-t5-xl
---
# LLM-BEM-Engineer

<!-- Logo 居中显示 -->
<div align="center">
  <img src="https://huggingface.co/GangJiang/LLM-BEM-Engineer/resolve/main/figs/logo.png?raw=true" width="40%" alt="LLM-BEM-Engineer" />
</div>

<hr>

<!-- Badge 样式美化 + 自适应布局 -->
<style>
  .badge-container {
    display: flex;
    flex-wrap: wrap;
    justify-content: center;
    align-items: center;
    gap: 6px;
    margin-top: 10px;
    margin-bottom: 10px;
  }
  .badge-container a img {
    height: 28px;
    transition: transform 0.2s ease;
  }
  .badge-container a:hover img {
    transform: scale(1.05);
  }
  @media (max-width: 500px) {
    .badge-container a img {
      height: 24px;
    }
  }
</style>

<!-- 徽章容器 -->
<div class="badge-container">
  <a href="https://huggingface.co/GangJiang" target="_blank">
  <img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-LLM--BEM--Engineer-ffc107?color=ffc107&logoColor=white"/>
  </a>
  <a href="https://colab.research.google.com/github/Gangjiang1/EPlus-LLM/blob/main/v2/Example.ipynb" target="_blank">
    <img alt="Open In Colab" src="https://colab.research.google.com/assets/colab-badge.svg"/>
  </a>
  <!-- <a href="https://www.linkedin.com/in/gang-jiang-46b990273" target="_blank" style="margin: 2px;">
    <img alt="LinkedIn" src="https://img.shields.io/badge/🤖LinkedIn-Connect-0A66C2?style=flat&logo=linkedin&logoColor=white" style="display: inline-block; vertical-align: middle;"/>
  </a>
  <a href="https://www.sciencedirect.com/science/article/pii/S0926580525002638" target="_blank">
    <img alt="Paper" src="https://img.shields.io/badge/Paper-EPlus--LLM%20V2-red?logo=arxiv&logoColor=white"/>
  </a>
  <a href="https://huggingface.co/EPlus-LLM/EPlus-LLMv2/resolve/main/figs/qr.png?raw=true" target="_blank">
    <img alt="WeChat" src="https://img.shields.io/badge/WeChat-Gang%20Jiang-brightgreen?logo=wechat&logoColor=white"/>
  </a> -->
  <a href="LICENSE" target="_blank">
    <img alt="License" src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?logo=apache&logoColor=f5de53" style="display: inline-block; vertical-align: middle;"/>
  </a>
</div>

**A Large Language Model Based AI Engineer for Automated Building Energy Modeling and Analysis**

<div align="center">
  <img src="https://huggingface.co/GangJiang/LLM-BEM-Engineer/resolve/main/figs/engineer-graphic.png?raw=true" alt="Illustration of LLM-BEM-Engineer for Auto-building energy modeling" width="700"/>
</div>


## 🎉 Key Features
- Multi-Modal Inputs: Supports heterogeneous inputs including natural language descriptions, voice, existing building energy models, and tabular data, enabling flexible and intuitive specification of building information.
- Agentic LLM Collaboration: A multi-agent LLM framework where specialized agents (e.g., manager, geometry, or HVAC system modeler) collaborate to construct building energy models.
- Comprehensive Building Scenarios Coverage: Covers nearly all major building geometry, HVAC systems, story, envelope, internal loads, schedules, and operation strategies, supporting diverse building types and use cases.
- Building Model Editing and Iterative Refinement: Enables targeted modification of existing building energy models, allowing users to revise, extend, or optimize specific components without rebuilding the entire model from scratch.
- Automated Simulation Checking and Debugging: Automatically validates generated EnergyPlus models, detects common modeling and simulation errors, and iteratively corrects issues to ensure runnable and physically consistent simulations.
- Scalability: Scales across not only diverse HVAC system configurations, but also nearly all building equipment and components, with automated sizing supported.

<div align="center">
  <img src="https://huggingface.co/GangJiang/LLM-BEM-Engineer/resolve/main/figs/1pic.png" alt="Description" width="600"/>
  <p><em>Overview of LLM-BEM-Engineer.</em></p>
</div>

- Flexible Design Scenarios:

(1) Building Use: The engineer can effectively auto-model in a wide spectrum of building functional types, including commercial buildings (e.g., offices, retail spaces, hospitals, and facilities), residential buildings (from single-family houses to high-rise apartments), as well as mixed-use complexes with multiple functions for different spaces.

(2) Geometry: It supports a diverse range of building forms and layouts, such as single- or multi-story structures; U-, L-, T-, square, courtyard, or editing irregular shapes; and various roof types including flat, gable, and hipped roofs. The tool also adapts to specifications of different orientations, window-to-wall ratios, and detailed internal zoning configurations.

(3) Construction and Material: It can understand different compositions of building construction and envelope assemblies. This incorporates wall, roof, and glazing systems with diverse material choices and insulation levels, ranging from conventional construction practices to advanced high-performance solutions.

(4) Operation and Schedule: It can auto-create descriptions for detailed operational patterns (e.g., space types) and schedules that drive building energy demand. This includes occupancy levels (e.g., residential use vs. office hours), and equipment operation profiles for lighting, appliances, and HVAC systems. In addition, it captures indoor environment control strategies across different zones, such as ventilation and infiltration rates, heating and cooling thermostat setpoints.

(5) Building System: The engineer can auto-model a wide array of heating, ventilation, and air conditioning (HVAC) configurations, ranging from common setups such as VAV (Variable Air Volume), FCU (Fan Coil Unit), VRF (Variable Refrigerant Flow), heat pump, and packaged AC units, to hybrid systems that integrate multiple approaches (e.g., VAV+FCU) as well as advanced designs like DOAS (Dedicated Outdoor Air System)-based configurations. It also allows flexibility in simulating system performance under different equipment and control logics.

<div align="center">
  <img src="https://huggingface.co/GangJiang/LLM-BEM-Engineer/resolve/main/figs/2pic.png" alt="Prompt-Model Description" width="600"/>
  <p><em>Supported dimensions and representative building archetypes auto-generated by the AI Engineer.</em></p>
</div>

## 🏗️ Target Users
This current platform is designed for engineers, architects, and researchers working in building performance, sustainability, and resilience. It is especially useful during early-stage conceptual design when modeling decisions have the greatest impact.
<div align="center">
  <img src="https://huggingface.co/GangJiang/LLM-BEM-Engineer/resolve/main/figs/3pic.png" alt="LLM-BEM-Engineer for automated generating" width="600"/>
  <p><em>LLM-BEM-Engineer for automated generating.</em></p>
</div>

<div align="center">
  <img src="https://huggingface.co/GangJiang/LLM-BEM-Engineer/resolve/main/figs/4pic.png" alt="LLM-BEM-Engineer for automated editing" width="600"/>
  <p><em>LLM-BEM-Engineer for automated editing.</em></p>
</div>

## 📁 LLM-BEM-Engineer Benchmark Dataset

This benchmark dataset is designed to evaluate the capability of **Large Language Models (LLMs)** in generating **Building Energy Models (BEMs)** from natural language descriptions.

The benchmark focuses on two essential aspects of real-world applicability:

- **Scalability**: The ability of LLMs to handle a wide range of building configurations and system complexities.
- **Robustness**: The ability of LLMs to correctly infer user intent under noisy, ambiguous, or incomplete inputs.

The benchmark consists of **two complementary test sets**, each designed to evaluate a different capability of LLMs in automated building energy model generation.

| Dataset | Purpose | Description |
|-------|--------|-------------|
| `detailed_prompt_test` | Scalability benchmark | Well-specified and detailed building modeling prompts |
| `robust_prompt_test` | Robustness benchmark | Noisy and high-level user input prompts |

For details, please refer to the *LLM-BEM-Engineer Benchmark* folder in this repository.

## 🚀 Quick Start

Here provides a code snippet to show you how to run the LLM-BEM-Engineer.  
  
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Gangjiang1/EPlus-LLM/blob/main/v2/Example.ipynb)

```python
# ⚠️ Please make sure:
# (1) You have adequate GPU memory.
# (2) You have replaced your own API key.
# (3) Your EnergyPlus engine is version 9.6.

### =============================================###
###                 Manager Agent                ###
### =============================================###

# Manager Agent (Foundation LLM: DeepSeek-Chat).

from openai import OpenAI
client = OpenAI(api_key="your_own_api", base_url="https://api.deepseek.com")

# Example of user input query (text or voice)
user_query = f"""
Simulate a 1 story hollow square, courtyard building.
The height of story 1 is 11.42 meters.
The horizontal segments are 144.24 meters long and 19.33 meters wide.
The vertical segments are 29.80 meters long and 390.88 meters wide.
The attic height is 26.60 meters. The building orientation is 352 degrees to the north.
Each story has 4 thermal zones in each orientation.
The window-to-wall ratio is 0.80 for the north, 0.58 for the south, 0.17 for the west, and 0.78 for the east.

The wall is made of concrete, with a thickness of 0.03 meters and the wall insulation is R18.
The roof is made of concrete, with a thickness of 0.05 meters and the roof insulation is R18.
The floor is made of concrete, covered with carpet.
The window U-factor is 1.8 W/m2K and the SHGC is 0.3.
This building has 1 space types. Space type 1 is for zone 1, 2, 3, 4. For space type 1, the people density is 10 m2/person, the lighting density is 4 W/m2, and the electric equipment density is 8 W/m2.
The people activity level is 130 W/person. The infiltration rate is 0.11 ACH.
The occupancy rate is 0.9 from 8:00 to 16:00 and 0.2 in other periods of time.
For zone 1, 2, 3, 4, the cooling setpoint is 24.0 Celsius during 6:00 to 18:00, and 26.0 Celsius in unoccupied periods. The heating setpoint is 20.0 Celsius during 6:00 to 18:00, and 18.0 Celsius in unoccupied periods.

The HVAC system in this building is packaged air conditioning unit, rooftop unit, DX system with electric heater for heating.
The unit 1 serves zone 1, zone 2.
It includes an economizer, which operates based on differential dry bulb.
The rated capacity is 41378 W for cooling and Autosize W for heating.
The rated cooling COP is 3.8 and the heating efficiency is 0.75.
The supply air temperature for cooling is 14.3 Celsius, and for heating is 40.7 Celsius.
The outdoor ventilation rate is 3.69 ACH.
The fan efficiency is 0.78, the pressure rise is 1770 Pa, and the maximum flow rate is Autosize m3/s.
The unit 2 serves zone 3, zone 4.
The rated capacity is Autosize W for cooling and 36963 W for heating.
The rated cooling COP is 3.96 and the heating efficiency is 0.87.
The supply air temperature for cooling is 18.6 Celsius, and for heating is 49.0 Celsius.
The outdoor ventilation rate is 1.18 ACH.
The fan efficiency is 0.64, the pressure rise is 1536 Pa, and the maximum flow rate is 130.08 m3/s.
"""

# Manager's prompt
manager_prompt = f"""
Please extract sentences related to the following categories from the provided content:
1. Building geometry, including shape, story, height, orientation, window-to-wall ratio, etc.
2. Building information, including materials, construction, insulations, information of space types, cooling and heating setpoints.
3. HVAC systems, including fan and coil units, control methods, supply temperature, ventilation, economizer, outdoor air system, etc.
4. Water loops, including chilled water, hot water, condenser water, and related equipment.

For each category, identify and extract only the relevant sentences.

The output format:
**Category 1:** (the building geometry sentences).
**Category 2:** (the building information sentences).
**Category 3:** (the HVAC system sentences).
**Category 4:** (the water loop sentences).

Provided content:
"""

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": manager_prompt},
        {"role": "user", "content": user_query},
    ],
    stream=False,
)

print(response.choices[0].message.content)

# An extraction function, extract_categories, is designed to extract different categories based on the regular expression **Category {n}:** defined in the manager_prompt.
# category_1, category_2, category_3, category_4 = extract_categories(response.choices[0].message.content)

### =============================================###
###           Fine-Tuned Modeler Agents          ###
### =============================================###

# ⚠️ Please make sure you have adequate GPU memory.
! pip install -U bitsandbytes -q # pip this repo at your first run
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
import torch
from peft import PeftModel, PeftConfig
import os

os.environ["CUDA_VISIBLE_DEVICES"] = "0"
device = "cuda:0"

# Load the Modeler config.
repo_id = "GangJiang/LLM-BEM-Engineer"
sub = "Modeler-Bldg_Geo" # 4 related agent names: Modeler-Bldg_Geo; Modeler-Bldg_Cons_Ops; Modeler-Water_Sys; Modeler-Air-Sys
config = PeftConfig.from_pretrained(repo_id, subfolder=sub)

# Load the base LLM, flan-t5-xl (8-bit quantized), and tokenizer
base_model = AutoModelForSeq2SeqLM.from_pretrained("google/flan-t5-xl", load_in_8bit=True)
tokenizer = AutoTokenizer.from_pretrained("google/flan-t5-xl")

# Load the Lora model
modeler_agent_model = PeftModel.from_pretrained(base_model, repo_id, subfolder=sub)
# Generation config
generation_config = modeler_agent_model.generation_config
generation_config.max_new_tokens = 3000
generation_config.temperature = 0.1
generation_config.top_p = 0.1
generation_config.num_return_sequences = 1
generation_config.pad_token_id = tokenizer.eos_token_id
generation_config.eos_token_id = tokenizer.eos_token_id

# This is the corresponding Modeler Agent input extract from the Manager Agent (details in the file: "Manager_Agent_Inference.ipynb").
# For example, modeler agent: Modeler-Bldg_Geo

modeler_agent_input=f"""
Simulate a 1 story hollow square, courtyard building.
The height of story 1 is 11.42 meters.
The horizontal segments are 144.24 meters long and 19.33 meters wide.
The vertical segments are 29.80 meters long and 390.88 meters wide.
The attic height is 26.60 meters.
The building orientation is 352 degrees to the north.
Each story has 4 thermal zones in each orientation.
The window-to-wall ratio is 0.80 for the north, 0.58 for the south, 0.17 for the west, and 0.78 for the east.
"""
modeler_agent_model.to(device)

# Modeler Agent generating...
input_ids = tokenizer(modeler_agent_input, return_tensors="pt", truncation=False).to(device)
generated_ids = modeler_agent_model.generate(input_ids = input_ids.input_ids,
                           attention_mask = input_ids.attention_mask,
                           generation_config = generation_config)
generated_output = tokenizer.decode(generated_ids[0], skip_special_tokens=True)

# View the generated result of the fine-tuned corresponding Modeler (e.g., Modeler-Bldg_Geo)
agent_action = generated_output
print(agent_action)

# Execute the modeling actions produced by the Modeler Agent
# exec(agent_action)
```

<!-- ## 📝 Citation

If you find our work helpful, feel free to give us a cite.

```
@article{jiang2025EPlus-LLMv2,
  author    = {Gang Jiang and Jianli Chen},
  title     = {Efficient fine-tuning of large language models for automated building energy modeling in complex cases},
  journal   = {Automation in Construction},
  volume    = {175},
  pages     = {106223},
  year      = {2025},
  month     = {July},
  doi       = {https://doi.org/10.1016/j.autcon.2025.106223}}

@article{jiang2025prompting,
  author    = {Gang Jiang and Zhihao Ma and Liang Zhang and Jianli Chen},
  title     = {Prompt engineering to inform large language models in automated building energy modeling},
  journal   = {Energy},
  volume    = {316},
  pages     = {134548},
  year      = {2025},
  month     = {Feb},
  doi       = {https://doi.org/10.1016/j.energy.2025.134548}}

@article{jiang2025EPlus-LLM,
  author    = {Gang Jiang and Zhihao Ma and Liang Zhang and Jianli Chen},
  title     = {EPlus-LLM: A large language model-based computing platform for automated building energy modeling},
  journal   = {Applied Energy},
  volume    = {367},
  pages     = {123431},
  year      = {2024},
  month     = {Aug},
  doi       = {https://doi.org/10.1016/j.apenergy.2024.123431}}
``` -->