Parametric

Parametric Simulation

Quick start
Energy Efficient Measures
Start Parametric Run
Monte Carlo

Quick Start

import BuildSimHubAPI as bsh_api

# 1. Set project and model key  
project_api_key = 'f98aadb3-254f-428d-82a6e4b9424c'  
model_api_key = '48003d7a-143f-45c1-4ab4d1968bbd'

# start running parametric simulation
bsh = bsh_api.BuildSimHubAPIClient()
new_pj = bsh.new_parametric_job(project_api_key)
new_pj.submit_parametric_study_local(model_api_key, track=True)

This is the minimum code to start a parametric study. However, since there is no energy efficient measures defined in the above code, the effect of this code is essentially the same as a single simulation.

Now, let's dig deeper to see how we can do a proper parametric study.

Energy Efficient Measures

BuildingOrientation():

# This measure changes the orientation of the building 
# (Apply to Class: Building, Field: North Axis)
# The value unit should be deg.

import BuildSimHubAPI as bsh_api

bldg_orientation = bsh_api.measures.BuildingOrientation()
# define the list of data.
data = [0, 90, 180, 270]
bldg_orientation.set_datalist(data)

WallRValue(unit)

# This changes the R-value of the wall insulation layer
# Since this measure only changes the insulation layer, so the overall R-value
# of the construction could be slightly higher.

import BuildSimHubAPI as bsh_api

wall_rvalue = bsh_api.measures.WallRValue('ip')
# define the list of data.
data = [20, 30, 40]
wall_rvalue.set_datalist(data)

RoofRValue(unit)

# This changes the R-value of the roof insulation layer. 
# For the attic roof, the floor and ceiling insulation will be changed.
# Since this measure only changes the insulation layer, so the overall R-value
# of the construction could be slightly higher.

import BuildSimHubAPI as bsh_api

roof_rvalue = bsh_api.measures.RoofRValue('si')
# define the list of data.
data = [5.0, 6.0, 7.0]
roof_rvalue.set_datalist(data)

RoofSolarAbsorption()

# This update the solar absorption on the outmost material layer of the roof construction.
import BuildSimHubAPI as bsh_api

roof_solar_absorption = bsh_api.measures.RoofSolarAbsorption()
# define the list of data.
data = [0.2, 0.3 ,0.4]
roof_solar_absorption.set_datalist(data)

WindowUValue(unit)

# Update window u value to building or by orientations
# if using the simple window method, this will change the U-value
# if using the detailed method (layer-by-layer), this will delete the window construction and then generate WindowMaterial:SimpleGlazingSystem with 0.4 SHGC or the SHGC value specified in SHGC measure
import BuildSimHubAPI as bsh_api

window_u = bsh_api.measures.WindowUValue('si')
# If apply the measure to an orientation, e.g. South: 
# window_u = bsh_api.measures.WindowUValue('si', orientation='S')

# define the list of data.
data = [3.2, 2.2 ,1.8]
window_u.set_datalist(data)

WindowSHGC()

# Update window SHGC value to the building, or by orientations
# if using the simple window method, this will change the SHGC
# if using the detailed method (layer-by-layer), this will delete the window construction and then generate WindowMaterial:SimpleGlazingSystem with 2.2 W/m2-K Window U-value or the U-Value measure specified in window u value measure

import BuildSimHubAPI as bsh_api

window_shgc = bsh_api.measures.WindowSHGC()
# If apply the measure to an orientation, e.g. South: 
# window_shgc = bsh_api.measures.WindowSHGC(orientation='S')

# define the list of data.
data = [0.3, 0.4 ,0.5]
window_shgc.set_datalist(data)

WindowWallRatio()

# This measure proportionally changes the WWR at one or all orientations to match the overall target WWR.
# If shrink (target WWR is smaller than actual model WWR) - reduce the size of the windows to the target value
# If expand (target WWR is larger than actual model WWR) - delete all the windows and redraw windows on each surface 
# that matches the target value

