BuiltIn Functions[LINK]
Several useful, builtin functions are available for use in Erl programs. You cannot configure these; they are internal to the language processor inside EnergyPlus. They provide access to a subset of general service routines that are useful inside the main EnergyPlus program or are intrinsic functions available in the underlying Fortran language. The “@” character is used to signal to the language processor that the following character string defines a builtin function that is used to assign a result to an Erl variable. The characters appended to the “@” operator must be one of the predefined names listed in Table 1, Table 2, Table 3, or Table 4. The syntax of the function call will vary depending on the arguments required by the function, but the general structure is:
SET <variable> = @<function name> <argument1> <argument2> … <argumentN>
Where “argument” can be either an Erl variable or a numeric constant.
For example, the following two statements can be used to set the value of an Erl variable called mySupplyRH to have percent relative humidity.
SET mySupplyRH = @RhFnTdbWPb mySupplyDryblub mySupplyHumRat mySupplyPress
SET mySupplyRH = mySupplyRH * 100
Builtin Math Functions[LINK]
Table 1 lists the builtin functions for common mathematical functions. The numerical model for these functions is provided by the underlying Fortran language and the compiler.
Builtin Math Functions for Erl
@Round 
Decreases precision of real number argument to nearest whole number, remains a real number. 
1 
@Mod 
Returns remainder after dividing the first argument by the second. 
2 
@Sin 
Sine, returns sine of angle given in radians. 
1 
@Cos 
Cosine, returns cosine of angle given in radians. 
1 
@ArcSin 
Arcsine, returns angle in radians from sine of angle. 
1 
@ArcCos 
ArcCosine, returns angle in radians from cosine of angle. 
1 
@DegToRad 
Degrees to radians, returns radians from degrees. 
1 
@RadToDeg 
Radians to degrees, returns degrees from radians. 
1 
@Exp 
Exponential, e , returns result. 
1 
@Ln 
Natural log, log (x), returns result. 
1 
@Max 
Maximum, returns largest value of two arguments. 
2 
@Min 
Minimum, returns smallest value of two arguments. 
2 
@Abs 
Absolute value, returns positive magnitude of argument. 
1 
@RandomUniform 
PseudoRandom Number Generator, returns random number with uniform probability distribution across the range of values passed as the arguments, inclusive. Argument 1 is the lower limit. Argument 2 is the upper limit. 
2 
@RandomNormal 
PseudoRandom Number Generator, returns random number with normal (Gaussian) probability distribution as a function of the mean, standard deviation, and limits. Argument 1 is the mean. Argument 2 is the standard deviation. Argument 3 is the lower limit. Argument 4 is the upper limit. 
4 
@SeedRandom 
Random Seed, controls the seed used in the random number generator for calls to @RandomUniform and @RandomNormal. Use is optional and provided for repeatable series of random numbers. The argument is rounded to the nearest whole number and then used to set the size and values of the seed for the number generator. 
1 
BuiltIn Simulation Management Functions[LINK]
Builtin EnergyPlus Simulation Management Functions for Erl
@FatalHaltEp 
Throws fatal error with time of occurrence and stops execution of current model. Argument passes a number that can be used as an error code. 
1 
@SevereWarnEp 
Throws severe error with time of occurrence and continues execution. Argument passes a number that can be used as an error code. 
1 
@WarnEp 
Throws warning error and continues execution. Argument passes a number that can be used as an error code. 
1 
Builtin Trend Variable Functions[LINK]
For control algorithms, you often need to be able put a sensor reading into some historical context. The trend variables are provided in Erl as a way to log the time history of data to use in control decisions. To use the trend variables in Erl programs, their values must be extracted and placed into normal Erl variables. Setting up an Erl variable as a trend variable requires an EnergyManagementSystem:TrendVariable input object. The access functions listed in Table 3 are used to obtain data from a trend variable during the execution of an Erl program. These functions act on trend variables and return values into the user’s Erl variables for subsequent use in calculations. Each trend function takes the name of the trend variable and an index that identifies how far back in time the function should be applied. Trend variable names are also Erl variables but with special pointers to another data structure with the time series data storage. The trend logs have a firstin, firstout storage array where only the most recent data are retained. Each element in the history corresponds to the result for that value over a zone timestep. The time difference between trend log items is the zone timestep in hours, so that the slope returned by @TrendDirection is in perhour units.
Builtin Functions for Trend Variables in Erl
@TrendValue 
Returns history value for a particular number of timesteps into the past. Dereferences data stored in trend into another Erl variable. Takes trend variable name and the specific timestep into the past to return. 
2 
@TrendAverage 
Returns historical average (mean) for values in trend variable. Takes trend variable name and number of steps into the past to analyze 
2 
@TrendMax 
Returns historical maximum for values in trend variable. Takes trend variable name and number of steps into the past to analyze. 
2 
@TrendMin 
Returns historical minimum for values in trend variable within the index. Takes trend variable name and number of steps into the past to analyze. 
2 
@TrendDirection 
Returns slope of a linear least squares fit of trend data within the index. Positive if trend is increasing, negative if decreasing. Takes trend variable name and number of steps into the past to analyze. 
2 
@TrendSum 
Returns sum of elements stored in trend. Takes trend variable name and number of steps into the past to analyze. 
2 
The trend functions all take as their second argument an array index. This number should be considered an integer for locating an array position. (It will be rounded down to the nearest integer using Fortran’s FLOOR intrinsic.) This index argument tells the trend functions how far back in time they should reach into the history log when they evaluate the function call. This enables you to compare long and shortrange trends.
Builtin Psychrometric Functions[LINK]
Building modeling often involves calculations related to moist air. A comprehensive set of builtin functions is available for psychrometric calculations. Table 4 lists the functions available for use in Erl programs that are related to moist air properties and some physical properties related to water. More discussion of the psychrometric functions is provided in the section “Pyschrometric services” in the Module Developer Guide.
Builtin Psychrometric Functions for Erl
@RhoAirFnPbTdbW 
Result 
Density of moist air 
kg/m < sup > 3 < /sup > 
Input 1 
Barometric pressure 
Pa 

