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. Loops, If logic statements and access to model attributes offer ways to reference the model data without referring to zones, surfaces and windows 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> Signals the end of the zone loop.  

In-Loop Place Holders 		   
<LoopZoneIDFName> Place holder is replaced with the IDF zone name of the current zone in the loop. E.g. Block1:Zone1  
<LoopZoneVariableName> Place holder is replaced with a version of the the IDF zone name which has been modified to be a legal Erl variable name (“:”, “.” and “?” replaced by "_"). E.g. Block1:Zone1 becomes Block1_Zone1  
<LoopZoneDataFromAttribute AttributeName FieldName> Looks up the component or template stored in AttributeName for the current loop and replaces the place holder with the value of the FieldName field.  
<LoopZoneAttribute AttributeName> Looks up the value of AttributeName and uses it instead of the place holder. E.g. <LoopZoneAttribute ZoneMultiplier> might be replaced with 1 or <LoopZoneAttribute OccupancySchedule> might be replaced with Office_Open_off. See full list of valid attribute names.  

 

Boolean

    
<If LoopZoneAttribute a < b Then> Boolean expression. E.g. <If LoopZoneAttribute MechanicalVentilationRateType = 2 Then>  
<If ZoneLoopValue a < b Then> Boolean expression. Using a value rather than an attribute. Often used in conjunction with <LoopZoneDataFromAttribute AttributeName FieldName>. e.g. <If ZoneLoopValue <LoopZoneAttribute ActivityTemplate AllGainsValue> > 10 Then>  

 

Other

    
<Any_Occupied_ZoneIDFName> Replace <Any_Occupied_ZoneIDFName> with the IDF zone name of any occupied zone in the model. (Actually, the first occupied zone it comes across while looping through.)  

 

Surface Loops

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

 

Loops  
<ForAllSurfaces> Loop through all surfaces in the current building.
<ForAllExternalSurfaces> Loop through all external surfaces in the current building.
<ForAllInternalSurfaces> Loop through all internal surfaces in the current building.
<LoopNextSurface> Signals the end of the surface loop.

In-Loop Place Holders 		 
<LoopSurfaceIDFName> Place holder is replaced with the IDF surface name of the current surface in the loop. E.g. Block1:Zone1_Wall_2_0_0
<LoopSurfaceVariableName> Place holder is replaced with a version of the the IDF surface name which has been modified to be a legal Erl variable name (“:”, “.” and “?” replaced by "_"). E.g. Block1:Zone1_Wall_2_0_0 will become Block1_Zone1_Wall_2_0_0
<LoopSurfaceAttribute AttributeName> Looks up the value of AttributeName and uses it instead of the place holder. E.g. <LoopSurfaceAttribute SillHeight> might be replaced with 0.8
<LoopSurfaceDataFromAttribute AttributeName FieldName> Looks up the object stored in AttributeName for the current loop and replaces the place holder with the value of FieldName. E.g. <LoopSurfaceAttribute WallConstr NumberLayers> might be replaced with 4
<LoopSurfaceZoneIDFName> Place holder is replaced with the IDF name of the zone that the current surface is in. E.g. Block1:Zone1_Wall_2_0_0 is in Block1:Zone1
<LoopSurfaceZoneVariableName> Place holder is replaced with the Erl variable name of the zone that the current surface is in. E.g. Block1:Zone1_Wall_2_0_0 is in Block1:Zone1, which becomes Block1_Zone1

Boolean 		 
<If LoopSurfaceAttribute a < b Then> Boolean expression. E.g. <If LoopSurfaceAttribute FixedExternalWallThickness = 1 Then> (Checkboxes: 1 means checked, 0 means unchecked)
<If SurfaceLoopValue a < b Then> Boolean expression. Using a value rather than an attribute. Often used in conjunction with <LoopSurfaceDataFromAttribute AttributeName FieldName> E.g <If SurfaceLoopValue <LoopSurfaceDataFromAttribute WallConstr NumberLayers> = 4 Then>

Window Loops

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

 

DB Erl Statement Description

Loops 		 
<ForAllWindows> Loop through all windows 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.
<ForAllTransparentInsulationShadedWindows> Loop through all windows with internal shading of type Transparent Insulation in the current building.
<ForAllMultipleStateElectrochromicShadedWindows> Loop through all windows with internal shading of type SageGlass Electrochromic in the current building.
<LoopNextWindow> End of the window loop.