# The target value should be specified as an absolute value instead of the percentage.

import BuildSimHubAPI as bsh_api

wwr = bsh_api.measures.WindowWallRatio()
# If apply the measure to an orientation, e.g. South: 
# wwr = bsh_api.measures.WindowWallRatio(orientation='S')

# define the list of data.
data = [0.3, 0.4 ,0.5]
wwr.set_datalist(data)

ShadeFin()

# This measure add Fin to the left and right side of windows on one or all orientations
# The value should be the depth of Fins
# If set to 0, it means there is no Fin

import BuildSimHubAPI as bsh_api

fin = bsh_api.measures.ShadeFin()
# If apply the measure to an orientation, e.g. South: 
# fin = bsh_api.measures.ShadeFin(orientation='S')

# define the list of data.
data = [0.5, 1.0 ,1.5]
fin.set_datalist(data)

ShadeOverhang()

# This measure adds the overhang to every window on one or all orientations
# The data is the depth of overhangs
# If set to 0, it means there are no overhangs

import BuildSimHubAPI as bsh_api

overhang = bsh_api.measures.ShadeOverhang()
# If apply the measure to an orientation, e.g. South: 
# overhang = bsh_api.measures.ShadeOverhang(orientation='S')

# define the list of data.
data = [0.5, 1.0 ,1.5]
overhang.set_datalist(data)

LightLPD(unit)

# change the building lighting power density
# This will set every zone to a single LPD value

import BuildSimHubAPI as bsh_api

lpd = bsh_api.measures.LightLPD('ip')
# define the list of data.
data = [0.8, 1.2 ,1.5]
lpd.set_datalist(data)

LightLPDPercent()

# apply percentage change of LPD - 
# the value should be absolute value instead of the percentage
# e.g. 0.4 for 40%

import BuildSimHubAPI as bsh_api

lpd_percent = bsh_api.measures.LightLPDPercent('ip')
# define the list of data - LPD change to 40%, 80% and 120%
data = [0.4, 0.8 ,1.2]
lpd_percent.set_datalist(data)

EquipmentEPD()

# change the equipment power density (use in caution - this will change kitchen appliances)
# Use this measure in caution. This will set every zone to a single LPD value

import BuildSimHubAPI as bsh_api

epd = bsh_api.measures.EquipmentEPD('ip')
# define the list of data.
data = [0.8, 1.2 ,1.5]
epd.set_datalist(data)

EquipmentEPDPercent()

# apply percentage changes to equipment power
# the value should be absolute value instead of the percentage
# e.g. 0.4 for 40%
import BuildSimHubAPI as bsh_api

epd_percent = bsh_api.measures.EquipmentEPDPercent('ip')
# define the list of data - EPD change to 40%, 80% and 120%.
data = [0.4, 0.8, 1,2]
epd_percent.set_datalist(data)

OccupancySensor()

# Occupancy sensor has only 1 (yes) and 0 (no) two options. If applied, 10% LPD credit will be added to all the lights classes.

import BuildSimHubAPI as bsh_api
occ_sensor = bsh_api.measures.OccupancySensor()

DaylightingSensor()

# Daylighting sensor has only 1 (yes) and 0 (no) two options. If applied, the location of the sensor will be placed in the middle of the floor, which has the longest exterior perimeter line.
import BuildSimHubAPI as bsh_api
occ_sensor = bsh_api.measures.DaylightingSensor()

CoolingCOP()

# Apply COP changes to all coils and chillers - Do not use it with cooling coil COP and chiller COP measures!
import BuildSimHubAPI as bsh_api
cop = bsh_api.measures.CoolingCOP()
data = [3.5, 4.5, 5.5]
cop.set_datalist(data)

CoolingChillerCOP()

# Apply COP changes to all chillers - Do not use it with cooling COP, as cooling COP measure may override all chiller COPs
import BuildSimHubAPI as bsh_api
cop_chiller = bsh_api.measures.CoolingChillerCOP()
data = [3.5, 4.5, 5.5]
cop_chiller.set_datalist(data)