Input 2 
Drybulb temperature 
°C 

Input 3 
Humidity ratio 
kgWater/kgDryAir 

@CpAirFnW 
Result 
Heat capacity of moist air 
J/kg°C 
Input 1 
Humidity ratio 
kgWater/kgDryAir 

@HfgAirFnWTdb’ 
Result 
Heat of vaporization for vapor 
J/kg 
Input 1 
Humidity ratio 
kgWater/kgDryAir 

Input 2 
Drybulb temperature 
°C 

@HgAirFnWTdb 
Result 
Enthalpy of the gas 

Input 1 
Humidity ratio 
kgWater/kgDryAir 

Input 2 
Drybulb temperature 
°C 

@TdpFnTdbTwbPb 
Result 
Dewpoint temperature 
°C 
Input 1 
Drybulb temperature 
°C 

Input 2 
Wetbulb temperature 
°C 

Input 3 
Barometric pressure 
Pa 

@TdpFnWPb 
Result 
Dewpoint temperature 
°C 
Input 1 
Humidity ratio 
kgWater/kgDryAir 

Input 2 
Barometric pressure 
Pa 

@HFnTdbW 
Result 
Enthalpy of moist air 
J/kg 
Input 1 
Drybulb temperature 
°C 

Input 2 
Humidity ratio 
kgWater/kgDryAir 

@HFnTdbRhPb 
Result 
Enthalpy of moist air 
J/kg 
Input 1 
Drybulb temperature 
°C 

Input 2 
Relative humidity 
Fraction (0.0 .. 1) 

Input 3 
Barometric pressure 
Pa 

@TdbFnHW 
Result 
Drybulb temperature 
°C 
Input 1 
Enthalpy of moist air 
J/kg 

Input 2 
Humidity ratio 
kgWater/kgDryAir 

@RhovFnTdbRh 
Result 
Vapor density in air 
kg/m < sup > 3 < /sup > 
Input 1 
Drybulb temperature 
°C 

Input 2 
Relative humidity 
Fraction (0.0 .. 1) 

@RhovFnTdbWPb 
Result 
Vapor density in air 
kg/m < sup > 3 < /sup > 
Input 1 
Drybulb temperature 
°C 

Input 2 
Humidity ratio 
kgWater/kgDryAir 

Input 3 
Barometric pressure 
Pa 

@RhFnTdbRhov 
Result 
Relative humidity 
Fraction (0.0 .. 1) 
Input 1 
Drybulb temperature 
°C 

Input 2 
Vapor density in air 
kg/m < sup > 3 < /sup > 

