Iterate

Iterate( initial, expr, until, maxIter, warn )

Iterates a computation until a termination condition (such as convergence) is satisfied, or until a maximum number of iterations is reached.

To use Iterate, the call to Iterate must occur at the top level of the definition (similar to how Dynamic must occur at the top level). The first parameter, initial, specifies the first value, and the second parameter, expr, specifies how the subsequent value is computed. The second parameter, expr, can depend directly or indirectly upon the variable defined by Iterate, forming a recurrence.

The third parameter, until, specifies a termination condition. Iterate continues evaluating expr until all array elements returned by expr are non-zero (true), or until the maximum number of iterations specified by the optional fourth parameter is reached. If the fifth parameter is specified as true, a warning is issued if the maximum number of iterations is reached without full convergence.

Iterate is often used when the iteration should occur over a large portion of your model. For smaller loops that can be self-contained in a single definition, or that appear in User-Defined Functions, the While is usually used instead.

Example

In the model depicted, the manner in which the market price reacts to a imbalance between supply and demand is modeled. Given a Price, the supply and demand at that price are forecast, and then used to determine a market price at that supply/demand point. By iterating on Price, the steady-state market equilibrium price is computed. This iteration is accomplished by defining Price as:

Iterate( Price_Guess, Next_price, abs(Next_price-price)<0.01, 50 )

This iterates until the change in price is less than 0.01, or until 50 iterations are computed.

Iterating Multiple Variables

In some cases, you may have several variables that you need to update in each iteration. For example, you may wish to update estimates for both Price and Market_size at each iteration. When you do this, it is important that you have only one variable defined as a call to Iterate. You would NOT want to define each of Price and Market_size using Iterate. Two instances of iterate in that fashion would specify two separate (and nested) iterations, which is not what is intended. Instead, what you need to do is group all variables into a single state representation. The components of that state are listed along an index.

In the above diagram, State_Index is defined as:

State_index ↓

"Price"

"Market Size"

Initial_state is defined as a table:

Table(State_index)(Price_Guess,Market_size_guess)

and Next_State is similarly defined:

Table(State_Index)(Price_Guess,Market_size_guess)

and a single call to Iterate is present in State:

Iterate( Initial_state, Next_State, abs(state-next_state)<0.01, 50)

for convenience, Price and Market_Size break out the elements of State so that their identifiers can be used directly in expressions. For example, Price is defined as Price[State_Index='Price'].

The preceeding definitions assume that State and Market_size have the same dimensionality. For example, both may be scalars, or both contain exactly the same indexes. When iterating over multiple variables, this is not always the case. When the indexes may differ, then you should place each component inside a reference. The preceeding definitions would thus become:

Initial_state := 
   Table(State_index)(\Price_guess,\Market_size_guess)
Next_state := 
   Table(State_Index)(Price_Guess,Market_size_guess)
Price := 
   #State[State_index='Price']
Market_size :=
   #State[State_index='Market Size']
State :=
   Iterate( Initial_state, 
            Next_State, 
            abs(price-next_price)<0.01 and abs(market_size-next_market_size)<1, 
            50)

Caveats

If you use Iterate in more than one node in your model, you should be careful that the two functions don't interact adversely. In general, two nodes containing Iterate should never be mutual ancestors of each other. Doing so makes the nesting order ambiguous and can result in inconsistent computations. Likewise, care must be taken to avoid similar ambiguities when using interacting Iterate and Dynamic loops.