examples

Use Cases

• How to modify a model
• How to modify a model with conditions
• How to retrieve a model's results?
• How to retrieve parametric study results?
• How to download all the models generated in a parametric study?

How to modify a model?

There are two different ways to modify a model:

1. Modify the model by applying BuildSim standard energy efficiency measures (EEMs).
2. Modify the model parameters.

Assume we need to change the lighting power density in the medium-size reference office building (Download here).

# This example shows how to modify the LPD in a model using # lighting power density measureimportBuildSimHubAPIasbshapiproject_api_key='f9dsadb3-253f-438c-a321-82aew4b9424e'model_api_key='609da2acf-de2-44fa-9883-a0df8bdsdb56'# start cloud client bsh=bshapi.BuildSimHubAPIClient()
new_sj=bsh.new_simulation_job(project_api_key)
# add light power density measure the list measure_list=list() light=bshapi.measures.LightLPD() light.set_data(6.0)
measure_list.append(light)
# apply measure - you will get a new model key (e.g.: 1-11-111), rerun the new model new_model_api=new_sj.apply_measures(measure_list, track_token=model_api_key)
# Run simulationresults=new_sj.run_model_simulation(new_model_api, unit='si', track=True)
print(str(results.net_site_eui)) +' '+results.last_parameter_unit)

The second method is using the BuildSim parameter batch modifications. Since changing the LPD only involves update the Watts per Zone Floor Area parameter in Lights object, so we should be able to do it through this method.

importBuildSimHubAPIasbshapiproject_api_key='f9dsadb3-253f-438c-a321-82aew4b9424e'model_api_key='609da2acf-de2-44fa-9883-a0df8bdsdb56'# start cloud client bsh=bshapi.BuildSimHubAPIClient()
new_sj=bsh.new_simulation_job(project_api_key)
# batch parameter modificationsnew_model_api=new_sj.parameter_batch_modification('Lights', 'Watts per Zone Floor Area', value=6.2, track_token=model_api_key)
# run simulationresults=new_sj.run_model_simulation(new_model_api, unit='si', track=True)
print(str(results.net_site_eui)) +' '+results.last_parameter_unit)

How to modify a model with conditions

To modify a model with conditions usually requires

1. Understand the parameters or systems set in the current model
2. Modify the correspondent parameteres.

Let's use the previous lighting power density as an example again. Assume we need to change the LPD if the current LPD is greater than 10.7 W/m2.

importBuildSimHubAPIasbshapiproject_api_key='f9dsadb3-253f-438c-a321-82aew4b9424e'model_api_key='609da2acf-de2-44fa-9883-a0df8bdsdb56'# start cloud client bsh=bshapi.BuildSimHubAPIClient()
# initialize a model object and a simulation objectmodel=bsh.model_results(project_api_key, model_api_key)
new_sj=bsh.new_simulation_job(project_api_key)
ifmodel.bldg_lpd() >=10.7:
new_model_api=new_sj.parameter_batch_modification('Lights', 'Watts per Zone Floor Area', value=6.2, track_token=model_api_key)
# run simulationresults=new_sj.run_model_simulation(new_model_api, unit='si', track=True)
print(str(results.bldg_lpd())) +' '+results.last_parameter_unit)

How to retrieve a model's results?

Once you have completed a simulation, you will receive a model API key or a model track token. The model API key looks like UIUD and the track token is something looks like 1-11-1111. The differences between these two keys are explained in the Getting started. Despite the differences, both keys work for retrieving a model's results.

importBuildSimHubAPIasbsh_apiproject_api_key='f9dsadb3-253f-438c-a321-82aew4b9424e'model_api_key='609da2acf-de2-44fa-9883-a0df8bdsdb56'# model_track_token = "1-11-111"bsh=bsh_api.BuildSimHubAPIClient()
# This works too:# results = bsh.model_results(project_api_key, model_track_token)results=bsh.model_results(project_api_key, model_api_key)
print(str(results.net_site_eui()) +' '+results.last_parameter_unit)

The results object contains all the information about the simulation results. Detail list of data that you can extract from the BuildSim Cloud is listed in Simulation Results page.

How to retrieve a parametric study results?

Unlike the results from a single model, retrieving results from parametric study requires a project API key and a model API key.

importBuildSimHubAPIasbsh_apiproject_api_key='f9dsadb3-253f-438c-a321-82aew4b9424e'model_api_key='609da2acf-de2-44fa-9883-a0df8bdsdb56'bsh=bsh_api.BuildSimHubAPIClient()
# This works too:results=bsh.parametric_results(project_api_key, model_api_key)
print(str(results.net_site_eui()) +' '+results.last_parameter_unit)

Use Pandas to retrieve simulation results

The parametric study usually involves hundreds of simulations. By using the parametric result object, we can extract the same result value from these simulations. However, parametric is a part of approach for exploring the best design. So we still have to decide which design we want to pursue after the study. Once we have determined a design among hundreds of simulations, how can we dive deeper to investigate the details of that particular simulation? Before we do that, we need a function to process the model list. You will need pandas package for this function.

importpandasaspddefpost_process_models(df): param_list=list() forindex, rowindf.iterrows(): msg=row['commit_msg'] parameters=msg.split(',') data_dict=dict() forkinrange(len(parameters)): title, val=parameters[k].split(':') data_dict[title.strip()] =float(val.strip()) param_list.append(data_dict) parameter_df=pd.DataFrame(param_list) returnpd.concat([df, parameter_df], axis=1)

Then, let's apply the filters on the models:

importBuildSimHubAPIasbshapi# paste your project_api_key and model_api_key here project_api_key='f9dsadb3-253f-438c-a321-82aew4b9424e'model_api_key='609da2acf-de2-44fa-9883-a0df8bdsdb56'bsh=bshapi.BuildSimHubAPIClient() data_list=bsh.model_list(project_api_key, model_api_key)
post_df=post_process_models(df) val=post_df.loc[(post_df['HeatingEff'] ==0.88) & (post_df['LPD'] ==0.858)]['commit_id'] model_id=val.values[0]
# extract the single model eui results=bsh.model_results(project_api_key, model_id) print(str(results.net_site_eui()) +' '+results.last_parameter_unit)

You have successfully extract the net site eui of the simulation, whose heating efficiency is 88% and lighting power density is 0.858 W/ft2.

How to download all the models generated in a parametric study

You can download all the models under a parametric study with a for loop.

importBuildSimHubAPIasbshapiimportosimporttimeimportpandas# get your project keyproject_api_key='f98aadb3-254f-428d-a321-82a6e4b9424c'# location where you want to store the modelsfolder_dir='/Users/download/'model_api_key='bd70dc9c-633c-4a2c-8bac-4f4032a7d7'bsh=bshapi.BuildSimHubAPIClient()
data_list=bsh.model_list(project_api_key, model_api_key)
df=pd.DataFrame(data_list) # drop the seed modeldf=df[df.commit_msg!='INIT']
forindex, rowindf.iteritems(): model=bsh.model_results(project_api_key, row['commit_id'])
print('Downloading the model: '+key)
content=model.download_model()
time.sleep(5)
# save to a file in localfull_path=os.path.join(folder_dir, row['commit_msg'] +'.idf')
print('Write the model to the file: '+full_path)
withopen(full_path, 'w') asfile:
file.write(content)
file.close()
print('Done!')