@RhFnTdbWPb 
Result 
Relative humidity 
Fraction (0.0 .. 1) 
Input 1 
Drybulb temperature 
°C 

Input 2 
Humidity ratio 
kgWater/kgDryAir 

Input 3 
Barometric pressure 
Pa 

@TwbFnTdbWPb 
Result 
Wetbulb temperature 
°C 
Input 1 
Drybulb temperature 
°C 

Input 2 
Humidity ratio 
kgWater/kgDryAir 

Input 3 
Barometric pressure 
Pa 

@VFnTdbWPb 
Result 
Specific volume 
m < sup > 3 < /sup > /kg 
Input 1 
Drybulb temperature 
°C 

Input 2 
Humidity ratio 
kgWater/kgDryAir 

Input 3 
Barometric pressure 
Pa 

@WFnTdpPb 
Result 
Humidity ratio 
kgWater/kgDryAir 
Input 1 
Dewpoint temperature 
°C 

Input 2 
Barometric pressure 
Pa 

@WFnTdbH 
Result 
Humidity ratio 
kgWater/kgDryAir 
Input 1 
Drybulb temperature 
°C 

Input 2 
Enthalpy of moist air 
J/kg 

@WFnTdbTwbPb 
Result 
Humidity ratio 
kgWater/kgDryAir 
Input 1 
Drybulb temperature 
°C 

Input 2 
Wetbulb temperature 
°C 

Input 3 
Barometric pressure 
Pa 

@WFnTdbRhPb 
Result 
Humidity ratio 
kgWater/kgDryAir 
Input 1 
Drybulb temperature 
°C 

Input 2 
Relative humidity 
Fraction (0.0 .. 1) 

Input 3 
Barometric pressure 
Pa 

@PsatFnTemp 
Result 
Saturation pressure 
Pa 
Input 1 
Drybulb temperature 
°C 

@TsatFnHPb 
Result 
Saturation temperature 
°C 
Input 1 
Enthalpy of moist air 
J/kg 

Input 2 
Barometric pressure 
Pa 

@CpCW 
Result 
Heat capacity of water 
J/kg 
Input 1 
Temperature 
°C 

@CpHW 
Result 
Heat capacity of water 
J/kg 
Input 1 
Temperature 
°C 

@RhoH2O 
Result 
Density of water 
kg/m < sup > 3 < /sup > 
Input 1 
Temperature 
°C 

Builtin Curve and Table Functions[LINK]
EnergyPlus has a number of different generic curve and table input objects that are used to describe the performance characteristics for various component models. Table 5 describes a builtin function called @CurveValue that is available for reusing those curve and table input objects in your Erl programs. Although the Erl language could be used to replicate the functionality, reusing those input objects can have advantages because the input may have already been developed for use in traditional component models or the limiting and interpolation methods are helpful. The @CurveValue function expects six arguments, although usually only a subset of them will be used depending on the number of independent variables involved with the curve or table. Because Erl does not support passing optional arguments, dummy variables do need to be included in the function call for all unused independent variables. For example, the Curve:Biquadratric object has only x and y independent variables, so input arguments 4, 5, and 6 will not be used when @CurveValue is evaluated:
Set MyCurveResult = @CurveValue myCurveIndex X1 Y1 dummy dummy dummy;
Note that although version 8.6 of EnergyPlus introduced changes to not allow uninitialized variables in expressions, @CurveValue has an exception to this for backward compatibility. @CurveValue only issues errors to the EDD file and does not fatal when called with uninitialized dummy variables.
The first input argument is always an Erl variable that has been declared using an EnergyManagementSystem:CurveOrTableIndexVariable input object. This variable identifies the location of a specific curve or table in the program’s internal data structures. It is important that you do not inadvertently reassign the value held in this variable because it is only filled once at the beginning of the simulation.
Builtin Function for Accessing Curves and Tables
@CurveValue 
Result 
Result from evaluating the curve or table as a function of the input arguments 

Input 1 
Index variable that “points” to a specific curve or table object defined elsewhere in the IDF. 
This variable needs to be declared and filled using an EnergyManagementSystem:CurveOrTableIndexVariable object. 

Input 2 
First independent variable 
Typically the “X” input value, always used 

Input 3 
Second independent variable 
Typically the “Y” value, only used if curve/table has two or more independent variables 

Input 4 
Third independent variable 
Typically the “Z” value, only used if curve/table has three or more independent variables. 

