Description

Given a control slot and a limit slot, limit end date/time, and limit value, this function uses hypothetical simulation (see description of the predefined function HypSim) to find a value x such that if the control slot were set to x at all timesteps in the range [current date, end limit date], then the limit slot’s maximum value in this range would equal the target value. If the value x exceeds the physical constraint for that slot at a particular timestep (max outflow on a reservoir for example), then the constrained value is used instead of the x value for that timestep.

A four-item list is returned. The first item in the list is a boolean TRUE value if a satisfying control slot value was found, FALSE otherwise. If the first item is TRUE, then the second item is the satisfying control slot value, otherwise this value is as close as the function could get to finding such a value. The third item is a list of the control slot values used in the solution. These values will all be the same as the second item, except if some of the values were constrained due to physical limitations. The fourth item is a list of the limit slot values that correspond to the control slot values given in the previous list.

Note: this function is very similar to HypLimitSim: this 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 and the additional information discussed above.

Type

LIST {BOOLEAN, NUMERIC, LIST, LIST}

Arguments

Type

Meaning

1

STRING

The name of the Subbasin over which to perform the hypothetical simulations. This should include the objects on which the control and limit slot exist as well as all other objects necessary to compute the limit slot’s value.
If there is no Subbasin with the given name, the string is taken to be the name of an object and a temporary Subbasin is created containing only that object.

An error will be issued if this subbasin contains a Data Object.

2

SLOT

The control slot, the slot with which you desire to control the target slot’s value.

3

NUMERIC

The minimum control slot value. A value less than this is not considered a legal return value.

4

NUMERIC

The maximum control slot value. A value greater than this is not considered a legal return value.

5

LIST { LIST { SLOT, NUMERIC, DATETIME } }

Fixed value(s) the user would like to set in each hypothetical simulation. Each item in the list is a list itself containing a slot, the value to set, and the timestep at which to set it.

6

SLOT

The limit slot, the slot whose value you would like to attain a certain value.

7

DATETIME

The end limit date/time, the end of the time range during which you are concerned with the limit slot’s value.

8

NUMERIC

The limit value, the value which you would like the limit slot to achieve but not exceed during the limiting time range.

9

NUMERIC

The tolerance or desired accuracy of the returned value. If the function is successful, it indicates that setting the control slot to the returned value will lead to a maximum limit slot value which differs by no more than the tolerance from the desired limit value.

10

NUMERIC

The maximum number of iterations of hypothetical simulations allowed. If this number is reached without finding an return value within the tolerance, then the function fails.

11

NUMERIC

The minimum number of timesteps before and after the current timestep which might be involved in the simulation. As part of hypothetical simulation RiverWare makes copies of the objects in the subbasin and this input is used to determine how much data should be copied from each object. One can usually set this value to 0 and RiverWare will use a heuristic to determine the range over which to copy data. If this function fails because there was not enough data on some object, then input a higher value.

Evaluation

There are two conditions in which that function will fail but this function will return false as the first item in the return list:

• The minimum and maximum control slot values lead to a range of limit values which does not include the input limit value. In this case the value returned is the minimum or maximum control slot value, which ever leads to a limit slot value closest to the input limit value.
• The tolerance is not achieved within the iteration limit. In this case, the value returned is the current best guess.

If "Hypothetical Simulation" diagnostics are turned on, then if HypLimitSimWithStatus can not find a satisfying control value, a diagnostic will be posted describing why it failed to do so.

Comments

See also documentation for HypLimitSim for more details; the differences between these two functions are how problems are dealt with, this function is more flexible (as described in the Evaluation section).

See also documentation See Hypothetical Simulation Overview; all comments mentioned there apply here as well.