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 create your own specific KPIs to assess a 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;
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
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 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.
Tip: To save time you can copy the above script and paste it into the dialog.
Tip: The DesignBuilderSoftware \ db-scripts Github repository includes the latest versions of the above script as well as other scripts used in DesignBuilder tutorials and examples.
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.
This example is essentially the same as the previous optimisation custom KPI example but it is based on a) a VRF system instead of Unitary Heat Cool and b) the objective is to minimise "EUI" instead of "Total system energy". It is interesting to note that the results in this example are rather more straightforward in that they easily point to a specific configuration whereas the results for the VRF system when using EUI as an objective are more nuanced. Why do you think this might be?
One explanation to consider is that the Unitary Heat Cool system is significantly more energy intensive compared with the VRF system (at least partly because the DesignBuilder Unitary Heat Cool system introduces higher mechanical ventilation fresh air change rates than the default VRF with DOAS template) and so heating and cooling loads dominate over lighting and other loads. This difference will of course influence the conclusions of the analysis.
To test this idea you might like to trying loading a Unitary Heat Cool system to replace the VRF system and see what results you get. Which system leads to the higher EUIs? Are the same set of optimal façade design configurations recommended?
Tip: One takeaway for anyone having completed both this tutorial and the previous one, is that even when you are analysing fabric/facade only design variables, the type of HVAC system used can influence the decision-making process! If you know that the design will use a VRF system then it's important to set that up in the model used for the optimisations. That way the right balance of heating and cooling influence will be included in the overall result. If you only consider zone loads then you miss out on the difference between heating and cooling efficiency. In general you should think carefully about what the results are telling you and about any assumptions that may be built into them. As always it helps to understand the base model and its results well before running the optimisations.