View source for Proactive Evaluation

[[Category:Evaluation]]

Normally, Analytica uses "lazy evaluation" -- it evaluates (i.e. computes) variables only when needed -- i.e. when you ask to see a r
Sometimes you want end users to see results as soon as they look at a user interface without having to click on '''[calc]''' buttons.  You can enable this by setting selected variables or modules for "Proactive evaluation" -- so that it evaluates those results as soon as you open their user-interface diagram and recomputes them when you change a variable that influences them.

== Lazy vs. Proactive evaluation ==

When you run a program or model in most computer languages and simulation software, the runtime system evaluates (i.e. computes) the value of every variable in a sequence determined by the program. So you have to wait while it runs. If you want to see the effect of changing an input assumption, you have to rerun the whole model.  Analytica's [[Flow architecture]] works in a different way. It normally does ''lazy evaluation'': It computes each variable X only when it needs to -- e.g. when you press a '''Calc''' button to view the result for X as a number, table, or graph. It must also compute any unevaluated variables that influence X -- i.e. on which X depends. After computing a variable, it retains (''caches'') its value for rapid redisplay when needed, until you change something that influences X, when it is reset to "uncomputed". The advantages of lazy evaluation are: 
* It only computes the variables you want to see, so you don't need twait while it computes everything else, as in a spreadsheet or most other modeling languages.
* It retains the result of any computation (while still valid) so you can view it again instantly.
* When you change an input, it only recomputes the things affected by that input and which affect the results you want to see.

Analytica's [[Flow architecture]] is what enables it to do this. It tracks the dependencies among variables, and which variables have been computed or invalidated. It knows what it needs to compute and when, without you having to think or worry about these issues -- which often take a great deal of effort to manage with conventional languages and models. 

The question of when to evaluate a variable can be subtle. Some models contain computed indexes -- i.e an Index variables that is not a simple list of variables.  If a computed index is used in a  [[Choice]] menu or an edit table, Analytica normally computes the index when loading the model so that the choice menu or edit table can display properly.  You can control this by unchecking  '''Proactively Evaluate Indexes''' in the [[Preferences dialog]]. 

:[[image:proactive preference.png]]

== Proactively compute user outputs ==

''New to [[Analytica 6.0]]''

Because of lazy evaluation, Analytica normally shows user output variables with a '''[calc]''' button initially. This also applies to Tall and Frame nodes in ACP. So, a user must click the '''[calc]''' button to launch the calculation and see the result when complete. Sometimes you may prefer to compute results and show them immediately when the model starts, or when the user views a diagram with user outputs, and recompute when the user changes an input that influences them.  You can do this by setting '''Proactive evaluation'''. 

The downside to proactive evaluation is, for calculations that take a long time, the user may prefer not to have to wait while the model or a user interface diagram is loading.  This can be annoying if you want to wait on recomputing a result until you've changed several inputs.  So it's best to set proactive evaluation only for results that compute quickly -- within a few seconds.

You can set proactive evaluation for user outputs at three levels:
* Module:  Applies to all user outputs in the diagram for that Module. The outputs are computed when you view the diagram (including user outputs, tall nodes, and frame nodes in ACP). 
* Variable: Applies to the variable and so any user outputs it may have in different diagrams. The variable is also proactively computed when the model is first loaded.
* User Output: Applies to a single user output node instance. If the same variable has another output node in a different diagram, viewing the other diagram won't trigger the proactive calculation. This does not cause the variable to be proactively evaluated at model load time.

You can also set Proactive evaluation 
*  Only in browse mode, or in both browse and edit mode. It is sometimes helpful to keep proactive calculation off in edit mode while you are developing your model logic, but switch it on for end users in browse mode.
* Only for mid values, for prob-values (uncertain or sample values), or both.  Setting Proactive evaluation only for Mid values is useful where it can compute mid values fast, but  probabilistic simulation takes a long time.

=== How to configure Proactive calculation of user outputs ===

There isn't yet a built-in user interface to configure Proactive evaluation. But. there's a standard library to make it easy (compared to using the [[Typescript Window]]):
# Select '''Add Library...''' on the [[File menu]] 
# Select <code>"Configure Proactive User Outputs"</code> library to import into your model.
# Open the library module, where you'll find this panel:

<center>[[image:Configure proactive configuration.png]]</center>

# If you've added modules or user outputs since you last visited this panel, press the '''[Refresh]''' button. 
#  Press the "Which diagram" menu, which shows all modules with user outputs. Select the diagram containing the user interface. 

In the image above, all probabilistic outputs in the module titled "Market model" are configured to proactively compute in both browse and edit mode. If you opt to configure at the "Variable" or "Output node only" level, it shows a third pulldown that allows you to select which variable or output to set. An output is set to proactively compute at any of these three levels, then it computes. 

=== Errors during proactive calculations ===

If an error or warning occurs during a proactive calculation, it quietly stops the calcualtion and shows the '''[calc]''' button again to avoid excessive messages when loading a model. 
Next time you press the '''[calc]''' button, it will show you the error. After detecting an error, it won't try the calculation again until there is a change in some variable that influences it so there is a chance that the error has been fixed.  

== Proactive evaluation on loading a model ==

You can configure indexes, variables or buttons to compute (or click) when your model first loads. These are some reasons you might want to do that:
* You want to display a [[MsgBox|message box]] with welcome information when a model is loaded. You could call the MsgBox() function in a proactively evaluated variable or button.  
* You want an [[AskMsgText]] dialog to ask for user name or password.  
* You want to precompute some results so that the user experiences a more snappy interaction when they start to explore the model. (The downside is that users will have to wait longer while the model is first loading.)

There isn't yet a user interface for the'''ProactivelyEvaluate''' attribute, so you must set it in the [[Typescript Window]], which you can get to by pressing ''F12'' (or ''Ctrl-' '').  

The '''ProactivelyEvaluate''' attribute takes a bit-field -- you set it a number which is the sum of any of these values that you want:
:<code>1</code> = Index Value
:<code>2</code> = Domain value
:<code>4</code> = Mid value
:<code>8</code> = Prob value
:<code>16</code> = For an edit table, accept each change to a cell as it's made, rather than waiting until user clicks the green checkmark.
:<code>32</code> = Evaluate the OnClick of any button or picture when the model is loaded.
:<code>64</code> = Proactively evaluate output node in edit mode. (If unset, it does it only in browse mode)

To configure a button with the identifier <code>do_init</code> to run when the model is first loaded:

*Right-click on the button. There will be a checkbox option on the context menu "run at load time". Select it. That's all you need to do - the button's onclick will run at load time.

You could also use this typescript command: (or if you are using a release older than 6.0.4)
:<code>ProactivelyEvaluate do_init:32</code>

To configure an index to proactively compute its index value at model load time, use:
:<code>ProactivelyEvaluate myIndex:1</code>

To configure a variable to compute both its mid-value and its sample value (the uncertainty value) at load time:
:<code>ProactivelyEvaluate myVariable:12</code>

=== Controlling for an entire object class ===
You can control the default behavior for object classes like ''Decision'', ''Variable'', ''Index'', ''Objective'', ''Constraint'', and ''Constant''. For example, you could make all constants proactive by typing
:<code>ProactivelyEvaluate Constant: 5</code>

Turning off the '''Proactively evaluate indexes''' preference is equivalent to typing
:<code>ProactivelyEvaluate Index: 0</code>
And turning it on is equivalent to setting it to <code>1</code>.

You can look at the current defaults from the [[Typescript Window]], e.g.
:<code> Untitled> Profile Index</code>
:<code>Object Index</code>
:<code>NodeColor: 39321,39325,65535</code>
:<code>ProactivelyEvaluate: 0</code>

You can override this default for individual variable objects by setting the attribute explicitly for the indicated variable.  For example:

:<code>Untitled> ProactivelyEvaluate Va1: 4</code>
:<code>Untitled> ProactivelyEvaluate In1: 0</code>

The above lines change the default so that index <code>In1</code> is lazily evaluated and variable <code>Va1</code> is proactively evaluated, regardless of the class default.

== Proactively submitting changes to a table ==

When the <code>16</code> flag is set for an edit table, it accepts any change to a cell immediately.  This is equivalent to the user pressing the green check button immediately after entering each cell. In a [[MultiTable]], this can be useful to trigger any computed cells to recalculate mmediately so that they are consistent with user changes. It  also forces any [[OnChange]] event to trigger after each cell change. Of course, this might be undesirable for very large table since it may cause a delay after each change -- and you can no longer drop all changes by pressing the red X button, since the changes have already been committed.

== When Proactive Evaluation occurs ==

When you configure a variable <code>X</code> for proactive evaluation, it occurs: (a) when the model is first loaded, and (b) when the definition of <code>X</code> is changed (e.g., by editing it in the object window). In a future release, we plan to add (c) when any value it depends on changes.

Suppose you change the definition of a variable that influences <code>X</code>.  This does not cause the immediate proactive evaluation of <code>X</code>.  Thus, if you have an output control for <code>X</code>, it will switch to a '''Calc''' button.  If the definition of <code>X</code> is edited, then it will proactively evaluate.  

== History ==

Analytica adopted lazy evaluation as part of its original design philosophy.  The main exception was for Indexes, which it evaluated proactively so that they would be available for display of result tables and graphs using those indexes.  In more recent releases, it has moved to lazy evaluation even for indexes where possible, and given the modeler the option of proactive evaluation for selected variables.

In Analytica 4.3 and earlier releases, it tried to evaluate every Index on loading the model. You can still set this behavior by checking the '''Proactively evaluate indexes''' [[Preferences|preference setting]]. But it's almost always best to turn this setting off, so you don't have to wait for computed indexes (which may include time-consuming [[DbQuery|database queries]]) to evaluate when you are loading your model.  Prior to Analytica 4.4, this setting was on by default, so if you are working with a legacy model, you may need to turn it off.

[[Analytica 4.3]] introduced the '''ProactivelyEvaluate''' attribute to let you turn off proactive evaluation of all index nodes, and turn on proactive evaluation for other class types or individual objects.  Its default was still to proactively evaluate indexes.

[[Analytica 4.4]] exposed the '''Proactively evaluate indexes''' preference on the [[Preference Dialog]], and set the default to ''off'' for new models.  For legacy models, it remained on to avoid breaking backward compatibility. But users were recommended to turn it off.

A variable used as a table index (even if it isn't formally an index) was evaluated proactively at model load time to enable the table definition to be parsed, up through [[Analytica 4.3]]. An internal restructuring of table parsing rendered  [[Analytica 4.4]] made this unnecessary, so that even indexes used by tables are evaluated in a lazy fashion.

[[Analytica 5.0]] Introduced proactive acceptance of definitions (flag 16) and proactive evaluation of [[OnClick]] (flag 32). 

[[Analytica 6.0]] added proactive calculation of output nodes, and the <code>"Configure Proactive User Outputs"</code> library. Also added a right click context menu item for buttons to run at load time.

==See Also==
* [[Evaluate]]
* [[Evaluation Modes]]
* [[:Category: Evaluation Functions]]
* [[CachingMethod]]
* [[MultiTable]], [[OnChange]]
* [[OnClick]]