CoolingCoilCOP()

# Apply COP changes to all coils- Do not use it with cooling COP, as cooling COP measure may override all coil COPs
import BuildSimHubAPI as bsh_api
cop_coils = bsh_api.measures.CoolingCoilCOP()
data = [3.5, 4.5, 5.5]
cop_coils.set_datalist(data)

HeatingDXEfficiency()

# Apply COP changes to all heating DX coils 
import BuildSimHubAPI as bsh_api
cop_coils = bsh_api.measures.HeatingDXEfficiency()
data = [2.8, 3.4, 4.2]
cop_coils.set_datalist(data)

HeatingEfficiency()

# Apply thermal efficiencies to burners, furnaces, and boilers
import BuildSimHubAPI as bsh_api
furnace_eff = bsh_api.measures.HeatingEfficiency()
data = [0.8, 0.85, 0.9]
furnace_eff.set_datalist(data)

WaterHeaterEfficiency()

# change the thermal efficiency of water heaters (exclude heat pump water heaters)
import BuildSimHubAPI as bsh_api
water_heater_eff = bsh_api.measures.WaterHeaterEfficiency()
data = [0.8, 0.85, 0.9]
water_heater_eff.set_datalist(data)

WaterUseReduction()

# apply percentage changes to the water use 
# the value should be absolute value instead of the percentage
# e.g. 0.4 for 40%

import BuildSimHubAPI as bsh_api
water_use = bsh_api.measures.WaterUseReduction()
data = [0.6, 0.8, 1.2]
water_use.set_datalist(data)

Infiltration()

# apply infiltration percent changes to infiltration / or default values
# the value should be absolute value instead of the percentage
# e.g. 0.4 for 40%

import BuildSimHubAPI as ash_api
infiltration = bsh_api.measures.Infiltration()
# If apply measure without specify datalist, the measure will apply default values
# The default include loosely insulated (0.01024128 m3/s-m2), average insulated (0.001024128 m3/s-m2) and well insulated (0.0001024128 m3/s-m2).
# else:
data = [0.4, 0.8, 1.2]
infiltration.set_datalist(data)
# this will change the infiltration to 40%, 80% or 120% of current infiltration.

DemandControl()

# This measure will attempt to add a demand control to an existing HVAC system in the IDF file
# If the seed model has mechanical ventilation object,
# this measure will turn on / off the mechanical ventilation object


# If the seed model has no mechanical ventilation object but the decision value is 1 (On)
# This measure will insert mechanical ventilation object - 
# based on original zone OA design and OA distribution effectiveness

# If OA design is missing - insert typical office space OA using sum method (ASHRAE 62.1)
# If OA distribution effectiveness is missing - insert 1.0 (Cooling) 0.8 (Heating) method (ASHRAE 90.1)

import BuildSimHubAPI as bsh_api
demand_control = bsh_api.measures.DemandControl()
# Since this is an on/off boolean style measure, user does not required to supply design inputs

HeatRecovery()

# This measure will attempt to add a heat recovery to an existing HVAC system in the IDF file
# If the seed model has heat exchange object in OA system,
# this measure will turn on / off the mechanical ventilation object

# If the seed model has no heat exchange object but the decision value is 1 (On)
# This measure will insert heat exchange object - 
# With: 0.7 at 100% sensible heating and 0.75 at 100% sensible cooling

import BuildSimHubAPI as bsh_api
heat_recovery = bsh_api.measures.HeatRecovery()
# Since this is an on/off boolean style measure, user does not required to supply design inputs

HVACTemplate()

