View source for Var..Do

[[Category: Evaluation Functions]]
[[Category: Variables]]

{{ReleaseBar}}
{{Release|5.0||''The <code>Var</code> is now deprecated. We recommend you use [[Local|Local..Do]] instead.''}}
 
== {{Local}} ''x'' := ''expr'' Do ''body'' ==
Declares a local value with identifier «x», so that the identifier «x» refers to the value obtained by evaluating «expr».  The identifier «x» can then be referred to within the «body» expression.  The expression «body» is said to be the ''lexical context'' of «x», since outside of the lexical context, the identifier «x» is not recognized.
:<code>{{Local}} q:=F(a,I) Do q / [[Sum]](q,I);</code>
:<code>q+1</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ ''error -- q is no longer in lexical context'' }
{{Local}} is often used in a procedural syntax, where the declaration is followed by a semi-colon and the '''Do''' keyword is omitted, such as:

:<code>{{Local}} x := [[Sum]](A, I);</code>
:<code>{{Local}} y := [[Sum]](B, I);</code>
:<code> (x + y) * (x - y)</code>

With this syntax, the lexical context for «x» extends from the expression immediately following the semi-colon to the end of the sub-expression that the [[Var..Do]] declaration is embedded in.  For example, in the following expression the lexical scope of <code>a</code> is shown in green.

:<code>1 + ({{Local}} a := b^2; <span style="background-color:LightGreen">{{Local}} c := a/b; c^2 - a - c - 2</span>) + 5</code>

{{Release|5.2||You can declare multiple local identifiers on the same line by separating them with commas. All have the same lexical scope.
:<code>{{Local}} a{{eq}}J, b, c, d{{eq}}2;</code>
When the {{eq}}«expr»  is omitted, the local is initialized to [[Null]]. So in the preceding example, <code>b</code> and <code>c</code> are set to [[Null]].

When a function has multiple return values, you can capture these into separate locals by placing the local names in parentheses. For example, the function [[SingularValueDecomp]] returns 3 matrix values.
:<code>{{Local}} (u, w, v) {{eq}} [[SingularValueDecomp]](a, I, J, J2);</code>}}

== Dimensionality Declaration ==
The ''allowed'' dimensions of a local value can be declared using the syntax:
:<code>{{Local}} «x»[«indexList»] := «expr» Do «body»</code>

an equivalent anachronism (considered deprecated) is
:<code>{{Local}} «x» := «expr» in each «indexList» Do «body»</code>

There are some situations where the extra information about which indexes are allowed is required in order to ensure that the «body» expression will array abstract correctly when new dimensions are added to a model later.

When the allowed indexes are declared, Analytica will ensure that when «body» is evaluated, the value of «x» will not have any indexes not listed in «indexList».  If the original value assigned to «x» has indexes beyond those found in «indexList», Analytica will automatically iterate, evaluating «body» multiple times one slice at a time. 

:''Note: You should not make any assumptions about the order of the iteration, or an assumption that every index value will actually be visited. Our spec for Local allows the leeway for the expression compiler to re-order iteration order, to skip cases that it can prove will not impact the final result, or even to evaluate multiple cases concurrently. Speed optimizations like these have no detectable effect on your result except in the case where «body» has side-effects. Side-effects may include user-interactions (like [[MsgBox]]), writing/logging to files, or assignment. In contrast, the [[For..Do]] declaration also iterates while also guaranteeing sequential ordered and complete visitation of all cases. Because a Local declaration allows the expression compiler extra leeway to apply speed optimizations, [[Local..Do]] declarations are usually preferred to [[For..Do]] since they are declarative and faster, unless, of course, you rely upon procedural programming style side-effects within «body». You may find it conceptually convenient to imagine Local..Do iterating over each non-allowed index combination, which is logically equivalent to what actually happens as long as you have no assignments or other side-effects within the «body».''

If the result of «expr» does not already have all the indexes declared in «indexList», the missing indexes are ''NOT'' added to «x».

==== Example ====
The following computes the standard deviation across only the time periods that are profitable:

