Tech-Meld/HeatBee-Database

HeatBee: Surrogate Modeling of High-Mass Vernacular Architecture in Arid Climates

    

HeatBee is an open-source building performance simulation pipeline and Machine Learning surrogate model investigating the transient thermodynamic behavior of vernacular rammed earth (pisé) architecture versus contemporary construction in Marrakesh, Morocco (Zone Climatique 5).

🎯 Key Physical Findings

Simulations were performed under the peak summer period of the Marrakesh Menara Airport EPW (peak outdoor dry-bulb: 45.52°C).

1. The Typology Comparison: Interior Mass vs. Envelope Insulation

• —As-Built Typology (Mode A): A 50 cm pisé room (with earth partitions and floor) maintains a peak operative temperature of 30.63°C and 20.3 Discomfort Degree Hours (>30°C), compared to 31.48°C and 81.1 DDH for an RTCM Zone 5 modern room (20 cm hollow brick with 4 cm XPS insulation and 15 cm concrete slabs).
• —Shared Interior Mass (Mode B): When both rooms are modeled with identical 15 cm concrete slab floors and partitions, the result equalizes: the RTCM-insulated room reaches 31.48°C (81.1 DDH), while the pisé room reaches 31.76°C (165.8 DDH).
• —Takeaway: The vernacular advantage is driven primarily by interior volumetric thermal mass coupled with nocturnal free cooling, rather than the exterior earth wall possessing superior steady-state thermal resistance over continuous code insulation.

2. Component Apportionment (Wall vs. Roof)

Holding interior mass constant (15 cm concrete partitions for all), component swapping reveals:

• —The 50 cm pisé exterior wall outperforms the RTCM insulated wall by 0.16°C (31.32°C vs 31.48°C peak), as extreme thermal inertia suppresses peak daytime flux.
• —The traditional mud/timber roof is the primary thermal vulnerability, admitting +0.50°C of excess heat compared to the RTCM-insulated roof (31.98°C vs 31.48°C).

3. Realistic Ground-Coupled Boundary

• —Under an adiabatic floor assumption (isolated upper-floor room), the pisé room peaks at 30.63°C.
• —Under realistic summer ground coupling (Kusuda $24.0^\circ\text{C}$–$25.0^\circ\text{C}$ subsoil), downward heat dissipation drops the pisé room peak to 29.61°C, bringing it completely below the 30.0°C adaptive comfort limit during a 45.5°C heatwave.

4. Thermal Mass and Ventilation Sweeps

• —Mass Diminishing Returns: Increasing pisé thickness from 15 cm to 45 cm reduces peak temperatures by 2.40°C, whereas adding another 30 cm (to 75 cm) yields only 0.71°C of marginal cooling. This aligns with the 1D periodic thermal penetration depth: $$\delta = \sqrt{\frac{k}{\rho c_p} \frac{P}{\pi}} \approx 11\text{ cm}$$ Beyond $4\delta \approx 44\text{ cm}$, the diurnal thermal wave is attenuated by ~98%.
• —Nocturnal Ventilation: Increasing airflow from 0 to 4 ACH drops peak temperatures by 1.46°C, but tripling airflow from 4 to 12 ACH yields only 0.51°C of additional relief as indoor air approaches ambient night temperature.

🔬 Benchmark Comparison (July–August Peak Heatwave)

Shared boundary conditions: Roof albedo 0.60, external wall solar absorptance 0.50, glazing SHGC 0.40, 4.0 ACH free cooling, adiabatic perimeter.

⚡ Machine Learning Surrogate Fidelity

• —Model: Gradient Boosted Decision Trees (XGBoostRegressor)
• —Training Dataset: 256 Latin Hypercube samples evaluated via EnergyPlus 26.2 ConductionFiniteDifference
• —5-Fold Cross Validation: $R^2 = 0.9450$ | $\text{RMSE} = 0.358^\circ\text{C}$ | $\text{MAE} = 0.275^\circ\text{C}$ (Spread $\sigma = 1.53^\circ\text{C}$)
• —Out-of-Sample Holdout (N=32 Unseen Runs, Seed 999): $\text{RMSE} = 0.316^\circ\text{C}$ | $\text{MAE} = 0.262^\circ\text{C}$
• —Inference Latency: $< 1\text{ ms}$ on CPU

⚠️ Limitations

1. 1.Single-Zone Idealization: The model represents an isolated single-room perimeter zone facing an exterior aperture, not a fully coupled 3D computational fluid dynamics (CFD) courtyard void.
2. 2.Simplified Infiltration & Internal Loads: Constant occupancy sensible gains (2 people, 240 W) without dynamic appliance scheduling or variable occupant window operation.
3. 3.No Sensor Calibration: This is a numerical comparative simulation; boundary conditions have not yet been calibrated against empirical data-logger measurements from historic medina structures.

🚀 Quickstart

# 1. Clone repository
git clone https://github.com/<your-username>/HeatBee.git
cd HeatBee

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run verified benchmark, sweeps, and holdout validation
python cli.py --benchmark
python cli.py --sweeps
python cli.py --holdout

# 4. Launch interactive dashboard
streamlit run app.py

📄 Citation & License

MIT License. If citing this software or dataset:

@software{heatbee2026,
  author = {Haytam Aarab},
  title = {HeatBee: Surrogate Modeling of High-Mass Vernacular Architecture in Arid Climates},
  year = {2026},
  publisher = {Zenodo},
  doi = {10.5281/zenodo.23145635}
}