Custom EnergyPlus Reports

EnergyPlus supports literally thousands of different output reports and DesignBuilder v3.2 supports only the most generally useful of these.

DesignBuilder developers are working on a much more flexible reporting mechanism which will provide access to all of the EnergyPlus output reports in a future version. In the meantime, if you need to view specific reports not provided by DesignBuilder, you can follow a process which gives access to any of the EnergyPlus reports while continuing to run your EnergyPlus simulations from within DesignBuilder. In summary the process is as follows:

1. For HVAC system node temperature, mass flow and humidity ratio outputs make the appropriate selections under the Miscellaneous Outputs on the Outputs tab of the Simulation Calculation options dialog.
2. Any other extra reports required can be added to an IDF file stored in the DesignBuilder EnergyPlus folder.
3. Include this IDF file by making a selection in DesignBuilder Simulation Calculation Options.
4. Run the simulation as normal from DesignBuilder.
5. Locate the EnergyPlus eso output file generated by the simulation.
6. View the eso output file using the 3rd party xEsoView utility.

The sections below describe each of the these stages in more detail.

1. Selecting Additional Reports

The purpose of this stage is to create a text file in EnergyPlus IDF format which contains a description of the extra reports required. The text in this file will be added to the end of the main EnergyPlus IDF input file before it is read by EnergyPlus.

You should refer to the main EnergyPlus help file InputOutputReference.pdf for descriptions of all of the EnergyPlus reports and for a detailed description of the required text format. If you are not familiar with the IDF text formats then you can use the EnergyPlus IDF editor instead to create the file.

Note: The DesignBuilder Support Desk isn't able to respond to questions relating to EnergyPlus use outside DesignBuilder. DesignBuilder users wishing to use EnergyPlus outside DesignBuilder should direct their EnergyPlus questions to the EnergyPlus Support Desk.

Nevertheless here is a brief description which should help you to get started with adding reports to an IDF file.

There are 2 ways to edit IDF data:

• In any text editor such as Notepad (which comes with Windows) or UltraEdit (an excellent commercial text editor which includes an IDF keyword highlight option).
• Using the IDF Editor supplied with EnergyPlus.

The text editor method is described below.

Create a file having extension .IDF and add IDF text to it in the format described below.

IDF Report Variable Format

The format used by EnergyPlus to define the "reports" (output data) required is described below.

A single "report" can be thought of as a single set of output data or alternatively as a line of data on a graph and is defined using a single line of text using this syntax:

Output:Variable, <Object name>, <Report Name>, <Interval>

• Output:Variable is an IDF keyword which indicates that what follows is a request for output data.
• <Object name> is the name of the object for which data is required, e.g. the zone or the HVAC component name. In some cases it is possible to enter "*" to indicate that the data is required for all relevant objects (e.g. all zones).
• <Report Name> is the name of the report (output data) required. Thousands of reports are available in all and you should refer to the EnergyPlus help file for details on what is available.
• <Interval> should be one of the following keywords:
  

   

  • Monthly
  • Daily
  • Hourly
  • Timestep - corresponds to the sub-hourly interval in DesignBuilder terminology.
  • Detailed - a special interval provided by EnergyPlus where detail down to the level of the HVAC timesteps can be provided. the actual intervals reported will often vary during the simulation, but it can at times provide useful debugging information.

For example to generate a new hourly data set for the "Time Heating Setpoint Not Met While Occupied" report for the zone having IDF name "Block1:Zone1" add this line of text to the IDF file:

Output:Variable, Block1:Zone1, Time Heating Setpoint Not Met While Occupied, hourly;

To generate sub-hourly data on the activity of the ideal loads economiser for all zones use:

Output:Variable, *, Ideal Loads Time Economizer Active, timestep;

Note the use of the "*" character to mean all objects and the semi-colon at the end of the line. For further clarification on how to specify requests for EnergyPlus outputs you can refer to the Output:Variable data provided by DesignBuilder in previously generated IDF files.

The above is just one way of obtaining outputs. Once familiar with EnergyPlus reports you can be creative with use of additional IDF to request further outputs. For example consider using these options.

System node conditions

To view all system node temperatures, mass flow rates and humidity conditions in a model simply add these 3 lines to the IDF file:

Output:Variable, *, System Node Temp, hourly;

Output:Variable, *, System Node MassFlowRate, hourly;

Output:Variable, *, System Node Humidity Ratio, hourly;

This data can be very useful when checking operation of the HVAC system.

Tariff Analysis

These reports can be used to run very sophisticated tariff analyses in EnergyPlus:

UtilityCost:Tariff

UtilityCost:Qualify

UtilityCost:Charge:Simple

UtilityCost:Charge:Block

UtilityCost:Ratchet

UtilityCost:Variable

UtilityCost:Computation

This example from the EnergyPlus manual shows how to specify a basic utility cost (e.g. cost of kWh of electricity). The data indicates that Electricity costs a flat 0.08 (currency e.g. - $ or £) per kWh.

TariffExample1,

Electricity:Facility,

kWh;

UtilityCost:Charge:Simple,

ChargeExample1,

TariffExample1,

totalEnergy,

Annual,

EnergyCharges,

0.08;

Life-cycle cost analysis

By adding IDF text you can specify data for construction cost estimating and life cycle cost data for a full life-cycle cost analysis. The relevant reports are as follows:

ComponentCost:Adjustments

ComponentCost:Reference

ComponentCost:LineItem

LifeCycleCost:Parameters

LifeCycleCost:RecurringCosts

LifeCycleCost:NonrecurringCost

LifeCycleCost:UsePriceEscalation

LifeCycleCost:UseAdjustment

Many more examples are provided in the EnergyPlus documentation.

RDD file

You can obtain a full list of available report types for a particular DesignBuilder model by running a quick simulation and viewing the eplusout.rdd file generated by EnergyPlus.

Note: for each zone, surface and opening in the DesignBuilder model, the IDF name for the object used the last simulation is displayed on the Options tab.

2. Include the IDF file

Select the IDF file using the controls on the Simulation tab of the Model options dialog under the Advanced header.

Note: The file must be located in the EnergyPlus folder.

3. Run the simulation

Run the simulation as usual from DesignBuilder.

4. Locate the EnergyPlus eso file

The eplusout.eso output file generated by EnergyPlus can be found in the EnergyPlus folder. If you wish to keep the output file for future analysis then you should make a copy and rename the copy for future reference because eplusout.eso will be overwritten during the next simulation.

5. View the eso file

The recommended way to view EnergyPlus results in eso files is through the Results Processor.

Alternatively you can xESOView, which is a free basic software 3rd party utility. It is not a perfect tool and outputs are not presentation quality but the software can be very useful for quickly checking results. xESOView can be downloaded from:

http://xesoview.sourceforge.net/

Once the program is installed, double-clicking on the eso file in Windows Explorer opens the file and loads it into xEsoView.

The screenshot above shows an example of how to use xEsoView to display the supply air mass flow rate into a zone.

Note: The DesignBuilder Support Desk cannot provide support for use of xEsoView