Following is a brief description of the new rules palette functions (Predefined Functions) available for use in the RiverWare Policy Language for writing rules. Details on the use of these function and the syntax involved are available in the Rulebased Simulation documentation online.

This function is used to find the greatest control slot value which doesn’t cause another specified slot to exceed a given value during a given time range. For example, this function could be used to find the constant outflow value, over some time period, that will keep the pool elevation from exceeding a given value. This function is similar to the HypTargetSim function except that instead of finding a control slot value that leads to the target slot value at a particular timestep, it finds a control slot value which leads to the limit slot value not exceeding a limiting value over a range of dates.

This function is used to find the greatest control slot value which doesn’t cause another specified slot to exceed a given value during a given time range. For example, this function could be used to find the constant outflow value, over some time period, that will keep the pool elevation from exceeding a given value. This function is similar to the HypTargetSim function except that instead of finding a control slot value that leads to the target slot value at a particular timestep, it finds a control slot value which leads to the limit slot value not exceeding a limiting value over a range of dates. This function returns a LIST. If a solution cannot be found with the given min and max values, it will return the closest answer it can find and a FALSE boolean value to let the user know that it failed. If the function succeeds it will return true.

Note: this function is very similar to HypLimitSim: the only difference is that HypLimitSim fails if it can not find a satisfying control slot value, whereas this function does not fail, rather it still returns a value, along with the indication that this value does not achieve the limit.

These functions are used to perform a lumped mass balance across several timesteps. Given a target range and the total inflows over the target range, it will compute the outflow required to meet the given target pool elevation at the target date. This is analagous to the target operation in Simulation. The TargetSlopeHWGivenInflow function needs to be used when performing a target operation on a Slope Power Reservoir.

This function takes a NUMERIC “value” and a NUMERIC “factor” as arguments. The “value” is converted into the units of “factor”. Then the function returns the largest integer multiple of “factor” which is not greater than the converted “value”.

This function takes a NUMERIC “value” and a NUMERIC “factor” as arguments. The “value” is converted into the units of “factor”. Then the function returns the smallest integer multiple of “factor” which is not less than the converted “value”.

This function takes a NUMERIC “value” and a NUMERIC “factor” as arguments. The “value” is converted into the units of “factor”. Then the function returns the fractional portion of this converted “value” after is has been divided by “factor”.

Returns a slot given a STRING that represents a slot name.

Given an OBJECT which is an element in an aggregate object, this function returns the name of that element as a STRING and without the name of the aggregate object at the beginning.

This new predefined function replaces the DIV button on the rules palette. It returns the integer portion of the division of two numbers.

This new predefined function replaces the MOD button on the rules palette. It returns the remainder of the integer division of two numbers.

This function takes a partially specified date/time and a fully specified reference date. The function resolves the partially specified date/time into one that is fully specified. The specified fields of the partial date/time are copied into the return date, and the missing fields are filled in so that the resulting date is the closest date possible to the reference date. If the partial date cannot be resolved to the reference date, it is resolved into the next date in the future which works. For example, if the partially specified value is “May 10”, and the reference date is the current timestep, the function will return the fully specified date that corresponds to the next May 10th that occurs after the current timestep.

This function takes a partially specified date/time and a fully specified reference date. The function resolves the partially specified date/time into one that is fully specified. The specified fields of the partial date/time are copied into the return date, and the missing fields are filled in so that the resulting date is the closest date possible to the reference date. If the partial date cannot be resolved to the reference date, it is resolved into the previous date in the past which works. For example, if the partially specified value is “May 10”, and the reference date is the current timestep, the function will return the fully specified date that corresponds to the previous May 10 that occurred before the current timestep.

Three functions were added which analyze a slot’s value over some number of years, noting the occurrence of certain "events". The functions all have the following set of arguments:

