BuildSim Cloud API library for Python
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
- EplusGIT model management system - compare, merge and copy - can be accessed through API
- Regional project and global project. - the newly added global project allows user upload custom weather files for simulation / parametrics.
- Design day condition - automatically update design day conditions.
Previous update: Version 1.5.5: 4. Package and distribution on PYPI 5. New [monte carlo] algorithm is implemented in parametric study. 6. New methods to modify energy efficiency measure and parameters in a single model.
Version 1.5.0: 7. API library is now supporting model download. Check out this script 8. Model upload support customize (.CSV) schedules. Check out this script 9. Supports hourly data extract from a single model. script 10. Support extracting a single table from HTML. script 11. Open 3D geometry viewer using API. script 12. Zone Load / Load component Extraction. script 13. Add post-processing functions - convert data to pandas dataframe, and utilize plotly for plotting.
Version 1.4.0 14. Initialize a simulation job / parametric job requires a project api key now. 15. User API key is deleted 16. Run function in simulation job supports multiple models submission. 17. Include more standard measures: Building orientation, overhangs, fins, roof absorptions, water heater, water usage, equipment power 18. Include more data retriving options at building level.
- 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
pip install BuildSimHubAPI
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.
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.
- Project list page: Simply click the "Copy Key" button and paste it in you application.
- 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).
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())
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.
- 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!
- More simulation configurations and output results return will be added in the future!
- BuildSim Plot: This is the new project which we are integrating plotly package with our standard API library to provide the capability of visualizations.
- BuildSim Learn: This is a new project which we are working on integrating scikit-learn into the current workflow to enhance the parametric workflow.
- 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.
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.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size BuildSimHubAPI-1.6.8-py3-none-any.whl (84.8 kB)||File type Wheel||Python version py3||Upload date||Hashes View hashes|
|Filename, size BuildSimHubAPI-1.6.8.tar.gz (57.8 kB)||File type Source||Python version None||Upload date||Hashes View hashes|
Hashes for BuildSimHubAPI-1.6.8-py3-none-any.whl