:<code>{{Local}} earnings[Time] := revenue-expenses;</code>
:<code>{{LocalIndex}} profitTimes := Subset(earnings > 0);</code>
:<code>[[SDeviation]](earnings[Time = profitTimes], profitTimes)</code>

Without the dimensional declaration restricting <code>earnings</code> to the [[Time]] index, [[Subset]] would complain that earnings has more than dimension in the event that <code>revenue-expenses</code> has an index in addition to [[Time]].  The dimensional declaration here allows the expression to fully array abstract if new dimensions are added to the model.

The above expression is meant to be illustrative, but for completeness we also note an alternative expression for the same computation that does not require iteration:
:<code>{{Local}} earnings := revenue - expenses Do [[SDeviation]](earnings, Time, w: earnings > 0)</code>

=== Atomic Declarations ===
A special case of the dimensional declaration is the declaration that a local value must be ''atomic'' -- i.e., a single non-array value.  In this case, the we simply specify a zero-length list of allowed indexes:
:<code>{{Local}} «x»[] := «expr» Do «body»</code>

Then inside «body», «x» is guaranteed to be atomic.

==== Example ====
The following computes the log-factorial of a number in an [[Array Abstraction|array-abstractable]] fashion (i.e., works even if ''n'' is originally an array:
:<code>{{Local}} n[] := n do [[Sum]]([[Ln]](1..n))</code>

Note: The local value can have the same identifier as a global variable, and the value of the global can appear within «expr» since that is outside the local identifier's lexical scope.  Inside «body», the identifier always refers to the local value.  Having two local values with the same identifier is not allowed.

=== Atomic..Do syntax ===
Analytica also recognizes the following syntax for declaring a local value as atomic:
:<code>Atomic «x» := «expr» Do «body»</code>

This syntax is equivalent to <code>{{Local}} «x»[] := «expr» Do «body»</code>{{Release||4.6| as long as the result of «expr» does not contain any [[Handle]]s.  It is actually equivalent to the following variation of [[Var..Do]]:
:<code>MetaVar «x»[] := «expr» Do «body»</code>}}

== Explicit Iteration ==
The following syntax:
:<code>{{Local}} «x» := «expr» In «I» Do «body»</code>

evaluates «expr», then iterates over each element of index «I», setting «x» to the «expr»[«I» = i] slice while «body» is evaluated.  In a sense, this is a dual to the dimension declaration -- here we are specifying the dimensions that are ''not'' allowed in «x», while the ''{{Local}} «x»[«I»] := ...'' syntax specifies the dimensions that are allowed. However, in this syntax, only a single index can be specified.

This dual style iteration is very rarely used.

== Assignment ==
Although side-effects are generally prohibited from within Analytica expressions (due to dependency-maintenance and Analytica's adherence to the principle of [http://en.wikipedia.org/wiki/index.php/Referential_transparency_(computer_science) referential transparency]), you can change the value of a local value using the [[Assignment Operator::_::=|assignment operator, :=]].  For example:

:<code>{{Local}} n := 27;</code>
:<code>{{Local}} steps := 0;</code>
:<code>[[While]] (n > 2) Do (</code>
::<code>steps := steps + 1;</code>
::<code>n := [[If]] [[Mod]](n, 2) [[Then]] n/2 [[Else]] 3*n + 1</code>
:<code>);</code>
:<code>steps</code>

Assignment always resets the value of «x», even if «x» contains a [[Handle|handle]].  In other words, when you assign to a local value, you are resetting the value that the local identifier refers to, as opposed to changing the value of the object pointed to by the local value.  See more in the section below on Meta-Inference.

=== Slice assignment ===
You can also assign to individual slices of a local value.  This is described in detail at [[Slice assignment]].

== Evaluation Mode ==
A local value refers to a value, not an object. Hence, the terminology "local value" (or just "local") should  be used and it should not be called a "local variable".  A local value is not a variable -- a variable in an object that has attributes, has a separate mid-value and sample-value, and usually appears on an influence diagram.  A local value has no attributes, does not appear in the global namespace, and does not maintain a separate [[Mid]]- and [[Sample]]-value.  

When the local value is declared, «expr» is evaluated in the current Evaluation mode.  From that point on, «x» becomes an alias for the value that resulted from that evaluation, whether or not the identifier «x» appears in Mid- or Sample- context.  This can be a source of confusion.  Consider the following example:

:<code>{{Local}} u := [[Uniform]](0, 1);</code>
:<code>[[SDeviation]](u)</code>

When this expression is evaluated in [[Mid]] mode it is not equivalent to <code>[[SDeviation]]([[Uniform]](0, 1))</code>.  The later evaluates to 0.29, while the former results in 0.  This is because <code>u</code> is assigned <code>[[Mid]]([[Uniform]](0,1))</code>, which is 0.5, and then the result is <code>[[SDeviation]](0.5)</code>, which is zero.

You can, of course, call [[Sample]]() or [[Mid]]() explicitly from «expr» when desired, e.g.:
:<code>{{Local}} u := [[Sample]]([[Uniform]](0, 1));</code>
:<code>[[SDeviation]](u)</code>

This confusion can be avoided by adhering to and conceptualizing the terminology that «u» is a ''local value'', not a ''local variable''. 

== Meta-Inference and the use of handles ==
Most models built in Analytica make no use of [[handle]]s, and so the considerations described here impact only the most advanced modelers.  Inference involving [[handle]]s provides a mechanism for [[meta-Inference]] -- that is, reasoning about or altering your model from within Analytica itself.  Advanced uses of [[meta-Inference]] can be used to extend Analytica's capabilities in many ways, creating functionality in your model beyond what is offered directly by the Analytica interface.

A [[handle]] is essentially a pointer to an Analytica object, such as a Variable, Index, or Module object. [[Meta-inference]] implementations usually need to store [[handle]]s inside local values, assign handles to local values, read information about the objects pointed to by these handles, and manipulate the objects pointed to by these handles.  

When implementing [[meta-inference]] algorithms, you should never use [[Var..Do]] to declare locals, but instead should use {{Release||4.6|[[MetaVar..Do]]}}{{Release|5.0||[[Local]]}} or [[LocalAlias..Do]]. The older [[Var..Do]] syntax suffers from several inconsistencies with how handles are treated, which is why is new deprecated (as of [[Analytica 5.0]]). 

* [[LocalAlias]] «x» := «expr» Do «body»
*: or equivalently, Alias «x» := «expr» Do «body»
* {{MetaVar}} «h»''[«indexList»]'' := «expr» Do «body»

When [[LocalAlias..Do]] is used to assign a [[handle]] to «x», then «x» is treated everywhere as an alias of the object pointed to.  If you were to copy the expression and substitute the object's identifier everywhere «x» appears (assuming the object is in the global namespace), you would get the identical result.  Once the local «x» is assigned a handle, you can no longer change the handle (i.e., change which object is pointed to), since an assignment, «x» := z, would be interpreted as an assignment to the object pointed to, rather than changing what «x» refers to.  You cannot declare dimensions in a [[LocalAlias..Do]] or [[LocalAlias..Do|Alias..Do]] declaration.

When a [[handle]] is assigned to a local value declared as {{MetaVar}}, then the local identifier refers to an atomic value that has a data type of "handle".  Operations such as ''«h»+1'' do not make sense, since this would be attempting to add 1 to a handle value, rather than adding 1 to value of the variable pointed to by the handle.  {{Release||4.6|As the declaration name [[MetaVar]] implies, this is usually the preferred method for declaring local values that are used to manipulate handles to objects. }} Your local value may contain a handle, or an array of handles, as well as other data types. {{Release||4.6|Like [[Var..Do]], you can declare dimensions inside a [[MetaVar..Do]] declaration (for example, the dimensions allowed to exist in the array of handles).}}

When a handle is assigned to a local «x» declared using [[Var..Do]], it acts as a hybrid between a [[LocalAlias]] and a {{MetaVar}}, which is confusing, so that we recommend that you do not use [[Var..Do]] with values containing handles.  In a value context, «x» acts as an alias to the object.  However, in an assignment context (an L-value context), it a acts like a local value, in which the local «x» changes to refer to the new value, rather than causing the object pointed to by «x» to be changed.  Consider:

:<code>Var x := [[Handle]](A);</code>
:<code>x := x + 1</code>

Here <code>x</code> is first assigned a handle to <code>A</code>.  In the assignment operation, when the right-hand side of the assignment is evaluated, <code>x + 1</code> refers to the value of <code>A</code> plus 1.  Hence <code>x</code> acts as an alias to <code>A</code>.  The assignment changes what the value the local identifier refers to, but does not alter <code>A</code>.  After the assignment, the local <code>x</code> contains a numeric value (or perhaps array of numeric values) and no longer points to the variable <code>A</code>.

Suppose in the above example that <code>A</code> evaluates to a [[Self-Indexed Arrays|self-indexed array]].  The right-hand side of the assignment is a value context, so in this case, <code>x</code> refers to the array-value of <code>A</code>.  If we wanted <code>x</code> to alias the index value of <code>A</code>, rather than the array value, we could use the following instead:

:<code>Var x := [[Handle]](A, asIndex: true);</code>
:<code>x := x + 1</code>

When you assign a handle to a local identifier that has been declared using {{Local}}, the value itself has a data type of [[Handle]]. This can be contrasted with locals declared using [[LocalAlias]], for which the identifier is the identifier of the object. Consider this example

<code>
:{{MetaVar}} h := [[Handle]](Va1);
:h := 2
:[[LocalAlias]] x := [[Handle]](Va3);
:x = 3
</code>

After this code is evaluated, the object <code>Va1</code> remains unchanged, the local <code>h</code> now has a value of 2 instead of a handle, and the [[Definition]] of the global variable <code>Va2</code> has been changed to 3. The local <code>x</code> still refers to the same variable as the global identifier <code>Va3</code>. The last line is only allowed in a context that allows side-effects to global variables, such as from a button script. 

When you have a handle to an object in a {{MetaVar}}, and you want to use it as if it were a global variable, you do this by using [[LocalAlias]] as illustrated here
<code>
:{{MetaVar}} h := [[Handle]]( I );      { The local with the handle to an object, in this case an index }
:[[LocalAlias]] J := h;
:[[Sum]]( a, J )
</code>

== History ==
There has been a long history of changes and enhancements to the Analytica language's syntax and treatment of local variables, which has lead to a proliferation of different constructs for declaring local variables, with subtle distinctions between them, and many of the distinctions really just required to support backward compatibility for models created in older releases of Analytica. Starting with [[Analytica 5.0]], this complexity has been simplified, so that now there are only three ways you need to know for declaring locals:
<code>
* [[Local]] v := ...;
* [[LocalAlias]] x := ...;
* [[LocalIndex]] I := ...
</code>
In addition, you may want to use [[For..Do]] in some occasions, which also introduces a local identifier.

The [[Local]] keyword was introduced in [[Analytica 5.0]] as is equivalent to [[MetaVar..Do]]. [[MetaVar..Do]] was introduced (in release [fill in]) to correct inconsistencies in [[Var..Do]]. [[Var..Do]] still has those inconsistencies, which can make it confusing to use when writing code that involves handles, but it continued to be used extensively since [[MetaVar..Do]] had such an unnatural name. In Analytica 1.0, local variables were declared via a [[Using..Do]] construct, now considered very archaic and seldom seen.

[[Analytica 5.2]] introduced several enhancements to local declarations. These include the ability to omit the «expr» value for a local (so that it defaults to [[Null]], and to declare multiple identifiers in the same declaration, both of which are illustrated by
:<code>{{Local}} a, b, c;</code>
It also introduced <code>reduced</code> dimensionality qualifier, and the ability to capture multiple return values.

== See Also ==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Local Values]]
* [[MetaVar..Do]]
* [[For versus Var]]
* [[For..Do]]
* [[Atomic..Do]]
* [[Index..Do]]
* [[MetaIndex..Do]]
* [[Meta-Inference]]
* [[LocalAlias..Do]], 
* [[Assignment Operator :=]]
* [[Slice assignment]]
* [[Function Parameter Qualifiers]]
* [[Looping over a model]]
* [[Dynamic loop]]
</div>