Description

Given a control slot and a target slot, target date/time, and target 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, target date], then the target slot’s value 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 three-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.

Note: this function is very similar to HypTargetSim: this only difference is that HypTargetSim 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 target and the list of control slot values.

Type

LIST {BOOLEAN, NUMERIC, 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 target slot exist as well as all other objects necessary to compute the target 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 target slot, the slot whose value you would like to attain a certain value.

7

DATETIME

The target date/time, the timestep at which you would like the target slot to attain the desired value.

8

NUMERIC

The target value, the value which you would like the target slot to achieve at the target date/time.

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 value which differs by no more than the tolerance from the desired target 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 target values which does not include the input target value. In this case the value returned is the minimum or maximum control slot value, which ever leads to a target value closest to the input target 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 HypTargetSimWithStatus can not find a satisfying control value, a diagnostic will be posted describing why it failed to do so.

Comments

See also documentation for HypTargetSim 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.