skip to main content
Expression Slots
Overview of Functionality
Functionality has grown extensively over the past several releases. In order to put new features into perspective, an overview of the existing state of the expression slot is presented here.
To create a new expression slot, open a Data Object and select Slots Add Expression Slot. The new slot is appended to the slot list with the name ExpressionX (where X is the smallest integer needed to make this name unique, beginning with 00000), and marked with the expression icon above. To open an expression slot, double-click on its name.
Expression Slots may be renamed through the Name: field in the Open Slot dialog. Expression Slots are initially created with the Run Control’s Initial: time only. When the expression is evaluated, the time range of the slot is expanded to mirror the time horizon in the Run Control dialog.
The units and Display Units label, scale, and precision of values displayed as the result of an Expression Slot may be changed through the Configuration menu. Expression Slots may display all RiverWare defined unit types, but default to a unit type of NONE. When the NONE unit type is selected, a Display Units field is available to enter a display label. This label is saved in the model file, but is not exported through DMIs in the same manner as RiverWare defined units. Any Expression Slots with Unit Type of NONE is written to DMIs with User Units of NONE. The label is only cosmetic, and in no way affects the calculation of the expression or scaling of the display value. When a unit type other than NONE is selected, an option menu appears for the user to select a RiverWare defined unit. These units ensure a consistency of labeling for exported data.
Expressions are only calculated based on the display values of the slots they reference. No attempt is made to reconcile varied units or carry them through an expression. The user is responsible for verifying that display values in referenced slots are consistent with the nature of the expression. Unit conversions may be performed after an Expression Slot has computed, by changing the Expression Slot’s units in the Configuration menu. Any such conversion will only be performed when changing from one RiverWare defined unit to another. The converted value is retained only as long as the Expression is not recalculated. When the expression is recalculated, the computed value will be assumed to be in the currently selected units.
The expression itself is displayed in the scrollable Expression: window. To create a new expression, select the Editor button or select View Expression Editor. The Expression Editor is a syntax-directed editor designed to assist in the construction of complex syntactically correct expressions within the RiverWare environment. The editor works by maintaining a partially constructed expression and allowing the user to manipulate unfinished portions using a collection of selection lists and text entry boxes. To use this dialog effectively, it is important to formulate the expression in its entirety (perhaps on paper) before beginning. The Expression Editor does not allow editing of previously determined portions of the expression. Errors in specifying an expression must be corrected by clearing the existing expression and beginning anew.
Initially, the editor contains a single ? indicating a portion of an expression which has not yet been completed. Clicking, without releasing, on the ? brings up a term selection list. Scrolling down to a term and releasing the mouse, inserts the selected term in place of the ?. Terms may contain additional ?s, to expand the complexity of the expression. One of two selection lists is available from any ?. These fall into two categories: General Terms and Range Terms. General Terms include algebraic manipulations, variables (slots and user-defined variables), and actual values. Range Terms indicate the range over which an expression is computed. This may be a collection of slots, a SubBasin, or a set of timesteps.
 
Term
Significance
? + ?
Addition
? - ?
Subtraction
? * ?
Multiplication
? / ?
Division
(?) ^ (?)
Exponentiation
( ? )
Parenthetical grouping
NUMBER
Numerical input;
Selecting NUMBER opens a text entry field.
Note:  Operator precedence is as follows (greatest to least): (), ^, * and /, and + and -. Parenthetical notation is automatically added to an expression when it is committed. This alleviates any later confusion regarding under-specified operator precedence.
 
Term
Significance
“SLOT” [ @t ]
Slot value at time of expression.
“SLOT” [ @t - NUMBER]
Slot value at offset from time of expression; the offset should be an integer number.
“SLOT” [ ? ]
Slot value at time ? Clicking on ? opens an entry field for a variable.
Note:  Selecting “SLOT” opens a slot selector dialog for selection of Object-Slot combinations in one of three ways:
• Selecting a black-lettered object in the Objects: column generates a list of all of its slots in the Slots: column. Selecting one of these slots and pressing the OK button concludes the selection. The chosen slot, referenced according to standard “object.slot” notation, is visible in the Selected Slot: field.
• Selecting a blue-lettered object type in the Objects: column generates a list of slots in the Slots: column which exist for every object of that type. Selecting one of these slots and pressing the OK button concludes the selection. The chosen slot(s) will appear as “@Var.slot” in the Selected Slot: field, where “Var” is a three letter variable representing the object type. This style of entry is useful for expressions which require iterating over every object of a given type.
• An “object.slot” may be typed directly into, or a partial selection may be edited directly in, the Selected Slot: field. This style of entry is useful to specify custom variables for iterations such as “@Var.slot.” In this case, Var must be defined elsewhere in the expression.
 
Term
Significance
S [ ? , ? ]
Sum second ? over range of first ?.
X [ ? , ? ]
Average second ? over range of first ?.
S [ ? IN ? , ? ]
Sum last ? over subset of first ? in range of second ?.
X [ ? IN ? , ? ]
Average last ? over subset of first ? in range of second ?.
Note:  The final ? of summation and average terms may be replaced by any Algebraic Terms, Slot References, or Iteration Operators. The latter results in nested loops. The ? IN ? range terms are useful for specifying a different variable than that automatically provided by a simple ? Range Term. If ? IN ? is selected as a term, the first ? opens a text entry field for entering a user variables, while the second ? produces a list of terms “over which” to range.
 
Term
Significance
t IN Time
t ranges over all simulation timesteps
t IN Time ?
t ranges over the Time Subset ? of all simulation timesteps.
i IN Integer
FROM ? TO ?
i ranges over all integers from ? to ?.
i IN Integer
FROM ? TO ? INC ?
i ranges over all integers from ? to ? in increments of ?.
Var IN “SubBasin
Var ranges over all the objects within SubBasin.
Note:  If the difference between the FROM and TO values is not an integer multiple of the INCrement, the TO value will not be considered within the range. Multiple Var IN “SubBasin” Range Terms are automatically appended to the list to represent every SubBasin on the workspace. Both user-defined and internally-defined SubBasins appear in the list. The Var variable name is composed of the first three letters of the SubBasin name.
 
Term
Significance
BY “SLOT”
Includes only timesteps where “SLOT” has a valid value.
FROM ? TO ?
Includes all integers from ? to ?.
FROM ? TO ? INC ?
Includes all integers from ? to ? in increments of ?.
FROM ?
Includes all integers from ?.
TO ?
Includes all integers to ?.
? ?
Creates multiple Time Subsets.
Note:  Multiple Time Subsets may be used to increment over integers which are themselves increments.
 
Term
Significance
@?
Value at variable time ?;
Selecting ? opens an entry field for the variable name.
Note:  All variables used in expressions must be defined within that expression.
SubBasins
Expression slots have been expanded to utilize the new SubBasin functionality previously described. It is now possible to iterate over user-defined SubBasins as well as object types. SubBasins will appear in the expression editor’s menu list when summing or averaging values. Note that any change in the membership of a SubBasin will be reflected in the calculations of any Expression Slots which reference it.
Linking
Expression slots may now be linked to other slots on the workspace. This is useful for propagating a set of calculated values into a dispatching Series Slot prior to simulation. Propagation across a link occurs every time an Expression slot is reevaluated, which may be done outside of a run by selecting Control Reevaluate Expression Slots from the main workspace menu bar, or by using the <Control>-e keyboard shortcut. Reevaluation of Expression slots may not be forced during a simulation run, but will still be done automatically at the conclusion of the run. Linking an Expression slot to a Simulation slot which receives a computed value during a run will cause an error and abort the run when the value propagates to the expression slot.
Revised: 07/05/2022