Summary Outputs (KPIs)

When creating an Objective, Additional Output or Constraint it is necessary to select a Summary output (aka KPI) to define the output involved. This topic summarises the Summary outputs available for selection.

Note: In general, outputs should be selected in the Simulation output options to allow them to be reported as results in Optimisation. For example, The Lighting energy KPI is only reported in parametric simulations when Internal gains including solar are requested as "graphable outputs" in Simulation output options.

List of KPIs

You can find more detailed descriptions of many of these outputs on the Simulation Detailed Results page.

Comfort

All comfort outputs are for the whole building using an area-weighted average of discomfort calculated for each zone. Note that the comfort-related outputs are termed "discomfort" because by convention DesignBuilder aims to minimise objectives and in the context of standardising optimisation outputs it is better to minimise discomfort than to maximise comfort.

 

Cost

Daylight

No daylight-specific KPIs are available in current versions of DesignBuilder.

Energy and Loads

Environmental impact

Heat gains

Unmet loads

The unmet load hours KPIs described below are the same values as those reported in the EnergyPlus Summary report. The Unmet load hours are described in more detail in the ASHRAE 90.1 Appendix G PRM Reference topic and also in the DesignBuilder LEED and ASHRAE 90.1 Appendix G User Guide.

 

Custom script

You can add your own custom script KPIs which allow you to read and, if necessary post-process, simulation results from any EnergyPlus output file or other source and write it to a specific database table using the API. You can use either CS-Script or Python scripts to do this. Note that the name you give to your Custom script KPI is important as it will be used to reference it in the script that you write.

 

The Custom script mechanism works as follows. For each simulation:

 

  1. In the AfterEnergySimulation hook that is called immediately after the simulation has been completed and results have been loaded to DesignBuilder, the script must create a new site level table called "ParamResultsTmp". It is necessary to first remove any existing table of the same name.
  2. The "ParamResultsTmp" table has 2 fields.
  3. Records should be added to the table, one for each custom script KPI used in the simulation.
  4. The first field in each record (index 0) should match the name of the KPI, the second field (index 1) should be the value to be read for this KPI for the current simulation.
  5. DesignBuilder reads the table after the script has finished executing and results are loaded to the parametric (optimisation, UA/SA or parametric analysis) system.

Note: While all simulations will call the AfterEnergySimulation hook, only parametric simulations actually read the ParamResultsTmp table created in the script.

Custom Script KPI Tutorials

The easiest way to understand how custom script KPIs works is to work through the Custom Script KPI tutorials which explain the steps involved:

User defined

No user-defined options are currently available.