This library allows you to quickly and easily use the BuildSimHub Web API v1 via Python.

This library represents the beginning of the Cloud Simulation function on BuildSimHub. We want this library to be community driven and BuildSimHub led. We need your help to realize this goal. To help, make sure we are building the right things in the right order, we ask that you create issues and pull requests or simply upvote or comment on existing issues or pull requests. We appreciate your continued support, thank you!

For more information, examples, and tutorials, please check our wiki page.

Table of Contents

• Latest Update
• Installation
• Quick Start
• Roadmap
• About
• License

Latest version: 1.7.0

1. HVAC system design options include 14 HVAC systems, which can be implemented on an idf model
2. Customized EnergyPlus class in a template with all the defiend design options
3. Support customized design options that allow users to build their own design options
4. Every design option include a small description of how the design option works (measure_help())
5. BuildSim data project finally is here!! -> provide useful and free utility functions for pre-processing meter / sensor data.
6. Design options also include demand control and heat recovery system for central air HVAC systems.

Previous update: Version 1.6.0:

1. EplusGIT model management system - compare, merge and copy - can be accessed through API
2. Regional project and global project. - the newly added global project allows user upload custom weather files for simulation / parametrics.
3. Design day condition - automatically update design day conditions.

Version 1.5.5:

1. Package and distribution on PYPI
2. New monte carlo algorithm is implemented in parametric study.
3. New methods to modify energy efficiency measure and parameters in a single model.

Version 1.5.0:

1. API library is now supporting model download. Check out this script
2. Model upload support customize (.CSV) schedules. Check out this script
3. Supports hourly data extract from a single model. script
4. Support extracting a single table from HTML. script
5. Open 3D geometry viewer using API. script
6. Zone Load / Load component Extraction. script
7. Add post-processing functions - convert data to pandas dataframe, and utilize plotly for plotting.

Installation

Prerequisites

• The BuildSimHub service, starting at the free level
• Python version 3.5 or 3.6, Python 2.7 is under-testing.
• If you wish to use the Built-in plotting function, you will then need the latest Plotly python package. The installation instruction can be found in here

Install Package

pip install BuildSimHubAPI

Setup environment

There are no requirements for regular users to access BuildSim Cloud besides a Python installation. However, for software vendors who would like to integrate the BuildSim Cloud, you can revise the vendor key in the info.config file.

Edit the info.config vendor_id:[Your name] If you decided to use BuildSim Cloud, please send your specific vendor id to us: weili.xu@buildsimhub.net.

Project key (required)

To activate a simulation through API client, you need to supply a project key - a key that helps BuildSim connect your local application to your project. The project key can be found in two places.

1. Project list page: Simply click the "Copy Key" button and paste it in you application.
2. In the project tab under every model: Under every model, search for project api key field in the project tab.

'''
Example of how to innitialize API client
'''
project_api_key = 'abcdef-ghijkl-mnopqrst'
bsh = buildsimhub.BuildSimHubAPIClient()
new_sj = bsh.new_simulation_job(project_api_key)

Model key (optional)

Some functions in the API library requires you to supply a model_api_key. These functions allow you to update a model's history or retrieve the simulation results from a model under the specified project. The model_api_key can be found in every model (highlighted in the figure below).

Quick Start

Hello BuildSim

from BuildSimHubAPI import buildsimhub
###############NOW, START THE CODE########################

bsh = buildsimhub.BuildSimHubAPIClient()
new_sj = bsh.new_simulation_job('abcdef-ghijkl-mnopqrst')
model = new_sj.run("/Users/weilixu/Desktop/5ZoneAirCooled.idf", track=True)

print(model.net_site_eui())

The BuildSimHubAPIClient creates a portal object that manages simulation workflow. From this object, you can initiate a simulationJob to conduct a cloud simulation. Call run() method with parameters can start the cloud simulation. The returned object is the model object, which contains full set of simulation results.

Quick start for Parametric simulation

import BuildSimHubAPI as bsh_api
project_api_key = '8d0aa6f4-50c3-4471-84e6-9bd4877ed19a'
file_dir = "/Users/weilixu/Desktop/data/UnitTest/5ZoneAirCooled.idf"
bsh = bsh_api.BuildSimHubAPIClient()
new_pj = bsh.new_parametric_job(project_api_key) 
 
# Define EEMs  
measure_list = list()  
  
wwr = bsh_api.measures.WindowWallRatio()  
wwr.set_min(0.3)  
wwr.set_max(0.6)  
measure_list.append(wwr)  
  
lpd = bsh_api.measures.LightLPD('ip')  
lpd.set_min(0.6)  
lpd.set_max(1.2)  
measure_list.append(lpd)  
  
heatEff = bsh_api.measures.HeatingEfficiency()  
heatEff.set_min(0.8)  
heatEff.set_max(0.95)  
measure_list.append(heatEff)  
  
# Add EEMs to parametric job  
new_pj.add_model_measures(measure_list)  
  
# Start!  
parametric = new_pj.submit_parametric_study_local(file_dir, algorithm='montecarlo', size=10, track=True)  

print(parametric.net_site_eui())

The parametric workflow requires user specified energy efficient measures. The full list of measures can be found in BuildSimHub wiki.

Roadmap

1. We are working on a standard EEMs, which allows user to apply common energy efficiency measures to any IDF models. Open an issue if you did not see any desired EEMs in the standard EEM library!
2. More simulation configurations and output results return will be added in the future!
3. BuildSim Plot: This is the new project which we are integrating plotly package with our standard API library to provide the capability of visualizations.
4. BuildSim Learn: This is a new project which we are working on integrating scikit-learn into the current workflow to enhance the parametric workflow.
5. If you are interested in the future direction of this project, please take a look at our open issues and pull requests. We would love to hear your feedback.

About

buildsimhub-python is guided and supported by the BuildSimHub Developer Experience Team.

buildsimhub-python is maintained and funded by the BuildSimHub, Inc. The names and logos for buildsimhub-python are trademarks of BuildSimHub, Inc.

License

The MIT License (MIT)