In-Loop Place Holders 		 
<LoopWindowIDFName> Place holder is replaced with the IDF window name of the current window in the loop. E.g. Block1:Zone1_Wall_2_0_0
<LoopWindowVariableName> Place holder is replaced with a version of the IDF window name which has been modified to be a legal Erl variable name (“:”, “.” and “?” replaced by "_"). Block1:Zone1_Wall_2_0_0 would become Block1_Zone1_Wall_2_0_0
<LoopWindowAttribute AttributeName> Looks up the value of window AttributeName and uses it instead of the place holder. E.g. <LoopWindowAttribute InternalBlindControlSolar> might be replaced with 120 or <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.
<LoopWindowZoneAttribute AttributeName> Looks up the value of the parent zone AttributeName attribute and uses it instead of the place holder. A typical application would be to access the zone "Occupancy Schedule" to obtain the availability schedule for "Follow Occupancy" operation), or "Activity Template" to filter windows using the parent zone activity.
<LoopWindowDataFromAttribute AttributeNameOfTable FieldName> Looks up the component or template stored in the window AttributeName attribute for the current loop item and replaces the place holder with the value of FieldName. E.g. <LoopWindowAttribute GlazingType Layers> might be replaced with 2 if the glazing for the current window has 2 layers.

Boolean Expressions 		 
<If LoopWindowAttribute a < b Then> Boolean expression. E.g. < If LoopWindowAttribute InternalBlind =1 Then> (Checkboxes: 1 means checked, 0 means unchecked)
<If WindowLoopValue a < b Then>

Boolean expression using a value rather than an attribute. Often used in conjunction with <LoopWindowDataFromAttribute AttributeName FieldName> E.g. <If WindowLoopValue <LoopWindowAttribute GlazingType Layers> >= 2 Then>

 

Optional Arguments

Optional arguments can be used with any loop type to further refine the included loops, filtering out data that is not required.

 

Optional Argument What it does Where it works
Tag Excludes any object that does not match the tag. Case sensitive. All attribute levels.
MaxSlope Excludes any surface or opening that has a slope value higher than this value. External surfaces and openings.
MinSlope Excludes any surface or opening that has a slope value less than this value. External surfaces and openings.
MaxOrientation Excludes any surface or opening that has an orientation value higher than this value. External surfaces and openings.
MinOrientation Excludes any surface or opening that has an orientation value less than this value. External surfaces and openings.
ZoneIDFName Excludes any zone, surface or opening that is in a zone that does not include this text anywhere in its name. Matching is case sensitive. Zone, surface and opening.
ActivityTemplate Excludes any objects that do not have the indicated Activity template loaded. The argument value must match exactly with the template but the matching is case insensitive. Building, zone, surface and opening.
LightingTemplate Excludes any objects that do not have the indicated Lighting template loaded. The argument value must match exactly with the template but the matching is case insensitive. Building, zone, surface and opening.
HVACTemplate Excludes any objects that do not have the indicated HVAC template loaded. The argument value must match exactly with the template but the matching is case insensitive. Building, zone, surface and opening.
GlazingTemplate Excludes any objects that do not have the indicated Glazing template loaded. The argument value must match exactly with the template but the matching is case insensitive. Building, zone, surface and opening.
ConstructionTemplate Excludes any objects that do not have the indicated Construction template loaded. The argument value must match exactly with the template but the matching is case insensitive. Building, zone, surface and opening.

 

The format of an optional argument is: {argument=value}

Note: There must be at least a single space between “>” and “{“.

If multiple alternative values are acceptable for an argument, the format is: {argument=value1//value2}. In this case the code is executed if the argument is either equal to value1 OR value2. See examples below.

 

Multiple arguments can be included, if they are separated by “;”.

Examples

< ForAllExternalSurfaces> {MinSlope=89;MaxSlope=91} to loop through external vertical walls only.
<ForAllWindows> {ZoneIDFName=Floor1}

to loop through windows in zones in block "floor 1".
<ForAllOccupiedZones> {ActivityTemplate=Domestic Bedroom}

to loop through occupied bedrooms.
<ForAllOccupiedZones> {ActivityTemplate=Domestic Bedroom//Domestic Bathroom} to loop through occupied bedrooms and bathrooms.
<ForAllZones> {LightingTemplate=LED; ZoneIDFName=Floor1//Floor2} to loop through all zones with LED lights on floor 1 and floor 2

Note: While loops can be nested, it is only possible to use conditional arguments in the outermost loop statement.

Boolean Expressions - 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

Custom 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 key used on the Variables dialog. DefaultValue is the value to be used in the script when it used in a standard, non-parametric simulation.  

DB Erl Changes to Standard EnergyPlus Erl

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