RuleBased Simulation
Mass Balance Functions
There is now the ability for Rulebased Simulation to solve mass balances on Reservoir objects at any timestep. This was accomplished by adding three new mass balance methods on the Reservoir class that can be called from within a rule:
Reservoir:massBalanceSolveInflow (double out, double stor, double storPrev, Date_Time *dateTime, double &in)
Reservoir:massBalanceSolveOutflow (double in, double stor, double storPrev, Date_Time *dateTime, double &out)
Reservoir:massBalanceSolveStorage (double in, double out, double storPrev, Date_Time *dateTime, double &stor)
These functions differ from the standard massBalance functions in that they solve for the desired value in two steps. First, the given Inflow, Outflow, or Storage, as well as the Previous storage, and the time step (variables in, out, stor, storPrev, dateTime) provided by the Rulebased Simulation are converted to local variables of the MethodInfo class. Then, these functions execute the standard Reservoir:massBalanceSolve... (MethodInfo *LocalInfo) function which solves the mass balance. This standard method is the one used in the regular Simulation mode. The value computed by the massBalanceSolve... (MethodInfo *LocalInfo) function is then passed back to the rule as the desired &in, &out, or &stor.
Tcl Aggregation Functions
Several new Tcl-based functions have been added to the RuleBased Simulation language which access the new SubBasin functionality from within rules. They are:
C_GetAllNamedBasins
• This function returns a list of all user-defined SubBasins for the current model.
C_GetObjectsInBasin basinDesignator
• This function returns a list of all Objects in the SubBasin basinDesignator.
C_AggOverTime basinDesignator slotName aggFunc aggFilter scale units <startDate <endDate>>
• This function returns a list of values and their context(s). Each object in the designated basin is individually aggregated over time, yielding one item of the list. The type of the values, and the number of contexts returned, are determined by the Aggregation Function.
C_AggOverObj basinDesignator slotName aggFunc aggFilter scale units <startDate <endDate>>
• This function returns a list of values and their context(s). All of the objects in the designated basin are aggregated for each time, yielding one item of the list. The type of the values, and the number of contexts returned are determined by the Aggregation Function.
C_AggOverTimeObj basinDesignator slotName aggFunc1 aggFunc2 aggFilter scale units <startDate <endDate>>
• This function returns a single value and appropriate context. Each object in the designated basin is individually aggregated over time according to aggFunc1. The resulting list of objects are then aggregated according to aggFunc2. The value and number of contexts returned are determined by the Aggregation Functions (see table below).
C_AggOverObjTime basinDesignator slotName aggFunc1 aggFunc2 aggFilter scale units <startDate <endDate>>
• This function returns a single value and appropriate context. All of the objects in the designated basin are aggregated according to aggFunc1 for each time. The resulting list of times are then aggregated according to aggFunc2. The value and number of contexts returned are determined by the Aggregation Functions.
Where the arguments to the above functions are specified as:
– basinDesignator:
– {basinName}
– {basinName {classType}}
– {direction refObject}
– {direction refObject {classTypes}}
– {direction refObject {classTypes} {terminators}}
– {direction refObject {classTypes} {terminators} {in/excludedBasins}}
– basinName:
– Any user-defined or RiverWare-defined basin.
– classTypes:
– AggDiversionSite
– AggReach
– Canal
– Confluence
– GroundWaterStorage
– LevelPowerReservoir
– PowerReservoir
– PumpedStorage
– Reach
– Reservoir
– SlopePowerReservoir
– StandAloneWU
– StorageReservoir
– Thermal
– WaterUser
– direction:
– UPSTREAM
– DOWNSTREAM
– refObject:
– An object name.
– terminators:
– Object name(s).
– in/excludedBasins:
– Any user-defined or RiverWare-defined basin(s)
– aggFunc:
– SUM
– AVG
– MIN
– MAX
– aggFilter (filters out all which are not flagged):
– IN_OUT
– INPUT
– OUTPUT
– <startDate>:
– An optional starting dateTime. If not specified, defaults to the current dateTime.
– <endDate>:
– An optional ending dateTime, only valid if <startDate> is also specified. This also defaults to the current dateTime.
AggFunc | C_AggOverObj | C_AggOverTime |
|---|---|---|
MIN or MAX | Returns {objectName dateTime value} for each dateTime in the range | Returns {objectName dateTime value} for each object in the SubBasin |
SUM or AVG | Returns {dateTime value} for each dateTime in the range | Returns {objectName value} for each object in the SubBasin |
AggFuncs | C_AggOverObjTime | C_AggOverTimeObj |
|---|---|---|
MIN or MAX, then MIN or MAX | Returns a single {objectName dateTime value} | Returns a single {objectName dateTime value} |
MIN or MAX, then SUM or AVG | Returns a single {value} | Returns a single {value} |
SUM or AVG, then MIN or MAX | Returns a single {dateTime value} | Returns a single {objectName value} |
SUM or AVG, then SUM or AVG | Returns a single {value} | Returns a single {value} |
Note: If an aggregate cannot be computed due to an invalid value in one of its items, the returned value will be “NaN” and the returned date, if applicable, will be “NO_DATE.” All aggregations are done in standard units. Values in units of acre-feet/month are NOT scaled to the length of each dateTime in the range. As such, their results will be invalid for any dateTimes which are not 31 days long.
Tcl Unit Conversion Functions
Two new functions have been added to facilitate unit conversions. They are:
C_GetStepSeconds <dateTime>
• This function returns the number of seconds in the timestep referenced by <dateTime>. If no <dateTime> is specified, the current dateTime is used. The number of seconds in the timestep may be used to convert between units of FLOW and VOLUME within rules.
C_ConvertValue fromValue fromScale fromUnits toScale toUnits <dateTime>
• This function converts a given fromValue with scale and units of fromScale and fromUnits, to a value in the scale and units of toScale and toUnits. All conversions must be within a single unit type; e.g., FLOW. The optional <dateTime> specification indicates the timestep who’s length will be used for conversions from/to units of acre-feet/month. If no <dateTime> is specified, the current dateTime is used.
Total Diversion to Meet Requests
A new function has been added which computes the Diversion required to satisfy the Diversion Requests of all WaterUsers of an AggDiversionSite at any timestep of the simulation. This function may be called from within a rule for AggDiversionSites using the Sequential Linking Structure only. In order to perform the calculation, the algorithm executes the selected returnFlowCalculation and returnFlowSplitCalculation Methods on each WaterUser. These account for all possibilities of Return Flow linking and quantities when computing the variable totalReq, which represents the Diversion requirement for satisfaction of all WaterUser requests. The function is defined as:
int nonShortDiversionReq(double &totalReq, Date_Time *when)
where totalReq is the calculated total Diversion and when is a pointer to the timestep at which the calculation is to be performed. The function returns 0 upon success and 1 upon failure.
Revised: 07/05/2022