Simulation
import BuildSimHubAPI as bsh_api
project_api_key = '7e140eec-b37f-4213-88b5f96c0065'
file_dir = "/Users/desktop/5ZoneAirCooled_UniformLoading.epJSON"
wea_dir = "/Users/desktop/in.epw"
# initialize the client
bsh = bsh_api.BuildSimHubAPIClient()
new_sj_run = bsh.new_simulation_job(project_api_key)
results = new_sj_run.run(file_dir, wea_dir, track=True)Above is the minimum code to run a cloud energy simulation. It requires a .idf file and .epw file as well as project_api_key to complete a successful run. More details about the run() method can be found in run.
One of BuildSim Cloud mission is to make the simulation as simple as possible without going through all the struggles. It intelligently handles many simulation parameters - including the EnergyPlus version, simulation job types, run period, unit system and external files.`
To kick-off a single model simulation, a user is required to start a new simulation job object.
import BuildSimHubAPI as bsh_api
project_api_key = "7e140eec-b37f-4213-88b5f96c0065"
bsh = bsh_api.BuildSimHubAPIClient()
new_sj = bsh.new_simulation_job(project_api_key)Run() function is the most straightforward method to request for cloud simulation.
It should be noted that this function will use the CPUs in the project, but the model uploaded to the BuildSim Cloud does not belong to the project. This is because each project has an associate weather file (.epw), but this function allows users to submit a different weather file than the project.
However, you can always find the model in the Simulation Dashboard page.
file_dir = "/Users/desktop/5ZoneAirCooled.epJSON"
wea_dir = "/Users/desktop/in.epw"
new_sj.run(file_dir, wea_dir)If user turned on track, the run function will return the simulation results object.
file_dir = "/Users/desktop/5ZoneAirCooled.epJSON"
wea_dir = "/Users/desktop/in.epw"
results = new_sj.run(file_dir, wea_dir, track=True)
""" output:
Submitting simulation request...
Received server response
Preprocessing... 0%
Initializing Simulation... 17%
January... 22%
February... 28%
March... 33%
...
"""file_dir = ["/Users/desktop/5ZoneAirCooled.epJSON",
"/Users/desktop/5Zone.idf"]
wea_dir = "/Users/desktop/in.epw"
new_sj.run(file_dir, wea_dir, track=True)
""" Output
Total progress 0%, success: 0, failure: 0, running: 2, queue: 0
Total progress 0%, success: 0, failure: 0, running: 2, queue: 0
Total progress 0%, success: 0, failure: 0, running: 2, queue: 0
Total progress 0%, success: 0, failure: 0, running: 2, queue: 0
Total progress 50%, success: 0, failure: 0, running: 1, queue: 0
Total progress 50%, success: 0, failure: 0, running: 1, queue: 0
"""file_dir = "/Users/desktop/5ZoneAirCooled.epJSON"
wea_dir = "/Users/desktop/in.epw"
# set to every 10 sec to track simulation status
results = new_sj.run(file_dir, wea_dir, track=True, request_time=10)file_dir = "/Users/desktop/5ZoneAirCooled.epJSON"
wea_dir = "/Users/desktop/in.epw"
# The default is ip unit
# new_sj.run(file_dir, wea_dir, unit='ip', track=True)
new_sj.run(file_dir, wea_dir, unit='si')Using up to 4 CPUs to run one simulation is typically faster than just one CPU. This method will divide an anual simulation model into 4 seasons and run 4 in parallel, and BuildSim Cloud will automatically combine the 4 season simulation results.
file_dir = "/Users/desktop/5ZoneAirCooled.epJSON"
wea_dir = "/Users/desktop/in.epw"
# only accept 1, 2, and 4 cores for a simulation
new_sj.run(file_dir, wea_dir, agent=4)This function is intended to be more comprehensive but currently it only works with .csv files as hourly schedule.
file_dir = "/Users/desktop/5ZoneAirCooled.epJSON"
wea_dir = "/Users/desktop/in.epw"
add_folder = "/Users/desktop/csvschedule"
# group all the csv schedules under one folder.
new_sj.run(file_dir, wea_dir, add_files=add_folder)- create_run_model(file_dir, add_files=None, unit='ip', agent=1, comment="Python API", track=False, request_time=5)
This function uploads an energy model from local computer to the target project, and run the simulation. Once the simulation is completed, you can find the model under the target project.
file_dir = "/Users/desktop/5ZoneAirCooled.idf"
new_sj.create_run_model(file_dir)file_dir = "/Users/desktop/5ZoneAirCooled.idf"
results = new_sj.create_run_model(file_dir, track=True)
""" output:
Submitting simulation request...
Received server response
Preprocessing... 0%
Initializing Simulation... 17%
January... 22%
February... 28%
March... 33%
...
"""file_dir = "/Users/desktop/5ZoneAirCooled.idf"
# set to every 10 sec to track simulation status
results = new_sj.create_run_model(file_dir, track=True, request_time=10)file_dir = "/Users/desktop/5ZoneAirCooled.idf"
# new_sj.create_run_model(file_dir, unit='ip')
new_sj.create_run_model(file_dir, unit='si')Using up to 4 CPUs to run one simulation is typically faster than just one CPU. This method will divide an anual simulation model into 4 seasons and run 4 in parallel, and BuildSim Cloud will automatically combine the 4 season simulation results.
file_dir = "/Users/desktop/5ZoneAirCooled.idf"
wea_dir = "/Users/desktop/in.epw"
# only accept 1, 2, and 4 cores for a simulation
new_sj.create_run_model(file_dir, agent=4)This function is intended to be more comprehensive but currently it only works with .csv files as hourly schedule.
file_dir = "/Users/desktop/5ZoneAirCooled.idf"
add_folder = "/Users/desktop/csvschedule"
# group all the csv schedules under one folder.
new_sj.create_run_model(file_dir, add_files=add_folder)This API function uploads a model to the target project with no simulation. It serves a quick check on building basic information such as window wall ratio and floor area before a simulation (see example: )
file_dir = "/Users/desktop/5ZoneAirCooled.epJSON"
new_sj.create_model(file_dir)file_dir = "/Users/desktop/5ZoneAirCooled.epJSON"
new_sj.create_model(file_dir)This function request to run an un-simulated model on the Cloud. It is typically used after create_model function (example), or parameter_batch_modification, or apply_measures
# retrieve the model api key or track token first
model_api_key = "7e140eec-b37f-4213-88b5f96c0065"
# track_token = "1-11-111"
results = new_sj.run_model_simulation(model_api_key)If user turned on track, the run function will return the simulation results object.
# retrieve the model api key or track token first
model_api_key = "7e140eec-b37f-4213-88b5f96c0065"
# track_token = "1-11-111"
results = new_sj.run_model_simulation(model_api_key, track=True)# retrieve the model api key or track token first
model_api_key = "7e140eec-b37f-4213-88b5f96c0065"
# track_token = "1-11-111"
results = new_sj.run_model_simulation(model_api_key,
track=True, request_time=10)# retrieve the model api key or track token first
# model_api_key = "7e140eec-b37f-4213-88b5f96c0065"
track_token = "1-11-111"
results = new_sj.run_model_simulation(track_token,unit='si')Using up to 4 CPUs to run one simulation is typically faster than just one CPU. This method will divide an anual simulation model into 4 seasons and run 4 in parallel, and BuildSim Cloud will automatically combine the 4 season simulation results.
# retrieve the model api key or track token first
# model_api_key = "7e140eec-b37f-4213-88b5f96c0065"
track_token = "1-11-111"
results = new_sj.run_model_simulation(track_token,agent=4)Work with create_model:
file_dir = "/Users/desktop/5ZoneAirCooled.epJSON"
new_sj.create_model(file_dir)
results = new_sj.run_model_simulation(track=True)Full example link.
Work with parameter_batch_modification
# modify all the lights power density, and run the simulation on the modified model
new_model_api = new_sj.parameter_batch_modification('Lights', 'Watts per Zone Floor Area', value=6.2)
results = new_sj.run_model_simulation(new_model_api, track=True)Full example link
Work with apply_measures
new_model_api = new_sj.apply_measures(measure_list)
results = new_sj.run_model_simulation(new_model_api, track=True)Full example link
This function allows user to modify a model's parameter. Specify the class_label and field_label to identify the class in the model
model_api_key = "7e140eec-b37f-4213-88b5f96c0065"
new_model_api = new_sj.parameter_batch_modification('Lights', 'Watts per Zone Floor Area', value=6.2, model_api_key)
results = new_sj.run_model_simulation(new_model_api, unit='ip', track=True)Apply energy measures on a seed model and simulate the new model.
It should be noted that once this method is called, the simulation job class will update its track_token and model_api_key to the new model.
The measure list has to be a python list object, and every element must inherit from the BuildSimHubAPI.measures.ModelAction.
# add light power density measure the list
measure_list = list()
daylit = bshapi.measures.DaylightingSensor()
measure_list.append(daylit)
# apply measure - you will get a new model key (e.g.: 1-11-111), re-run the new model
new_model_api = new_sj.apply_measures(measure_list)
results = new_sj.run_model_simulation(new_model_api, track=True)