# This measure will change the HVAC system in the idf file
# This measure only supports EnergyPlus version 8.7 and above
#        The HVAC system types are:
#        0. sys1: PTAC
#        1. sys2: PTHP
#        2. sys3: PSZ-AC
#        3. sys4: PSZ-HP
#        4. sys5: Packaged VAV with Reheat
#        5. sys6: Packaged VAV with PFP Boxes
#        6. sys7: VAV with Reheat
#        7. sys8: VAV with PFP Boxes
#        8. sys9: Warm air furnace, gas fired
#        9. sys10: Warm air furnace, electric
#        10. doasvrf: DOAS with variable refrigerant flow
#        11. doasfancoil: DOAS with Fan coils
#        12. doaswshp: DOAS with water source heat pump (ground as condenser)
#        13. DOAS with active cool beam + convective baseboard
import BuildSimHubAPI as bsh_api

hvac_template = bsh_api.measures.HVACTemplate()
data = [1,3,5,7,10]
hvac_template.set_datalist(data)

Customized EEMs

It is allowed to customize your own EEMs with BuildSim Cloud. There are two types of customizable EEMs a user can define.

Continuous variable EEMs: This EEMs supports continuous variables in the parametric study. For instance, varying the lighting power density from 6.0 to 12.0 W/m2
Discrete variable EEMs: This EEMs supports discrete variables in the parametric study. For instance, a user has three types of chillers and wants the parametric study test out these three chillers

Start Parametric Run

Initialize the study

import BuildSimHubAPI as bsh_api  
import BuildSimHubAPI.postprocess as pp  
  
# 1. set your folder key  
project_key = 'f98aadb3-254f-428d-82a6e4b9424c'  
file_dir = "/Users/Desktop/5ZoneAirCooled.idf"  
  
bsh = bsh_api.BuildSimHubAPIClient()   
new_pj = bsh.new_parametric_job(project_key)

Apply measures Apply window wall ratio and lighting power density measures to the parametric study.

measure_list = list()
# Define EEMs  
wwr = bsh_api.measures.WindowWallRatio()  
wwr_ratio = [0.6, 0.4]  
wwr.set_datalist(wwr_ratio)  
  
lpd = bsh_api.measures.LightLPD('ip')  
lpdValue = [1.2, 0.9]  
lpd.set_datalist(lpdValue)

measure_list.append(wwr)
measure_list.append(lpd)

# add measure list to the parametric study
new_pj.add_model_measures(measure_list)

Run parametric simulation

results = new_pj.submit_parametric_study_local(file_dir, track=True)

The full script example can be found in this link.

submit_parametric_study()

If the seed model is on the cloud instead of local, the parametric can also pick up this model on the cloud to run parametric study

model_api_key = "48003d7a-143f-45c-4ab4d1968bbd"

new_pj = bsh.new_parametric_job(project_key, model_api_key)
# ... measures

results = new_pj.submit_parametric_study( track=True)

Monte Carlo Method

The Monte Carlo method is the broad class of computational algorithms that rely on repeated random sampling to obtain numerical results. It is often used in optimization, parameter sensitivity analysis, as well as generating training data for AI algorithms. The BuildSim Cloud implements latin hypercube sampling to generate random variables. This type of MC algorithms explores the distributions of multi-variable more effectively with fewer samples. For most of the building design problems, research demonstrated that around 200-250 samples should be enough to provide a high-resolution dataset for design analysis.

A full example of using Monte Carlo method is included in the monte_carlo_test.py.

Define energy efficient measure

It is different to define an energy efficiency measure for Monte Carlo than the regular parametric.

wwrn = bsh_api.measures.WindowWallRatioNorth()
# set max and min
wwrn.set_min(0.3)
wwrn.set_max(0.6)
measure_list.append(wwrn)

We need to define the maximum and minimum values for each energy efficiency measure so that the sampling algorithm can sample values from this range.

Activate the algorithm

To activate the algorithm, we can start from the regular parametric study:

results = new_pj.submit_parametric_study(algorithm='montecarl', size=200, track=True)

and the rest will be exactly the same as the regular parametric study.

To learn more about how to retrieve the results from the parametric study, check out Parametric Simulation Results.

BuildSimHub Inc

Home / Blog / Twitter@buildsim / LinkedIn@buildsim

Provide feedback

Saved searches

Use saved searches to filter your results more quickly