The analysis period start and end dates define the period during which the analysis will be performed. Within the analysis period, only the timesteps which occur on or between the day and month of the event period start and end dates are considered. Each of these periods within the analysis period is called an event period. At each event period, an event can either occur or not. An event is defined by the value threshold and comparison type and the subevent count threshold and comparison type. At each timestep within an event analysis period, the slot’s value is compared to the threshold value. If the value threshold is an upper bound and the slot’s value is greater than the value threshold, then a subevent is said to have occurred at that timestep; similarly, if the value comparison is a lower bound and the slot’s value is less than the value threshold, then a subevent is said to have occurred. After the subevents within an event analysis period have been noted, then they are counted up and compared to the subevent count threshold. If the subevent count threshold is an upper bound and the number of subevents which occurred in an event analysis period is greater than the subevent count threshold, then an event is said to have occurred, and similarly, if the subevent count comparison is a lower bound and the number of subevents which occurred in an event analysis period is less than the subevent count threshold, then an event is said to have occurred. For example, a user might define an event as outflows from a particular reservoir of greater than 10,000 cfs on five days between March 1 and July 31 of each year in the analysis period.

The three new functions are:

A three column table interpolation function has been added to the list of pre-defined rules functions. If the user has a three column table that relates three different variables (for example, time of the year vs. flow rate vs. loss coefficient), the function will take values for two of the columns and will perform a three-dimensional, linear interpolation to find the corresponding value in the third column.

This function returns the sum of a LIST of NUMERIC values.

Given a LIST of lists and an index, this function will sum the values at the given index in each list.

These functions return the maximum/minimum number in a LIST of NUMERIC values.

These functions are passed in two DATETIME arguments. They return the greater/lesser date of the two.

This function returns true if the given date is a leap year.

This function returns a LIST of dates, separated by a given interval, and centered at a given date. If desired, dates not within the run duration are filtered out.

Returns true if the value is an even number

Returns true if the value is an odd number

This function returns a sequence of values in a given range with a given offset.

These functions are just like GetTableRowVals and GetTableColumnVals except that if a NaN is encountered, it is skipped and left out of the return list instead of causing the rule to terminate early.

This function returns a list of the names of all user-defined Water Types defined in the model.

This function returns a list of the names of all user-defined Water Owners defined in the model.

This function returns a list of the names of all user-defined Release Types defined in the model.

This function returns a list of the names of all user-defined Destination Types defined in the model.

This function returns a list of unique names of ReleaseTypes of all Supplies which represent outflows from an Object.

This function returns a list of unique names of Destinations of all Supplies which are of the indicated Release Type (possibly “all” or “none”) and which represent outflows from the indicated Object.

This function returns a list of names of Accounts on the specified Object that are of the specified Water Type. The Water Owner Argument can be “none”.

This function returns a list of names of Accounts on the specified Object that are of the specified Water Owner. The Water Owner Argument can be “none”.

This function returns a list of names of Accounts on the specified Object that have Supplies which are of the indicated Release Type (possibly “all” or “none”) and Destination (possibly “all” or “none”) and which represent outflows from the indicated Object. Supplies which represent “internal flows” between two Accounts on the Object are not considered.

The first Argument of the following eight functions -- “SourceList” or “TargetList” -- is a list (ListValue) of {OBJECT, ACCOUNT NAME} pairs, each represented by a two-element ListValue. (The Account Name item is a StringValue). That is, the first Argument is a ListValue of constrained ListValues.

Values passed in for the second and third Arguments -- ReleaseTypeString and DestinationString -- can be “all” or “none.” (“None” corresponds to Supplies which have the default ReleaseType or default Destination).

There are two sets of functions in this section:

Each function in the first group returns a ListValue of SupplyNames (StringValues) corresponding to the {OBJECT, ACCOUNT NAME} pairs in the SourceList or TargetList argument.

The functions in the second group (whose names end in “1to1”) return an ordered ListValue of SupplyNames (StringValues) where exactly ONE SupplyName value corresponds to each of the {OBJECT, ACCOUNT NAME} pairs in the SourceList or TargetList argument. If there is no Supply that meets the criteria, an empty string (““) is returned to correspond to the Source/Target item. If there is MORE THAN ONE Supply that meets the criteria, a run-time error is reported.

This function returns a ListValue of names of Supplies which represent outflows from the Objects, from the indicated Accounts. THIS function does NOT impose the restriction that zero or one Supplies matches the criteria for every item in the Source List.

