Skip to content

examples

Jump to bottom
Weili edited this page Jul 6, 2018 · 4 revisions

Use Cases

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 measure

import BuildSimHubAPI as bshapi

project_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 simulation
results = 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.

import BuildSimHubAPI as bshapi

project_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 modifications
new_model_api = new_sj.parameter_batch_modification('Lights', 'Watts per Zone Floor Area', value=6.2, track_token=model_api_key)
# run simulation
results = 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.

import BuildSimHubAPI as bshapi

project_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 object
model = bsh.model_results(project_api_key, model_api_key)
new_sj = bsh.new_simulation_job(project_api_key)

if model.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 simulation
    results = 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.

import BuildSimHubAPI as bsh_api
project_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.

import BuildSimHubAPI as bsh_api
project_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.

import pandas as pd
def post_process_models(df):  
    param_list = list()  
    for index, row in df.iterrows():  
        msg = row['commit_msg']  
        parameters = msg.split(',')  
        data_dict = dict()  
        for k in range(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)  
    return pd.concat([df, parameter_df], axis=1)

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

import BuildSimHubAPI as bshapi  

# 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.

import BuildSimHubAPI as bshapi
import os
import time
import pandas

# get your project key
project_api_key = 'f98aadb3-254f-428d-a321-82a6e4b9424c'
# location where you want to store the models
folder_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 model
df = df[df.commit_msg != 'INIT']

for index, row in df.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 local
    full_path = os.path.join(folder_dir, row['commit_msg'] + '.idf')
    print('Write the model to the file: ' + full_path)
    with open(full_path, 'w') as file:
        file.write(content)
        file.close()
    print('Done!')

BuildSimHub Inc

Home / Blog / Twitter@buildsim / LinkedIn@buildsim

Clone this wiki locally