skip to main content
USACE-SWD Modeling Techniques : Miscellaneous Topics : Performance Tips and Information
Performance Tips and Information
Run time of the USACE‑SWD models is always an important feature to consider. See Improving Model Run Performance in Debugging and Analysis for general tips and approaches.
User Tips
The following items are specific tips for USACE‑SWD models.
• Make sure each rule is not executing more often than necessary. Typically, each rule only needs to execute once per timestep. See Execution Constraints to Execute Rule Once per Timestep for details on the approach to control this.
• When diverting from reservoirs using the ComputeReservoirDiversions function, make sure that Reservoir.Available for Diversion is not linked to Diversion.Available For Diversion. This link is unnecessary and can lead to excessive dispatching of the diversion object. The following section describes the issue:
When the diversions from reservoirs conservation operation was initially implemented, the reservoir and the diversion object required the following links:
Reservoir.Diversion <---> Diversion.Diversion
Reservoir.Available for Diversion <---> Diversion.Available For Diversion
This was required because the diversion object required that Available For Diversion was known as one of its dispatch conditions. It was later found that the link between the Available For Diversion slots was leading to issues when the reservoir was low. To fix this, Available For Diversion was removed as a required known in the Diversion object's dispatch method (in RiverWare 4.9). With this change, the link between the slots is no longer necessary.
In terms of performance, with this link in place, whenever the reservoir sets a new storage, the Available for Diversion at the next timestep is set. With the link in place, the value propagates to the diversion object and the diversion object redispatches. This can lead to unnecessarily dispatching these objects many times over the forecast period.
Remove these links if they exist. See Linking Setup for details on the linking structure.
• If not debugging, disable the following, as they are computationally intensive and are typically not necessary:
– Diagnostics
– RPL Set Analysis
• Close any unused open windows, particularly the Model Run Analysis tool. This and other dialogs attempt to redraw after every timestep and can slow down the model.
• Close other applications that are competing for computer resources.
Internal RiverWare Changes
The following sections describe changes to the code to specifically improve performance in USACE‑SWD models.
No Dispatching Beyond Forecast Period
The default behavior in RiverWare is for objects to dispatch whenever they have adequate information to do so. It was noted in the analyses that objects were dispatching well into the future beyond the end of the forecast period at the current timestep due to the step response routing method on reaches that distributes a current inflow into outflows at future timesteps. No information beyond the forecast period is used for calculations at the current timestep, and information from dispatching beyond the forecast period is overwritten anyway by subsequent calculations as the model steps forward. Dispatching beyond the end of the forecast period is, therefore, not necessary.
To limit dispatching to the forecast period only, changes were made to the controller. At the beginning of the run, the flood basin computational object tells the controller what the forecast period is. If there are multiple flood basin computational objects, the controller uses the largest forecast period. At the beginning of each timestep, the controller calculates the end time of the forecast period by adding the forecast period to the current controller time. A condition was added to the checkDispatching method so that if the date of the dispatch is beyond the end time of the forecast period, the dispatch entry is not put on the dispatch queue for solving.
No Setting of Values Beyond Forecast Period in Step Response Routing
The step response routing method in reach calculates and sets outflow values into future timesteps. If the timesteps are beyond the end of the forecast period, this work is unnecessary because this information is not needed in the model for solving at the current timestep.
The step response routing method was modified so that if forecasting is being used, the reach asks the controller for the end time of the forecast period. The step response calculations are then limited so that outflow values are not calculated or set beyond the end of the forecast period.
Cache Routing Vectors
On the computational subbasin, there was significant time spent getting the appropriate control point and looking up the routing vector on its routing coefficients slot for the upstream reservoir.
Instead of doing this lookup each time, the code was changed to cache the routing vector information on a data structure in the computational object the first time coefficients are requested for a particular upstream and downstream object pair. Subsequent requests can then access the routing information from the data structure instead of redoing the lookup. If variable routing coefficients that can change with each timestep are being used, the data structure is cleared at the beginning of each timestep. Otherwise, the data structure can be used throughout the whole run.
Custom Downstream Dispatch Order
In analyzing dispatching, it was noted that excess dispatching occurs where values have been set on a number of different objects across the model. Dispatching order in RiverWare is based on a queue where objects dispatch in the order in which they come onto the queue. For example, in flood control where a value is set on each reservoir in the system, the reservoirs all go onto the queue and each reservoir dispatches in order before any objects dispatch that have come onto the queue as a result of the reservoir dispatches. This means the effect of an upstream reservoir's dispatching is not propagated to the downstream reservoir before it dispatches the first time, so it must go back on the queue to dispatch again (and maybe a third or fourth time due to additional upstream reservoirs).
To address this problem, a custom downstream dispatch order was implemented. The first time custom dispatching is called, the rule controller creates an ordered upstream to downstream list of objects in the network based on the topology information of upstream and downstream links between objects. Custom dispatching then iterates the dispatch queue successively for each object in the ordered list and dispatches all of that object's entries so that a downstream object does not dispatch before upstream effects have been propagated to it.
There is overhead associated with iterating the queue by object, so custom dispatching is only called in places where a number of objects across the basin are being put on the queue at the same time. For the COE model this has been implemented for computing incremental local inflows, the flood control rule, and the hydropower rule.
Note:  The flood control algorithm is sensitive to small changes in input values, even changes that may be within convergence of slots. Changing the dispatch order of objects can affect how very small changes get propagated downstream or not and can change results by kicking off an operation at an earlier or later timestep. The custom dispatch order actually ensures that even small changes are propagated upstream to downstream, and due to this, gives different results at particular timesteps compared to the baseline executable. However, even though results at individual timesteps may differ, the overall trends and form of the solution is the same.
Revised: 01/05/2024