Input 5 
Fourth independent variable 
Only used if table has four or more independent variables 

Input 6 
Fifth independent variable 
Only used if table has five independent variables 

Builtin Weather Data Functions[LINK]
EnergyPlus sets up 24 hours of weather data for Today and Tomorrow during DesignDay setup or based on incoming data from the weather file (epw). This data is used as the basis for setting the environment variables for a given zone timestep in WeatherManager::SetCurrentWeather. This data can be useful for predictive control or for setting Weather Data actuator overrides based on the incoming weather data using the BeginZoneTimestepBeforeSetCurrentWeather calling point.
Table 6 describes a set of builtin functions to access this weather data. For all of these functions, the first argument is the hour (from 0 to 23) and the second argument is the zone timestep number (from 1 to number of timesteps per hour). To access the current timestep use internal variables “Hour”’ and “TimeStepNum”:
@TodayBeamSolarRad Hour TimeStepNum,
Builtin Functions for Accessing Today and Tomorrow Weather Data
@TodayIsRain 
Rain indicator, 1.0 = raining 

@TodayIsSnow 
Snow indicator, 1.0 = snow on ground 

@TodayOutDryBulbTemp 
Outdoor drybulb temperature 
°C 
@TodayOutDewPointTemp 
Outdoor dewpoint temperature 
°C 
@TodayOutBaroPress 
Outdoor barometric pressure 
pascal 
@TodayOutRelHum 
Outdoor relative humidity 
percent 
@TodayWindSpeed 
Wind speed 
m s^{−1}

@TodayWindDir 
Wind direction (N = 0, E = 90, S = 180, W = 270) 
degrees 
@TodaySkyTemp 
Sky temperature 
°C 
@TodayHorizIRSky 
Horizontal infrared radiation rate per area 
W m^{−2}

@TodayBeamSolarRad 
Direct normal solar irradiance 
W m^{−2}

@TodayDifSolarRad 
Diffuse horizontal solar irradiance 
W m^{−2}

@TodayAlbedo 
Ratio of ground reflected solar to global horizontal irradiance (unused) 
dimensionless 
@TodayLiquidPrecip 
Liquid precipitation depth 
mm 
@TomorrowIsRain 
Rain indicator, 1.0 = raining 

@TomorrowIsSnow 
Snow indicator, 1.0 = snow on ground 

@TomorrowOutDryBulbTemp 
Outdoor drybulb temperature 
°C 
@TomorrowOutDewPointTemp 
Outdoor dewpoint temperature 
°C 
@TomorrowOutBaroPress 
Outdoor barometric pressure 
pascal 
@TomorrowOutRelHum 
Outdoor relative humidity 
percent 
@TomorrowWindSpeed 
Wind speed 
m s^{−1}

@TomorrowWindDir 
Wind direction (N = 0, E = 90, S = 180, W = 270) 
degrees 
@TomorrowSkyTemp 
Sky temperature 
°C 
@TomorrowHorizIRSky 
Horizontal infrared radiation rate per area 
W m^{−2}

@TomorrowBeamSolarRad 
Direct normal solar irradiance 
W m^{−2}

@TomorrowDifSolarRad 
Diffuse horizontal solar irradiance 
W m^{−2}

