DesignBuilder Erl

DesignBuilder provides access to the full EnergyPlus Runtime Language (Erl) which is described in detail in the EMS application guide. You can enter Erl script to modify your simulations on the EMS Program dialog.

 

This page describes a powerful set of extensions to Erl which allow code to be made portable between models. Zone loops, if blocks and site, building and zone attributes offer ways to reference the model data without referring to zones by name in the Erl scripts.

 

The combined Erl plus DB extensions language is referred to as DB Erl in the documentation.

 

Note: Erl is case sensitive.

loops

In models having more than one zone it is usually more convenient to write code using loop statements. It is possible to loop through all zones, surfaces and openings in a model. It is also possible to work with only particular zones, surfaces and openings.

Zone Loops

These have the general format:

 

<ForAllZones>,

IF <LoopZoneVariableName>_DeltaT < 0 ,

SET <LoopZoneVariableName>_DeltaT = 0,

ENDIF,

<LoopNextZone>,

 

When code is written in this way it becomes easier to manage, especially in models having more than a handful of zones or where the code is to made portable for use in any model.

 

A summary of all the zone loop-related statements is given in the table below.

 

DB Erl statement Description  

 

Loops

   
<ForAllZones> Loop through all zones in the current building.  
<ForAllOccupiedZones> Loop through all occupied zones in the current building. A zone is considered to be occupied if the Occupancy density is > 0 and the Zone type is 1-Standard.  
<ForAllUnoccupiedZones> Loop through all unoccupied zones in the current building.  
<ForAllOccupiedCooledZones> Loop through all occupied zones in the current building that have the Cooled checkbox on the HVAC tab checked.  
<ForAllOccupiedNonCooledZones> Loop through all zones in the current building that do not have the Cooled checkbox on the HVAC tab checked.  
<ForAllOccupiedHeatedZones> Loop through all occupied zones in the current building that have the Heated checkbox on the HVAC tab checked.  
<ForAllOccupiedNonHeatedZones> Loop through all occupied zones in the current building that do not have the Heated checkbox on the HVAC tab checked.  
<LoopNextZone> End of the zone loop.  
<LoopZoneIDFName> Replace <LoopZoneIDFName> with the IDF zone name of the current zone in the loop.  
<LoopZoneVariableName> Replace <LoopZoneVariableName> with the IDF zone name of the current zone in the loop, but modified to be a legal Erl variable name. <LoopZoneVariableName> returns the same as <LoopZoneIDFName> but with characters ":" and "." replaced by "_".  
<LoopZoneDataFromAttribute AttributeName FieldName>    
<LoopZoneAttribute AttributeName> Look up and replace with current loop zone attribute. E.g. <LoopZoneAttribute OccupancySchedule> might be replaced with Office_Open_off. See full list of valid attribute names below.  

 

Other

   
<Any_Occupied_ZoneIDFName> Replace <Any_Occupied_ZoneIDFName> with the IDF zone name of any occupied zone in the model.  

 

Surface Loops

Opening Loops

DB Erl Statement Description
Loops  
<ForAllWindows> Loop through all window in the current building.
<ForAllExternalWindows> Loop through all external windows in the current building.
<ForAllShadedWindows> Loop through all windows in the current building having the Window shading checkbox on the Openings tab checked.
<ForAllSlattedBlindsShadedWindows> Loop through all windows in the current building having the Window shading checkbox on the Openings tab checked and whose selected Window shading system is from the Slatted blinds category.
<ForAllDiffusingShadedWindows> Loop through all windows in the current building having the Window shading checkbox on the Openings tab checked and whose selected Window shading system is from the Diffusing shades category.
<ForAllElectrochromaticSwitchableShadedWindows> Loop through all windows in the current building having the Window shading checkbox on the Openings tab checked and whose selected Window shading system is from the Window blinds - Electrochromic Switching category.
<LoopNextWindow> End of the window loop.
<LoopWindowIDFName> Replace <LoopWindowIDFName> with the IDF window name of the current window in the loop.
<LoopWindowVariableName> Replace <LoopWindowVariableName> with the IDF name of the current window in the loop modified to be a legal Erl variable name. LoopWindowVariableName is the same as LoopWindowIDFName but with characters ":" and "." replaced by "_".
<LoopWindowDataFromAttribute AttributeNameOfTable FieldName>  
<LoopWindowAttribute AttributeName> Look up and replace with current loop window attribute. E.g. <LoopWindowAttribute RevealOutsideProjection> might be replaced with 0.5 if the Outside reveal depth for the window is 0.5m. See full list of valid attribute names below.

Include/exclude blocks of code

When the DB Erl pre-processor encounters an <If...> directive, followed eventually by an <Endif> directive, it will include the code between the <If...> and the <Endif> only if the boolean expression following <If ... evaluates to True. Otherwise the block of code is not included in the model IDF file.

 

DB Erl statement Description  
<If Boolean expression Then>

Where Boolean expression is an expression evaluating to True or False. E.g.

 

<If BuildingAttribute HourlyOutput = 1 Then>

Erl statements for hourly output

<Endif>

 

Boolean expression must be in the form:

 

  • SiteAttribute, BuildingAttribute, LoopZoneAttribute or LoopWindowAttribute followed by,
  • Attribute name followed by,
  • an operator which must be one of "=, <>, >, <, >=, <=, followed by,
  • Test value. Note for numbered list items, only the number part of should be tested for. e.g.:

 

This is correct:

<If LoopZoneAttribute MechanicalVentilationRateType = 2 Then>,

 

This is incorrect:

<If LoopZoneAttribute MechanicalVentilationRateType = 2-Min Fresh Air (Per Person)

 

 
<Endif> marks the end of the block of text to be included/excluded.  

Parametric Variables

EMS parametric variables can be introduced into the DB Erl script to provide varying settings based on a parametric analysis or optimisation study. The syntax is:

 

<Var, VarName, DefaultValue> VarName is the corresponding variable name used on the Variables dialog. DefaultValue is the value to be used in the script when it used in a non-parametric simulation.  

DB Erl Changes to Standard EnergyPlus Erl

DesignBuilder Erl is identical to the standard Erl language syntax with 1 exception:

 

List of Valid Attribute Names