Iterate

2021-06-30T21:32:46Z

HEshraghi: /* Example */

[[category:Evaluation Functions]]
[[category:Top level functions]]
[[Category:Doc Status D]] 

== Iterate(initial, expr, until'', maxIter, warn'') ==
Repeats the computation «expr» until the termination condition «until» becomes true (nonzero), or the number of iterations reaches «maxIter». The parameters «expr» and «until» may, and usually do, depend on variable(s) that depends on the variable defined with Iterate. This creates a recurrence, [[Draw arrows#Influence cycle or loop|cycle or loop]] in the influence diagram, something that is not otherwise allowed except in [[Dynamic]] loops. Analytica iterates the evaluation around the cycle until it reaches the termination condition «until», usually a convergence or equilibrium.

You may use [[Iterate]] only as the main function defining a variable (as with [[Dynamic]]). You may not nest it inside an expression.

'''Parameters:'''
* «initial»: the starting value for the iteration
* «expr»: how the subsequent values are computed from the previous value. «expr» may, and usually does, depend directly or indirectly upon the variable defined by Iterate, forming a recurrence or cycle in the influence diagram.
* «until»: The termination condition. Iterate continues evaluating «expr» until «until» is true (non-zero) -- if «until» is an array, until all its elements are true (nonzero) -- or until the number of iterations reaches «maxIter», if specif.
* ''«maxIter»'': (optional) The maximum number of iterations. If omitted, it will keep iterating until the «until» becomes true. Unless you are absolutely certain the iteration will converge, it is a good idea to specify a value for «maxinter».
* ''«warn»'': (optional) If true (nonzero), it will give a warning if it terminates due to reaching the maximum number of iterations «maxinter», rather than the termination condition «until».

[[Iterate]] is useful when you want adjust a variable and repeat a calculation over several variables in the model to meet a constraint. If you can perform the iteration within the definition of a single variable or [[User-Defined Functions]], it is usually simpler and clearer to use the [[While..Do]] construct.

For more complex cases, especially when you want to adjust multiple variables to solve constraints and/or find a maximum or minimum, it is simpler and faster to use the [[Analytica Optimizer Guide|Analytica Optimizer]].

== Example ==
:[[Image:Market Equilibrary Diagram.jpg]]

This example models how a market price reaches equilibrium to correct an imbalance between supply and demand. It forecasts a the supply and demand given an initial price, and modifies the <code>Price</code> iteratively until the supply exactly matches the demand reaching a market equilibrium. <code>Price</code> is defined as:

:<code>Price := Iterate(Price_Guess, Next_price, Abs(Next_price-price) < 0.01, 50)</code>

It iterates until the change in price between successive iterations is less than 0.01, or reaches 50 iterations.

== Iterating Multiple Variables ==
You may want to update several variables in each iteration: For example, both <code>Price</code> and <code>Market_size</code>. You should define only one variable using [[Iterate]]. (If you define both <code>Price</code> and <code>Market_size</code> using [[Iterate]], it will create two nested iterations, which would not do what you want.) Instead, you can define a new single variable that groups all the variables into a single state, listing them along an index.

:[[Image:Market Equilib Diagram2.jpg]]

In the above diagram, <code>State_index</code> is defined as a list of labels:
:{| class="wikitable"
! State_index ▼
|-
| "Price"
|-
| "Market Size"
|}

You define the initial state and next state each as a table indexed by <code>State_index</code>:

:<code>Variable Initial_state := Table(State_index)(Price_Guess, Market_size_guess)</code>
:<code>Variable Next_State := Table(State_Index)(Price_Guess, Market_size_guess)</code>

and define <code>State</code> using Iterate:
:<code>Variable State := Iterate(Initial_state, Next_State, abs(state-next_state) < 0.01, 50)</code>

For convenience in the rest of the model, it is useful to define <code>Price</code> and <code>Market_Size</code> as the elements of <code>State</code>:
:<code>Variable Price := State[State_Index = 'Price']</code>
:<code>Variable Market_Size := State[State_Index = 'Market Size']</code>

So far, we assume that <code>State</code> and <code>Market_size</code> have the same dimensions -- both are scalars, or both are arrays with the same indexes. If you want them to have different dimensions, you can include their values using [[Using References|references]]:

:<code>Variable Initial_state := </code>
::<code>Table(State_index)(\Price_guess, \Market_size_guess)</code>
:<code>Variable Next_state := </code>
::<code>Table(State_Index)(\Price_Guess, \Market_size_guess)</code>
:<code>Variable Price := </code>
::<code>#State[State_index = 'Price']</code>
:<code>Variable Market_size :=</code>
::<code>#State[State_index = 'Market Size']</code>
:<code>Variable State :=</code>
::<code>Iterate(Initial_state, Next_State, </code>
:::<code>Abs(Price-next_price) < 0.01 AND Abs(Market_size - Next_market_size) < 1, </code>
:::<code>50)</code>

Note that '[[Using References|\]]' and '[[#]]' are the reference and de-reference operators. Gathering references to values into an array is a flexible method that generalizes to any number of variables.

== Iterate with Dynamic ==
Iterate can be used in conjunction with [[Dynamic]]. Depending on the model structure, this can either result in an iteration within a dynamic loop, where the iteration to convergence occurs at each point in time, or it can result in a dynamic loop within an iteration, in which case the entire dynamic loop is computed to completion within each iteration.

Suppose <code>X</code> is a variable defined with Iterate, and <code>Y</code> is a variable defined with [[Dynamic]]. Then <code>X</code> might depend directly or indirectly on <code>Y</code>, and <code>Y</code> might depend directly or indirectly on <code>X</code>. This creates four distinct dependency structures. When neither <code>X</code> nor <code>Y</code> depends on the other, then there is no interaction. Similarly, when <code>Y</code> depends on <code>X</code>, but <code>X</code> is not downstream of <code>Y</code>, then <code>X</code> is not within <code>Y</code>'s dynamic loop, so again there is no interaction. In this case, <code>X</code> is iterated to completion once, independent of the dynamic loop, then the dynamic loop performs its looping using this value.

When <code>X</code> depends on <code>Y</code>, but <code>Y</code> does not depend on <code>X</code>, then the dynamic loop is completely inside the Iteration for <code>X</code>, so that the dynamic loop is computed to completion within each iteration.

The most difficult case is when <code>X</code> and <code>Y</code> both depend on the other. When this happens, the iterate expression could, in principle, be interpreted as being inside the dynamic or around the dynamic. Analytica resolves this ambiguity by assuming that the iterate is inside the dynamic, so that as the dynamic loop is evaluated at each time period, the iteration in <code>X</code> is run to completion for that time period. Variables inside <code>X</code>'s definition are implicitly assumed to be sliced by the current dynamic time (as occurs with any variable appearing inside a dynamic loop).

You may encounter situations where you want to compute one or more variables using Iterate, which in turn are utilized within a dynamic loop, but where you desire the iteration to occur around the dynamic loop. For example, you may have completed an entire [[Dynamic]] model, and now you want to wrap [[Iterate]] around the full model to adjust an input parameter. In the future, we may introduce a new variation on the iterate function that would make it possible to specify that [[Iterate]] is wrapped around a given dynamic loop. Until then, one way to cause Iterate to wrap around a dynamic loop is by using a [[WhatIf]] to compute the value of the input parameter. To demonstrate, suppose you have an input parameter, <code>K</code>, used by a dynamic model having some output <code>Y</code>. We want to define <code>K</code> using [[Iterate]] where the update expression and termination expressions depend on <code>Y</code>. To do this, we introduce two variables:
:<code>Variable Y2 := WhatIf(Y, K, K2)</code>
:<code>Variable K2 := Iterate(K, f(K2, Y2), g(K2, Y2))</code>

Here <code>f()</code> is the update expression and <code>g()</code> is the termination expression. When <code>K2</code> is evaluated, the iteration re-evaluates the full model repeatedly, with <code>K2</code> eventually being set to the "converged" value for the parameter <code>K</code>. As a final step, we may want to set <code>K</code> to be this computed value for <code>K2</code>. For this last step, we would need to use a button:
:<code>Button Update_K := (K := K2)</code>

Pressing the button causes the entire evaluation to take place.

(To do: provide some examples)

== Interacting Iterate Functions ==
If you have two (or more) variables defined using the [[Iterate]] function, they should not be mutually dependent on each other. This case creates an ambiguity (for example, the result would depend on which was evaluated first), and results in an error message.

It is okay for one to be nested within the other, in which case the inner iteration runs to convergence during each iteration of the outer iterate. However, the need for nested iterations like this are rare. You should make sure that you don't intend to have a single iteration with multiple variables updated in the same iteration (see the earlier section on this page).

If you have two interacting Iterate loops that are not clearly nested, you will see this error message:

:''A disallowed cyclic dependency involving the Iterate function in ''ident'' detected. You may have two nodes defined with Iterate functions, with each depending on the other. If you use two Iterate functions, one needs to be clearly nested inside the other. If you intend to have a single iteration involving two or more nodes, the Iterate function should appear only once.''

=== Iterate with Change in Evaluation Mode ===
Suppose <code>X</code> is defined using [[Iterate]], and the update expression depends on [[Sample]](X) -- for example, it may use a statistical function like [[Mean]](X). If <code>X</code> is evaluated in [[Mid]] mode, it appears as if there are two interacting Iterate loops, and the above error message, ''A disallowed cyclic dependency involving Iterate....'' occurs.

== Iterate vs. While..Do ==
[[Iterate]] and [[While..Do]] are closely related, and both are often used for implementing convergence algorithms. When implementing an iterative algorithm in a [[User-Defined Functions|User-Defined Function]], you would normally use [[While..Do]]. However, in some situations you may develop a fairly sizable influence diagram model, where you wish to iterate over the entire model. In that case, Iterate is very convenient, and may require only small modifications.

The [[While..Do]] construct requires its parameter, which determines when the loop terminates, to be atomic, while [[Iterate]] allows array-valued termination conditions, but continues until all cells are true.

There are a few other approaches to implementing iterations within Analytica. [[NlpDefine]] performs a full optimization search. The [[Solve]] and [[GoalSeek]] functions are similar, although scaled down somewhat in their sophistication. [[User-Defined Functions]] can be recursive, although the [[recursion]] depth is usually limited to 255, which can be a limiting factor. And to iterate over an existing model structure, [[While..Do]] can be used with [[WhatIf]], or from a button script, [[While..Do]] can be used with assignment (often a useful way to iterate in very large scale sampling applications that exceed memory required for built-in Monte Carlo sampling). And of course, there is [[Dynamic]].

== See Also ==
* [[Analytica_User_Group/Past_Topics#The_Iterate_Function|Webinar on the Iterate Function]]
* [[Dynamic]]
* [[ComputedBy]]
* [[While..Do]]
* [[Using References]]
* [[DefineOptimization]]
* [[WhatIf]]
* [[Recursion]]
* <code>Newton Raphson Method.ana</code> example model in the <code>Example Models/Decision Analysis folder</code> installed with Analytica

ChanceDist - Custom discrete distribution

2021-06-30T20:03:51Z

HEshraghi: Remove a usage section

[[category:Custom distributions]]
[[category:Discrete distributions]]
[[Category:Doc Status C]] 

== ChanceDist(P, A, I) ==

Creates a discrete probability distribution. «A» is an array of outcomes, and «P» is the corresponding array of probabilities. «A» and «P» must both be indexed by «I».

== When to Use ==

Use [[ChanceDist]]() instead of the probability table when:
* The array of outcomes «A» is multidimensional, or
* The outcomes and probabilities arrays are defined as other Variables; the Variables can be used in other parts of your model.

As of build 4.0.0.51, [[ChanceDist]] cannot be used within [[Random]]. This enhancement may occur in future releases.

== Example ==

:<code>Index Index_b := [Red, White, Blue]</code>
:<code> Variable Array_1 :=</code>
:{| class="wikitable"
! colspan="3" | Index_b ▶
|-
! Red !! White !! Blue
|-
| 0.3 || 0.2 || 0.5
|}

== Mid Value ==

[[ChanceDist]] is a discrete distribution, and as such it assumes that the data points in «A» are categorical (discrete). It also assumes that the ordering for the points is the ordering given in «A». Thus, the [[Mid]] value returns the middle point along the ordering given by «A» (where the position of the middle point is based on the weightings of each point in «P»).

When «A» consists of unordered numeric points, this can be confusing, since the [[Mid]] value isn't the same as the numeric median. For example, with <code>P = 1/5 and</code> <code>A = [9, 3, 1, 8, 7]</code>, the [[Mid]] value is 1.

Even when the points in «A» are ordered and numeric, [[Mid]] is not the same as the continuous median when the number of points is even. For example, <code>P = 1/4</code> and <code>A = [1, 2, 3, 4]</code> would return <code>Mid = 3</code> even though <code>Median = 2.5</code>. The discrete median is always a point in the domain, hence must be one of the points in «A».

In general in Analytica, [[Mid]] returns the median for a distribution. This is still the case even in cases just mentioned as long as you realize that [[ChanceDist]] returns the categorical median, which is different from the continuous median. For example, if you define <code>X := ChanceDist(P, A)</code>, where «A» is an index, and set the domain of «X» to be an index domain based on «A», then the statistics result view for «X» will display the categorical median which will coincide with the [[Mid]] value for «X». The index-valued domain tells Analytica that «X» is discrete with a defined element ordering given by «A».

When you are really dealing with a continuous quantity, you should be using either [[ProbDist]] or [[CumDist]] to define the distribution. If you really want to re-sample from «A», but want [[Mid]] to return the "numerically-middle" sample, then use (for uniform «P»):

:<code>ChanceDist(1/Size(I), Sort(A, I), I)</code>

or for non-uniform P:

:<code>Var order := SortIndex(A, I) Do ChanceDist(P[I = order], A[I = order], I)</code>

== See Also ==
* [[ProbTable]]
* [[Uniform]]
* [[Prob_ChanceDist]]
* [[Custom discrete probabilities]]
* [[Distribution Densities Library]]

Analytica Docs - User contributions [en]

Iterate

ChanceDist - Custom discrete distribution