@TomorrowAlbedo 
Ratio of ground reflected solar to global horizontal irradiance (unused) 
dimensionless 
@TomorrowLiquidPrecip 
Liquid precipitation depth 
mm 
BuiltIn Functions[LINK]
Several useful, builtin functions are available for use in Erl programs. You cannot configure these; they are internal to the language processor inside EnergyPlus. They provide access to a subset of general service routines that are useful inside the main EnergyPlus program or are intrinsic functions available in the underlying Fortran language. The “@” character is used to signal to the language processor that the following character string defines a builtin function that is used to assign a result to an Erl variable. The characters appended to the “@” operator must be one of the predefined names listed in Table 1, Table 2, Table 3, or Table 4. The syntax of the function call will vary depending on the arguments required by the function, but the general structure is:
SET <variable> = @<function name> <argument1> <argument2> … <argumentN>
Where “argument” can be either an Erl variable or a numeric constant.
For example, the following two statements can be used to set the value of an Erl variable called mySupplyRH to have percent relative humidity.
SET mySupplyRH = @RhFnTdbWPb mySupplyDryblub mySupplyHumRat mySupplyPress
SET mySupplyRH = mySupplyRH * 100
Builtin Math Functions[LINK]
Table 1 lists the builtin functions for common mathematical functions. The numerical model for these functions is provided by the underlying Fortran language and the compiler.
BuiltIn Simulation Management Functions[LINK]
Builtin Trend Variable Functions[LINK]
For control algorithms, you often need to be able put a sensor reading into some historical context. The trend variables are provided in Erl as a way to log the time history of data to use in control decisions. To use the trend variables in Erl programs, their values must be extracted and placed into normal Erl variables. Setting up an Erl variable as a trend variable requires an EnergyManagementSystem:TrendVariable input object. The access functions listed in Table 3 are used to obtain data from a trend variable during the execution of an Erl program. These functions act on trend variables and return values into the user’s Erl variables for subsequent use in calculations. Each trend function takes the name of the trend variable and an index that identifies how far back in time the function should be applied. Trend variable names are also Erl variables but with special pointers to another data structure with the time series data storage. The trend logs have a firstin, firstout storage array where only the most recent data are retained. Each element in the history corresponds to the result for that value over a zone timestep. The time difference between trend log items is the zone timestep in hours, so that the slope returned by @TrendDirection is in perhour units.
The trend functions all take as their second argument an array index. This number should be considered an integer for locating an array position. (It will be rounded down to the nearest integer using Fortran’s FLOOR intrinsic.) This index argument tells the trend functions how far back in time they should reach into the history log when they evaluate the function call. This enables you to compare long and shortrange trends.
Builtin Psychrometric Functions[LINK]
Building modeling often involves calculations related to moist air. A comprehensive set of builtin functions is available for psychrometric calculations. Table 4 lists the functions available for use in Erl programs that are related to moist air properties and some physical properties related to water. More discussion of the psychrometric functions is provided in the section “Pyschrometric services” in the Module Developer Guide.
Builtin Curve and Table Functions[LINK]
EnergyPlus has a number of different generic curve and table input objects that are used to describe the performance characteristics for various component models. Table 5 describes a builtin function called @CurveValue that is available for reusing those curve and table input objects in your Erl programs. Although the Erl language could be used to replicate the functionality, reusing those input objects can have advantages because the input may have already been developed for use in traditional component models or the limiting and interpolation methods are helpful. The @CurveValue function expects six arguments, although usually only a subset of them will be used depending on the number of independent variables involved with the curve or table. Because Erl does not support passing optional arguments, dummy variables do need to be included in the function call for all unused independent variables. For example, the Curve:Biquadratric object has only x and y independent variables, so input arguments 4, 5, and 6 will not be used when @CurveValue is evaluated:
Set MyCurveResult = @CurveValue myCurveIndex X1 Y1 dummy dummy dummy;
Note that although version 8.6 of EnergyPlus introduced changes to not allow uninitialized variables in expressions, @CurveValue has an exception to this for backward compatibility. @CurveValue only issues errors to the EDD file and does not fatal when called with uninitialized dummy variables.
The first input argument is always an Erl variable that has been declared using an EnergyManagementSystem:CurveOrTableIndexVariable input object. This variable identifies the location of a specific curve or table in the program’s internal data structures. It is important that you do not inadvertently reassign the value held in this variable because it is only filled once at the beginning of the simulation.
Builtin Weather Data Functions[LINK]
EnergyPlus sets up 24 hours of weather data for Today and Tomorrow during DesignDay setup or based on incoming data from the weather file (epw). This data is used as the basis for setting the environment variables for a given zone timestep in WeatherManager::SetCurrentWeather. This data can be useful for predictive control or for setting Weather Data actuator overrides based on the incoming weather data using the BeginZoneTimestepBeforeSetCurrentWeather calling point.
Table 6 describes a set of builtin functions to access this weather data. For all of these functions, the first argument is the hour (from 0 to 23) and the second argument is the zone timestep number (from 1 to number of timesteps per hour). To access the current timestep use internal variables “Hour”’ and “TimeStepNum”:
Documentation content copyright © 19962022 The Board of Trustees of the University of Illinois and the Regents of the University of California through the Ernest Orlando Lawrence Berkeley National Laboratory. All rights reserved. EnergyPlus is a trademark of the US Department of Energy.
This documentation is made available under the EnergyPlus Open Source License v1.0.