Expression Data Types
The RiverWare Policy Language language is composed of seven data types, such as numeric values, datetimes, text strings, and slots. The data types are the building blocks of RPL. They are the only types of data which expressions and functions are allowed to evaluate to and are the structure controlling what information can be entered in different parts of the RPL. The structure editor uses expression data types to enforce block and function validity as they are constructed. Attempting to enter an expression of one type where another type is expected, immediately results in an error.
Unspecified expressions are pieces of the RPL which have not yet been defined when creating a RPL set. Unspecified expressions are shown in the Rule and Function Editor as the name of the expression type, colored blue (by default), and surrounded by small angle braces (< expr >). An unspecified expression may be filled in directly with the appropriate data, or it may be replaced with a function which will evaluate to the appropriate data type. In most cases, unspecified expressions can be completed by using Palette buttons. This is the recommended approach. The complexity and syntactical requirements of some expression types, particularly object and slot, behooves you to use the built-in tools for formatting a correct expression.
Example 3.1
A rule contains an unspecified numeric expression: <numeric expr>
The expression may be filled in with an actual value and units by entering: 100.0 cfs
or it could be replaced by an arithmetic operator which evaluates to a value and units by selecting the N + N palette button:
<numeric expr> + <numeric expr>
or it could be replaced by yet another palette selection which returns a value and units, such as a series slot lookup:
Lake Mead.Outflow []
In all of these cases, the original requirement that the expression evaluate to a number and units is satisfied.
Table 3.1 lists the expression data types. More complete descriptions follow.
Expression Type | Unspecified Representation | Description | Examples |
|---|---|---|---|
NUMERIC | <numeric expr> | A number and its units. | 150 cfs 349.47926 “acre-feet/day” 1 NONE |
BOOLEAN | <boolean expr> | True or False. | TRUE FALSE |
DATETIME | <datetime expr> | An actual or symbolic date. | @“t”, @“t-1” @“Current Timestep” @“Previous Timestep” @“January 4, Current Year” |
STRING | <string expr> | Quoted text and/or numbers. | “Entering spring runoff season.” “Minimum flow violated by 5%“ |
OBJECT | <object expr> | An object in the current model. | %“Havasu” %“Kentucky-Barkley Canal” %“SJBelowNavajo::ColoradoAg” |
SLOT | <slot expr> | A slot on an object in the current model. | $“Lake Mead.Outflow” $“Kentucky.Pool Elevation” $“Rio Chama.Hydrologic Inflow” |
LIST | <list expr> | A list of any mix of data types. | { 1561 [“ft”], 1573 [“ft”], 1589 [“ft”] } { @“April 15, 1999” } { %“Powell”, 10 [“cfs”], TRUE } { { %“Mead”, TRUE }, { $“Inflow” } } |
NUMERIC
The numeric expression data type is comprised of a number and its units. Numeric expressions may be typed directly into a block or function by double-clicking the unspecified <numeric expr> and typing a value and units into the textfield. As in Simulation, numbers are stored and evaluated internally with twelve significant figures of precision. When a numeric expression is typed directly into a block or function, the default display precision is eight digits beyond the decimal point. The precision of displayed numbers can be modified by scrolling the Precision selector in the Adv. Properties portion of the RPL Set Editor.
Units for numeric expressions must follow the value, separated by a single space. If no units are specified, the value is considered to be of a dimensionless unit type with units of NONE. When a numeric expression is typed directly into a block or function, the units may be entered without quotes if the unit name contains no special punctuation characters such as hyphens or forward slashes. When quotes are omitted, they will be filled in automatically.
Example 3.2
Entering numeric expressions with the display precision set to the default of 8, causes the following text to be shown in the editor.
Exact Text Typed Into Textfield | Resulting Display |
|---|---|
150 cfs | 150.00000000 “cfs” |
0.000000004 “feet/day” | 0.00000000 “feet/day” |
0.5 NONE | 0.50000000 |
248650 acre-feet | “parse error” due to hyphen, therefore you must type the quotes |
BOOLEAN
The boolean expression data type can be either true or false. The expressions may be entered directly in the editor by double-clicking the unspecified <boolean expr>, and typing into the textfield. The editor accepts lowercase, uppercase and capitalized spellings, but automatically converts these entries into an uppercase format.
Example 3.3
Entering boolean expressions (as shown below) cause the following text to be shown in the editor.
Exact Text Typed Into Textfield | Resulting Display |
|---|---|
true | TRUE |
False | FALSE |
FALSE | FALSE |
tRuE | “parse error” |
DATETIME
The datetime expression type is used to represent moments in time. Datetimes may be entered directly by double-clicking an unspecified <datetime expr>, and typing into the resulting textfield. All datetime expressions begin with an @ symbol and are followed by the datetime specification in double quotes (“ and ”).
Datetime expressions may be specified symbolically. Symbolic representations of points in time are common in everyday language, but rare in programming languages. Symbolic representations include such datetimes as “next week,” “20th day of month,” and “April, next year.” These types of datetime specifications are allowed in the RiverWare Policy Language. They facilitate the writing of RPL expressions by using date conventions to which you are more accustomed. They are evaluated by the RPL language, in the context in which they are used, to determine an exact moment in time. Slot access is still performed internally with exact datetime specification in number of seconds since New Year’s, 1700 C.E.
Fully or Partially Specified Datetime Expressions
Datetime expressions fall into two categories and each may be used in the following instances or contexts:
Fully Specified
Fully specified datetimes are those which can be mapped directly to an instant in time, such as @“t” or @“June 4, 1986.” Fully specified datetimes are required for all slot lookups, slot assignments and predefined function arguments.
Partially Specified
Partially specified datetimes are those which cannot be mapped to a specific instant in time, such as @“Current Month” or @“Tuesday.” Partially specified datetimes are used in boolean comparisons. For example, a check for whether the current timestep is a Tuesday could be done with a fully specified datetime, @“t”, and a partially specified datetime, @“Tuesday”:
IF ( @“t” == @“Tuesday” ) THEN ...
If you have a partially specified datetime that you want to convert into a fully specified datetime, use the CompletePartialDate predefined function; see CompletePartialDate for details.
Formats
There are four general datetime formats. Within each format, there are specific components which the user can specify. Table 3.2 lists the four formats and components, which you can specify separately.
Name | Time components (from lowest to highest resolution) | Components you can specify separately | Examples |
|---|---|---|---|
1. Month, day, year | Year, Month, Day of Month, Hour, Minute, Second | @“August 23, 1997 4:00:00” @“7/22/1997 4:0000” | |
Month | @“August”, @“Month 8”, @“Current Month” | ||
Day of Month | @“DayOfMonth 23”, @“Previous DayOfMonth” | ||
Year | @“Year 1997”, @“Current Year” , @“... Year” | ||
Time | @“4:12:00” | ||
2. Timestep | Timesteps since the beginning of run | @“Timestep 12”, @“t+2” | |
Timestep | @“Max Timestep”, @“t-1” | ||
3. Day, week, year | Year, Week of Year, Day of Week, Hour, Minute, Second | @“Monday Week 10, 1997 4:00:00” @“DayOfWeek 5 Week 12, 1998, 12:00:00” | |
Day of Week | @“Monday”, @“DayOfWeek 7”, @“Next DayOfWeek” | ||
Day of Week and Time | @“Monday 4:12”, @“4:12 DayOfWeek 1”, @“4:12 Finish DayOfWeek” | ||
4. Day, year | Year, Day of Year, Hour, Minute, Second | @“DayOfYear 227, 1997 4:00:00” | |
Day of Year | @“DayOfYear 23”, @“Start DayOfYear” | ||
Day of Year and Time | @“DayOfYear 23 4:12”, @“4:12 Current DayOfYear” | ||
Thus, for the first format, you can specify almost any component. For the second format, you can only specify the timestep and nothing else. So you cannot specify @“Timestep 12, Year 1997”; an error would return.
As you specify components, you only specify as much as is needed to uniquely reference the date. So, if in a boolean comparison you are comparing a date to see it is in 1997, you would enter (date == @“Year 1997”). But, if you want to compare if it is March of 1997, you enter @“March 1997” but do not include the word “Year” before 1997.
The list of symbolic specifiers include the following: Min, Max, Start, Finish, Previous, Current, and Next. Any of these specifiers can be used in the examples above.
If no time (hours, minutes, seconds) is specified at all, it defaults to 24:00:00. If a time is specified, it may appear either before or after the specification of the Month, Day, and Year. Times may be specified with or without seconds, if they are not specified then they default to 0 (e.g., both 17:23 and 17:23:00 refer to the same time of day).
Examples
Mixing of symbolic datetime elements results in an almost infinite number of datetime specifications. Table 3.3 lists examples for some of these acceptable fully specified expressions and their interpretations. The symbolic datetime elements shown can be combined into other forms not explicitly enumerated.
Table 3.4 lists partially specified datetime expressions.
Note: These tables do not capture all the possible combinations of partially specified datetime expressions.
Fully Specified Datetime Expression | Interpretation |
|---|---|
@“4/01/1996 14:00:00” | April 1, 1996, 2 p.m. |
@“April 1, 1996 14:00” | April 1, 1996, 2 p.m. |
@“April 1, 1996 14:00:00” | April 1, 1996, 2 p.m. |
@“t” or @“Current Timestep” | the current timestep |
@“t-1” or @“Previous Timestep” | the previous timestep |
@“t+1” or @“Next Timestep” | the next timestep |
@“Start Timestep” | the begin timestep in the run or the begin timestep in an expression slot (in the evaluation range). |
@“Finish Timestep” | the finish timestep in the run or the last timestep in an expression slot (in the evaluation range). |
@“April 1, Current Year 14:00:00” | April 1 of the current year, 2 p.m. |
@“April 1, 1996 Current Hour:00:00” | April 1, 1996 at the hour of the current timestep. |
@“April Next DayOfMonth, 1996 Previous Hour:00:00” | Depends on the current timestep |
@“7/22/1997 1:34:00 + 2 Days” | the date/time which is 48 hours after the given date (i.e., 7/24/97 1:34:00) |
@“+ 25” | the date/time 25 timesteps beyond the current timestep |
@“Next Timestep - 1” | Confusing way to refer to current timestep |
@“2 hours before Current Timestep” | 2 hours before current timestep |
Partially Specified Datetime Expression | Interpretation |
|---|---|
@“Year 1997” | the year specified as 1997 |
@“Previous Year” | the year before the current year |
@“Current Year” | the year specified as the year of the current timestep |
@“Month 4” | the month specified as April |
@“April” | the month specified as April |
@“April 22” | the 22nd day in April |
@“6:00 April 22” | 6:00 AM on April 22 |
@“April 22 6:00” | 6:00 AM on April 22 |
@“6:00” | 6:00 AM |
@“DayOfMonth 4” | the day of the month specified as the 4th |
@“Next DayOfMonth” | the day of the month specified as the day after the day of the current timestep |
@“Max DayOfMonth” | the day of the month that is the last day in the month |
@“Monday” | the day of week specified as Monday |
@“WeekOfYear 2” | the week of year specified as the second |
@“DayOfWeek 2” | the day of week specified as Monday |
@“6:00 Previous DayOfWeek” | 6:00 AM on the previous day of the week |
@“DayOfYear 157” | the day of year specified as 157 |
@“Max DayOfYear” | the day corresponding to the last day of the year |
Datetime Math
When performing addition or subtraction math on datetime values (for example, adding three timesteps to the current timestep), there are three approaches that can be used.
Math Within a Datetime Specification
Within a datetime literal, it is possible to add or subtract integral values from a base time. Thus, possible specifications for a datetime value three timesteps beyond the current timestep include the following:
• @“t + 3” or
• @“t + 3 timestep” or
• @“t + 3 day” (if the timestep is 1 Day) or
• @“t + 72 hour” (if the timestep is 1 Day)
The list of time units that are available in this context are (case insensitive):
• Minute
• Hour
• Day
• Week
• Month
• Year
Note: The date time math occurs within the quoted literal expression, which cannot include references to variables, that the integral increment is assumed to have units of “timestep” when the units are unspecified, and that the latter two specifications are less general because they assume that the model has a 1 Day timestep.
This approach to datetime math is probably the easiest to read, but is of course only useful when literal specification is possible. For example, when one would like to increment a base datetime by a number of timesteps which is itself the result of expression evaluation, then one of the alternative approaches to datetime math is required.
Mathematical Expressions Involving a Datetime Operand
A numeric value can be added to or subtracted from a datetime value. Continuing the example from above, the following expressions would evaluate to three timesteps beyond the current timestep in a model with a 1 Day timestep:
• @“t” + 72 “hour” or
• @“t” + 3 “day”
he list of time units that are available in this context are (case sensitive):
• min, minute
• hr, hour
• day
• week
• month
• year
Here are the math operations supported for datetime values:
• <DATETIME> + <NUMERIC> results in a <DATETIME>
• <NUMERIC> + <DATETIME> results in a <DATETIME>
• <DATETIME> - <NUMERIC> results in a <DATETIME>
• <DATETIME> - <DATETIME> results in a <NUMERIC> (with units of time).
In such expressions, the numeric value must have units of type Time. ]
Note: Timestep is not a legal unit of Time, so this type of approach could not be used when one would like to add some number of timesteps in a model whose timestep increment is not fixed (i.e., 1 Month or 1 Year timesteps).
The following operations are not supported as the result is undefined:
• <NUMERIC> - <DATETIME>, <DATETIME> + <DATETIME>
Note: Datetime math with partially specified datetime expressions is not supported. For example, the expression @”1:00” + 1 “hr” would cause the run to abort with an error message.
Note: Within RPL evaluation, 1 “Month” is equal to 31 days and 1 “Year” is equal to 365 days as defined in the Units List dialog. (To view the Units List dialog, from the Units menu in the main RiverWare workspace, select List Available Units. Then select the RPL Units at the top of the Units List dialog, and uncheck the box at the bottom left for Show only types that are present on the workspace.) If you are trying to compute a flow by dividing a volume by 1 “month”, it will use 31 days for the month. If you then set that value on a slot with a 1 Month timestep on a month that only has 30 days, the values will be not be the same due to the conversion. Instead, convert the volume to a flow using VolumeToFlow and specify the month or divide by GetDaysInMonth and specify the desired month. For non constant timestep lengths, the best approach is to stay in volumes as long as possible, and then convert to a flow when ready to set the value on a flow type slot.
Using the OffsetDate function
The OffsetDate predefined function allows you to specify the increment and length of timestep to use for the addition or subtraction; see OffsetDate for details. Thus, you could enter the following:
• OffsetDate(@ “t”, 1, “1 Days”)
This function is most useful for variable length timesteps (1 Month, 1 Year).
STRING
The string expression data type is any text surrounded by double quotes (“ and”). An unspecified string expression may be entered directly in expression by double-clicking the <string expr>, and typing in the string surrounded by double quotes. String expressions may contain any combination of letters, numbers and punctuation except double quotes.
OBJECT
The object expression data type is used to reference objects in the currently loaded model. An unspecified object expression may be completed by double-clicking the <object expr> and typing in the object name in double quotes and preceded by a percent symbol. When an object expression is typed directly into a block or function, the object name may be entered without quotes if the object name contains no spaces or special punctuation characters. When quotes are omitted, they will be filled in automatically.
It is highly recommended that you do not type object names directly into blocks and functions. The potential for error is great. An extra space or an incorrectly capitalized letter will invalidate the object expression. There is, however, a convenient and foolproof way to enter this data. Most commonly, an unspecified object expression is completed by using the Object Selector in the RPL Palette or by typing in a variable name whose type is an object expression.
Table 3.5 lists examples of object expressions entered directly into the Editor.
Exact Text Typed Into Textfield | Resulting Display |
|---|---|
%“Lake Mead” | Lake Mead |
% DataObj | DataObj |
% Havasu Diversion | “parse error” due to space |
In contexts where an object expression is used as part of a complete slot specification, the object expression must be followed by a <string expression> indicating the slot.
Example 3.4
The Pool Elevation of Lake Powell could be filled into:
<object expr>.<string expr>
and result in the following expression:
Lake Powell.”Pool Elevation”
Note: For Expression Slots and Object Level Account Methods, you can use the keyword ThisObject to access the containing object. For example, to get the slot named DailyTotals from this data object, you could create the expression shown in the image.
SLOT
The slot expression data type is used to specify a specific slot on an object of the currently-loaded model. The expression must include the object on which the slot resides as well as the slot name itself. An unspecified slot expression may be completed by double-clicking the <slot expr>, typing in the object name, a dot, and the slot name, all in double quotes and preceded by a dollar symbol. When a slot expression is typed directly into a block or function, the object.slot name may be entered without quotes if neither of the names contain spaces or special punctuation characters. Regardless of how a slot expression is entered, the dollar sign and quotes are automatically omitted in the resulting display.
Again, it is highly recommended that you do not type object.slot names directly into blocks and functions. The same convenient and foolproof way to enter object data is available to enter object.slot data. An unspecified slot expression may be completed by using the Slot Selector in the RPL Palette or by typing in a variable name whose type is a slot expression. The Slot Selector is an interface similar to the one used elsewhere in RiverWare, which formats a selected object and slot correctly and inserts it into the slot expression.
Table 3.6 lists examples of slot expressions entered directly into the editor.
Exact Text Typed Into Textfield | Resulting Display |
|---|---|
$“Lake Mead.Outflow” | Lake Mead.Outflow |
$ DataObj.target | DataObj.target |
$ Havasu Diversion.Inflow | “parse error” due to space |
$ “Havasu Diversion”.Inflow | “parse error” |
LIST
List expressions are ordered collections of other expression data types. Lists can contain zero or more elements. Elements may be of different types, and lists may even contain other lists. An unspecified list expression may be completed by double-clicking the <list expr> and typing in a comma-separated list of other expressions enclosed in curly braces ({ and }). As with object and slot expressions, it is highly recommended that you do not type list expressions directly into the Editor. The Palette contains a multitude of functions for creating and retrieving information from lists. Examples of valid lists expressions, before the expression language expands their elements, include:
{ 1561 [“ft”], 1573 [“ft”], 1589 [“ft”], 3800.05 [cfs] }
{ @“April 15, 1999” }
{ }
{ %“Powell”, 10 [“cfs”], True }
{ { %“Mead”, “Max Outflow”, TRUE }, { $“Inflow” }, False }
When an element of a list is read, its expression type must match the type expected by the reading function. If a function finds an object where a datetime is expected, the run is halted and an error is posted. The flexibility of lists is an advantage as long as the types of their contents are known, and they are used properly within blocks and functions. Because of their flexibility, however, the types of their elements cannot always be determined prior to a model run. For this reason, list type-checking is only done during execution, and errors in configuration are not caught until a run is in progress.
Revised: 08/02/2021