(See general section comments, above).

This function returns a ListValue of names of Supplies which represent internal flows on the Objects, from the indicated Accounts (to other Accounts on the same Object.) THIS function does NOT impose the restriction that zero or one Supplies matches the criteria for every item in the Source List.

(See general section comments, above.)

This function returns a ListValue of names of Supplies which represent inflows to the Objects, to the indicated Accounts. THIS function does NOT impose the restriction that zero or one Supplies matches the criteria for every item in the Target List.

(See general section comments, above.)

This function returns a ListValue of names of Supplies which represent internal flows on the Objects, to the indicated Accounts (from other Accounts on the same Object.) THIS function does NOT impose the restriction that zero or one Supplies matches the criteria for every item in the Target List.

(See general section comments, above.)

This function returns an ordered ListValue of names of Supplies which represent outflows from the Objects, from the indicated Accounts. EXACTLY one Supply Name (or "") is returned for each Account in the Source List.

(See general section comments, above).

This function returns an ordered ListValue of names of Supplies which represent internal flows on the Objects, from the indicated Accounts (to other Accounts on the same Object.) EXACTLY one Supply Name (or "") is returned for each Account in the Source List.

(See general section comments, above.)

This function returns an ordered ListValue of names of Supplies which represent inflows to the Objects, to the indicated Accounts. EXACTLY one Supply Name (or "") is returned for each Account in the Target List.

(See general section comments, above.)

This function returns an ordered ListValue of names of Supplies which represent internal flows on the Objects, to the indicated Accounts (from other Accounts on the same Object.) EXACTLY one Supply Name (or "") is returned for each Account in the Target List.

(See general section comments, above.)

This is used to find the index of a given item in a list. If the item is not contained in the list, a “-1” is returned.

This new RPL operator takes any type of argument. When it is evaluated, it aborts the run with an error message which contains the argument as part of the message. For example:

An IF-THEN-ELSE button has been added to the rules palette. This simplifies the creation of IF-THEN-ELSE expressions. Prior to this release, users had to separately use the IF button and the ELSE button.

 

The previous use of these to functions was error prone. Two calls to one these functions which are equivalent but in different units will give different results. Therefore it is necessary to include the unit type that should be used to perform this operation. The Log function now takes two arguments, both NUMERIC. The Log function takes the first argument, converts it into the units of the second argument, and then returns the base 10 logarithm of the converted value. The Ln function converts the first NUMERIC into the units of the second and then returns the natural logarithm of the converted value.

If these functions are used in existing rulesets, they will continue to be used in the old way and will be renamed OldLog and OldLn. We encourage users to updated their rulesets to use the new functions.

There are several rules predefined functions which simulate the behavior of a SubBasin of objects into the future without changing those objects (HypSim, HypTargetSim, HypTargetSimWithStatus, HypLimitSim, and HypLimitSimWithStatus). The first argument to all of these functions is a string, which has been interpreted as the name of the SubBasin on which to perform the hypothetical simulation. We have generalized these methods to also accept the name of an object as the first argument. If the first argument is not the name of a SubBasin but is the name of an object, then the hypothetical simulation is performed on just that object. This eliminates the need to make several single object subbasins.

RiverWare 4.1 has the ability to search for strings in the name, descriptions and definitions of groups, functions and rules. Users can access the search functionality through the "Find..." menu items in the Group and Ruleset editors.

Rules can now be rearranged within the Policy Group Editor dialog. Previously, rules could only be rearranged through the main Ruleset Editor.

Rulesets are now able to be compressed and saved with the .gz file extension. If moving rulesets between UNIX and Windows, the ruleset files must be compressed.

The rules palette has been re-designed for ease of use. Below is a screen shot of the new palette. The palette buttons are still located on the main palette view. However, now there are separate tabs for the rules functions. The first tab is the main palette view, the second tab is for User-Defined Functions (added to the ruleset by the user), and the third tab is for pre-defined functions in RiverWare. These are now grouped by type instead of listed in alphabetical order. The user can switch between the group view and the function view using the Functions menu. Also in the Functions menu is a search mechanism which will search for a string in a function’s name, description, and/or definition.