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

 

The Operational cost (Opex) and LCC total present value KPIs both require the Detailed HVAC model option to be used as they use settings on the Economics model data tab which is only available for Detailed HVAC.

 

The LCC total present value values calculated in optimisation and other parametric simulations will only correspond with the value calculated directly by EnergyPlus if the basis for calculation is the same. In practice this means that the following 2 requirements must be met:

 

 

This should be the case for models created in v7.

Tip: You can carry out powerful analyses to simultaneously optimise whole life cycle cost and whole life cycle environmental impact performance using DesignBuilder's optimisation tools. Choose the LCC and LCA KPIs for this sort of analysis.

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.