Tutorial applies to DesignBuilder v7.0 and later.
DesignBuilder Optimisation, Parametric Analysis and Uncertainty and Sensitivity Analysis tools provide an extensive list of Key Performance Indicators (KPIs) that can be used to assess the performance of building design variants, but in some cases you may need to use your own specific KPIs to assess your design. This example shows how to write a C# or Python script to create your own KPI that reads any EnergyPlus output and links it to an optimisation objective.
The tutorial is based on an example problem to identify the set of design variations that lead to optimal building performance based on Energy Use Intensity (EUI), while at the same time minimising construction cost. Current versions of DesignBuilder don't include a built-in EUI KPI so the tutorial demonstrates how to write a script to access that output from the EnergyPlus results.
Optimal settings for Window To Wall %, Glazing type and Shading overhang length will be identified for the building that provide the lowest EUI while keeping costs as low as possible. Default building component costs and other settings are used throughout to allow us to focus on the Custom Script KPI.
The model has a VRF system and it uses Detailed HVAC to allow EnergyPlus to calculate a realistic EUI value. Simple HVAC does not allow the HVAC energy consumption to be included in the EUI reported by EnergyPlus. The default VRF HVAC template is used.
1. Create a new model located at London Gatwick.
2. Add a building using default settings and draw a rectangular block measuring 20m by 10m with block height of 3.5m as shown below.
3. Load the Generic Office Area Activity template at building level on the Activity Tab.
4. Go to the Lighting tab and switch on Lighting control. This makes for a complex relationship between the façade configuration and heating, cooling and lighting energy consumption which would make it nigh on impossible to pre-guess the outcome without an optimisation analysis.
5. Set the Detailed HVAC model option and load the default VRF with HR and DOAS HVAC template.
Click on the Simulation tab and run a base annual simulation. Because it is a simple model you can select hourly results. Make sure to also choose Monthly results which are required by the Optimisation process. Check the hourly results for the simulation period to ensure that the model is behaving as expected, including temperatures within the building, operations periods etc. Make any adjustments to the model and repeat this step until you are happy with the base model hourly results.
1. Open the Parametric, Optimisation and UA/SA Analysis Settings dialog by clicking on the 
toolbar icon and set the Analysis type on the Analysis tab to 2-Optimisation.
2. Go to the Objectives tab and add 2 new objectives for construction capital cost and EUI. You can either edit the existing objectives or first delete those and create 2 new objectives. The steps involved are described below.
To create the "EUI" objective, a new Summary Output (aka KPI) must be created. Click on the Objective KPI to open the list of existing Summary Outputs in the Info panel. The "EUI" KPI won't be listed there at first, so create it now by clicking on the existing Custom Script Summary Output on the list of KPIs, click on the Create copy of highlighted item Info toolbar icon and edit the clone. Make the following settings on the Summary Output dialog.
Note: The name entered here on the Summary Outputs dialog must match the name given in the custom script described below. You may like to copy the name and paste it somewhere safe where you can easily access it later when writing the script.
Save the newly created KPI and select it on the Optimisation Objectives dialog.
Name the objective "EUI". That name is for your own reference only and unlike the Summary Output name, does not need to match anything else. Select the 1-Min Min/Max option to say that you wish to minimise EUI. The dialog should now look something like the screenshot below.
Now create the cost objective. This is more straightforward as we can use a standard KPI.
Select the Capital cost (Total Capex) KPI and call the objective "Capital Cost". Select the 1-Min Min/Max option to say that you wish to minimise EUI. The objectives dialog should now look like the screenshot below.
With both objectives defined, the Objectives tab should now be set up as follows:
Now set up the design variables. The 3 variables to be included are:
With all 3 variables defined, the Variables tab should now be set up as follows:
The next task is to write the script that will feed the EUI result into the parametric results reading system. Steps are as follows.
1. Click on the Scripts 
toolbar icon to open the Script Manager dialog and click on the Enable scripts checkbox.
2. Click on the Script browse item. A list of the existing scripts appears in the Info panel to the right.
3. Depending on whether your script will be written in C# or Python, click either on the CS-Script or Python-Script category and press the Add new item Info toolbar icon to open the Edit script dialog.
4. Copy and paste the script below into the script window. In summary, the script works as follows. The eplustbl.csv simulation output file is loaded into the EpNet library (when using CS-Script) or to the eppy library (when using Python); the LEED "EAp2-17a. Energy Use Intensity - Electricity" table is opened and the EUI sub-total for Electricity loaded. The script then writes that to a temporary table used by DesignBuilder to pick up custom script results for each optimisation simulation. Our example building is entirely powered by electricity, so the Electricity EUI is also the total EUI.
CS-Script
using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using System.Windows.Forms;
using DB.Api;
using DB.Extensibility.Contracts;
using EpNet;
using EpNet.Results;
namespace DB.Extensibility.Scripts
{
public class RunCustomScript : ScriptBase, IScript
{
public override void AfterEnergySimulation ()
{
// called after simulation is finished but before results are loaded to DB
var tablePath = ApiEnvironment.EnergyPlusFolder + @"eplustbl.csv";
if (File.Exists(tablePath)) {
var tableReader = new TableReader(tablePath);
if (tableReader != null) {
// open the LEED EUI Electricity results table
ResultTable EUITable = tableReader.GetTable("EAp2-17a. Energy Use Intensity - Electricity");
// read the sub total for EUI Electricity
string EUI = EUITable.Rows[7][1].ToString();
// store results in the site level "ParamResultsTmp" table, one record per result
Site site = ApiEnvironment.Site;
site.RemoveTable("ParamResultsTmp");
site.AddTable("ParamResultsTmp", 2);
Table table = site.GetTable("ParamResultsTmp");
// field 0 is the Name of the corresponding SummaryResults record, field 1 is the result
Record record = table.AddRecord();
record[0] = "EUI (kWh/m2)";
record[1] = EUI;
} else {
MessageBox.Show(@"Error creating TableReader");
}
} else {
MessageBox.Show(@"File does not exist " + tablePath);
}
}
}
}
Python-Script
from eppy.results import readhtml
from os import path
from Python_example__Common_methods import show_message
def after_energy_simulation():
tablePath = api_environment.EnergyPlusFolder + r"eplustbl.htm"
if path.exists(tablePath):
filehandle = open(tablePath, 'r').read()
if filehandle is not None:
htables = readhtml.titletable(filehandle)
EUITable = tuple(htable for htable in htables if htable[0] in ['EAp2-17a. Energy Use Intensity - Electricity'])
real_eui_table = EUITable[0]
eui_table_content = real_eui_table[1]
EUI = str(eui_table_content[8][1])
site = api_environment.Site
rem_table = site.RemoveTable("ParamResultsTmp")
add_table = site.AddTable("ParamResultsTmp", 2)
table = site.GetTable("ParamResultsTmp")
record = table.AddRecord()
record[0] = "EUI (kWh/m2)"
record[1] = EUI
else:
show_message("Information", "Error creating TableReader")
else:
show_message("Information", "File does not exist " + tablePath)
Tip: The example EUI scripts and associated optimisation KPIs and objectives described above can of course be easily adapted to report any result included in the EnergyPlus .csv (for EpNet) or .htm (for eppy) output files by making the appropriate modifications.
Click on the Simulation tab and press update to re-run a base annual simulation. Before pressing OK, ensure that you are generating LEED Summary outputs as this data is required by the custom script.
Navigate to the Optimisation + UA/SA tab on the Simulation screen and press the Update toolbar icon to open the Optimisation Calculation Options dialog and make the following settings. These should be the same or similar to the defaults.
Press the Start button to run the optimisation simulations.
After the optimisation has converged and you have closed the Calculation Options dialog, you should see results similar to those below on the main screen.
The optimisation results showing the trade off between EUI and capital cost will be highly dependent on the costs associated with the various building components, especially the glazing, external walls and overhang shading fins. Given the default costs used in this model, we can see that for the very best energy performance at 111.4 kWh/m2, it necessary to spend 319,173 GBP for 45% WWR, double glazed low-e glazing with 1.5m overhangs.
The Pareto graphs (above and below) clearly show that there are diminishing returns in energy savings as more glazing and shading overhang length are added to reduce EUI. Construction costs can be saved by reducing glazing and overhang lengths with a possible "sweet spot" illustrated in the screenshot below with 23% WWR, double glazed low-e glazing and no shading keeping costs down while still keeping EUI low at 114.8 kWh/m2.
