Customise Your Optimisation, Parametric Analysis and UA/SA Analyses with Custom Scripts

When it comes to optimising real-world building configurations, it can be frustrating when the list of built-in variable types and KPIs provided with the software does not include exactly what you are trying to assess in your analysis. To help you avoid running into this sort of limitation, DesignBuilder now allows more adventurous modellers to create their own variable types and KPIs using simple scripts.



Custom Variables
In addition to an extensive set of built in variable types, DesignBuilder also offers 3 ways to set up custom variables:

• Custom Script variables provide an extremely flexible way to control the exact impact of each variable change on the model via our extensive API. For example, a Custom Script variable could be used when setting up a natural ventilation optimisation where zone setpoint temperatures are linked and optimal values are to be identified. So if the design variable is heating setpoint temperature, the natvent setpoint may need to be adjusted to ensure a minimum deadband between the 2 setpoints to avoid simultaneous heating and venting. This sort of behaviour can easily be set up in a custom script by ensuring that the natvent setpoint is always higher than the heating setpoint by at least the deadband value.
• Custom EMS variables allow you to vary the parameters used in your EMS scripts. EMS provides custom simulation runtime control to override selected aspects of standard EnergyPlus behaviour, and with EMS variables you can parametrically adjust any number of parameters within your scripts. For example, if you have used an EMS script to implement a custom controller for an HVAC system and you aren't sure about the best values for some parameters in the controller logic, you can set them up as variables and run an optimisation study to identify optimum settings based on the objectives that you provide. 
• Custom IDF variables are similar to Custom Script variables except that in this case the parametric changes are made to the EnergyPlus IDF input file rather than to the model.

Custom KPIs
DesignBuilder comes with an extensive list of built-in KPI options that can be selected for objectives, constraints, or other outputs. However, if you ever need to work with your own performance metrics then you can create a custom KPI by writing a script. 

For example, there is no built-in Energy Use Intensity (EUI) KPI, however, the Program help provides an example script that shows how to set this up. The same method can be used to create a KPI based on any EnergyPlus output found in the EnergyPlus Summary output tables.

DesignBuilder comes with several example scripts that you can use as templates and modify based on your own requirements to help you get started. You can learn for example how to create your own comfort KPIs designed especially for use in optimisation studies such as “PPD % discomfort area” and “TM52 occupant discomfort”.

The step-by-step optimisation tutorials in the Program help are a great place to start when learning how to use custom variables and KPIs.