Data and code for "Surrogate-Assisted Optimization of Parametric Facade Louvres for Annual Solar-Gain Reduction: A Grasshopper-Python Gaussian Process Framework"

Description

This replication package contains the numerical data, source code, corrected trained Gaussian Process Regression model, external-validation evidence, benchmark comparisons, and optimization records supporting the associated research article. The controlled case examines annual incident solar-energy minimization for an east-facing parametric facade-louvre system in Dhahran, Saudi Arabia. The archive includes a 150-case Latin Hypercube Sampling training dataset, an independently seeded 30-case external-validation dataset, a documented correction record for LHS_0150, regenerated GPR predictions and uncertainty intervals, RBF-SVR and Random Forest prediction benchmarks, a 2,762-row corrected-model replay of the archived surrogate candidate sequence, a 2,854-row direct-simulation optimization log, 637 paired unique geometries, final direct verification, portable Python scripts, model metadata, environment files, and a documented Grasshopper-Ladybug workflow. The deposited model achieves external R2 = 0.999575, RMSE = 44.07 kWh, MAE = 35.68 kWh, and MAPE = 0.523%. Both optimization routes retain the selected design of 0.90 m and -45 degrees. Direct verification gives 2,153 kWh compared with the corrected GPR prediction of 2,018.75 kWh. The README documents file relationships, variables, units, random seeds, reproduction steps, correction provenance, and interpretation limits.

Steps to reproduce

1. Download and extract the complete dataset archive while preserving its folder structure. 2. Install Python 3.12 and open a terminal in the extracted dataset’s root directory. 3. Create and activate a clean Python environment if desired. 4. Install the required packages: pip install -r 00_documentation/requirements.txt 5. Run the complete reproducibility workflow: python 04_code/run_all.py 6. The workflow loads the corrected training dataset, fits the final Gaussian Process Regression model, evaluates it against the independent validation set, compares it with the benchmark models, rescales the archived optimization candidate sequence using the corrected model, and regenerates the principal model, prediction, validation, and audit outputs. 7. To reproduce the Latin Hypercube Sampling coordinates separately, run: python 04_code/01_generate_samples.py The training design uses random seed 42, and the independent validation design uses random seed 2026. 8. Confirm the principal external-validation results: R² = 0.999575 RMSE = 44.0723 kWh MAE = 35.6780 kWh MAPE = 0.5232% 9. Confirm that the selected design is LouvreLength = 0.900 m and LouvreAngle = −45°, with a corrected surrogate prediction of 2018.75 kWh and a directly simulated result of 2153 kWh. 10. The Grasshopper–Ladybug application workflow, input definitions, weather identifier, simulation period, and component connections are documented in the 05_workflow folder. To use the optional Hops prediction service, install the additional requirements and start the server: pip install -r 00_documentation/requirements-grasshopper.txt python 04_code/04_prediction_server.py The local prediction endpoint is: http://127.0.0.1:5000/predict 11. Consult 00_documentation/DATA_DICTIONARY.md for column definitions and 01_data/correction_log.csv for the documented correction to sample LHS_0150. 12. File integrity can be checked using the SHA-256 values provided in 00_documentation/FILE_MANIFEST_SHA256.csv.

Institutions

• American University in Cairo

  Cairo, Cairo
• Ain Shams University

  Cairo, Cairo
• Umm al-Qura University

  Mecca Region, Makkah

Categories

Licence