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!
- The BuildSimHub service, starting at the free level
- Python version 2.6, 2.7, 3.4, 3.5 or 3.6
Simply clone this repository and place in any folder you wish to build your application on. Examples:
After you downloaded the whole package, the first you need to do is to reconfigure your user API in the info.config file. You can find the API key associate with your account under the profile page:
Simple edit the info.config
user_api_key:[YOUR_API_KEY]
The following is the minimum needed code to initiate a regular simulation with the helpers/simulationJob
from BuildSimHubAPI import buildsimhub
#this key can be found under an energy model
model_key="0ade3a46-4d07-4b99-907f-0cfeece321072"
#absolute directory to the energyplus model
file_dir = "/Users/weilixu/Desktop/5ZoneAirCooled.idf"
###############NOW, START THE CODE########################
bsh = buildsimhub.BuildSimHubAPIClient()
newSJ = bsh.new_simulation_job(model_key)
response = newSj.create_model(file_dir)
############### WE DONE! #################################
#You can print the responses to verify whether the simulation
#is success or not.
print (response)The BuildSimHubAPIClient creates a portal object that manages simulation workflow.
From this object, you can initiate a simulationJob to conduct a cloud simulation. Call createModel() method with parameters can start the cloud simulation.
from BuildSimHubAPI import buildsimhub
bsh = buildsimhub.BuildSimHubAPIClient()
#this key can be found under your project folder
model_key="0ade3a46-4d07-4b99-907f-0cfeece321072"
#absolute directory to the energyplus model
file_dir = "/Users/weilixu/Desktop/5ZoneAirCooled.idf"
newSJ = bsh.new_simulation_job(model_key)
response = newSj.create_model(file_dir)
######BELOW ARE THE CODE TO TRACK SIMULATION#########
if(response == 'success'):
while newSJ.track_simulation():
print (newSJ.trackStatus)
time.sleep(5)As mentioned previously, BuildSimHubAPIClient manages the entire workflow of the simulation. So once a cloud simulation is successfully started by the SimulationJob class, you can simply call trackSimulation() function to receive the simulation progress.
from BuildSimHubAPI import buildsimhub
bsh = buildsimhub.BuildSimHubAPIClient()
#this key can be found under your project folder
model_key="0ade3a46-4d07-4b99-907f-0cfeece321072"
#absolute directory to the energyplus model
file_dir = "/Users/weilixu/Desktop/5ZoneAirCooled.idf"
newSJ = bsh.new_simulation_job(model_key)
response = newSj.create_model(file_dir)
if(response == 'success'):
while newSJ.track_simulation():
print (newSJ.trackStatus)
time.sleep(5)
######BELOW ARE THE CODE TO RETRIEVE SIMULATION RESULTS#########
response = newSJ.get_simulation_results('html')
print(response)If the Job is completed, you can get results by calling get_simulation_results(type) function.
#Object and Functions
The easiest way to generate a SimulationJob class is calling the newSimulationJob() method in the BuildSimHubAPIClient.
Nevertheless, you have to provide a folder_key in order to create a new SimulationJob instance.
The folder_key can be found under each folder of your project
SimulationType class helps you configure the cloud simulation. There are two simulation types: regular and fast. Also, ou can increase the number of agent by calling the increaseAgents() function.
simulationType = bsh.get_simulation_type()
numOfAgents = simulationType.increaseAgents();
print (numOfAgents)It should be noted that the maximum number of agents working on one simulation job is limited to 12, and the more agents you assigned to one simulation job, the faster your simulation can be. You can also call resetAgent() function to reset the number of agent to 2.
A simulation job manages one type of cloud simulation. It contains three main functions which are listed below:
The create_model() function has in total 4 parameters.
file_dir(required): the absolute local directory of your EnergyPlus / OpenStudio model (e.g., "/Users/weilixu/Desktop/5ZoneAirCooled.idf")comment(optional): The description of the model version that will be uploaded to your folder. The default message isUpload through Python APIsimulationType(optional): The simulation Type should be generated from SimulationType class. This class manages the simulation type as well as how many agents you want to assign to this simulation job. It should be noted that if this parameter is not used, then create_model method will not run simulationagent(optional): The agent number is a property of SimulationType class. If fast simulation is selected, then the default of agent will be 2.
This method returns two types of information:
If sucess: success
or error message states what was wrong in your request.
The run_simulation() function can be called inside a simulation job if the simulation is not conducted. The function has two parameters:
simulationType(optional): The simulation Type should be generated from SimulationType class. This class manages the simulation type as well as how many agents you want to assign to this simulation job. It should be noted that if this parameter is not used, then create_model method will not run simulationagent(optional): The agent number is a property of SimulationType class. If fast simulation is selected, then the default of agent will be 2.
The track_simulation() function does not require any parameters. However, it is required that a successful cloud simulation is created and running on the cloud. Otherwise, you will receive this message by calling this function:
No simulation is running or completed in this Job - please start simulation using createModel method.
If there is a simulation running on the cloud for this simulationJob, then, this function will return true and you can retrieve the simulation status by get the class parameter trackStatus. Example code is below:
if(newSimulationJob.track_simulation()):
print(newSimulationJob.trackStatus)The get_simulation_results(type) function requires 1 parameter, the result type. Currently, you can retrieve three types of results: the error file (err), eso file (eso) and html file (html), generated from EnergyPlus simulation.
response = newSimulationJob.get_simulation_results('err')
print (response)The model class contains a set of methods that provides the model information and results (after simulation)
- num_total_floor(): can be called before simulation is completed. It returns the number of floors, or -1 if there is an error.
- num_zones(): can be called before simulation is completed. It returns the total number of thermal zones, or -1 if there is an error.
- num_condition_zones(): can be called before simulation is completed. It returns the total number of conditioned zones, or -1 if there is an error.
- conditioned_floor_area (unit): can be called before simulation is completed. It returns the floor areas of conditioned spaces, or -1 if there is an error. This method has an optional input: unit. If you wish to get ft2 unit, then you need to specify 'ip' for the unit parameter:
m.condition_floor_area("ip") - gross_floor_area(unit): can be called before simulation is completed. It returns the total floor areas (including plenum spaces), or -1 if there is an error. This method has an optional input: unit. If you wish to get ft2 unit, then you need to specify 'ip' for the unit parameter:
m.gross_floor_area("ip") - window_wall_ratio(): can be called before simulation is completed. It returns the total window to wall ratio (above floor surface area) or -1 if there is an error.
- new_site_eui(): It returns the net site eui of the simulation (includes generators such as PV). The unit should be based on model specification: SI (kWh/m2 or MJ/m2), IP(kWh/m2).
- total_site_eui(): It returns the total site eui of the simulation. The unit should be based on model specification: SI (kWh/m2 or MJ/m2), IP(kWh/m2).
- not_met_hour_cooling(): returns the time sepoint not met hours during cooling condition period. unit: hour
- not_met_hour_heating(): returns the time sepoint not met hours during heating condition period. unit: hour
- not_met_hour_total(): returns the time sepoint not met hours during heating and cooling condition period. unit: hour
- total_end_use_electricity(): returns the total electricity consumption of the design. unit: kWh or GJ, IP is kBtu
- total_end_use_naturalgas(): returns the total natural gas consumption of the design. unit: kWh or GJ, IP is kBtu
- lastParameterUnit: You can check the value of the variable requested by the most recent API call.
m = newSj.model
print(str(m.net_site_eui())+ " " + m.lastParameterUnit)
#Output: 242.98 MJ/m2
print(str(m.total_end_use_electricity())+ " " + m.lastParameterUnit)
#Output: 156.67 GJ- We are also working on APIs for results retrieving, which let users to get simulation results for post-processing.
- 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.