Knowledgebase
Customise Your Optimisation, Parametric Analysis and UA/SA Analyses with Custom Scripts
Posted by Luis Sousa on 30-Jul-21 01:55 PM
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 do 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 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 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 which 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.

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.