Analytica Docs - User contributions [en]

Introduction to Optimizer

2016-01-03T16:35:27Z

Jhernandez3: /* To Validate the Activation */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>This introduction explains what the Analytica Optimizer is and how you can obtain a copy of the software. It also details how you can activate and validate your copy of as well as activate high-end, add-on engines for the Optimizer.
==What is the Analytica Optimizer?==

The Analytica Optimizer enhances Analytica with powerful functions for finding optimal decisions and solving difficult equations. Most Analytica Optimizer models aim to find a decision strategy — values for ''decision'' variables — to maximize or minimize a quantified objective subject to a set of equality or inequality constraints. Some models seek a feasible solution that satisfies a set of constraints without regard to an objective.

===Types of Optimization ===

A ''linear program'' (LP) requires the objective function and constraints to be linear functions of decision variables. LPs are solvable using straightforward algorithms that yield unique (global) maximizing or minimizing solutions. Although LP algorithms are well understood, large-scale optimizations can be computationally complex.

When pairs of decision variables are multiplied together, including squared decision variables, quadratic terms result. A ''quadratic problem'' (QP) has quadratic terms in the objective and linear constraints. A generalization of a QP, in which one or more constraints contains quadratic terms, is called a ''Quadratically Constrained Program'' (QCP). If the objective and constraint functions satisfy a mathematical property known as convexity, QP solutions are always unique (global). Non-convex formulations can result in “local” solutions that may or may not represent the global optimum.

''Nonlinear Programming'' (NLP) does not impose restrictions on the mathematical properties of objectives and constraints. A wide variety of computational algorithms can be applied to NLPs. Strategies include gradient tracking and genetic algorithms that allow potential solutions to compete within the computation.

With all classes of optimization, Analytica supports variables that are continuous, discrete (integer, Boolean, grouped), or a mixture of continuous and discrete decision variables.

The Analytica Optimizer analyzes your objective functions and constraints automatically to discover the type of optimization and select the appropriate solver engine.

===Premium Solver Specifications===

The standard edition of Analytica Optimizer uses the Premium Solver Platform licensed from Frontline Systems, Inc., the developer of the Optimizer/Solver in Microsoft Excel, and a world leader in spreadsheet optimization.

The Premium Solver is the leading add-on software for spreadsheet optimization, and incorporates state-of-the-art technologies. The LP and QP solver engines that come included with Analytica Optimizer handle up to 8000 variables and 8000 constraints in addition to bounds on the decision variables. Up to 2000 of these variables may be constrained to be integer-valued for ''Mixed-Integer Programming''. Up to 2000 decision variables of any kind are supported when quadratic constraints are present. The NLP solvers offer hybrid methods using classical gradient-search and evolutionary (genetic) algorithms for smooth and discontinuous objective functions with up to 500 decision variables and 250 constraints. Large scale add-on engines that eliminate the limit on variables and constraints entirely are also available at extra cost (see [http://wiki.analytica.com/index.php?title=Introduction_to_the_Guide#Installing_Add-On_Optimizer_Engines Installing Add-On Optimizer Engines]).
If your problems exceed these limits, or you need a solver that is even faster, you can add any of a number of high-end solvers, LP, QP, or NLP, that include some of the most powerful solver engines available anywhere (see the [http://wiki.analytica.com/index.php?title=DefineOptimization#Engine_Settings Engine] Settings parameter of [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() for details.

===Optimizing with Uncertain Values and Intelligent Arrays===

The Analytica Optimizer performs optimization under uncertainty to maximize expected values and minimize loss percentiles, as well as other statistical functions of objectives and constraints. Analytica allows users to combine Intelligent ''arrays'' with all classes of optimization. Thus, you can easily create ''arrays of optimizations'' conditioned on samples from uncertain variables, for parametric analysis of effects of key assumptions, and for each time period in a dynamic model.

===Compatibility with Other Analytica Editions===

The Analytica Optimizer is an edition of Analytica that includes all the functionalities of the Analytica Enterprise edition. After using Analytica Optimizer to create optimizing models, you can deliver them to end users on the desktop using Analytica Power Player with Optimizer, or via a web browser on a server using the Analytica Web Player (AWP) or Analytica Decision Engine (ADE) with an Optimizer license.

==Obtaining the Analytica Optimizer==

You can purchase a license for the Analytica Optimizer or the Analytica Power Player with Optimizer from Lumina Decision Systems. Or you can purchase an upgrade to Optimizer if you already have a license for the Analytica Enterprise or Professional editions.

If your copy of Analytica is for release 4.2 or earlier, you need to upgrade to release 4.3 or later to obtain the newest Optimizer features as described in this Guide. Substantial discounts are available if you have a maintenance agreement for Analytica 4.2 (included free for 12 months from purchase).

For more information:

* Visit the [[ http://www.lumina.com/|Lumina web site]], or
* Call Lumina at 650-212-1212

==Activating your Analytica Optimizer==

If you have purchased an individual license of Analytica Optimizer, you will be sent an Activation Key. This key allows you to retrieve a license specific to your computer and account from Lumina’s activation server. The license itself is contained in a file, usually stored in the Analytica installation directory and usually named Analytica.lic. The term activation refers to the process of obtaining this file.

===First-Time Install===

When installing Analytica for the first time, you will run the Analytica installer program, which you can find in [[ http://www.lumina.com/support/downloads/|Lumina Downloads]]. If you have purchased the 64-bit edition, download Ana64Setup.exe, otherwise download AnaSetup.exe.

If you run the installer from your own end-user account (recommended), then enter the activation key when prompted, and the installer will automatically retrieve and install your license file over the internet (if you don’t have an internet connection, see “Manual Activation”). If a system administrator runs the installer from an account other than your own end-user account, leave the activation key field blank, then after it is installed, log into your own account and follow the instructions for “Previous edition already installed”.

===Previous Edition Already Installed===

If you already have an edition of Analytica 4.6 installed (including the Trial Edition), your installation includes the Analytica Optimizer files and there is no need to download new software. However, you need to enter a new activation key with the Optimizer option.

To activate Analytica Optimizer while you are connected to the internet:

# Start Analytica in the usual way, e.g., via the Windows Start menu, or by doubleclicking an Analytica model file.
# From Analytica’s '''Help menu''', select '''Update License''' to display the '''Analytica Licensing Information''' box.
# Enter the activation key into the '''License ID''' box, replacing the license name currently displayed. As soon as the key is correctly entered, an '''Activate''' button appears to the right.
# Click '''Activate''' to retrieve your license from the activation server. Your license name then appears in the '''License ID''' box.
# Click '''OK'''.
# Exit and restart Analytica.

===Manual Activation===

Automatic activation will fail if you do not have a connection to the internet, or if your firewalls and proxy servers are configured to prevent Analytica from communicating with the activation server. In this case, you can obtain a license file through manual activation. You will need your activation key and the Host ID and User ID that are displayed at the bottom of the Analytica Licensing Information dialog from Step 2 above. Enter this information into the form at http://www.lumina.com/support/activate-analytica/, and the license file will be emailed to you.

===Floating License===

If your organization provides you with a floating license to Analytica Optimizer, your IT department will provide you with the name (and possibly IP port) of the Reprise License Manager (RLM) server computer where your IT department will have already installed and activated a floating license.

Run the Analytica installer as described in “First-Time Install”, but during the install, on the '''License Information''' page, select '''Centrally managed license (RLM License Server)''' and enter the ''server host name'', or '''port@host''', provided to you.

If you already have Analytica installed, you can also enter this information into the Analytica License Information by selecting '''Update License''' from the '''Help''' menu.

===To Validate Successful Activation ===

To verify successful activation of Analytica Optimizer, examine the splash screen when Analytica starts up, or go to '''Help > About Analytica'''. The splash screen should display '''Analytica Optimizer''', as shown below.

[[File:1-1.png|400px]]

==Installing Add-On Optimizer Engines==

You can add other engines for solving optimization problems to the Analytica Optimizer. Some engines provide superior performance on particular classes of optimization problems, and some engines handle larger numbers of variables or constraints. The following add-on engines are available:

* Large Scale LP
* Large Scale SQP
* Large Scale GRG
* Gurobi (LP/QP)
* XPRESS (LP/QP)
* MOSEK (cQCP/NLP)
* KNITRO (NLP)
* OptQuest (NSP)<br />

When you purchase an add-on engine license, or obtain an add-on engine trial, Lumina will provide you with the following items:

# <tt>EngineSetup.exe</tt> (or <tt>EngineSetup64.exe</tt> for Analytica 64-bit users), the add-on engine installer from Frontline Systems.
# The password required by EngineSetup.
# The <tt>SolverAddons.lic</tt> file.
# A Lumina activation key.

===To Install an Add-On Engine===

# Install Analytica Optimizer first, if you have not already done so.
# Run <tt>EngineSetup.exe</tt> or <tt>EngineSetup64.exe</tt>, the add-on engine installation program. Use <tt>EngineSetup64.exe</tt> when you are using Analytica 64-bit.
# The <tt>EngineSetup</tt> program will ask for a password and activation key. Enter the password provided to you by email when you are sent the EngineSetup program. You may leave the '''activation key''' blank.

<Tip title="Note">

If you're using the v14 release of EngineSetup, you will need to correct a bug that places the release's settings in the v11 registry hive instead of the v14 registry hive.

To correct the bug:

# From the '''Start''' menu, run <tt>RegEdit.exe</tt>.
# Navigate to <tt>HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/SolverEngines</tt>.
# Right-click on <tt>v11</tt>, select '''Rename''', then change to<tt> v14</tt>.
# Start up Analytica and select '''Update License''' from the Help menu.
# Enter the activation key provided into the '''License ID''' box, then click '''Activate'''
</Tip>

===To Validate the Activation===

To test for proper installation, open Analytica, and create a variable defined as follows:

<code>Variable Engines := OptEngineInfo("All","TrialPeriod")</code>

The names of available engines should appear with non-zero values.

<footer>Analytica Optimizer Guide / {{PAGENAME}} / Quick Start</footer>

Optimizer Quick Start

2016-01-03T16:33:58Z

Jhernandez3: /* Decisions */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1
Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt :=
DefineOptimization(
Decisions: Radius, Height,
Constraints: Volume_Constraint,
Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:

<tt>OptSolution(Opt, Decision)</tt>
* Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>
* Decision: Identifier for the counterpart Decision input node<br />

<code>Decision Opt_Radius := OptSolution(Opt, Radius)
Decision Opt_Height := OptSolution(Opt, Height)</code>

The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.

<code>Objective Opt_Surface := OptObjective(Opt)</code>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

<code>Variable Status := OptStatusText(Opt)</code>

This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:

<code>Variable Radius := Sequence(4.5, 6.5, 0.1)
Variable Height := Required_volume/(pi*Radius^2)</code>

Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]

<code>Decision X := 0 (or any value at all)
Initial Guess of X := [-4, 2, 0, 2, 4]
Objective Polynomial :=
1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800
Variable Opt := DefineOptimization(
Decision: X,
Maximize: Polynomial)
Variable X_solution := OptSolution(Opt,X)
Objective Max_Objective := OptObjective(Opt)</code>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<tip title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</tip>''

''<tip title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<footer> Introduction / {{PAGENAME}} / Optimization Characteristics</footer>

Optimizer Quick Start

2016-01-03T16:32:51Z

Jhernandez3: /* The Initial Guess Attribute */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1

Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt :=
DefineOptimization(
Decisions: Radius, Height,
Constraints: Volume_Constraint,
Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:

<tt>OptSolution(Opt, Decision)</tt>
* Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>
* Decision: Identifier for the counterpart Decision input node<br />

<code>Decision Opt_Radius := OptSolution(Opt, Radius)
Decision Opt_Height := OptSolution(Opt, Height)</code>

The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.

<code>Objective Opt_Surface := OptObjective(Opt)</code>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

<code>Variable Status := OptStatusText(Opt)</code>

This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:

<code>Variable Radius := Sequence(4.5, 6.5, 0.1)
Variable Height := Required_volume/(pi*Radius^2)</code>

Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]

<code>Decision X := 0 (or any value at all)
Initial Guess of X := [-4, 2, 0, 2, 4]
Objective Polynomial :=
1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800
Variable Opt := DefineOptimization(
Decision: X,
Maximize: Polynomial)
Variable X_solution := OptSolution(Opt,X)
Objective Max_Objective := OptObjective(Opt)</code>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<tip title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</tip>''

''<tip title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<footer> Introduction / {{PAGENAME}} / Optimization Characteristics</footer>

Optimizer Quick Start

2016-01-03T15:57:10Z

Jhernandez3: /* The Initial Guess Attribute */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1 </code>

<code>Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt := </code>

:<code>DefineOptimization(</code>

::<code>Decisions: Radius, Height, </code>

::<code>Constraints: Volume_Constraint, </code>

::<code>Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:

<tt>OptSolution(Opt, Decision)</tt>
* Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>
* Decision: Identifier for the counterpart Decision input node<br />

<code>Decision Opt_Radius := OptSolution(Opt, Radius) </code>

<code>Decision Opt_Height := OptSolution(Opt, Height)</code>

<nowiki> </nowiki>The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.

<code>Objective Opt_Surface := OptObjective(Opt)</code>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

<code>Variable Status := OptStatusText(Opt)</code>

<nowiki> </nowiki>This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:

<code>Variable Radius := Sequence(4.5, 6.5, 0.1) </code>

<code>Variable Height := Required_volume/(pi*Radius^2)</code>

Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]

<code>Decision X := 0 (or any value at all)</code>

<code>Initial Guess of X := [-4, 2, 0, 2, 4] </code>

<code>Objective Polynomial := </code>

:<code>1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800</code>

<code>Variable Opt := DefineOptimization(</code>

:<code>Decision: X, </code>

:<code>Maximize: Polynomial) </code>

<code>Variable X_solution := OptSolution(Opt,X)</code>
<code>Objective Max_Objective := OptObjective(Opt)</code>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<tip title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</tip>''

''<tip title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<footer> Introduction / {{PAGENAME}} / Optimization Characteristics</footer>

Optimizer Quick Start

2016-01-03T15:47:07Z

Jhernandez3: /* Chapter Summary */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1 </code>

<code>Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt := </code>

:<code>DefineOptimization(</code>

::<code>Decisions: Radius, Height, </code>

::<code>Constraints: Volume_Constraint, </code>

::<code>Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:

<tt>OptSolution(Opt, Decision)</tt>
* Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>
* Decision: Identifier for the counterpart Decision input node<br />

<code>Decision Opt_Radius := OptSolution(Opt, Radius) </code>

<code>Decision Opt_Height := OptSolution(Opt, Height)</code>

<nowiki> </nowiki>The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.

<code>Objective Opt_Surface := OptObjective(Opt)</code>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

<code>Variable Status := OptStatusText(Opt)</code>

<nowiki> </nowiki>This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:

<code>Variable Radius := Sequence(4.5, 6.5, 0.1) </code>

<code>Variable Height := Required_volume/(pi*Radius^2)</code>

Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]

<code>Decision X := 0 (or any value at all)</code>

<code>Initial Guess of X := [-4, 2, 0, 2, 4] </code>

<code>Objective Polynomial := </code>

<code>1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800</code>

<code>Variable Opt := DefineOptimization(</code>
:<code>Decision: X, </code>
:<code>Maximize: Polynomial) </code>
<code>Variable X_solution := OptSolution(Opt,X) </code>
<code>Objective Max_Objective := OptObjective(Opt)</code>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<tip title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</tip>''

''<tip title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<footer> Introduction / {{PAGENAME}} / Optimization Characteristics</footer>

Optimizer Quick Start

2016-01-03T15:45:52Z

Jhernandez3: /* The Initial Guess Attribute */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1 </code>

<code>Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt := </code>

:<code>DefineOptimization(</code>

::<code>Decisions: Radius, Height, </code>

::<code>Constraints: Volume_Constraint, </code>

::<code>Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:

<tt>OptSolution(Opt, Decision)</tt>
* Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>
* Decision: Identifier for the counterpart Decision input node<br />

<code>Decision Opt_Radius := OptSolution(Opt, Radius) </code>

<code>Decision Opt_Height := OptSolution(Opt, Height)</code>

<nowiki> </nowiki>The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.

<code>Objective Opt_Surface := OptObjective(Opt)</code>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

<code>Variable Status := OptStatusText(Opt)</code>

<nowiki> </nowiki>This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:

<code>Variable Radius := Sequence(4.5, 6.5, 0.1) </code>

<code>Variable Height := Required_volume/(pi*Radius^2)</code>

Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]

<code>Decision X := 0 (or any value at all)</code>

<code>Initial Guess of X := [-4, 2, 0, 2, 4] </code>

<code>Objective Polynomial := </code>

<code>1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800</code>

<code>Variable Opt := DefineOptimization(</code>
:<code>Decision: X, </code>
:<code>Maximize: Polynomial) </code>
<code>Variable X_solution := OptSolution(Opt,X) </code>
<code>Objective Max_Objective := OptObjective(Opt)</code>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<tip title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</tip>''

''<tip title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<nowiki><footer> Introduction / </nowiki>{{PAGENAME}} / Optimization Characteristics<nowiki></footer></nowiki>

Optimizer Quick Start

2016-01-03T15:44:45Z

Jhernandez3:

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1 </code>

<code>Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt := </code>

:<code>DefineOptimization(</code>

::<code>Decisions: Radius, Height, </code>

::<code>Constraints: Volume_Constraint, </code>

::<code>Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:

<tt>OptSolution(Opt, Decision)</tt>
* Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>
* Decision: Identifier for the counterpart Decision input node<br />

<code>Decision Opt_Radius := OptSolution(Opt, Radius) </code>

<code>Decision Opt_Height := OptSolution(Opt, Height)</code>

<nowiki> </nowiki>The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.

<code>Objective Opt_Surface := OptObjective(Opt)</code>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

<code>Variable Status := OptStatusText(Opt)</code>

<nowiki> </nowiki>This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:

<code>Variable Radius := Sequence(4.5, 6.5, 0.1) </code>

<code>Variable Height := Required_volume/(pi*Radius^2)</code>

Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]

<code>Decision X := 0 (or any value at all)</code>

<code>Initial Guess of X := [-4, 2, 0, 2, 4] </code>

<code>Objective Polynomial := </code>

<code><code>1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800</code>

<code><code>Variable Opt := DefineOptimization(</code>
:<code>Decision: X, </code>
:<code>Maximize: Polynomial) </code>
<code>Variable X_solution := OptSolution(Opt,X) </code>
<code>Objective Max_Objective := OptObjective(Opt)</code>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<tip title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</tip>''

''<tip title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<nowiki><footer> Introduction / </nowiki>{{PAGENAME}} / Optimization Characteristics<nowiki></footer></nowiki>

Optimizer Quick Start

2016-01-03T15:41:44Z

Jhernandez3: /* Obtaining the Optimized Objective Value */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1 </code>

<code>Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt := </code>

:<code>DefineOptimization(</code>

::<code>Decisions: Radius, Height, </code>

::<code>Constraints: Volume_Constraint, </code>

::<code>Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:

<tt>OptSolution(Opt, Decision)</tt>
* Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>
* Decision: Identifier for the counterpart Decision input node<br />

<code>Decision Opt_Radius := OptSolution(Opt, Radius) </code>

<code>Decision Opt_Height := OptSolution(Opt, Height)</code>

<nowiki> </nowiki>The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.

<code>Objective Opt_Surface := OptObjective(Opt)</code>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

<code>Variable Status := OptStatusText(Opt)</code>

<nowiki> </nowiki>This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:

<code>Variable Radius := Sequence(4.5, 6.5, 0.1) </code>

<code>Variable Height := Required_volume/(pi*Radius^2)</code>

Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]

<code>Decision X := 0 (or any value at all)</code>
<code>Initial Guess of X := [-4, 2, 0, 2, 4]</code>
<code>Objective Polynomial :=</code>
<code><code>1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800</code>
<code>Variable Opt := DefineOptimization(</code>
:<code>Decision: X, </code>
:<code>Maximize: Polynomial) </code>
<code>Variable X_solution := OptSolution(Opt,X) </code>
<code>Objective Max_Objective := OptObjective(Opt)</code>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<Tip Title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</Tip>''

''<Tip Title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</Tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<footer> Introduction / {{PAGENAME}} / Optimization Characteristics</footer>

Optimizer Quick Start

2016-01-03T15:37:30Z

Jhernandez3: /* Obtaining the Solution */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1 </code>

<code>Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt := </code>

:<code>DefineOptimization(</code>

::<code>Decisions: Radius, Height, </code>

::<code>Constraints: Volume_Constraint, </code>

::<code>Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:

<tt>OptSolution(Opt, Decision)</tt>
* Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>
* Decision: Identifier for the counterpart Decision input node<br />

<code>Decision Opt_Radius := OptSolution(Opt, Radius) </code>

<code>Decision Opt_Height := OptSolution(Opt, Height)</code>

<nowiki> </nowiki>The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.
Objective Opt_Surface := <tt>OptObjective(Opt)</tt>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .
Variable Status := <tt>OptStatusText(Opt)</tt>
This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:
Variable Radius := Sequence(4.5, 6.5, 0.1)

Variable Height := Required_volume/(pi*Radius^2)
Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]
<nowiki>Decision X := 0 (or any value at all)
Initial Guess of X := [-4, 2, 0, 2, 4]
Objective Polynomial :=
1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800
Variable Opt := DefineOptimization(
Decision: X,
Maximize: Polynomial)
Variable X_solution := OptSolution(Opt,X)
Objective Max_Objective := OptObjective(Opt)</nowiki>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<Tip Title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</Tip>''

''<Tip Title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</Tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<footer> Introduction / {{PAGENAME}} / Optimization Characteristics</footer>

Optimizer Quick Start

2016-01-03T15:36:54Z

Jhernandez3: /* Obtaining the Solution */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1 </code>

<code>Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt := </code>

:<code>DefineOptimization(</code>

::<code>Decisions: Radius, Height, </code>

::<code>Constraints: Volume_Constraint, </code>

::<code>Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:

<tt>OptSolution(Opt, Decision)</tt>
* Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>
* Decision: Identifier for the counterpart Decision input node

<code>Decision Opt_Radius := OptSolution(Opt, Radius) </code>

<code>Decision Opt_Height := OptSolution(Opt, Height)</code>

<nowiki> </nowiki>The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.
Objective Opt_Surface := <tt>OptObjective(Opt)</tt>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .
Variable Status := <tt>OptStatusText(Opt)</tt>
This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:
Variable Radius := Sequence(4.5, 6.5, 0.1)

Variable Height := Required_volume/(pi*Radius^2)
Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]
<nowiki>Decision X := 0 (or any value at all)
Initial Guess of X := [-4, 2, 0, 2, 4]
Objective Polynomial :=
1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800
Variable Opt := DefineOptimization(
Decision: X,
Maximize: Polynomial)
Variable X_solution := OptSolution(Opt,X)
Objective Max_Objective := OptObjective(Opt)</nowiki>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<Tip Title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</Tip>''

''<Tip Title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</Tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<footer> Introduction / {{PAGENAME}} / Optimization Characteristics</footer>

Optimizer Quick Start

2016-01-03T15:34:36Z

Jhernandez3: /* Objectives */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1 </code>

<code>Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt := </code>

:<code>DefineOptimization(</code>

::<code>Decisions: Radius, Height, </code>

::<code>Constraints: Volume_Constraint, </code>

::<code>Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:
«<tt> OptSolution(Opt, Decision)</tt> .
• Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>

• Decision: Identifier for the counterpart Decision input node
Decision Opt_Radius := <tt>OptSolution(Opt, Radius)</tt>

Decision Opt_Height := <tt>OptSolution(Opt, Height)</tt>
The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.
Objective Opt_Surface := <tt>OptObjective(Opt)</tt>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .
Variable Status := <tt>OptStatusText(Opt)</tt>
This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:
Variable Radius := Sequence(4.5, 6.5, 0.1)

Variable Height := Required_volume/(pi*Radius^2)
Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]
<nowiki>Decision X := 0 (or any value at all)
Initial Guess of X := [-4, 2, 0, 2, 4]
Objective Polynomial :=
1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800
Variable Opt := DefineOptimization(
Decision: X,
Maximize: Polynomial)
Variable X_solution := OptSolution(Opt,X)
Objective Max_Objective := OptObjective(Opt)</nowiki>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<Tip Title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</Tip>''

''<Tip Title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</Tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<footer> Introduction / {{PAGENAME}} / Optimization Characteristics</footer>

Optimizer Quick Start

2016-01-03T15:33:19Z

Jhernandez3: /* Decisions */

[[Category: Analytica Optimizer Guide]]
<breadcrumbs> Analytica Optimizer Guide > {{PAGENAME}}</breadcrumbs>

This quick-start tutorial aims to show you how to:
* Set up a basic NLP optimization model using Decision, Objective, and Constraint Nodes
* Define the central Optimization node using the [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function
* Obtain solution output and status
* Specify domain types (i.e., integer, continuous, etc.) and bounds for decisions
* Combine parametric analysis with optimization
* Change initial guesses for non-convex solution spaces

==Introduction to Structured Optimization==

The Analytica Optimizer releases from version 4.3 onward include a set of features, collectively called Structured Optimization, designed to simplify the optimization modeling process. In Structured Optimization format, ''Linear Programming'' (LP), ''Quadratic Programming'' (QP) and ''Nonlinear Programming'' (NLP) optimizations can all be modeled in similar ways. All types of optimization are specified using the <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.<ref>DefineOptimization() supersedes the LPDefine(), QPDefine() and NLPDefine() function that were used to specify optimizations prior to Analytica 4.2. These functions remain available for backward compatibility, but are now deprecated.</ref>

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>function automatically analyzes your model to determine the type of optimization and selects the appropriate optimization engine, although you can still override this process if desired.

Another significant change associated with Structured Optimization is the introduction of the Constraint object type. Constraint objects give users the ability to specify constraints, or arrays of constraints, in common expression format using equality or inequality operators. This intuitive interface allows users to easily integrate different types of constraints and to organize constraint arrays efficiently.

This section includes simple NLP examples to demonstrate the roles of Decision variables, Constraint objects, Objective variables, and Decision attributes in the Structured Optimization framework. The same basic structure applies to LP and QP optimizations as well.

== The Optimum Can Example ==
The Optimum Can example determines the dimensions of a cylindrical object having a minimum surface area for a given volume. Admittedly, this is not a very interesting optimization problem. In fact, the solution can be derived on paper using basic differential calculus. However, the simplicity of the example allows us to focus on the workflow and object relationships using the new Structured Optimization framework in Analytica.

=== Decisions ===

[[File:2-2.png|50px]]

In this example, we will decide on the '''Radius''' and '''Height''' of a cylindrical vessel. We represent each of these as a Decision variable in the influence diagram. The values we define for these nodes will be used as initial guesses for optimization types that require an initial guess (''NLP'' or ''non-convex QP''). Otherwise, the definitions of these inputs are not important. We use 1cm as an initial guess for both the radius and height.

<code>Decision Radius := 1 </code>

<code>Decision Height := 1</code>

=== Constants ===

[[File:2-3.png|50px]]

Constants have no special interpretation in optimization definitions. They can be used as usual for values that stay constant in the model. In this example, we will use a Constant for the required volume which does not vary in the model.

<code>Constant Required_Volume := 1000</code>

Variables

[[File:2-4.png|50px]]

General variables are used for intermediate values as well as for the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function described below. We also use a variable to define Volume of the cylinder.

<code>Variable Volume := pi*Radius^2*Height</code>

Constraints

[[File:2-5.png|50px]]

Constraints contain equality or inequality conditions that restrict the range of optimized results. In this example, we use a constraint object to enforce the minimum volume requirement on our can.

<code>Constraint Volume_Constraint := (Volume >= Required_Volume)</code>

=== Objectives ===

[[File:2-6.png|50px]]

Most optimizations have an objective value to maximize or minimize. (Some problems are only concerned with feasible solutions that meet constraints.) In this example we are minimizing the surface area of our can. We define surface area using an Objective variable. The can has round disks at the top and base with surface area ('''πR2''') and a tubular side with surface area ('''2πRH''').

<code>Objective Surface_area := 2 * (pi * Radius^2) + (2 * pi * Radius * Height)</code>

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() Function

The [http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]() function is the key component of all Structured Optimization models. It brings all other components together, specifying the optimization to be performed. This function is typically placed in a Variable object in the center of our influence diagram. Although this function includes many optional parameters, we will only use the core parameters in this example:
* '''Decision:''' <br />
:Identifier for the decision node (or a list of identifiers separated by commas if there are multiple decisions). Specify All to include all decision nodes in the model or All in module to include all desired decisions within a designated module.

* '''Constraint:''' <br />
:Identifier for the constraint node (or a list of identifiers separated by commas if there are multiple constraints). Specify All to include all constraint nodes in the model or All in module to include all desired constraints within a designated module. You can also specify inequality or equality expressions directly, or omit the parameter entirely in an unconstrained optimization problem.

* '''Maximize/Minimize:''' <br />
:Use the words “Maximize” or “Minimize” depending on the type of problem. Follow this with an expression or with the identifier for the relevant objective node.

We define our Define Optimization node as:

<code>Variable Opt := </code>

<code> DefineOptimization(</code>

<code> Decisions: Radius, Height, </code>

<code> Constraints: Volume_Constraint, </code>

<code> Minimize: Surface_area)</code>

=== Viewing the Optimization Object ===
The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function evaluates to a special object that contains detailed information about the optimization. The object appears as a blue hyperlink that shows the type of optimization problem you have constructed. In this case we see it is NLP . You can double-click the optimization object to open a new window revealing internal details from the optimization engine. Clicking reference objects allows you to drill down to finer levels of detail. This information is also available by using the [[OptInfo]]() function.

[[File:2-7.png|600px]]

In this case, we have allowed Analytica to automatically determine the type of problem. Alternatively, you can specify the problem type along with the desired engine and other settings by adding optional parameters to <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>. See [[Optimizer Function Reference]] for more details about the Type and Engine parameters of <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .

=== Obtaining the Solution ===
Now that we have specified an optimization, how do we compute and view the result? You may be tempted to re-evaluate the Radius and Height decision variables to see if their values have changed. But this is not how optimization works in Analytica. Input values always retain their original definitions. (In this case, we simply used 1 as a dummy value for Radius and Height.) To obtain the solution, you need to create an output node defined with the <tt>[http://wiki.analytica.com/index.php?title=OptSolution OptSolution]()</tt> function. This function usually uses two parameters:
«<tt> OptSolution(Opt, Decision)</tt> .
• Opt: Identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt>

• Decision: Identifier for the counterpart Decision input node
Decision Opt_Radius := <tt>OptSolution(Opt, Radius)</tt>

Decision Opt_Height := <tt>OptSolution(Opt, Height)</tt>
The Decision parameter is optional. If it is omitted, the solution will include all decisions along a local index named <tt> .DecisionVector</tt> ..

[[File:2-8.png|600px]]

=== Obtaining the Optimized Objective Value ===
To conveniently evaluate the optimized objective value (the surface area of the solution can) you can use the <tt>[http://wiki.analytica.com/index.php?title=OptObjective OptObjective]()</tt> function. The only parameter is the identifier for the Define Optimization node.
Objective Opt_Surface := <tt>OptObjective(Opt)</tt>

=== Viewing Optimization Status ===
To check the status of an optimization, use the <tt>[http://wiki.analytica.com/index.php?title=OptStatusText OptStatusText]()</tt> .. function. Enter the identifier for the node containing <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> .
Variable Status := <tt>OptStatusText(Opt)</tt>
This will reveal a text string describing the status of the optimization result. Status messages differ according to problem characteristics and the engine being used. In general these messages indicate whether or not a feasible solution has been found and if so, whether or not the optimizer was able to converge to a bounded solution. In this example status is: “Optimal solution has been found.”

[[File:2-9.png|600px]]

===Copying Optimized Results to Definitions===

In some cases, you may wish to copy the optimized decision values into the definition of the original decisions. With this, the result for variables downstream of the decisions will reflect their optimal values as well.

You can configure your model to copy optimized results into the original decisions by adding two buttons to your model. The first button solves for the optimal solution and copy the optimal values. The second button restores the original (non-optimized) definition. Functions provided in the '''Structured Optimization Tool.ana''' library take care of the details.

To configure these buttons:

# With the diagram in focus, select '''Add Library''' from the '''File''' menu.
# Select <code>Structured Optimization Tools.ana</code> and click '''Open'''.
# Select '''Embed''', then click '''OK'''.
# Drag a button from the tool bar, title it "Set to Optimal."<br />
:[[File:2-10.png|400px]]
<ol start="5"><li>Click [[File:expr_btn.png]] to edit the button’s Script attribute to Use_opt_decisions( opt ).</li></ol>
<ol start="6"><li> Drag a second button to the diagram, name it "Restore Defintions" and set its Script attribute to <code>Restore_Decision_Defs( opt ).</code></li></ol>
:[[File:2-11.png|400px]]
Now we’re ready to try them out.
<ol start="7">
<li>Click [[File:expr_btn.png]] to enter browse mode. Click the '''Set to Optimal''' button.</li>
<li>Open the object window for '''Radius''':</li>
</ol>
:[[File:2-12.png|600px]]

===Changing Variable Types (Domain)===

Click either '''Radius''' or '''Height''' to open the Object window for the node. You will notice a pull-down menu for '''Domain'''. This attribute specifies the variable type. It is always visible for decision nodes if you are using the Optimizer edition.

Suppose the factory requires Radius and Height to be integer values in centimeters for tooling purposes, or because they don’t like decimals. Change the Domains of <tt>Radius</tt> and <tt>Height</tt> to '''Integer '''and re-evaluate the solution:

[[File:2-13.png|600px]]

The new solution finds the integer values that come closest to meeting the optimization criteria.

See [http://wiki.analytica.com/index.php?title=Optimizer_Attribute_Reference Optimizer Attribute Reference] for descriptions of all available domains.

=== Setting Bounds on Decision Values ===
Suppose the cans must not exceed a 5cm radius in order to meet National Association for the Advancement of People with Small Hands (NAAPSH) guidelines. One way to set this limit would be to add another constraint. But since this restriction applies directly to one of the decision variables, it is easier to simply set an upper bound on the variable directly.

Double-click the '''Radius''' variable and enter '''5''' as the upper bound. The updated solution will describe a thinner can that is 5cm in Radius and 13cm in Height.

'''Bounds and Domains'''

Some Domain types are not compatible with bounds. If one of these domains is selected ('''i.e.''' '''Boolean'''), bounds attributes will not be visible.

'''Bounds and Feasible Solutions'''

It is possible to have no feasible solution within the designated bounds. For example, if you restrict '''Radius''' to 5cm while restricting '''Height''' to 10cm, it will be impossible to produce a can that meets the minimum volume constraint. The [[OptStatusText]]() function indicates whether or not a feasible solution has been found.

===Using Parametric Analysis with Optimization ===
Before adding optimization to existing models, it is often useful to perform a parametric analysis to see how variations in decision inputs affect the objective value. If you have done this, your Decision and Objective variables will include parametric indexes. To demonstrate this in the ''Optimum Can'' example, we can define the '''Radius''' to be a sequence of values that vary parametrically. We then re-define '''Height''' such that the volume of the cylinder remains constant as radius varies:
Variable Radius := Sequence(4.5, 6.5, 0.1)

Variable Height := Required_volume/(pi*Radius^2)
Now you can evaluate the objective '''Surface_Area''' to see how it is affected by '''Radius'''.

[[File:2-14.png|400x400px]]

An optimization requires a scalar-valued objective. An array-valued objective usually implies an array of optimizations, each optimizing an individual element of the objective array. But parametric indexes are an exception to this rule! If the Objective is an array over parametric indexes, the indexes are ignored by the optimization. So even though we have an array valued Objective in this example, there is still only one optimization run.

[[File:2-15.png|500x500px]]

Parametric analysis is a good way to gain insight into your model. The Structured Optimization framework is designed so that it will not be confused by this

===The Initial Guess Attribute ===

LP and convex QP problems do not rely on initial guesses and always yield globally optimal solutions. But in NLP and non-convex QP problems it is not always possible to guarantee that a solution found by the optimizer is a global optimum. It might be merely a “local” optimum within the solution space. Optimization methods for these problems use an initial guess from which to start the search for a solution. The particular solution the optimizer returns may depend on the starting point.

Normally, Analytica uses the defined value of the Decision variables as the initial guess. In the ''Optimum Can'' example, we initially defined <code>Radius</code> and <code>Height</code> as 1. If a decision variable is defined using a parametric index, Analytica uses the first element of the parametric array as the initial guess.

You can change the initial guess without re-defining the decision variable using the '''Initial Guess''' attribute in the Decision node. We can demonstrate this using the ''Polynomial NLP.ana'' example where the objective is a non-convex curve with local maxima.

The Initial Guess attribute is hidden by default. To make it visible in Decision nodes:
* Select '''Attributes'''... from the '''Object''' menu.
* Check the '''Initial Guess''' box.<br />

The attribute will now be visible in the Object windows of all Decision variables.

The polynomial curve in this model is designed to have several critical points.

[[File:2-16.png|500x500px]]
<nowiki>Decision X := 0 (or any value at all)
Initial Guess of X := [-4, 2, 0, 2, 4]
Objective Polynomial :=
1+X/6-X^2/2+X^4/24-X^6/720+X^8/40320-X^10/3628800
Variable Opt := DefineOptimization(
Decision: X,
Maximize: Polynomial)
Variable X_solution := OptSolution(Opt,X)
Objective Max_Objective := OptObjective(Opt)</nowiki>

The array of initial guesses will cause Analytica to abstract over the index and perform multiple optimizations.

[[File:2-17.png|500px]]

We see that the result depends on the initial guess for this non-convex NLP.

If the array of guesses were entered as a ''definition'' for the decision variable instead of as an ''initial guess'' attribute, Analytica would interpret it as a parametric index and apply only one initial guess. (See subsection above.) Therefore, it is necessary to use the Initial Guess parameter if you want to perform multiple optimizations using an array of guesses.

''<Tip Title="Note">Finding multiple different local extrema in this fashion can be a useful way to locate multiple solutions of interest. One often needs to combine unmodeled factors with insight and results obtained from a model, so these other solutions may turn out to be more interesting for reasons that you have not modeled.</Tip>''

''<Tip Title="Note">When your interest is in finding just the global optima, there are additional methods for dealing with the problem of local optima. The '''Multistart''' and topological search options can be utilized with gradient-based methods (see [http://wiki.analytica.com/Coping_with_Local_Optima Coping with Local Optima]). The “Evolutionary” and “OptQuest” engines use population-based search methods that are more robust to local optima.</Tip>''

== Chapter Summary ==
The ''Optimum Can'' example demonstrates the basic workflow of Structured Optimization in Analytica. It includes input Decision variables, a Constraint object, an Objective variable, intermediate Variables and the central <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function.

The <tt>[http://wiki.analytica.com/index.php?title=DefineOptimization DefineOptimization]()</tt> function recognizes the non-linear characteristics of the Optimum Can model and classifies it as an NLP. The function evaluates as a special object containing details about the optimization.

The Domain attributes in Decisions allow setup of variable type and bounds.

Structured Optimization is compatible with a decision variable defined as a parametrically varying sequence.

If the Initial Guess attribute is kept hidden or left blank, Analytica will use the defined value of the decision variable as an initial guess. Users can override this value or enter an array of initial guesses by using the Initial Guess attribute in Decision nodes. This attribute is hidden by default but can be made visible when necessary.

<footer> Introduction / {{PAGENAME}} / Optimization Characteristics</footer>

Introduction to Optimizer

2016-01-03T15:30:03Z

Jhernandez3: /* To Validate the Activation */

Analytica Optimizer Guide

2016-01-03T15:28:32Z

Jhernandez3:

This Guide explains how to use the Analytica Optimizer. It provides a Quick Start Tutorial and an introduction to the basic concepts of optimization, including linear, quadratic, and nonlinear programming (NLP), as well as special topics in NLP. However, it is not a complete textbook on optimization. For more challenging applications, you might find it useful to consult one of the many good textbooks on optimization.[[Category: Analytica Optimizer Guide]]
== Sections ==
* [[Introduction to the Guide|Introduction]]

* [[Quick Start]]

* [[Optimization Characteristics]]

* [[Optimizing with Arrays]]
* [[Key Concepts: The Airline NLP Example]]
* [[Optimizer Attribute Reference]]
* [[Optimizer Function Reference]]
* [[Control Settings]]

==Using this Guide==

==== If you're new to Analytica ====
You will find it easier if you first learn the essentials of Analytica before learning the Analytica Optimizer described here. Start with the [http://wiki.analytica.com/index.php?title=Analytica_Tutorial Analytica Tutorial] to learn the basics of interacting with Analytica and its modeling language, especially [http://wiki.analytica.com/index.php?title=Analytica_Tutorial#Working_with_Arrays_.28Tables.29 Working with Arrays]. It's important to have a good understanding of Intelligent Arrays to make good use of the Optimizer.

==== If you're new to the Analytica Optimizer ====
We suggest you start with the [http://wiki.analytica.com/index.php?title=Quick_Start Quick Start], an introductory tutorial that takes you through the key steps to create a simple optimization. The section on [http://wiki.analytica.com/index.php?title=Optimization_Characteristics Optimization Characteristics] explains the general principles of optimization and the types of optimization, including Linear Programming (LP), Quadratic Programming (QP), and Non-Linear Programming (NLP). We also recommend reading [http://wiki.analytica.com/index.php?title=Optimizing_with_Arrays Optimizing with Arrays] to master optimization with parametric analysis. [http://wiki.analytica.com/index.php?title=Key_Concepts%3A_The_Airline_NLP_Example Key Concepts: The Airline NLP Example] explains how to use optimization in models having dynamic influences and Monte Carlo-based uncertainties.

==== If you've used Analytica Optimizer 4.2 or earlier ====
The 4.3 release of Analytica introduced ''Structured Optimization'', a new set of features that eliminates many difficult steps previously required for structuring optimizations in Analytica. For example, it can use a set of decision variables of varying dimensions, instead of requiring you to combine and flatten them manually. It introduces Constraints as a new object class. It can discover automatically whether your objective is linear, quadratic, or nonlinear, and apply the appropriate solver engine --and a whole lot more.

So if you’ve used the Optimizer before, we strongly recommend that you read the [http://wiki.analytica.com/index.php?title=Quick_Start Quick Start], which introduces [http://wiki.analytica.com/index.php?title=Quick_Start#Introduction_to_Structured_Optimization Structured Optimization], and the [http://wiki.analytica.com/index.php?title=Optimizing_with_Arrays Optimizing with Arrays] section of this guide (at least). Even though Analytica 4.4 still supports functions from releases 4.2 and earlier of Optimizer for backward compatibility, you will likely want to learn and use the new functions instead.

== Conventions Used in this Guide ==
Under the title of each page on this guide, the page's hierarchy and any parent pages are listed.

The pages in this guide can be read in any order. However, if you want to read the guide sequentially, there are links to the previous and next pages at the bottom of each page which will take the reader through all of the guide's pages in order.

Throughout this guide, we use a shorthand notation for displaying the definitions of Analytica objects. An object’s class (e.g., Variable, Decision, Constraint, etc) and identifier is followed by ''':=''', and the definition is displayed on the right.

[[File:1-1-new.png|400px]]

In the above example, a Constraint object class with the identifier '''Volume Constraint''' is defined as '''Volume >= Required Volume'''.__NOTOC__

Reference sections

2015-12-29T04:25:57Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > {{PAGENAME}}</breadcrumbs><br />

The following appendices shows you how to select an appropriate sample size, the specifications for Analytica, the list of reserved identifiers and error message types, forward and backward compatibility information, a bibliography, and a list of all the Analytica functions.

* [[Selecting the Sample Size]]
* [[Analytica Specifications]]
* [[Identifiers Already Used]]
* [[Error Message Types]]
* [[Forward and Backward Compatibility]]
* [[Bibliography]]<br />

<footer>Analytica Enterprise / {{PAGENAME}} / functions by category</footer>

Reference sections

2015-12-29T04:25:27Z

Jhernandez3:

Bibliography

2015-12-29T04:21:09Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Appendices > {{PAGENAME}}</breadcrumbs><br />

Morgan, M. Granger and Max Henrion. ''Uncertainty: A Guide to Dealing with Uncertainty in Quantitative Risk and Policy Analysis'', Cambridge University Press (1990,1998).

Written by the original authors of Analytica, this text provides extensive background on how to represent and analyze uncertainty in quantitative models. It includes chapters on:
* Building good policy models
* Categorizing types and sources of uncertainty
* How people make judgments under uncertainty
* Encoding expert judgment in the form of probability distributions
* Choosing a computational method for propagating uncertainty in a model
* Analyzing uncertainty in very large models Displaying and communicating uncertainty
* Displaying and communicating uncertainty
* How to tell if representing uncertainty could make a significant difference to your conclusions, or “the value of knowing how little you know” <br />

We recommend the second edition, published in 1998, which contains a full chapter on Analytica (Chapter 10). If you have the first edition (1990), we recommend that you ignore Chapter 10, which describes the precursor of Analytica and is quite out of date!

Clemen, Robert T. ''Making Hard Decisions: An Introduction to Decision Analysis''. Duxbury Press (1991).

Howard, R., and J. Matheson. ''Influence Diagrams. In Readings on the Principles and Applications of Decision Analysis'', eds. R. Howard and J. Matheson. pp. 721-762. Menlo Park, CA: Strategic Decisions Group (1981).

Keeney, R. ''Value–Focused Thinking: A Path to Creative Decision Making'', Cambridge, MA: Harvard University Press (1992).

Knuth, D.E. ''Seminumerical Algorithms, 2nd ed., vol. 2 of The Art of Computer Programming'', Reading, MA: Addison-Wesley (1981).

L’Ecuyer, P. ''Communications of the ACM'', 31, 742-774 (1988).

Park, S.K., and K.W. Miller. ''Communications of the ACM'', 31, 1192-1201 (1988).

Pearl, J. ''Probabilistic Reasoning in Intelligent Systems'', San Mateo, CA: Morgan Kaufmann (1988).

<footer> Forward and Backward Compatibility / {{PAGENAME}} / Function List</footer>

Forward and Backward Compatibility

2015-12-29T04:20:38Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Appendices > {{PAGENAME}}</breadcrumbs><br />

==Backward compatibility==

Models created in earlier releases of Analytica can be loaded, viewed, evaluated, and modified with Analytica 4.6. No file conversions are required. There are many bug fixes included with every new release of Analytica, so if your model utilizes an undocumented feature that was really a bug, a change in model behavior could result.

===Show result warnings===

When you are trying a model for the first time in 4.6, the first thing you should do is ensure that ''Show Result Warnings'' is checked in the '''Preferences''' box. While evaluating your model, avoid selecting ''Ignore Warnings'' if warnings do appear. If any expression in your model produces a warning that you can live with, surround the expression with '''IgnoreWarnings(...)''' to suppress the warning, so that you don’t feel compelled to select the '''Ignore Warnings''' button. When you leave warnings on while your model evaluates, most potential backward-compatibility issues are reported to you.

===Sort (collation) order===

Analytica 4.5 and later uses regional sort order when comparing and sorting text, whereas Analytica 4.4 and earlier use pure ANSI (ASCII) order. Region awareness allows more intelligent handling of accented characters and other language subtleties. In the unlikely event that your model relies on ANSI ordering, you can configure it to use ANSI ordering in Analytica 4.5 or later as follows: press ''F12'' to open the T'''ypescript''' window and type: <code>TextLocale:ANSI</code>.

===Character codes===

Every character has a numeric character code associated with it, which is used by the '''Chr()''' and '''Asc()''' functions. The characters associated with codes from 128 to 160, 173, 178 and 179 have changed to be consistent with the Unicode standard. Your model is only impacted by this if it
relies on the specific numeric value passed to Chr() or received from Asc(). If uses these characters in text or attributes, the conversion in handed automatically or you will see no difference.

==Recommended Modifications==

After you upgrade to the most recent release, there are several setting changes we recommend you make to your model, although these are optional. Analytica will initially configure these to operate a legacy mode to minimize the chance of introducing a difference when you start using your model in the new release; however, legacy modes prevent you from taking full advantage of improvements and fixes.

===ClearType fonts===

Analytica 4.4 and later can render influence diagram nodes using ClearType fonts, which are smooth anti-aliased fonts that look nicer than the fonts used pre-4.4. To turn on ClearType fonts in legacy models, open the '''Set Diagram Style...''' box for your top-level model diagram from edit mode and check the '''ClearType fonts''' checkbox (the checkbox will not be present for models started in Analytica 4.4 or later, which already use ClearType). Then visit each module and adjust any nodes that word wrap in an undesirable fashion. For most diagrams, you can do this by pressing ''Ctrl+A'' (select all) and then pressing ''Ctrl+T'' ('''Adjust size''') multiple times until an acceptable appearance is obtained. With ClearType support, ''Ctrl+T'' cycles through multiple criteria for adjusting node sizes.

===Domain as self index===

You should turn off the '''Domain acts as self index''' preference. A small percentage of models created in Analytica 4.2 or earlier might be impacted, and only in those cases should this preference be on, at least until you update the model appropriately. The older domain treatment is inferior in many ways, and some features are only available when this preference is off.

===Proactive evaluation===

We recommend that you turn off the '''Proactively evaluate indexes''' preference. This will generally speed up the time it takes to load your model. This preference is on in models created initially in 4.3 or earlier.

==Forward compatibility==

It is also possible to run models created or edited in Release 4.6 in earlier releases of Analytica, such as Analytica 4.4, 4.0 or even 3.1, provided you don’t rely on functions, features, characters, or functionalities new to Analytica 4.6. The models load into earlier releases of Analytica, although they might encounter problems during parsing or evaluation in the places where 4.6 features are used. A few 4.6 features might be stripped out of the model if it is re-saved from an earlier Analytica User Guide 443 Appendices Appendices release, such as values for system attributes or system variables that don’t exist in the earlier version.

===UTF-8 file format ===

Models that contain Unicode characters (characters not present in the ASCII, or ISO-8859-1, character set, generally those with character codes above 255, including Chinese, Japanese, Korean, Cyrillic, Greek and other alphabets and esoteric mathematical and graphical symbols)
are saved using the UTF-8 character encoding, whereas Analytica 4.4 and earlier assume model files to be ASCII-encoded. These UTF-8 files will load into Analytica 4.4 and earlier, but extended characters (any character with an ASCII code above 127) become mangled into two or three characters. The user is warned about the problem when the model is loaded into the earlier release.

This is not a problem if you have not used any Unicode characters in your model, since in that case, Analytica will save your model using the ASCII encoding. If your model does utilize Unicode characters, then you need to tell your users that 4.5 or later is required, since Unicode support was introduced in Release 4.5.

<footer> Error Message Types / {{PAGENAME}} / Bibliography</footer>

Error Message Types

2015-12-29T04:20:07Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Appendices > {{PAGENAME}}</breadcrumbs><br />

There are several types of error messages in Analytica. Many messages are designed to inform you that something in the model needs to be corrected; some messages indicate that Analytica cannot continue or complete your request. Each error message begins with its message type, one of warning, lexical, syntax, evaluation, system, and fatal errors. In general, Analytica allows you to continue working on your model unless it cannot proceed until a problem has been corrected. When you are editing a variable definition, you can request an error message by pressing Alt-Enter or by clicking the definition warning icon .

==Warning==

A warning indicates that there is a possible problem. Here is an example.

:::[[File:warning.png|400px]]

A warning is reported during result evaluation to inform you that continuing can yield unexpected results.

You can suppress evaluation warnings for all variables by disabling the Show result warnings preference (see [http://wiki.analytica.com/index.php?title=Preferences_dialog Preferences dialog]). When Show result warnings is unchecked, any warning conditions encountered during result evaluation is ignored. You can also suppress
warnings during evaluation of a single expression with the [http://wiki.analytica.com/index.php?title=IgnoreWarnings IgnoreWarnings(expr)] function.

If an identifier in a module you are adding to a model has a name conflict with an identifier in the model, you see a warning similar to the following.

:::[[File:warning2.png|400px]]

==Lexical error==

A lexical error occurs when a component of an expression was expected and is missing or is invalid. For example, if you enter a number with an invalid number suffix, you might get a message similar to the following.

:::[[File:lexical.png|400px]][[File:lexical.png|400px]]

==Syntax error==

A syntax error occurs when an expression contains a syntax mistake. Analytica often reports the mistake together with the fragment of the expression that contained the error. Here is an example.

:::[[File:syntax.png|400px]]

The following are two common syntax errors.

If you attempt to change the identifier for a variable, and the new identifier is assigned to another node, you see a message similar to the following.

'''Expecting ","''' Indicates a comma is missing, or there are too few parameters to a function.
'''Expecting ")"''' Indicates there are too many parameters to a function.

If you attempt to change the identifier for a variable, and the new identifier is assigned to another node, you see a message similar to the following.

:::[[File:syntax2.png|400px]]

==Evaluation error==

An evaluation error occurs when there is a problem while evaluating a variable, user-defined function, or system function. You are asked if you want to edit the definition of the variable currently being evaluated.

:::[[File:evaluation.png|400px]]

If a system function expects a specific kind of argument, an error message similar to the following is displayed.

:::[[File:evaluation2.png|400px]]

This message indicates that an argument passed to the function is of a different type or cannot be handled by that function. You might need to redefine a variable being used as an argument to the function, or change an expression being passed as an argument.

==Invalid number==

If a calculation tries to perform a division by zero, it displays a warning with an option to continue calculating. Three possible error codes can be returned as a result of an invalid calculation.

{| class="wikitable"
! '''Code'''
! '''Meaning'''

|-
| '''INF'''
| Infinity, such as 1/0.

|-
| '''NAN'''
| Not A Number. Results from invalid functions such as Sqrt(-1), or 0/0.

|-
| '''NULL''' (blank)
| Displays as a blank cell if the result is a table, or shows the '''Compute''' button otherwise. Results from certain functions, such as SubIndex(), when a result is not available.

|}

You can test for these results in an expression using "X=INF", Isnan(X), or X=NULL.

==System error==

If you see this message type, please [mailto:support@lumina.com email us] or click [http://www.lumina.com/support/support-issue/ here] to report the error.

==Out of memory error==

Indicates that Analytica has used up all available memory and cannot complete the current command. If this occurs, first save your model. Before attempting to evaluate again, close some windows, use a smaller sample size, or expand the memory available to Analytica (see [[Analytica_Specifications#Memory_usage|Memory Usage]]).

<footer>Identifiers Already Used / {{PAGENAME}} / Forward and Backward Compatibility</footer>

Identifiers Already Used

2015-12-29T04:19:43Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Appendices > {{PAGENAME}}</breadcrumbs><br />

Each object, whether built-in or created by you, must have a unique identifier. This identifier must start with a letter, and can be up to 20 characters including letters, digits, and underscores. If you try to create an identifier already in use, it warns you and appends a digit to make it unique.

To see all identifiers currently in use:

# Press ''Control+’'' (Control + single apostrophe), to open the '''Typescript''' Window
# Type '''List''', then press ''Enter''.<br />

To see all identifiers starting with the prefix “Con”:
<ol start="3"><li>Type List "^Con", then press ''Enter''.</li></ol>

<Tip Title="Note"> Any regular expression can appear between the quotes.</Tip>

<footer>Analytica Specifications / {{PAGENAME}} / Error Message Types</footer>

Analytica Specifications

2015-12-29T04:18:56Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Appendices > {{PAGENAME}}</breadcrumbs><br />

==Hardware and Software==

{| class="wikitable"
|-
| CPUs supported
| Pentium or higher and equivalent AMD processors recommended
|-
| System Software
| Windows XP, Vista, Windows 7, Server
|-
| Memory requirements
|128 MB (512 MB+ recommended)
|-
| Application size
|Approximately 6 MB
|-
| Maximum memory usable by <br />
Analytica process
| Analytica 64-bit: 128GB (limited by max pagefile size)
Analytica 32-bit:<br />
:4GB on Windows x64<br />
:3GB if /3GB flag added in C:\boot.ini<br />
:2GB without /3GB flag in C:\boot.ini
|}

==Objects==

{| class="wikitable"
|-
| Number of system objects
| 738
|-
| Maximum user-defined objects
| 31,900
|-
| Maximum number of local variables
|No fixed limit
|}

==Uncertainty==

{| class="wikitable"
|-
| Probability methods
| Random Latin HyperCube<br />
Median Latin HyperCube<br />
Monte Carlo
|-
| Maximum sample size
| 99,999,999 for Analytica Enterprise, Optimizer, Power Player, and ADE<br />
30,000 (other editions)<br />
limited by available memory
|-
| Random sampling methods
|Minimal Standard
L’Ecuyer<br />
Knuth
|}

==Numbers and arrays==

{| class="wikitable"
|-
| Number precision
| 15 significant digits for floating-point numbers
9 digits for integers
|-
| Maximum elements in a dimension
| 99,999,999 (Analytica Enterprise, Optimizer, Power Player, and ADE)<br />
30,000 (other editions)
|-
| Maximum dimensions in an array
|15
|}

== Memory usage ==
The '''Memory Usage''' window displays the amount of memory available on your system, as well as the memory currently in use by all applications, including Windows itself. The memory available on your system is the sum of all physical memory installed on your system and the pagefile on
your hard disk, which is used to complement the physical memory.

To display the '''Memory Usage''' window, select '''Show Memory Usage''' from the '''Window''' menu. The memory usage displays in two sizes, depending on whether you check Expanded View. The expanded view contains a large number of memory statistics.

[[File:memory.png|600px]]

<Tip Title="Tip>The above window appears automatically when Analytica runs low on memory.</Tip>

[[File:memory_2.png|800px]]

If you require additional memory to run your model at a given sample size, you can take several steps to increase the amount of memory available to Analytica:
# Close other open applications.
::All applications require a segment of memory to operate, and this reduces the memory available to Analytica.
<ol start="2"><li> Increase the size of your computer’s page file. </li></ol>
<ol start="3"><li> Analytica is a 32-bit process, and like all 32-bit process, the Windows operating system limits the maximum amount of memory that can be used by a 32-bit process to a default limit of 2GB. In Windows XP and Vista, this limit can be increased to 3GB by editing the system file C:\boot.ini. For the line corresponding to your operating in that file, append /3GB and /USERVA options. For example, after your edit, the line may be: </li></ol>
::: <code>multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows XP" /3GB /USERVA</code>
::After making the edit, a system reboot is required for this to take effect.
<ol start="4"><li> Consider adding more physical memory to your computer. </li></ol>
:: If you are limited by the 3GB per process ceiling, then adding more memory will not increase available space, although it may speed up execution when other applications are also open. Analytica 64-bit will directly benefit from any RAM you add.
<ol start="5"><li> Add a solid-state drive to your computer and locate your page file on it. </li></ol>
<ol start="6"><li> Consider ways to reorganize your model. Are there dimensions that can be removed from the model, or especially from problematic high-dimensional results. The Performance Profiler (in Analytica Enterprise) can help you pinpoint variables that consume a lot of memory.</li></ol> <br />

For additional ideas for coping with memory limitations, see [http://wiki.analytica.com/index.php?title=Managing_Memory_and_CPU_Time_for_large_models Managing Memory and CPU Time for large models].<br />

<footer>Selecting the Sample Size / {{PAGENAME}} / Identifiers Already Used</footer>

Selecting the Sample Size

2015-12-29T04:18:28Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Appendices > {{PAGENAME}}</breadcrumbs><br />

Each probabilistic value is simulated by computing a random sample of values from the actual probability distribution.

You can control the sampling method and sample size by using '''Uncertainty Setup'''. This appendix briefly discusses how to select a sample size.

==Choosing an Appropriate Sample Size==

There is a clear trade-off for using a larger sample size in calculating an uncertainty variable. When you set the sample size to a large value, the result is less noisy, but it takes a longer time to compute the distribution. For an initial probabilistic calculation, a sample size of 20 to 50 is usually adequate.

How should you choose the sample size <code>m</code>? It depends both on the cost of each model run, and what you want the results for. An advantage of the Monte Carlo method is that you can apply many standard statistical techniques to estimate the precision of estimates of the output distribution. This is because the generated sample of values for each output variable is a random sample from the true probability distribution for that variable.

==Uncertainty about the Mean==

First, suppose you are primarily interested in the precision of the mean of your output variable <code>y</code>. Assume you have a random sample of <code>m</code> output values generated by Monte Carlo simulation:

:(y<sub>1</sub>, y<sub>2</sub>, y<sub>3</sub>, …y<sub>m</sub>) <div class="floatright">(1)</div>

You can estimate the mean and standard deviation of y using the following equations:

:<big><math>\vec y=\sum_{i=1}^m \frac { y_i }m</math></big><div class="floatright">(2)</div>

:<big><math>s^2=\sum_{i=1}^m \frac { (y_i - \vec y)^2} {m - 1}</math></big><div class="floatright">(3)</div>

This leads to the following confidence interval with confidence <code>α</code>, where <code>c</code> is the deviation for the unit normally enclosing probability <code>α</code>:

:<big><math>\left (\vec y-c\frac {s} {\sqrt m}, \vec y + c\frac {s} {\sqrt m}\right ) </math></big><div class="floatright">(4)</div>

Suppose you wish to obtain an estimate of the mean of <code>y</code> with an α confidence interval smaller than <code>w</code> units wide. What sample size do you need? You need to make sure that:

:<big><math>w>2c \frac {s}{\sqrt m}</math></big><div class="floatright">(5)</div>

Or, rearranging the inequality:

:<big><math>m> \left ( \frac {2cs}{w}\right ) ^2</math></big><div class="floatright">(6)</div>

To use this, first make a small Monte Carlo run with, say, 10 values to get an initial estimate of the variance of y — that is, s2. You can then use equation (6) to estimate how many samples reduce the confidence interval to the requisite width w.

For example, suppose you wish to obtain a 95% confidence interval for the mean that is less than 20 units wide. Suppose your initial sample of 10 gives s = 40. The deviation c enclosing a probability of 95% for a unit normal is about 2. Substituting these numbers into equation (6), you get:

:<big><math>m> \left ( \frac {2 \times 2 \times 40}{20} \right )^2 = 8^2 = 64</math></big><div class="floatright">(7)</div><br />

So, to get the required precision for the mean, you should set the sample size to about 64.

== Estimating Confidence Intervals for Fractiles ==

Another criterion for selecting sample size is the precision of the estimate of the median and other fractiles, or more generally, the precision of the estimated cumulative distribution. Assume that the sample m values of y are relabeled so that they are in increasing order:

:<big><math> y_1 \le, y_2 \le, ...y_m</math></big>

<code>c</code> is the deviation enclosing probability <code>α</code> of the unit normal. Then the following pair of sample values constitutes the confidence interval:

:(<big>y<sub>i</sub>, y<sub>k</sub></big>)

where:

:<big><math>i = \left \lfloor mp - c \sqrt {mp (1-p)} \right \rfloor</math></big><div class="floatright">(8)</div><br />

:<big><math>i = \left \lceil mp - c \sqrt {mp (1-p)} \right \rceil</math></big><div class="floatright">(9)</div>

<Tip Title="Note"> The brackets in equations (8) and (9) above mean round up [[File:lceil.png]] and round down[[File:rfloor.png]], since they are computing numbers that need to be integers.</Tip>

Suppose you want to achieve sufficient precision such that the <code>a</code> confidence interval for the pth fractile Y<sub>p></sub> is given by (y<sub>1</sub>, y<sub>2</sub>), where y<sub>i</sub> is an estimate of '''<math>{Y_p-{_\Delta}{_p}}</math>''', and y<sub>k</sub> is an estimate of '''<math>{Y_p+{_\Delta}{_p}}</math>'''. In other words, you want <math>\alpha</math> confidence of Y<code>p</code> being between the sample values used as estimates of the (<math>p-{_\Delta}{_p})</math>) and (<math>p+{_\Delta}{_p})</math>) fractiles. What sample size do you need? Ignoring the rounding, you have approximately:

:<big><math>i = m(p-{\Delta}p), k = m(p+{\Delta} p)</math></big><div class="floatright">(10)</div><br />

Thus:

:<big><math>k - i = 2m{\Delta}p</math></big><div class="floatright">(11)</div><br />

From equations (8) and (9) above, you have:

:<big><math>k - i = 2c\sqrt {mp(1-p)}</math></big><div class="floatright">(12)</div><br />

Equating the two expressions for k-1 , you obtain:

:<big><math>2mp\Delta p = 2c \sqrt {mp(1-p)}</math></big><div class="floatright">(13)</div><br />

:<big><math>m=p(1- p) \left (\frac {c}{\Delta p} \right )^2</math></big><div class="floatright">(14)</div><br />

For example, suppose you want to be 95% confident that the estimated fractile Y<sub>.90</sub> is between the estimated fractiles Y<sub>.85</sub> and Y<sub>.95</sub>. So you have <math>\Delta p</math>=0.05, and c≈2. Substituting the numbers into equation (14), you get:

:<big><math>m = 0.90 \times (1 - 0.90) \times \left (\frac {2}{0.05} \right )^2 = 144</math></big><div class="floatright">(15)</div><br />
On the other hand, suppose you want the credible interval for the least precise estimated percentile (the 50th percentile) to have a 95% confidence interval of plus or minus one estimated percentile. Then:

:<big><math>m = 0.5 \times (1 - 0.5) \times \left (\frac {2}{0.01} \right )^2 = 10,000</math></big><div class="floatright">(16)</div><br />

These results are completely independent of the shape of the distribution. If you find this an appropriate way to state your requirements for the precision of the estimated distribution, you can determine the sample size before doing any runs to see what sort of distribution it might be.

<footer>Appendices / {{PAGENAME}} / Analytica Specifications</footer>

COM Automation Objects

2015-12-29T04:17:15Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

The Microsoft Component Object Model (COM) provides a framework for interprocess communication within the Windows operating system. Using the functions described in this section, you can instantiate and call other applications that expose a COM automation interface (known as the IDispatch interface). You can write your own COM servers in C++, C#, VB, and a host of other languages, and then call them, or you can use existing interfaces to call applications from other vendors.

These functions allow your model to call other applications. This is different from having other applications call your Analytica model. The Analytica Decision Engine (ADE) product provides the latter functionality.

If you intend to use these functions, you should refer to [http://wiki.analytica.com/index.php?title=COM_Integration Com Integration], where the topic is covered in greater depth.

== [http://wiki.analytica.com/index.php?title=COMCreateObject COMCreateObject](name,''server,flags,user,password'') ==
Instantiates a COM object. This is the first step when using COM. Only the first parameter, name, is required, which is the textual name of a registered server such as "'''ADE4.CAEngine", "MSXML2.DomDocument" or "clsid:72C24DD5-D70A-438B-8A42-98424B88AFB8'''".

The optional server parameter is the name of the computer where the object will be run for remote invocation. Without this parameter, the object is instantiated on the same computer where Analytica is running.

The flags parameter allows control over several esoteric flags. These may be added together. The most notable flags are:
* 0x1 = Allow in-process instantiation
* 0x2 = Allow out-of-process instantiation
* 0x40000 = Allow 32-bit component
* 0x80000 = Allow 64-bit component<br />

To specify the account credentials that the object will run under, you may specify the '''user''' and '''password''' parameters.

You will usually set aside a variable as the object that is instantiated. The definition to this variable will be just a call to [http://wiki.analytica.com/index.php?title=COMCreateObject COMCreateObject](). The object itself will persist (i.e., continue running) as long as the variable remains computed. When the variable is invalidated, the object is released and the COM server will usually terminate. If you hold the result of [http://wiki.analytica.com/index.php?title=COMCreateObject COMCreateObject] in a local variable, the COM object is released when the local variable falls out of scope (more generally, when Analytica the last use of the object falls out of scope).

==obj -> method()==

After using the [http://wiki.analytica.com/COMCreateObject COMCreateObject]() or [http://wiki.analytica.com/index.php?title=SpreadsheetOpen SpreadsheetOpen]() function to instantiate an automation object, you can call method or read and write properties of the object using the -> operator, as show in this example which calls a method:

:<code>ade->OpenModel("Portfolio.ana”)</code>

where Variable ade is defined as <code>COMCreateObject("ADE4.CAEngine")</code>. Without parenthesis, properties are read, e.g.,

:<code>ade->OutputBuffer</code>

and properties can be set using assignment,

:<code>ade->DefaultRenderingStyle->StringQuotes := 2</code>

The -> operator provides a convenient and terse syntax resembling the object syntax of many programming languages, but you should think of this operator as being an abbreviation for the [http://wiki.analytica.com/index.php?title=COMCallMethod COMCallMethod](), [http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty]() and [http://wiki.analytica.com/index.php?title=COMPutProperty COMPutProperty]() functions. Each of these functions provide additional options that are useful in some circumstances.

==[http://wiki.analytica.com/index.php?title=COMCallMethod COMCallMethod](obj, methodName, ''parameters...,resultIndex...,concurrent'')==

Calls the method of '''obj''' named <code>methodName</code>, passing zero or more '''parameters''' to the method. When the method returns an array, you may want to map this to existing indexes in your model, which is done by specifying the result index or indexes in the <code>resultIndex</code> parameter. Because '''parameters''' may have any number of specified arguments, <code>resultIndex</code> must be specified using the named parameter calling syntax. The optional [http://wiki.analytica.com/index.php?title=COM_Integration#Concurrent_calls concurrent parameter] issues method calls asynchronously or in parallel.

===Example===

The <code>GetPriceHistory</code> method of the <code>Reuters</code> object returns a 2-D array of historic stock prices (this is a hypothetical app sold by a hypothetical 3rd party). The first dimension is the trading date, the second has for items: the Open, Close, High and Low. The method itself accepts three parameters: a stock symbol, a start and and end date. You wish to map the result to indexes that already exist in your model.

:<code>COMCallMethod(reuters,”GetPriceHistory”,”AAPL”,8-Jan-2014,Today(), resultIndex:Time,DateOpenCloseHighLow)</code>

==[http://wiki.analytica.com/index.php?title=COMArray COMArray](x,i...)==

When you pass Analytica arrays as parameters of a COM method, the call is iterated (invoked multiple times) for each atomic combination of parameters, and the results from each call are collected. When a method expects an array-valued parameter, you must package it using the [http://wiki.analytica.com/index.php?title=COMArray COMArray] function. The first parameter, <code>x</code>, in the array being passed, and the remaining parameters are the Analytica indexes of <code>x</code>. The list of indexes tells it which indexes are intrinsic (any not listed are iterated) and the order of dimensions that the server expects.

===Example===

:<code>mathObj->PrincipleEigenVector( COMArray(X,I,J), resultIndex:I )</code>

The method called here expects a 2-D matrix and returns a 1-D vector.

==[http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty](obj, propertyName, ''parameters...,resultIndex...'')==

Retrieves a property with the given name. Most properties have no parameters, so usually this call is used with only <code>obj</code> and <code>propertyName</code>, and even more commonly the syntax <code>obj->propertyName</code> is used instead. Some COM objects have indexed properties (the parameters usually act like subscripts), and in those cases parameters may be specified. To call an indexed property, you must use [http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty](), since the obj->name(x) syntax where the name is followed by parenthesis for a parameter list is interpreted as a method call. Some COM applications make a strong distriction between methods and properties, others don’t.

When [http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty] is called, <code>propertyName</code> is text, surrounded by quotes, or an expression that evaluates to text. The <code>resultIndex</code> specifies the Analytica indexes for the result when the property’s value is an array.

===Example===

:<code>COMGetProperty( Wnetwork, "UserDomain" )</code>

Which is equivalent to

:<code>Wnetwork->UserDomain</code>

==[http://wiki.analytica.com/index.php?title=COMPutProperty COMPutProperty](obj, propertyName, value, ''parameters...'')==

Sets the property named <code>propertyName</code> of <code>obj</code> to <code>value</code>. The call

:<code>COMSetProperty(renderStyle,”NumberAsText”,true)</code>

is equivalent to

:<code>renderStyle->NumberAsText := true</code>

When a property is an indexed property, '''parameters''' are specified, usually indicating subscript coordinates of some kind.

== See Also ==
* [http://wiki.analytica.com/index.php?title=Attrib_of_Obj Attrib of Obj]
* [http://wiki.analytica.com/index.php?title=COMArray COMArray]
* [http://wiki.analytica.com/index.php?title=COMCallMethod COMCallMethod]
* [http://wiki.analytica.com/index.php?title=COMCreateObject COMCreateObject]
* [http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty]
* [http://wiki.analytica.com/index.php?title=COMPutProperty COMPutProperty]<br />

<footer>RunConsoleProcess - call other applications / {{PAGENAME}} / Appendices</footer>

COM Automation Objects

2015-12-29T04:15:21Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

The Microsoft Component Object Model (COM) provides a framework for interprocess communication within the Windows operating system. Using the functions described in this section, you can instantiate and call other applications that expose a COM automation interface (known as the IDispatch interface). You can write your own COM servers in C++, C#, VB, and a host of other languages, and then call them, or you can use existing interfaces to call applications from other vendors.

These functions allow your model to call other applications. This is different from having other applications call your Analytica model. The Analytica Decision Engine (ADE) product provides the latter functionality.

If you intend to use these functions, you should refer to [http://wiki.analytica.com/index.php?title=COM_Integration Com Integration], where the topic is covered in greater depth.

== [[COMCreateObject]](name,''server,flags,user,password'') ==
Instantiates a COM object. This is the first step when using COM. Only the first parameter, name, is required, which is the textual name of a registered server such as "'''ADE4.CAEngine", "MSXML2.DomDocument" or "clsid:72C24DD5-D70A-438B-8A42-98424B88AFB8'''".

The optional server parameter is the name of the computer where the object will be run for remote invocation. Without this parameter, the object is instantiated on the same computer where Analytica is running.

The flags parameter allows control over several esoteric flags. These may be added together. The most notable flags are:
* 0x1 = Allow in-process instantiation
* 0x2 = Allow out-of-process instantiation
* 0x40000 = Allow 32-bit component
* 0x80000 = Allow 64-bit component<br />

To specify the account credentials that the object will run under, you may specify the '''user''' and '''password''' parameters.

You will usually set aside a variable as the object that is instantiated. The definition to this variable will be just a call to [[COMCreateObject]](). The object itself will persist (i.e., continue running) as long as the variable remains computed. When the variable is invalidated, the object is released and the COM server will usually terminate. If you hold the result of [[COMCreateObject]] in a local variable, the COM object is released when the local variable falls out of scope (more generally, when Analytica the last use of the object falls out of scope).

==obj -> method()==

After using the [http://wiki.analytica.com/COMCreateObject COMCreateObject]() or [http://wiki.analytica.com/index.php?title=SpreadsheetOpen SpreadsheetOpen]() function to instantiate an automation object, you can call method or read and write properties of the object using the -> operator, as show in this example which calls a method:

:<code>ade->OpenModel("Portfolio.ana”)</code>

where Variable ade is defined as COMCreateObject("ADE4.CAEngine"). Without parenthesis, properties are read, e.g.,

:<code>ade->OutputBuffer</code>

and properties can be set using assignment,

:<code>ade->DefaultRenderingStyle->StringQuotes := 2</code>

The -> operator provides a convenient and terse syntax resembling the object syntax of many programming languages, but you should think of this operator as being an abbreviation for the [http://wiki.analytica.com/index.php?title=COMCallMethod COMCallMethod](), [http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty]() and [http://wiki.analytica.com/index.php?title=COMPutProperty COMPutProperty]() functions. Each of these functions provide additional options that are useful in some circumstances.

==[http://wiki.analytica.com/index.php?title=COMCallMethod COMCallMethod](obj, methodName, ''parameters...,resultIndex...,concurrent'')==

Calls the method of '''obj''' named <code>methodName</code>, passing zero or more '''parameters''' to the method. When the method returns an array, you may want to map this to existing indexes in your model, which is done by specifying the result index or indexes in the <code>resultIndex</code> parameter. Because '''parameters''' may have any number of specified arguments, <code>resultIndex</code> must be specified using the named parameter calling syntax. The optional [http://wiki.analytica.com/index.php?title=COM_Integration#Concurrent_calls concurrent parameter] issues method calls asynchronously or in parallel.

===Example===

The <code>GetPriceHistory</code> method of the <code>Reuters</code> object returns a 2-D array of historic stock prices (this is a hypothetical app sold by a hypothetical 3rd party). The first dimension is the trading date, the second has for items: the Open, Close, High and Low. The method itself accepts three parameters: a stock symbol, a start and and end date. You wish to map the result to indexes that already exist in your model.

:<code>COMCallMethod(reuters,”GetPriceHistory”,”AAPL”,8-Jan-2014,Today(), resultIndex:Time,DateOpenCloseHighLow)</code>

==[http://wiki.analytica.com/index.php?title=COMArray COMArray](x,i...)==

When you pass Analytica arrays as parameters of a COM method, the call is iterated (invoked multiple times) for each atomic combination of parameters, and the results from each call are collected. When a method expects an array-valued parameter, you must package it using the [http://wiki.analytica.com/index.php?title=COMArray COMArray] function. The first parameter, <code>x</code>, in the array being passed, and the remaining parameters are the Analytica indexes of <code>x</code>. The list of indexes tells it which indexes are intrinsic (any not listed are iterated) and the order of dimensions that the server expects.

===Example===

:<code>mathObj->PrincipleEigenVector( COMArray(X,I,J), resultIndex:I )</code>

The method called here expects a 2-D matrix and returns a 1-D vector.

==[http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty](obj, propertyName, ''parameters...,resultIndex...'')==

Retrieves a property with the given name. Most properties have no parameters, so usually this call is used with only <code>obj</code> and <code>propertyName</code>, and even more commonly the syntax <code>obj->propertyName</code> is used instead. Some COM objects have indexed properties (the parameters usually act like subscripts), and in those cases parameters may be specified. To call an indexed property, you must use [http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty](), since the obj->name(x) syntax where the name is followed by parenthesis for a parameter list is interpreted as a method call. Some COM applications make a strong distriction between methods and properties, others don’t.

When [http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty] is called, <code>propertyName</code> is text, surrounded by quotes, or an expression that evaluates to text. The <code>resultIndex</code> specifies the Analytica indexes for the result when the property’s value is an array.

===Example===

:<code>COMGetProperty( Wnetwork, "UserDomain" )</code>

Which is equivalent to

:<code>Wnetwork->UserDomain</code>

==[http://wiki.analytica.com/index.php?title=COMPutProperty COMPutProperty](obj, propertyName, value, ''parameters...'')==

Sets the property named <code>propertyName</code> of <code>obj</code> to <code>value</code>. The call

:<code>COMSetProperty(renderStyle,”NumberAsText”,true)</code>

is equivalent to

:<code>renderStyle->NumberAsText := true</code>

When a property is an indexed property, '''parameters''' are specified, usually indicating subscript coordinates of some kind.

== See Also ==
* [http://wiki.analytica.com/index.php?title=Attrib_of_Obj Attrib of Obj]
* [http://wiki.analytica.com/index.php?title=COMArray COMArray]
* [http://wiki.analytica.com/index.php?title=COMCallMethod COMCallMethod]
* [[COMCreateObject]]
* [http://wiki.analytica.com/index.php?title=COMGetProperty COMGetProperty]
* [http://wiki.analytica.com/index.php?title=COMPutProperty COMPutProperty]<br />

<footer>RunConsoleProcess - call other applications / {{PAGENAME}} / Appendices</footer>

RunConsoleProcess - call other applications

2015-12-29T04:13:58Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

This function lets an Analytica model run a console process, that is, start another Windows application. The application or program can be a simple one with no graphical user interface, or it can interact directly with the user. [http://wiki.analytica.com/index.php?title=RunConsoleProcess RunConsoleProcess]() can provide data as input to the program and return results generated by the application. The '''program''' parameter contains text to specify the directory path and name of the program. It can feed input to the program via command line parameters in '''cmdLine''', via the '''stdIn''' parameter, piped to the ''StdIn'' input channel of the program, or via a data file created with [http://wiki.analytica.com/index.php?title=WriteTextFile WriteTextFile](). Normally, when the program completes, [http://wiki.analytica.com/index.php?title=RunConsoleProcess RunConsoleProcess] returns a result (as text) any information the program writes to '''''stdOut'''''. Analytica can also use [http://wiki.analytica.com/index.php?title=ReadTextFile ReadTextFile]() to read any results the program has saved as a data file.

==Required parameter==

===program===

Text to specify the directory path and name of the Windows application (program) to run. A relative path is interpreted relative to Analytica’s '''CurrentData-Folder'''. If it cannot find or launch the application, it gives an error message.

==Optional parameters==

===cmdline===

Text given input to the program as command line parameters. (It is separated from the '''program''' parameter to protect against a common type of virus attack.)

===stdIn===

Text to be piped to the '''''StdIn''''' input channel of the program.

===block===

If you omit '''block''' or set it to True (1), [http://wiki.analytica.com/index.php?title=RunConsoleProcess RunConsoleProcess]() ''blocks'' — that is, after calling the process, Analytica stops and waits until the console process terminates and returns a result before it resumes execution. While blocked, Analytica still notices Windows events. If you press Control+Break (or Control+.) before the process terminates, it kills the process, and ends further computation by Analytica, just as when Analytica is computing without another process.

If you set '''block''' to False (0), [http://wiki.analytica.com/index.php?title=RunConsoleProcess RunConsoleProcess]() spawns an independent process that runs concurrently with Analytica. Within Analytica, it returns empty text. Analytica and the spawned process each continues running independently until it terminates. If you press ''Control+Break'' (or ''Control+''), it interrupts and stops further computations by Analytica, but has no effect on the spawned process. An unblocking process might continue running even after you exit Analytica. Unblocking processes are useful when you want to send data to another application for display, such as a special graphing package or GIS, or for saving selected results. It is difficult for Analytica to get any results or status back from an unblocking process. If you need results back it is usually best to use a blocking process.

===curDir===

The directory the process should use as its default directory to read and write files. If omitted, it uses the application’s own directory as the default.

===priority===

Sets the priority that Windows should give the spawned process relative to the Analytica process. The default (0) is the same priority as the Analytica process. Setting it to +1 or +2 raises its priority, taking more of the CPU for the process. -1 or -2 lowers the priority, letting other processes (including Analytica) use more of the CPU.

===showErr===

Controls the display of error messages from a blocking process. By default, if the process writes anything to '''stdErr''', Analytica displays it as an error message when the process terminates. If '''showErr'''=2 it shows any text in '''stdErr''' as a warning message. If '''showErr'''=0, it ignores anything in '''stdErr'''. Analytica always ignores any error in an unblocking process, which is assumed to control the display of its own errors.

[http://wiki.analytica.com/index.php?title=RunConsoleProcess RunConsoleProcess]() fully supports Intelligent Arrays. If any parameter is passed an array, it runs a separate process for each element of the array. It runs multiple blocking processes sequentially. It runs multiple non-blocking processes concurrently.

==Examples==

=== Run a VB Script ===
Suppose the Visual Basic program file HelloWorld.vbs is in your model directory and contains:

:<code>WScript.Echo "Hello World"</code>

Your call to [http://wiki.analytica.com/index.php?title=RunConsoleProcess RunConsoleProcess] might look like:

:<code>RunConsoleProcess("C:\Windows\System32\CScript.exe", "CScript /Nologo HelloWorld.vbs")</code>
The first parameter identifies the program to be launched. You don’t need to worry about quoting any spaces in the path name. The second parameter is the command line as it might appear on a command prompt. This expression returns the text value "Hello World".

To send data to the '''StdIn''' of the process, include the optional parameter <code>StdIn</code>:

:<code>RunConsoleProcess("C:\Windows\System32\CScript.exe", "CScript /Nologo HelloWorld.vbs", StdIn: MyDataToSend)</code>

where <code>MyDataToSend</code> is an Analytica variable that gives a text value.

===To run a batch file===

Suppose the directory '''C:\Try''' contains a data file named <code>data.log</code> and a batch file named <code>DoIt.bat</code> containing:

:<code>#DoIt.bat — dump the log</code>
:<code>Type data.log</code>

This batch file assumes it is run from the directory <code>C:\Try</code> so does not mention the directory of <code>data.log</code>. From Analytica, you call:

:<code>RunConsoleProcess("C:\Windows\System32\Cmd.exe", "Cmd /C DoIt.bat",CurDir: "C:\Try")</code>
Or you can run it directly:

:<code>RunConsoleProcess("DoIt.bat", "DoIt.bat", CurDir: "C:\Try")</code>

== See Also ==
* [http://wiki.analytica.com/index.php?title=ReadTextFile ReadTextFile]()
* [http://wiki.analytica.com/index.php?title=RunConsoleProcess RunConsoleProcess]()
* [http://wiki.analytica.com/index.php?title=WriteTextFile WriteTextFile]()<br />

<footer>Performance Profiler library / {{PAGENAME}} / COM Automation Objects</footer>

Performance Profiler library

2015-12-29T04:12:59Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

The Performance Profiler library shows you the computation time and memory space used by each variable and function.

__TOC__
<br />

If you have a large model that takes a long time to run or uses a lot of memory, you might want to find out which variables or functions are using the Lion’s share of the time or memory. As experienced programmers know, the results are often a surprise. With the results from the Performance Profiler, you know where to focus your efforts to make the model faster or use less RAM.

First add '''Performance Profiler.ana''' from the '''Libraries''' folder into your model.

::[[File:performance_profiler_1.png|300px]]

Now display the results (table or graph) for the variables whose performance you want to profile. Open the library, and click '''Performance profiles'''.

::[[File:performance_profiler_2.png|600px]]

This table lists the variables and functions by row, with the class of the object, parent '''module''', '''Bytes''' of RAM (random access memory), and '''CPU msecs''' (milliseconds of time used by the central processing unit). The last column, '''msecs w ancestors''', shows the CPU milliseconds to compute each variable or function including all its ancestors — i.e., the variables and functions it uses. The Profiler shows all variables and functions that use more than 24 bytes of RAM (the minimum) or take more than 1 millisecond to compute. Use '''Sort objects by''' to sort the table by any column.

If you want to inspect a variable or function to see why it’s taking so much time or memory, just click its title in the <code>.Objects</code> index column to open its '''Object''' window.

==Update profiles==

After computing more results, click this button to update the performance profile to reflect the additional time and memory used.

==Zero out times==

If you want to look at the incremental time used by additional results, or another computation, first click this button to zero out the times already computed.

==Understanding memory usage==

For complex definitions, it might use much more RAM while it is computing than it needs to cache the final result — the Profiler reports only the latter. The Bytes show the RAM used to store the value of each variable, mid, probabilistic, or both, depending on which it has computed. Typically, an array takes about 12 bytes per number to store. For example, an uncertain dynamic array of numbers, with an index I of 20 elements, <code>Time</code> has 30 elements, and <code>Samplesize</code> = 1000, would use about 20 x 30 x 1000 x12 = 7,200,000 bytes or 7.2 Megabytes. Analytica uses an efficient representation for arrays with many zeroes (sparse arrays) or many repeated values. An array that is an exact or partial copy of another array can share slices. In such cases, it might actually use less memory than it reports.

==Understanding computation time==

The CPU time listed is the time it took to evaluate the mid and/or prob value of each variable or function, depending on which type of evaluation it did. It is zero if the results computed did not cause evaluation of the variable or function. A variable is usually only computed at most once each for its mid and prob value. Rare exceptions include when the variable is referenced directly or indirectly in a parameter to <code>Whatif</code> or <code>WhatIfall</code>, which might cause multiple evaluations. A function can be called many times. The CPU time reported is the sum over all these evaluations.

==Time and virtual memory==

Like most 32-bit applications on Windows, Analytica can use up to 3 GB of memory. If your computer doesn’t have that much RAM installed, and it needs more than is available, it can use virtual memory — that is, it saves data onto the hard disk. Since reading and writing a hard disk is usually much slower than RAM, using virtual memory often causes the application to slow down substantially. In this case, finding a way to reduce memory usage below the amount of physical RAM available can speed up the application considerably. Another approach is to install more RAM, up to 4 GB.

==Performance profiling attributes and function==

The Performance Profiler library uses a function, two attributes, and a command, which are also available for you to write your own functions using memory or time. For an example of how to use them, you can open up the library.

===[http://wiki.analytica.com/index.php?title=MemoryInUseBy MemoryInUseBy](v)===

This function returns the number of bytes in use by the cached result(s) for variable v — with the same disclaimer that shared memory can be counted more than once. It includes memory used by mid and prob values if those results have been computed and cached, but it doesn’t force them to be computed if they haven’t been.

This function includes these two special read-only attributes:

====EvaluationTime====

This attribute returns the time in seconds to evaluate its variable or function, not including the time to evaluate any of its inputs.

====EvaluationTimeAll====

This attribute returns the time in seconds to evaluate its variable or function, including the time to compute any of its inputs that needed to
be evaluated (and their inputs, and so on).

===ResetElapsedTimings===

This command sets these attributes back to zero. Like any command, you can use it in a button script, the Typescript, but not in a regular definition.

<Tip Title="Tip"> These features, including the Performance Profiler, are only available for Analytica Enterprise, Power Player, and ADE editions.</Tip>

== See Also ==
* [http://wiki.analytica.com/index.php?title=MemoryInUseBy MemoryInUseBy]<br />

<footer>Huge Arrays / {{PAGENAME}} / RunConsoleProcess - call other applications</footer>

Making a browse-only model and hiding definitions

2015-12-29T04:11:05Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

When you are ready to let others use the models you have created, you might want to save it as browse-only, so that end users can only change the variables you have designated as inputs (by making input nodes for them). You might also want to hide definitions of variables or functions to protect confidential or proprietary data or algorithms.

__TOC__

With Analytica Enterprise, you can save models that are locked as browse-only and with hidden definitions, using these steps:

# Hide selected definitions in your model, for entire model, modules, or by variable.
# Save your master model file (and any linked submodules) so that you can still view and modify it yourself.
# Select '''Save a copy''' from the '''File''' menu, and check '''Lock and encrypt''' and optionally '''Save as a browse-only model copy''' to save an '''''encrypted''''' copy — that is a file scrambled into a non-human-readable form.
# Distribute the encrypted copy to your end users.<br />

The third step permanently locks your model so that hidden definitions can never again be viewed in that copy. It is therefore recommended that you save a protected copy of your model, and leave your original model as a master (unprotected) copy. Until the model is stored in an encryped form (step 3), an end user is not prevented from unhiding your definitions, or from viewing them by other means (e.g., by loading the Analytica model file into a text editor).

<Tip Title="Tip"> An encrypted model file cannot be decrypted, even by the original author. If it is locked as browse-only, it can never again be edited. If definitions are hidden, they can never again be viewed or edited. Always place a master copy of your model (and any sub-modules) in a safe place before making an encrypted copy.</Tip>

==Hiding and unhiding definitions==
To hide the definition of a single variable or function, select its node and select '''Hide Definition(s)''' from the '''Object''' menu, so it becomes checked. You cannot hide multiple nodes, except by hiding all nodes in a parent module. To hide the definitions of all objects in a module:<br />

# Select the node of the module in its parent diagram, or open the module and select no nodes inside it.
# Select '''Hide Definition(s)''' from the '''Object''' menu, so it becomes checked.<br />

If a variable, function, or module is hidden, when you try to view its definition, it displays:

:<code>[Definition is Hidden]</code>

<Tip Title="Tip">The definition of a variable with an input node is always visible regardless of whether it or its parent module is marked as Hidden.</Tip >

==Unhiding and inheritance of hiding==

Definition hiding is inherited down the module hierarchy. If you hide a module, you hide the definitions of all the objects that it contains, including its submodules and all the objects that they contain — unless you explicitly unhide an object or submodule, in which it or the objects it contains are not hidden. To unhide a variable, function, or module:
# Select its node in its parent diagram.
# Select '''Unhide Definition(s)''' from the '''Object''' menu, so it becomes checked.<br />

In the module hierarchy shown below, module '''Mo1''' is hidden, and therefore so are the objects it contains, module '''Mo2''', '''Va1''', and '''Va2'''. But module '''Mo3''' is unhidden, and therefore so are the objects it contains, '''Va3''' and '''Mo4'''. However, object '''Va4''' is itself explicitly hidden.

:[[File:browse-only_1.png|250px]]

<Tip Title="Tip"> The '''Hide Definition(s)''' and '''Unhide Definition(s)''' menu options are disabled if the current model, or any of its linked submodules, has been encrypted. In this case, encryption has locked hiding in place.</Tip>

After hiding the definitions you want, you can view your model to check everything is as you want. You can still Unhide items if you want to view or edit them. But, after saving the model in encrypted form, no one, even you, can view hidden definitions or edit any variables that are not inputs, even if they open the model file in a text editor. That’s why it’s important that you save a master copy for your own use.

==Saving an encrypted copy of your model==

When you are ready to save an encrypted copy of your model, select '''Save a Copy''' In from the '''File''' menu.

:[[File:browse-only_2.png|500px]]

Enter a filename that is different than the filename of your master copy, to make sure that you retain an editable version for your self.

Check ''Lock and encrypt the copy'' at the bottom of the dialog to save the model in an encrypted form that makes any hidden definitions unviewable, even if you try to edit the file.

Check ''Save as a browse-only model'' if you also want to prevent users from changing any variables not designated as inputs. In that case, the model is locked in browse-only mode, even if the user runs the model with an Analytica edition that normally allows editing.

Optionally check ''Save everything in one file by embedding linked modules'' to produce a single file that can be distributed. If your model is utilizing unlocked linked modules, the content in those may remain exposed unless you use this option (alternatively, you can link to locked copies of those modules in your main model before saving your main model in a locked form). Even if you do not lock your model, this option can provide a convenient way to distribute your model as a single file to end-users, or to bundle it for upload to the Analytica Cloud Player. '''Publish to cloud''' on the '''File''' menu saves everything in a single file automatically during the upload.

A browse-only model is always encrypt to prevent anyone from editing the source Analytica file. Thus, it automatically checks ''Lock and encrypt the copy'' and the ''Save in XML format'' option is not available.

If you want end users to be able to use other Enterprise features, such as database access, file reading and writing, Huge Arrays, or performance profiling, they need the Power Player — or their own Enterprise edition. Enterprise and Optimizer-level features are available to users viewing your model through the Analytica Cloud Player (ACP).

When a browse-only model (saved as such from Enterprise) is loaded into Analytica Professional, it runs it in Power Player mode, so that database access, etc., is available.

==Linked libraries and submodules==

<Tip Title="Warning"> When your model utilizes linked libraries or submodules, you need to be very careful that the module files you distribute to your users are indeed encrypted or locked as you intend, while at the same time ensuring that you do not accidentally encrypt your master copies of these modules. Because locking a model as encrypted or browse only is an irreversible operation, it is extremely
important that you don’t accidentally lock your master versions. If your model uses linked libraries or linked modules, to avoid inadvertently making these mistakes, it is highly recommended that you embed all modules and libraries check in your encrypted copy by checking Save everything in one file by embedding linked modules.</Tip>

When you save a copy of your model, without checking the ''Save everything in one file by embedding linked modules'' option, Analytica 4.2 and later will save a locked copy only of the top-level model file. The locked status of any linked modules remain in their original state, such that individual module files may remain non-encrypted or editable. If you don’t want to embed all linked modules in your encrypted copy, then you’ll need to save an encrypted copy of each submodule individually, and then use '''“Add Module...”''' with the ''Link and Merge'' options to switch your model to using the locked copy, prior to saving a copy of your top-level model.

If you ever use a pre-4.2 release of Analytica, take extreme caution when encrypting a model containing linked modules -- release 4.1 and earlier will also encrypt the linked module files. Thus, it is imperative that you make a copy of all linked sub-modules before saving an encrypted copy.

In Analytica 4.2 and later, you can distribute locked copies of libraries or modules, allowing other model developers to utilize those libraries without being able to view your proprietary definitions (when they are encrypted) or being able to modify the libraries (when locked as browse-only). When using locked libraries, certain operations involving objects in those modules are restricted. You cannot embed an encrypted sub-module within a non-encrypted module, but you can use it as a linked module. Embedding an encrypted module in an encrypted module is allowed. Various operations that might allow a user to gain access to your hidden definitions are disallowed, such as moving an object with a hidden definition from an encrypted module to a non-encrypted module.

<Tip Title="Warning"> If you distribute locked module files for use by others to use in their models, it is important to ensure that they are using Analytica 4.2 or later. Loading an encrypted or browse-locked module into a model from Analytica 4.1 or earlier will result in the entire model being placed in the same locked state. The ability to utilize a combination of locked and unlocked modules in the same model requires Analytica 4.2 or later.</Tip>

== See Also ==
* [http://wiki.analytica.com/index.php?title=Modules_and_Libraries Modules and Libraries]
* [http://wiki.analytica.com/index.php?title=Obfuscated_and_Browse-Only_Models Obfuscated and Browse-Only Models]<br />

<footer>Read data from URL on internet / {{PAGENAME}} / Huge Arrays</footer>

Read data from URL on internet

2015-12-29T04:07:37Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

The [http://wiki.analytica.com/index.php?title=ReadFromUrl ReadFromUrl function], on the Database menu, reads text from URL sources, such as HTTP web pages or FTP sites.

==[http://wiki.analytica.com/index.php?title=ReadFromUrl ReadFromUrl](url, ''method, formValues, formFields, formIndex'')==

Reads text or images from a URL (Universal Resource Locator) location on the web. In most cases, this is called with a single parameter -- the URL. When reading from a web page, the URL should begin with 'http://....'. When reading a text file from an FTP site, it should begin with 'ftp://...'. The entire text from the requested location is returned as a text value. In most cases, you will need to write Analytica expressions to parse the data. When the URL is an http request that points to an image (*.jpg, *.png, *.gif, etc), a picture object is returned that can be assigned to the pict attribute of objects. With the exception of http requests to known image types, the source data must be textual, and if not, the resulting data will be garbled.

Some web pages and most FTP sites require user and password authentication to access. To authenticate, embed the user name and password in the URL as follows:

:<code>ReadFromUrl('http://user:password@www.site.com/dir/page.htm')</code>
:<code>ReadFromUrl('ftp://user:password@site.com/directory/file.txt')</code>

The optional second through fourth parameters are used to submit data to web forms. There are two methods used to submit data to HTTP web forms: <code>method:'POST'</code>or <code>method:'GET'</code>. The field names and the values submitted for those fields are specified in <code>formValues</code> and <code>formFields</code>, which must share a common index, and if that common index is anything other than <code>form-Fields</code>, it should be specified in the <code>formIndex</code> parameter.

== See Also ==
* [http://wiki.analytica.com/index.php?title=ReadFromUrl ReadFromUrl]<br />

<footer>Read and write text files / {{PAGENAME}} / Making a browse-only model and hiding definitions</footer>

Read and write text files

2015-12-29T04:06:23Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

==[http://wiki.analytica.com/index.php?title=ReadTextFile ReadTextFile](filename)==

Reads a file <code>filename</code> and returns its contents as a text value. If <code>filename</code> contains no directory path, it tries to read from the current folder, usually the folder containing the current model file. If it doesn’t find the file, it opens a Windows browser dialog to prompt the user. For example:

:<code>Function LinesFromFile(filename: Atom Text)</code>
:<code>Definition:</code>
::<code>VAR r := SplitText(ReadTextFile(filename), Chr(10));</code>
::<code>Index lines :=1..Size(r);</code>
::<code>Array(lines, r)</code>

This function reads in the file and splits the text up at the end of each line, with the Chr(10) line feed character. It then defines a local index ''lines'', to be used as the index of the array of lines that it returns.

The optional parameter <code>showDialog</code> controls whether the file dialog appears. If not specified, then the dialog appears only if the file does not exist. If you set <code>showDialog</code> to true (1), it always prompts for the file, even if it finds one by that name. This gives the user a chance to change the filename, while still providing a default name.

==[http://wiki.analytica.com/index.php?title=WriteTextFile WriteTextFile](filename, text, ''append, warn, sep'')==

Writes text to the file <code>filename</code>. The <code>filename</code> is relative to the current data directory. It returns the full pathname of the file if it is successful in writing or appending to it. By default, the '''append''' flag is <code>False</code> and '''warn''' flag is <code>True</code>. If the file doesn’t already exist, it creates the file in the current data directory — and if the file does exist, it asks if you want to replace it. If '''append''' is <code>True (1)</code>, and the file already exists, it appends the text to the end of the file. If warn is <code>False (0)</code>, it does not issue a warning before overwriting an existing file when append is <code>False</code>, or when modifying an existing file when append is <code>True</code>.

If text is an array, it writes each element to the file, inserting separator <code>sep</code> between elements, if provided. If text has more than one dimension, you can control the sequence in which they are written by using function [http://wiki.analytica.com/index.php?title=JoinText JoinText]() to join the text over the index you want innermost.

You can write or append to multiple files when <code>filename</code> is an array of file names. If text has the same index(es), it writes the corresponding slice of text to each file — following proper array abstraction.

== See Also ==
* [http://wiki.analytica.com/index.php?title=ReadTextFile ReadTextFile]
* [http://wiki.analytica.com/index.php?title=WriteTextFile WriteTextFile]<br />

<footer>Database functions / {{PAGENAME}} / Read data from URL on internet</footer>

Database functions

2015-12-29T04:04:52Z

Jhernandez3: /* See Also */

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

The Database library on the Definition menu contains five functions for working with ODBC databases.

==[http://wiki.analytica.com/index.php?title=DbLabels DBLabels](dbIndex)==

Returns a list of the column labels for the result table. This statement can be used to define an index which can then be used as the second argument to [http://wiki.analytica.com/index.php?title=DbTable DBTable](). The first argument, '''dbIndex''', must be defined by a [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement.

==[http://wiki.analytica.com/index.php?title=DbQuery DBQuery](connection, sql, ''key'')==

Used to define an index variable. The definition of the index should contain only one [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement. <code>connection</code> specifies a data source (e.g., <code>'DSN=MyDatabase'</code>) and sql defines an SQL query. The optional <code>key</code> parameter may specify the name of a column in the database that
will be used to determine the row index values returned by [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]. It is best to only use key columns that contain unique values in each row.

When placed as the definition of an index variable, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() is evaluated as soon as the definition is complete, or immediately when the model is loaded. If you place it in a variable node, it will be evaluated when the result is requested, rather than when the model is loaded, provided there are no index nodes downstream that depend on it. When it is evaluated, the actual query is performed. The resulting result table is cached inside Analytica, to subsequently be accessed by [http://wiki.analytica.com/index.php?title=DbTable DBTable]() or [http://wiki.analytica.com/index.php?title=DbLabels DBLabels]().

When the optional <code>key</code> parameter is not specified, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() returns a sequence 1..n, where n is the number of records (rows) in the result table. When <code>key</code> is specified, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery] returns a list consisting of the values from that column in the data source.

[http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() should appear only once in a definition, and if it is embedded in an expression, the expression must return a list with n elements.

[http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() processes the sql statement in read-only mode, so that the data source cannot be altered as a result of executing this statement. To alter the data source, use [http://wiki.analytica.com/index.php?title=DbWrite DBWrite]().

== [http://wiki.analytica.com/index.php?title=DbTable DBTable](dbIndex, column) ==
== [http://wiki.analytica.com/index.php?title=DbTable DBTable](dbIndex, columnList) ==
== [http://wiki.analytica.com/index.php?title=DbTable DBTable](dbIndex, columnIndex) ==
[http://wiki.analytica.com/index.php?title=DbTable DBTable]() is used to get at the data within a result table. The first argument, <code>dbIndex</code>, must be the name of a variable (normally an index) in your Analytica model that is defined with a [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement. If the second argument, <code>column</code>, is a text value, it identifies the name of a column label in the result table, in which case [http://wiki.analytica.com/index.php?title=DbTable DBTable]() returns a 1D array (indexed by <code>dbIndex</code>) with the data for that column. If the second argument is a list of text values (the <code>columnList</code> form), then [http://wiki.analytica.com/index.php?title=DbTable DBTable]() returns a 2D table with records indexed by <code>dbIndex</code>, and columns implicitly indexed (i.e., self-indexed/null-indexed). If the second argument is the name of an Analytica variable (usually an index) whose value evaluates to a list of text values, those text values become the column headings for a 2D table with columns indexed by <code>columnIndex</code>, and rows indexed by <code>dbIndex</code>. With this last form, <code>columnIndex</code> can be defined as [http://wiki.analytica.com/index.php?title=DbLabels DBLabels](<code>dbIndex</code>).

== [http://wiki.analytica.com/index.php?title=DbTablenames DbTableNames](connection, ''catalogs, schemas, tables, tableTypes'') ==
Connects to an ODBC data source and returns catalog data for the data source. <code>connection</code> specifies a data source (e.g., '<code>DSN=MyDatabase</code>'). '''Catalogs, schemas, tables, '''and''' table-Types''' may be names or patterns (as long as the driver manager on your computer is ODBC 3-compliant). Use the percent symbol (%) as a wildcard in each field to match zero or more characters.Underscore (_) matches one character. Most drivers use backslash (\) as an escape character,so that the characters %, _, or \ as literals must be entered as \%, \_, or \\. '''tableTypes''' might be a comma-delimited list of table types. Your data source and ODBC driver might or might not support this call to varying degrees.

=== Examples ===
To get all catalog entries (tables, views, schemas, etc) in <code>My db</code>:

:<code>DBTableNames('DSN=My db')</code>

To get just information on tables in <code>My db</code>:

:<code>DBTableNames('DSN=My db',tables:'%')</code>

To get all valid views:

:<code>DbTableNames('DSN=My db',tableTypes:'VIEW')</code>

The precise value you give to tableTypes depends on which database server you are querying. If you are not sure which type names are used by your database, evaluate [http://wiki.analytica.com/index.php?title=DbTablenames DBTableNames] first with none of the parameters and you should see a column that provides the type names for existing catalog entries.

== [http://wiki.analytica.com/index.php?title=DbWrite DBWrite](connection, sql) ==
This function is identical to [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() except that the query is processed in read-write mode, making it possible to store data in the data source from within Analytica.

== [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery](connection, mdx) ==
[http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery] lets you read or write multidimensional data on an OLAP server database, returning or sending a multidimensional Analytica array. It uses the standard query language, MDX. MDX is analogous to SQL, but where SQL accesses any standard relational database, MDX accesses
multidimensional “hypercube” databases. [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery]() works with Microsoft SQL Server Analysis Services.

<code>connection</code> is the standard text used to identify and connect with the database, similar to that used in other database functions, such as DBQuery(). mdx is text containing the query in the MDX language.

[http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery]() creates a local index for each dimension. The local indexes are named <code>.Axis1</code>,<code>.Axis2</code>,<code> .Axis3</code>, etc., and contain the cube member captions as elements. Some cube axes returned from MDX queries are hierarchical, and for these, [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery] concatenates member captions, separated by commas. For example, if a particular hierarchical axis included calendar year and quarter, an element of <code>.Axis1</code> might be “2003,1”, i.e., Calendar year 2003, quarter 1. To use a separator other than comma, specify an optional parameter, <code>sep</code>, to [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery].

For additional usage information and examples, please refer to [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery].

== [http://wiki.analytica.com/index.php?title=SqlDriverInfo SqlDriverInfo](driverName) ==
Returns a list of attribute-value pairs for the specified driver. If <code>driverName=<nowiki>''</nowiki></code> (an empty text value), returns a list of the names of the drivers. <code>driverName</code> must be a text value — it cannot be a list of text values or an index that is defined as a list of text values. This statement would not
normally be used in a model, but might be helpful in understanding the SQL drivers that are available.

== See Also ==
* [http://wiki.analytica.com/index.php?title=Category%3ADatabase_Functions Analytica Database Functions]<br />

<footer>Database access / {{PAGENAME}} / Read and write text files</footer>

Database functions

2015-12-29T04:04:05Z

Jhernandez3: /* See Also */

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

The Database library on the Definition menu contains five functions for working with ODBC databases.

==[http://wiki.analytica.com/index.php?title=DbLabels DBLabels](dbIndex)==

Returns a list of the column labels for the result table. This statement can be used to define an index which can then be used as the second argument to [http://wiki.analytica.com/index.php?title=DbTable DBTable](). The first argument, '''dbIndex''', must be defined by a [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement.

==[http://wiki.analytica.com/index.php?title=DbQuery DBQuery](connection, sql, ''key'')==

Used to define an index variable. The definition of the index should contain only one [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement. <code>connection</code> specifies a data source (e.g., <code>'DSN=MyDatabase'</code>) and sql defines an SQL query. The optional <code>key</code> parameter may specify the name of a column in the database that
will be used to determine the row index values returned by [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]. It is best to only use key columns that contain unique values in each row.

When placed as the definition of an index variable, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() is evaluated as soon as the definition is complete, or immediately when the model is loaded. If you place it in a variable node, it will be evaluated when the result is requested, rather than when the model is loaded, provided there are no index nodes downstream that depend on it. When it is evaluated, the actual query is performed. The resulting result table is cached inside Analytica, to subsequently be accessed by [http://wiki.analytica.com/index.php?title=DbTable DBTable]() or [http://wiki.analytica.com/index.php?title=DbLabels DBLabels]().

When the optional <code>key</code> parameter is not specified, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() returns a sequence 1..n, where n is the number of records (rows) in the result table. When <code>key</code> is specified, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery] returns a list consisting of the values from that column in the data source.

[http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() should appear only once in a definition, and if it is embedded in an expression, the expression must return a list with n elements.

[http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() processes the sql statement in read-only mode, so that the data source cannot be altered as a result of executing this statement. To alter the data source, use [http://wiki.analytica.com/index.php?title=DbWrite DBWrite]().

== [http://wiki.analytica.com/index.php?title=DbTable DBTable](dbIndex, column) ==
== [http://wiki.analytica.com/index.php?title=DbTable DBTable](dbIndex, columnList) ==
== [http://wiki.analytica.com/index.php?title=DbTable DBTable](dbIndex, columnIndex) ==
[http://wiki.analytica.com/index.php?title=DbTable DBTable]() is used to get at the data within a result table. The first argument, <code>dbIndex</code>, must be the name of a variable (normally an index) in your Analytica model that is defined with a [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement. If the second argument, <code>column</code>, is a text value, it identifies the name of a column label in the result table, in which case [http://wiki.analytica.com/index.php?title=DbTable DBTable]() returns a 1D array (indexed by <code>dbIndex</code>) with the data for that column. If the second argument is a list of text values (the <code>columnList</code> form), then [http://wiki.analytica.com/index.php?title=DbTable DBTable]() returns a 2D table with records indexed by <code>dbIndex</code>, and columns implicitly indexed (i.e., self-indexed/null-indexed). If the second argument is the name of an Analytica variable (usually an index) whose value evaluates to a list of text values, those text values become the column headings for a 2D table with columns indexed by <code>columnIndex</code>, and rows indexed by <code>dbIndex</code>. With this last form, <code>columnIndex</code> can be defined as [http://wiki.analytica.com/index.php?title=DbLabels DBLabels](<code>dbIndex</code>).

== [http://wiki.analytica.com/index.php?title=DbTablenames DbTableNames](connection, ''catalogs, schemas, tables, tableTypes'') ==
Connects to an ODBC data source and returns catalog data for the data source. <code>connection</code> specifies a data source (e.g., '<code>DSN=MyDatabase</code>'). '''Catalogs, schemas, tables, '''and''' table-Types''' may be names or patterns (as long as the driver manager on your computer is ODBC 3-compliant). Use the percent symbol (%) as a wildcard in each field to match zero or more characters.Underscore (_) matches one character. Most drivers use backslash (\) as an escape character,so that the characters %, _, or \ as literals must be entered as \%, \_, or \\. '''tableTypes''' might be a comma-delimited list of table types. Your data source and ODBC driver might or might not support this call to varying degrees.

=== Examples ===
To get all catalog entries (tables, views, schemas, etc) in <code>My db</code>:

:<code>DBTableNames('DSN=My db')</code>

To get just information on tables in <code>My db</code>:

:<code>DBTableNames('DSN=My db',tables:'%')</code>

To get all valid views:

:<code>DbTableNames('DSN=My db',tableTypes:'VIEW')</code>

The precise value you give to tableTypes depends on which database server you are querying. If you are not sure which type names are used by your database, evaluate [http://wiki.analytica.com/index.php?title=DbTablenames DBTableNames] first with none of the parameters and you should see a column that provides the type names for existing catalog entries.

== [http://wiki.analytica.com/index.php?title=DbWrite DBWrite](connection, sql) ==
This function is identical to [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() except that the query is processed in read-write mode, making it possible to store data in the data source from within Analytica.

== [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery](connection, mdx) ==
[http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery] lets you read or write multidimensional data on an OLAP server database, returning or sending a multidimensional Analytica array. It uses the standard query language, MDX. MDX is analogous to SQL, but where SQL accesses any standard relational database, MDX accesses
multidimensional “hypercube” databases. [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery]() works with Microsoft SQL Server Analysis Services.

<code>connection</code> is the standard text used to identify and connect with the database, similar to that used in other database functions, such as DBQuery(). mdx is text containing the query in the MDX language.

[http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery]() creates a local index for each dimension. The local indexes are named <code>.Axis1</code>,<code>.Axis2</code>,<code> .Axis3</code>, etc., and contain the cube member captions as elements. Some cube axes returned from MDX queries are hierarchical, and for these, [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery] concatenates member captions, separated by commas. For example, if a particular hierarchical axis included calendar year and quarter, an element of <code>.Axis1</code> might be “2003,1”, i.e., Calendar year 2003, quarter 1. To use a separator other than comma, specify an optional parameter, <code>sep</code>, to [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery].

For additional usage information and examples, please refer to [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery].

== [http://wiki.analytica.com/index.php?title=SqlDriverInfo SqlDriverInfo](driverName) ==
Returns a list of attribute-value pairs for the specified driver. If <code>driverName=<nowiki>''</nowiki></code> (an empty text value), returns a list of the names of the drivers. <code>driverName</code> must be a text value — it cannot be a list of text values or an index that is defined as a list of text values. This statement would not
normally be used in a model, but might be helpful in understanding the SQL drivers that are available.

== See Also ==
* [http://wiki.analytica.com/index.php?title=Category%3ADatabase_Functions Analytica Database Functions]

<footer>Database access / {{PAGENAME}} / Read and write text files</footer>

Database functions

2015-12-29T04:01:57Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

The Database library on the Definition menu contains five functions for working with ODBC databases.

==[http://wiki.analytica.com/index.php?title=DbLabels DBLabels](dbIndex)==

Returns a list of the column labels for the result table. This statement can be used to define an index which can then be used as the second argument to [http://wiki.analytica.com/index.php?title=DbTable DBTable](). The first argument, '''dbIndex''', must be defined by a [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement.

==[http://wiki.analytica.com/index.php?title=DbQuery DBQuery](connection, sql, ''key'')==

Used to define an index variable. The definition of the index should contain only one [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement. <code>connection</code> specifies a data source (e.g., <code>'DSN=MyDatabase'</code>) and sql defines an SQL query. The optional <code>key</code> parameter may specify the name of a column in the database that
will be used to determine the row index values returned by [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]. It is best to only use key columns that contain unique values in each row.

When placed as the definition of an index variable, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() is evaluated as soon as the definition is complete, or immediately when the model is loaded. If you place it in a variable node, it will be evaluated when the result is requested, rather than when the model is loaded, provided there are no index nodes downstream that depend on it. When it is evaluated, the actual query is performed. The resulting result table is cached inside Analytica, to subsequently be accessed by [http://wiki.analytica.com/index.php?title=DbTable DBTable]() or [http://wiki.analytica.com/index.php?title=DbLabels DBLabels]().

When the optional <code>key</code> parameter is not specified, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() returns a sequence 1..n, where n is the number of records (rows) in the result table. When <code>key</code> is specified, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery] returns a list consisting of the values from that column in the data source.

[http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() should appear only once in a definition, and if it is embedded in an expression, the expression must return a list with n elements.

[http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() processes the sql statement in read-only mode, so that the data source cannot be altered as a result of executing this statement. To alter the data source, use [http://wiki.analytica.com/index.php?title=DbWrite DBWrite]().

== [http://wiki.analytica.com/index.php?title=DbTable DBTable](dbIndex, column) ==
== [http://wiki.analytica.com/index.php?title=DbTable DBTable](dbIndex, columnList) ==
== [http://wiki.analytica.com/index.php?title=DbTable DBTable](dbIndex, columnIndex) ==
[http://wiki.analytica.com/index.php?title=DbTable DBTable]() is used to get at the data within a result table. The first argument, <code>dbIndex</code>, must be the name of a variable (normally an index) in your Analytica model that is defined with a [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement. If the second argument, <code>column</code>, is a text value, it identifies the name of a column label in the result table, in which case [http://wiki.analytica.com/index.php?title=DbTable DBTable]() returns a 1D array (indexed by <code>dbIndex</code>) with the data for that column. If the second argument is a list of text values (the <code>columnList</code> form), then [http://wiki.analytica.com/index.php?title=DbTable DBTable]() returns a 2D table with records indexed by <code>dbIndex</code>, and columns implicitly indexed (i.e., self-indexed/null-indexed). If the second argument is the name of an Analytica variable (usually an index) whose value evaluates to a list of text values, those text values become the column headings for a 2D table with columns indexed by <code>columnIndex</code>, and rows indexed by <code>dbIndex</code>. With this last form, <code>columnIndex</code> can be defined as [http://wiki.analytica.com/index.php?title=DbLabels DBLabels](<code>dbIndex</code>).

== [http://wiki.analytica.com/index.php?title=DbTablenames DbTableNames](connection, ''catalogs, schemas, tables, tableTypes'') ==
Connects to an ODBC data source and returns catalog data for the data source. <code>connection</code> specifies a data source (e.g., '<code>DSN=MyDatabase</code>'). '''Catalogs, schemas, tables, '''and''' table-Types''' may be names or patterns (as long as the driver manager on your computer is ODBC 3-compliant). Use the percent symbol (%) as a wildcard in each field to match zero or more characters.Underscore (_) matches one character. Most drivers use backslash (\) as an escape character,so that the characters %, _, or \ as literals must be entered as \%, \_, or \\. '''tableTypes''' might be a comma-delimited list of table types. Your data source and ODBC driver might or might not support this call to varying degrees.

=== Examples ===
To get all catalog entries (tables, views, schemas, etc) in <code>My db</code>:

:<code>DBTableNames('DSN=My db')</code>

To get just information on tables in <code>My db</code>:

:<code>DBTableNames('DSN=My db',tables:'%')</code>

To get all valid views:

:<code>DbTableNames('DSN=My db',tableTypes:'VIEW')</code>

The precise value you give to tableTypes depends on which database server you are querying. If you are not sure which type names are used by your database, evaluate [http://wiki.analytica.com/index.php?title=DbTablenames DBTableNames] first with none of the parameters and you should see a column that provides the type names for existing catalog entries.

== [http://wiki.analytica.com/index.php?title=DbWrite DBWrite](connection, sql) ==
This function is identical to [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() except that the query is processed in read-write mode, making it possible to store data in the data source from within Analytica.

== [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery](connection, mdx) ==
[http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery] lets you read or write multidimensional data on an OLAP server database, returning or sending a multidimensional Analytica array. It uses the standard query language, MDX. MDX is analogous to SQL, but where SQL accesses any standard relational database, MDX accesses
multidimensional “hypercube” databases. [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery]() works with Microsoft SQL Server Analysis Services.

<code>connection</code> is the standard text used to identify and connect with the database, similar to that used in other database functions, such as DBQuery(). mdx is text containing the query in the MDX language.

[http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery]() creates a local index for each dimension. The local indexes are named <code>.Axis1</code>,<code>.Axis2</code>,<code> .Axis3</code>, etc., and contain the cube member captions as elements. Some cube axes returned from MDX queries are hierarchical, and for these, [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery] concatenates member captions, separated by commas. For example, if a particular hierarchical axis included calendar year and quarter, an element of <code>.Axis1</code> might be “2003,1”, i.e., Calendar year 2003, quarter 1. To use a separator other than comma, specify an optional parameter, <code>sep</code>, to [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery].

For additional usage information and examples, please refer to [http://wiki.analytica.com/index.php?title=MdxQuery MdxQuery].

== [http://wiki.analytica.com/index.php?title=SqlDriverInfo SqlDriverInfo](driverName) ==
Returns a list of attribute-value pairs for the specified driver. If <code>driverName=<nowiki>''</nowiki></code> (an empty text value), returns a list of the names of the drivers. <code>driverName</code> must be a text value — it cannot be a list of text values or an index that is defined as a list of text values. This statement would not
normally be used in a model, but might be helpful in understanding the SQL drivers that are available.

== See Also ==

<footer>Database access / {{PAGENAME}} / Read and write text files</footer>

Database access

2015-12-29T03:49:53Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Analytica Enterprise > {{PAGENAME}}</breadcrumbs><br />

Analytica Enterprise provides several functions for querying external databases using Open Database Connectivity (ODBC). '''''ODBC''''' is a widely used standard for connecting to relational databases, on either local or remote computers. It uses queries in Structured Query Language (SQL, pronounced “sequel,”) to read from and write to databases.

==Overview of ODBC==

SQL is a widely used language to read data from and write data to a relational database. A relational database organizes data in two-dimensional tables, where the columns of a table serve as fields or labels, and the rows correspond to records, entries, or instances. In Analytica, it is more natural to refer to the columns as labels and rows as records. For instance, an address book table might have the columns or labels LastName, FirstName, Address, City, State, Zip, Phone, Fax, and E-mail, and each individual would occupy one row or record in that table.

The result of an SQL query is a two-dimensional table, called a '''''result table'''''. The rows are the records matching the criteria specified by the query. The columns are the requested fields.

Analytica Enterprise provides functions that accept an SQL query, using standard SQL syntax, as a text-valued parameter. These functions return the result of the query as an array with two dimensions, with its rows indexed by a '''''record index''''', and columns indexed by a '''''label index'''''. So, the basic structure of an Analytica model for retrieving a result table is this.

:[[File:db_access_1.png|200px]]

Each of these three nodes could require the information from the <code>Result_Table</code>. For example, the definition of the record index would require knowing how many records (rows) are in the result table; the label index might need to read the names of the columns — although, often they are known in advance; and of course, the <code>Result_Table</code> needs to read the table. The Database library provides the functions, [http://wiki.analytica.com/index.php?title=DbQuery DBQuery], [http://wiki.analytica.com/index.php?title=DbLabels DBLabels], and [http://wiki.analytica.com/index.php?title=DbTable DBTable] to define these variables. These functions work in concert to perform the query only once (when the record index is evaluated), and share the result table between the nodes.

Suppose as an example that we have a database containing the addresses individuals. To ensure the titles are meaningful, we name the indexes Individuals and Address_fields. The query is then encoded in the indexes and variable as follows.

:<code>Index Individuals := DBQuery(Data_source,'SELECT*FROM Addresses')</code>

:<code>Index Address_fields := DBLabels(Individuals)</code>

:<code>Variable Address_fields := DBTable(Individuals, Address_fields)</code>

In the above example, the record index is defined using [http://wiki.analytica.com/index.php?title=DbQuery DBQuery](), the label index is defined using [http://wiki.analytica.com/index.php?title=DbLabels DBLabels](), and the result table is defined using [http://wiki.analytica.com/index.php?title=DbTable DBTable](). Each function is described below.

To specify a data source query, two basic pieces of information must always be known. These are the data source identifier and the SQL query text. These two items are the parameters to the [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() function, and are discussed in the following two subsections.

==DSN and data source==

A '''data source''' is described by a text value, which can contain the Data Source Name (DSN) of the data source, login names, passwords, etc. Here, we describe the essentials of how to identify and access a data source. These follow standard ODBC conventions. For more details, consult one of the many texts on ODBC.

<Tip Title="Tip">You must have a DSN already configured on your machine. If not, consult with your Network
Administrator. See [[Database_access#Configuring_a_DSN|Configuring a DSN]].</Tip>

The general format of a data source identification text is (the single quotes are Analytica’s text delimiters):

:<code>'attr1=value1; attr2=value2; attr3=value3;'</code>

For example, the following data source identifier specifies the database called 'Automobile Data', with a user login 'John' and a password of 'Lightning':

:<code>'DSN=Automobile Data; UID=John;PWD=Lightning'</code>

If a database is not password protected, then a data source descriptor might be as simple as:

:<code>'DSN=Automobile Data'</code>

If a default data source is configured on your machine (consult your database administrator), you can specify it as:

:<code>'DSN=DEFAULT'</code>

Some systems might require one login and password for the server, and another login and password for the DBMS. In this case, both can be specified as:

:<code>'DSN=Automobile Data; UID=John;</code>
:<code>PWD=Lightning; UIDDBMS=JQR; PWDDBMS=Thunder'</code>

You can use the DRIVER attribute to specify explicitly which driver to use, instead of letting it be determined automatically by the data source type. For example:

:<code>'DSN=Automobile Data; DRIVER=SQL Server'</code>

Instead of embedding a long data source connection text inside the [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() statement, you can define a variable in Analytica whose value is the appropriate text value. The name of this variable can then be provided as the argument to [http://wiki.analytica.com/index.php?title=DbQuery DBQuery](). Another alternative is to place the connection information in a file data source (a .DSN file). Such a file would consist of lines such as:

:<code>DRIVER = SQL Server</code>
:<code>UID = John</code>
:<code>PWD = Lightning</code>
:<code>DSN = Automobile Data</code>

Assuming this data is in a file named MyConnect.DSN, the connection text can be specified as:

:<code>'FILEDSN=MyConnect.DSN'</code>

In some applications, you might wish to connect directly to a driver rather than a registered data source. Some drivers allow this as a way to access a data file directly, even when it is not registered. Also, some drivers provide this as a way o f interrogating the driver itself. To perform such a connection, use the driver keyword. For example, if the Paradox driver accepts the directory of the data files as an argument, you can specify:

:<code>'DRIVER={Paradox Driver};DIRECTORY='D:\CARS'</code>

The specific fields used here (UID, PWD, UIDDBMS, PWDDBMS, DIRECTORY, etc.) are interpreted by the ODBC driver, and therefore depend on the specific driver used. Any fields interpreted by your driver are allowed.

If you do not wish to embed the full DSN in the connection text, a series of dialogs pop up when the [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() function is evaluated. For example, you can leave the UID and PWD (user name and password) out of your model. When the model is evaluated, Analytica prompts you to enter the required information. Explicitly placing information in your model eliminates the extra dialog. A blank connection text can even be used, in which case you need to choose among the data sources available on your machine when the model is being evaluated. Although the user can form the DSN via the graphical interface at that point, the result is not automatically placed in the definitions of your Analytica model. However, you might be able to store the information in a DSN file (depending on which drivers and driver manager you are using). You might also be able to register data sources on your machine from that interface.

<Tip Title="Tip">In 64-bit Windows, ODBC drivers may be either 64-bit drivers or 32-bit drivers. When you are using Analytica 64-bit, you can only make use of 64-bit ODBC drivers. If you do not have a 64-bit driver for the database you are using installed on your computer, you will not be able to query that database from Analytica 64-bit. Likewise, the 32-bit editions of Analytica can only make use of 32-bit ODBC drivers, so the appropriate 32-bit driver must be installed on your computer.<br /><br />

Note that 64-bit versions of the Microsoft JET drivers do not exist. These drivers are installed with Microsoft Access and include the Access ODBC driver, the Excel ODBC driver, and the flat file ODBC driver. Microsoft apparently has no plans to release 64-bit versions of these drivers, and has indicated it wants to phase out the use of these drivers entirely. These drivers therefore cannot be utilized from Analytica 64-bit. Most other major database drivers are available in both 32- and 64-bit.</Tip>

==Configuring a DSN==

To access a database using ODBC, you must have a Data Source Name (DSN) already configured on your machine. In general, configuring a DSN requires substantial database administration expertise as well as the appropriate access permissions on your computer and network. To configure a data source, you should consult with your Network Administrator or your database product documentation. The general task of configuring a DSN is beyond the scope of this manual.

If you find you must configure a DSN yourself, the process usually involves the following steps (assuming your database already exists):

# Select the ODBC icon from the Windows Control Panel.
# Select the User DSN, System DSN, or File DSN tab depending on your needs. Most likely, you will want System DSN. Click the '''Add''' button.
# Select the driver. For example, if your database is a Microsoft Access database, select the Microsoft Access Driver and click '''Finish'''.
# You are led through a series of dialogs specific to the driver you selected. These include dialogs that allow you to specify the location of your database, as well as the DSN name that you will use from your Analytica model. An example is shown here.
<br />

::[[File:db_access_2.png|600px]]

==Specifying an SQL query==

You can use any SQL query as a text parameter within an Analytica database function. SQL queries can be very powerful, and can include multiple tables, joins, splits, filters, sorting, and so on.

We give only a few simple examples here. If you are interested in more demanding applications, please consult one of the many excellent texts on SQL.

The SQL expression to select a complete table in a relational database, where the table is named VEHICLES, would be:

:<code>'SELECT * FROM vehicles'</code>

<Tip Title="Tip">SQL is case insensitive, but Analytica is case sensitive for labels of Column names.</Tip>

To select only two columns (make and model) from this same table and sort them by make:

:<code>'SELECT make, model FROM vehicles ORDER BY make'</code>

These examples provide a starting point. When using multiple tables, one detail to be aware of is that it is possible in SQL to construct a result table with two columns containing the same label. For example:

:<code>'SELECT * FROM vehicles, companies'</code>

where both tables for vehicles and companies contain a column labeled '''Id'''. In this case, you can only access one (the first) of the two columns using [http://wiki.analytica.com/index.php?title=DbTable DBTable](). Thus, you should take care to ensure that duplicate column labels do not result. This can be accomplished, for example, using
the AS keyword, for example:

:<code>'SELECT vehicles.Id AS vid, companies.Id AS cid, * FROM vehicles, companies'</code>

For users that are unaccustomed to writing SQL statements, products exist that allow SQL statements to be constructed from a simple graphical user interface. Many databases allow queries to be defined and stored in the database. For example, from Microsoft Access, one can define a query by running Access and using the Query Wizard graphical user interface. The query is given a name and stored in the database. The name of the query can then be used where the name of a table would normally appear, for example:

:<code>'SELECT * FROM myQuery'</code>

==Retrieving an SQL result table==

To retrieve a result table from a data source, you need:

# The data source connection text.
# The SQL query. These are discussed in the previous two sections. For illustrative purposes, suppose the connection text is <code>'DSN=Automobile Data'</code>, and the SQL statement is

:<code>'SELECT * FROM vehicles'. Obtain the relational Result_table</code>

Thus:

:<code>Index Records := DBQuery('DSN=Automobile Data',</code><code>'SELECT * FROM vehicles')</code>
:<code>Index Labels := DBLabels(Records)</code>
:<code>Variable Result_table := DBTable(Records, Labels)</code>

You can now display <code>Result_table</code> to examine the results.

This basic procedure can be repeated for any result table. The structure of the model stays the same, and just the connection text and SQL query text change.

==Separating columns of a database table==

It is often more convenient for further modeling to create a separate variable for each column of a database table. Each column variable uses the same record index. For example, we might create separate variables for <code>Make</code>, <code>Year</code>, and <code>Car</code> model from the vehicles database table.

:[[File:db_access_3.png|200px]]

In this case, the record index is still defined using [http://wiki.analytica.com/index.php?title=DbQuery DBQuery](), and each column is defined using [http://wiki.analytica.com/index.php?title=DbTable DBTable](). The actual SQL query is issued only once when the record index is evaluated.

Suppose you wished to have <code>Make</code>, <code>Model</code>, <code>Year</code>, <code>MPG</code>, etc., as separate Analytica variables, each a one-dimensional array with a common index. For example:

:<code>Index Records := DBQuery('DSN=Automobile Data',</code>
:<code>'SELECT * FROM vehicles')</code>
:<code>Variable Make := DBTable(Records, 'make')</code>
:<code>Variable Model_Year := DBTable(Records, 'year')</code>
:<code>Variable Car_Model := DBTable(Records, 'model')</code>

Since <code>Model</code> is a reserved word in Analytica, we named the variable <code>Car_Model</code> instead of just <code>Model</code>. But, the second parameter to [http://wiki.analytica.com/index.php?title=DbTable DBTable]() specifies the name of the column as stored in the database. This does not have to be the same as the name of the variable in Analytica.
Alternatively, you can construct a table containing a subset of the columns in a result table. For example, if vehicles has a large number of columns, you might create this variable with only the three columns you are interested in:

:<code>Variable SubCarTable:= DBTable(Records, ['make','model','year'])</code>

This table is indexed by <code>Records</code> and by an implicit index (a.k.a. a null index). The first argument to [http://wiki.analytica.com/index.php?title=DbTable DBTable]() must always be an indexed defined by [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() — remember the SQL query is defined in that node, and this is how [http://wiki.analytica.com/index.php?title=DbTable DBTable]() knows which table is being retrieved.

==[http://wiki.analytica.com/index.php?title=DbWrite DBWrite](): Writing to a database==

You can use SQL to change the contents of the external data source from within an Analytica model. Using the appropriate SQL statements, you can add or delete records from an existing database table. You can also add columns, and create or delete tables, if your data source driver supports these operations.

[http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() cannot alter the data source, because it processes the SQL statement in read-only mode. Instead, use [http://wiki.analytica.com/index.php?title=DbWrite DBWrite](), which is identical to [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() except that it processes the SQL statement in read-write mode. [http://wiki.analytica.com/index.php?title=DbWrite DBWrite]() can make any change to the database that can be expressed as an SQL statement, and is supported by the ODBC driver.

To send data from your model into the database, you must convert that data into a text value — more precisely, into an SQL statement. Analytica offers some tools to help this process. Here, we illustrate a common case — writing a multi-dimensional array to a table in a database. We use the <code>ODBC_Library.ana</code> library distributed with Analytica.

Suppose you want to write the value of variable <code>A</code>, which is a three dimensional array indexed by <code>I</code>, <code>J</code>, and <code>K</code>, into a relational table named <code>TableA</code>, so that other applications can use the data.

First, we need to convert the 3D array into the correct relational table form. Then we convert the table into the SQL text to write to the database.

Our approach is to first convert the three-dimensional array A into a two dimensional table, which we store into <code>TableA</code>. <code>TableA</code> needs the two indexes <code>ARowIndex</code> and <code>ALabelIndex</code>. These three variables are defined as follows:

:<code>Index ALabelIndex := Concat(IndexNames(A),['A'])</code>
:<code>Index ARowIndex := sequence(1, Size(A))</code>
:<code>Variable TableA := MDArrayToTable(A, ARowIndex, ALabelIndex)</code>

<code>[http://wiki.analytica.com/index.php?title=MdArrayToTable MDArrayToTable]</code><code>(a, row, col) </code>'''(pure relational transformation)''' is described in [http://wiki.analytica.com/index.php?title=Relational_tables_and_multiD_arrays#MDArrayToTable.28a.2C_row.2C_col.29_.28pure_relational_transformation.29 MDArrayToTable(a, row, col) (pure relational transformation)]. <code>ALabelIndex</code> evaluates to [<code>'I','J','K','A'</code>], and <code>ARowIndex</code> sets aside one row for each element of <code>A</code>. <code>TableA</code> is then a table with one row for each element of <code>A</code>, where the value of each index for that element is listed in the corresponding column, and the value of that element appears in the final column.

Next, set up <code>TableA</code> in the database with the same columns. This is most easily done using the front end provided with your database. For example, if you are using MS Access, start the MS Access program, and from there, create a new table. Alternatively, you could issue the statement:

:<code>DBWrite(DB,'CREATE TABLE TableA(I <text>, J <text>, K <text>, A <text>)')</code>

from an Analytica expression (replacing <code><text></code> with whatever type is appropriate for your application). Be sure that the column labels in the database table have the same names as the labels of <code>ALabelIndex</code> in the Analytica model.

<Tip Title="Tip"> If you want to use column labels in the database that are different from the Analytica index names, define <code>ALabelIndex</code> to be a 1D array, self indexed. Set the domain of <code>ALabelIndex</code> to be the database labels, and the values of the array to the index names. (The last value is arbitrary.)</Tip>

Our data is now in the form of a 2D table as needed for a database table. Next we construct the SQL text to write the table to the database. You must choose whether you want to append rows to the existing database table, or replace the table entirely. Or you can replace only selected entries. Your choice affects how you construct the SQL statement. Here, we totally replace any existing data with the new data, so after the operation, the database table is exactly the same as <code>TableA</code> in the Analytica model. The SQL statements for performing the write is:

:<code>DELETE * FROM TableA</code>
:<code>INSERT INTO TableA(I, J, K, A) VALUES ('i1','j1','k1','a111')</code>
:<code>INSERT INTO TableA(I, J, K, A) VALUES ('i1','j1','k2','a112')</code>
:<code>...</code>

The first statement removes existing data, since we are replacing it. We follow this by one <code>INSERT INTO</code> statement for each row of <code>TableA</code>. The data to the right of the VALUES keyword is replaced by the specific values for indexes <code>I, J, K</code>, and array <code>A</code> (the example above assumes the values are all text values). If your values are numeric, you should note that MSAccess adds quotes around them automatically.

Since writing the table requires a series of SQL statements, we have two options: Evaluate a series of [http://wiki.analytica.com/index.php?title=DbWrite DBWrite]() functions, or lump the series of SQL statements into one long text value and issue one [http://wiki.analytica.com/index.php?title=DbWrite DBWrite]() statement. In Analytica, the second option is much more efficient for two reasons. First, the overhead of connecting with the database occurs only one time. Second, intermediate result tables do not have to be read from the ODBC driver, while if you issued separate [http://wiki.analytica.com/index.php?title=DbWrite DBWrite]() statements, each one would go through the effort of acquiring the result table, only to be ignored.

== Important feature (double semicolon) ==

To allow multiple SQL statements in a single [http://wiki.analytica.com/index.php?title=DbWrite DBWrite]() function (or in a single [http://wiki.analytica.com/index.php?title=DbQuery DBQuery]() function), Analytica provides an extension to the SQL language. The double semicolon separates multiple statements. For example:

:<code>'DELETE * FROM TableA ;; SELECT * FROM TableA'</code>

This first deletes the data from the table, and then reads the (now empty) table. When ;; is used, only the last SQL statement in the series returns a result table. Most statements that write to a database return an empty result table.

We are now ready to write the Analytica expression that constructs the SQL statement to write the table to the database. The function to do this already exists in the ODBC_Library. First, use the '''Add Module''' item on the '''File''' menu to insert the ODBC_Library into your model; then use the [http://wiki.analytica.com/index.php?title=WriteTableSql WriteTableSql]() function, which returns the SQL statement (as a text value) for writing the table to the database. The function requires that I and L contain no duplicates (which should be the case anyway).

Finally, define:

:<code>Variable Write_A_to_DB := DBWrite(DB, WriteTableSql(A, RowIndex,LabelIndex,'TableA'))</code>

== Creating an output node to write to a database ==
<code>Write_A_to_DB</code> writes array <code>A</code> to the database whenever it is evaluated. But, this happens when the model user causes <code>Write_A_to_DB</code> to be evaluated, not necessarily whenever <code>A</code> changes. To make it easy for the end user to perform the write, we suggest you make an output node for <code>WriteAtoDB</code>:
# Select node <code>Write_A_to_DB</code> in its diagram.
# Select the '''Make Output Node''' command on the '''Edit''' menu.
# Move the new output node to a convenient place in the user interface of the model.<br />

Initially, the output node shows the '''Calc''' button. When you click it, it writes A to the database. It also displays the result of evaluating [http://wiki.analytica.com/index.php?title=DbWrite DBWrite](), usually an empty window, not very interesting to the user. To avoid this, append “<code>; 'Done</code>' ” to its definition:

:<code>Write_A_to_DB := DBWrite(DB, WriteTableSql(A, RowIndex, LabelIndex,'TableA'); 'Done'</code>

Now, when you or an end user of the model, clicks <code>Write_A_to_DB</code>, after writing <code>A</code> to the database, it shows '<code>Done</code>' in the output node. It reverts to the '''Calc''' button, whenever <code>A</code> changes.

== See Also ==
* [http://wiki.analytica.com/index.php?title=Category%3ADatabase_Functions Database Functions]<br />

<footer>Analytica Enterprise / {{PAGENAME}} / Database functions</footer>

Analytica Enterprise

2015-12-29T03:48:32Z

Jhernandez3:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > {{PAGENAME}}</breadcrumbs><br />

You need either Analytica Enterprise or [http://wiki.analytica.com/index.php?title=Analytica_Optimizer_Guide Analytica Optimizer] to create models using the features described in this section. You can use the Analytica Power Player or the [http://wiki.analytica.com/index.php?title=ADE_User_Guide Analytica Decision Engine] to run models created with Enterprise or Optimizer with these features, and can change them using [http://wiki.analytica.com/index.php?title=ADE_User_Guide Analytica Decision Engine]. You can use any edition of Analytica to run a model that uses buttons, or was saved as browse-only with hidden definitions.

<strong>Analytica Enterprise </strong>offers all the functionality of Analytica Professional, plus your model can read from and write to Excel spreadsheets and databases, use Huge Arrays (up to 100 million elements per Index dimension), apply the Profiler to see computational effort by variable, create Browse-only models, and encrypt confidential model elements. You can order Analytica Enterprise [http://www.lumina.com/shoppingcart/productorder/ here].

==Sections==
* [[Database access]]
* [[Database functions]]
* [[Read and write text files]]
* [[Read data from URL on internet]]
* [[Making a browse-only model and hiding definitions]]
* [[Huge Arrays]]
* [[Performance Profiler library]]
* [[RunConsoleProcess - call other applications]]
* [[COM Automation Objects]]

<footer>Procedural Programming / {{PAGENAME}} / Appendices</footer>

Other Procedural Functions

2015-12-29T03:47:31Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

==[http://wiki.analytica.com/index.php?title=CurrentDataFolder CurrentDataFolder](''folderPath'')==

Sets the current data folder to '''folderPath'''. The '''''current data folder''''' is the folder used by functions that read data files such as [http://wiki.analytica.com/index.php?title=ReadTextFile ReadTextFile](), [http://wiki.analytica.com/index.php?title=WriteTextFile WriteTextFile](), and [http://wiki.analytica.com/index.php?title=SpreadsheetOpen SpreadsheetOpen]() when their filename parameter contains no other path. When starting a model, it is the current model folder that contains the model. Specifying a path as a parameter to the function changes the current data folder to that path. If '''folderPath''' is omitted, it returns the path to the current data folder.

==[http://wiki.analytica.com/index.php?title=CurrentModelFolder CurrentModelFolder](folderPath)==

Sets the current model folder to '''folderPath'''. The '''''current model folder''''' is the folder into which the model (and submodules) are saved, by default. When starting a model, it is the folder containing the model. You can change it by selecting a different folder directly using the folder browser from '''Save as''', or by using this function. If '''folderPath''' is omitted, it returns the path to the current model folder.

==[http://wiki.analytica.com/index.php?title=Evaluate Evaluate](e)==

If <code>e</code> is a text value, [http://wiki.analytica.com/index.php?title=Evaluate Evaluate](e) tries to parse <code>e</code> as an Analytica expression, evaluates it, and returns its value. For example:

:<code>Evaluate('10M /10') → 1M</code>

One use for Evaluate(e) is to convert a number formatted as text into a number it can compute with, for example:

:<code>Evaluate('1.23456e+10') → 12.3456G</code>

If <code>e</code> is an expression that generates a text value, it evaluates the expression, and then parses and evaluates the resulting text value. For example:

:<code>(VAR x := 10; Evaluate(x & "+" & x)) → 20</code>

If <code>e</code> is a number or expression that is not a text value, it just returns its value:

:<code>Evaluate(10M /10) → 1M</code>

If <code>e</code> is a text value that is not a valid expression — for example, if it has a syntax error — it returns <code>Null</code>.

Like other functions, it evaluates the parameter as mid (deterministic) or prob (probabilistic), according to the context in which it is called.

[http://wiki.analytica.com/index.php?title=Evaluate Evaluate](e) parses and evaluates text <code>e</code> in a global context. Thus, <code>e</code> cannot refer to local variables, local indexes, or function parameters defined in the definition that uses [http://wiki.analytica.com/index.php?title=Evaluate Evaluate](e). For example, this would give an evaluation error:

:<code>Variable A := (VAR r := 99; Evaluate('r^2') )</code>

If <code>e</code> evaluates to a handle before it is passed to the function, then that object is evaluated and its (mid or sample) value is returned.

===[http://wiki.analytica.com/index.php?title=Evaluate Evaluate] and dependencies===

Analytica’s dependency mechanism does not work with variables or functions whose identifiers appear inside the text parameter of [http://wiki.analytica.com/index.php?title=Evaluate Evaluate](). For example, consider:

:<code>Variable B := Evaluate("F(A)")</code>
:<code>Variable C := F(A)</code>

Initially <code>B</code> and <code>C</code> compute the same value. If you then change the definition of function <code>F</code> or variable <code>A</code>, Analytica’s dependency maintenance ensures that <code>C</code> is recomputed when needed using the new definition of <code>F</code> and <code>A</code>. But, <code>B</code> does not know it depends on <code>F</code> and <code>A</code>, so is not recomputed, and can become inconsistent with the new values for <code>F</code> and <code>A</code>. In rare cases, you might intentionally want to break the dependency, in which case [http://wiki.analytica.com/index.php?title=Evaluate Evaluate]() is appropriate; otherwise, use it only with care.

==[http://wiki.analytica.com/index.php?title=EvaluateScript EvaluateScript](t)==

This function evaluates a text value <code>t</code> as if it was typescript. This can provide access to typescript commands that aren’t available in expressions.

<Tip Title="Tip ">Avoid using [[EvaluateScript]](t) except from event attributes (<code>OnClick</code>, <code>OnChange</code> or <code>Script</code>), or functions called from event attributes. This minimizes the danger of undermining the no-side effects rule.</Tip>

==[http://wiki.analytica.com/index.php?title=GetProcessInfo GetProcessInfo](item)==

Returns information about the current Analytica process from the Windows operating system. There are a large number of recognized values for '''item''', and for a complete list see [http://wiki.analytica.com/index.php?title=GetProcessInfo GetProcess-Info]. Some of the possible values for item are:

<code>"Process ID", "Thread ID", "Computer Name", "User Name", "Windows Version", "Command Line", "Total RAM", "Total Virtual", "Free RAM", "Private Bytes".</code>

:<code>GetProcessInfo("User Name") → "Drice"</code>

You can also access the value of an environment variable as "''item:name''".

:<code>GetProcessInfo("HOMEPATH”) → "\Users\Drice"</code>

A few options provide information about Analytica’s state:

<code>"User Objects", "Total Objects".</code>

:<code>GetProcessInfo("User Objects") → 76</code>

==[http://wiki.analytica.com/index.php?title=GetRegistryValue GetRegistryValue](root, subfolder, name)==

Reads a value from the Windows system registry. This can be quite useful if you install your Analytica model as part of a larger application, and if your model needs to find certain data files on the user’s computer (for example, for use with [http://wiki.analytica.com/index.php?title=ShowPdfFile ShowPdfFile], [http://wiki.analytica.com/index.php?title=ReadTextFile ReadTextFile], or [http://wiki.analytica.com/index.php?title=RunConsoleProcess RunConsoleProcess]). The locations of those files could be stored in the registry by your installer, so that your model knows where to look.

===Example===

<code>GetRegistryValue("HKEY_CURRENT_USER", "Software/MyCompany/MyProduct", "FileLocation")</code>

==[http://wiki.analytica.com/index.php?title=IgnoreWarnings IgnoreWarnings](expr)==

Evaluates its parameter <code>expr</code>, and returns its value, while suppressing most '''[[warnings]]''' that might otherwise be displayed during the evaluation. It is useful when you want to evaluate an expression that generates warnings, such as divide by zero, that you know are not important in that context, but you do not want to uncheck the option ''Show Result Warnings'' in the [http://wiki.analytica.com/index.php?title=Preferences_dialog Preferences dialog], because you do want to see warnings that might appear in other parts of the model.

==[http://wiki.analytica.com/index.php?title=IsResultComputed IsResultComputed](x)==

Returns 1 if the value of <code>x</code> is computed when the function is evaluated. To test whether the sample value of x has been computed, use [http://wiki.analytica.com/index.php?title=Sample Sample](IsResultComputed(x)), or to test the mid value use [http://wiki.analytica.com/index.php?title=Mid Mid](IsResultComputed(x)).

==[http://wiki.analytica.com/index.php?title=OpenURL OpenURL](url)==

Opens '''url''' in a browser window, using your default browser.

==[http://wiki.analytica.com/index.php?title=ShowPdfFile ShowPdfFile](filename)==

Opens '''filename''' using Adobe Reader or Acrobat if one is installed on this computer and the file is a PDF document. [http://wiki.analytica.com/index.php?title=ShowPdfFile ShowPdfFile] is most useful when called from a button script, for example, as a way to provide the user of your model with a way to open a user guide for your model.

==[http://wiki.analytica.com/index.php?title=Try Try]( expr, catch, ''errorNum'')==

Attempts to evaluate and return the result for <code>expr</code>. If an evaluation error occurs directly in <code>expr</code>, or in a User-Defined Function (UDF) called from <code>expr</code>, then <code>catch</code> is evaluated without reporting the error.

===Example===

:<code>Try( COMCreateObject("MSXML"), catch: Null )</code>

Inside the <code>catch</code> expression, you can refer to local variables named <code>ErrorText</code>, <code>ErrorNumber</code> and <code>ErrorLocation</code>, containing information about the error. <code>ErrorLocation</code> contains a handle to the object where the error occurred. You can re-issue the error from within the catch expression by calling [http://wiki.analytica.com/index.php?title=ReThrow ReThrow](). In some cases, you might want to change the error text to your own by calling [http://wiki.analytica.com/index.php?title=Error Error]().

You may optionally specify specific error numbers to catch using the '''errorNum''' parameter:

:<code>Try( COMCreateObject("MSXML"),</code>
:<code>errorNum: 42770, 43033, 43034,</code>
:<code>catch: Error("You don’t have MSXML installed")</code>
:<code>)</code>

To find the error number for the '''errorNum''' parameter, set your catch expression to [http://wiki.analytica.com/index.php?title=MsgBox MsgBox](ErrorNumber) and cause the error to occur. Once you have the number or numbers, reset your '''catch''' expression as you would like it.

[http://wiki.analytica.com/index.php?title=Try Try]() does not suppress or catch warnings. For that, use [http://wiki.analytica.com/index.php?title=IgnoreWarnings IgnoreWarnings]().

== See Also ==
* [http://wiki.analytica.com/index.php?title=CurrentDataFolder CurrentDataFolder]
* [http://wiki.analytica.com/index.php?title=CurrentModelFolder CurrentModelFolder]
* [http://wiki.analytica.com/index.php?title=Evaluate Evaluate]
* [http://wiki.analytica.com/index.php?title=EvaluateScript EvaluateScript]
* [http://wiki.analytica.com/index.php?title=Category%3AFunctions Functions]
* [http://wiki.analytica.com/index.php?title=GetProcessInfo GetProcessInfo]
* [http://wiki.analytica.com/index.php?title=GetRegistryValue GetRegistryValue]
* [http://wiki.analytica.com/index.php?title=IgnoreWarnings IgnoreWarnings]
* [http://wiki.analytica.com/index.php?title=IsResultComputed IsResultComputed]
* [http://wiki.analytica.com/index.php?title=OpenURL OpenURL]
* [http://wiki.analytica.com/index.php?title=ShowPdfFile ShowPdfFile]
* [http://wiki.analytica.com/index.php?title=Try Try]<br />

<footer>Dialog Functions / {{PAGENAME}} / Analytica Enterprise</footer>

Dialog Functions

2015-12-29T03:46:08Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

Dialog functions display dialog boxes to give special information, warnings, or error messages, or to request information from the user. Dialogs are '''''modal''''' — meaning that Analytica pauses evaluation while showing the dialog until the user closes the dialog ('''ShowProgressBar''' is an exception in that it continues evaluation while it displays the progress bar). If the user clicks the '''Cancel''' button, it stops further evaluation — as if the user pressed ''Control+.'' ('''Control+period''').

Dialog functions display their dialog when evaluated. If the definition of a variable <code>A</code> calls a dialog function, it will display the dialog when it evaluates <code>A</code>. If it evaluates <code>A</code> in mid and prob mode, it displays the dialog each time. It does not display the dialog again until it evaluates <code>A</code> again — for example, because one of its inputs changes.

==[http://wiki.analytica.com/index.php?title=MsgBox MsgBox](message, ''buttons, title'')==

Displays a dialog with the text '''message''', a set of '''buttons''' and an icon (according to numerical codes below), with '''title''' in the dialog header bar. Analytica pauses until the user clicks a button. If the user clicks the '''Cancel''' button, it stops evaluation. Otherwise it returns a number, depending on which button the user presses (see below).

The optional buttons parameter is a number that controls which buttons to display, as follows:

:0 = OK only
:1 = OK and Cancel (the default if the '''buttons''' parameter is omitted)
:2 = Abort, Retry, and Ignore
:3 = Yes, No, and Cancel
:4 = Yes and No
:5 = Retry and Cancel

To display an icon in the dialog, add one of these numbers to the '''buttons''' parameter:

:16 = Critical (white X on red circle)
:32 = Question
:48 = Exclamation
:64 = Information

'''[http://wiki.analytica.com/index.php?title=MsgBox MsgBox]''' returns a number depending on which button the user presses:

:1 = OK
:2 = Cancel (stops any further evaluation)
:3 = Abort
:4 = Retry
:5 = Ignore
:6 = Yes
:7 = No

Here are some examples.

:<code>Msgbox('OK, I''m done now.', 0+64,'Information') →''</code>

:::[[File:msgbox1.png|150px]]

:<code>Msgbox('Uh uh! Looks like trouble!', 5+16, 'Disaster') →</code>

:::[[File:msgbox2.png|200px]]

:<code>Msgbox('Do you really mean that?', 3+32, 'Critical question') →</code>

:::[[File:msgbox3.png|250px]]

:<code>Msgbox('This could be a real problem!', 2+48, 'Critical question') →</code>

:::[[File:msgbox4.png|250px]]

==[http://wiki.analytica.com/index.php?title=Error Error](message)==

Displays an evaluation error in a dialog mentioning the variable whose definition calls this function, showing the '''message''' text:

::Variable Xyz := Error('There seems to be some kind of problem')
::Xyz →

:::[[File:msgbox5.png|300px]]

If you click '''Yes''', it opens the definition of the variable or function whose definition (or Check attribute) calls [http://wiki.analytica.com/index.php?title=Error Error]() in edit mode (if the model is editable). If you click '''No''' or '''Cancel''', it stops evaluation.

===Error in check===

If you call [http://wiki.analytica.com/index.php?title=Error Error]() in a [http://wiki.analytica.com/index.php?title=Check_Attribute check attribute], it shows the error message when the check fails ''instead'' of the default check error message, letting you tailor the message.

==[http://wiki.analytica.com/index.php?title=AskMsgChoice AskMsgChoice](question, ''title, optionList, default, showAll, comboBox'')==

Opens a dialog displaying '''question''' text with a choice drop down control where the user can select an answer from a list. The '''optionList''' parameter is a list or 1-D array of selections, and '''default''' is initial selection. The selected item is returned as the result.

When <code>showAll</code> is <code>true</code>, then an «All» option is also included, and if selected then the entire '''optionList''' is returned. When '''comboBox''' is specified as <code>true</code>, then a combo box control is displayed rather than a choice list. In a combo box, the user is free to enter his own text, but the '''optionList''' provides suggestions.

===Example===

<code>AskMsgChoice("Please rate","Survey",["Loved","Liked", "Neutral", "Disliked", "Hated"])</code>

==[http://wiki.analytica.com/index.php?title=AskMsgNumber AskMsgNumber](question, ''title, default'')==

Displays a dialog showing '''question''' with '''title''', if given. It shows a field for user to enter a number, containing '''default''' number if given. When the user enters a number into the dialog, and clicks '''OK''', it returns the number.

==[http://wiki.analytica.com/index.php?title=AskMsgText AskMsgText](question, ''title, maxText, default, password'')==

Opens a dialog displaying '''question''' text with a field for the user to provide an answer, which it returns as text.

If you specify '''title''' text it displays that in the title bar of the dialog. If you specify '''maxText''' as a number, it will accept only that many characters. If you specify '''default text''', it displays that as the default answer. If you set '''password''' to true, the characters typed are hidden as they are typed.

===Example===

<code>AskMsgText("Enter your model access key", title: "License Entry", maxText: 15)</code>

==[http://wiki.analytica.com/index.php?title=ShowProgressBar ShowProgressBar](title, text, p)==

Displays a dialog with the '''title''' in title bar, a '''text''' message and a progress bar showing fraction <code>p</code> of progress along the bar. The dialog appears the first time you call it with <code>p<1</code>. As long as <code>0<=p<1</code>, it shows a '''Cancel''' button, and continues evaluation. If you click '''Cancel''', it stops further computation, as if the user had pressed ''Control+.'' ('''Control+period'''). If <code>p=1</code>, it shows the '''OK''' button and stops further computation. If you click '''OK''', it closes the dialog. The dialog also closes if called with <code>p>1</code> or when the computation completes.

:::[[File:msgbox6.png|250px]]

===Declaration===

<code>[http://wiki.analytica.com/index.php?title=ShowProgressBar ShowProgressBar](title, text: Text atomic; p: number atomic)</code>

===Example===

In this example:

<code>VAR xOrig := X;</code><br />
<code>VAR result :=</code>
:<code>FOR n[] := @Scenario DO (</code>
::<code>ShowProgressBar("Progress", "Computing Across All Scenarios", (n-1)/Size(Scenario)); </code>
::<code>WhatIf(Y, X, xOrig[@Scenario=n]))</code>
:<code>;</code>
:<code>ShowProgressBar("Progress", "Done", 1);</code>

== See Also ==
* [http://wiki.analytica.com/index.php?title=Category%3AUser-interface_functions User Interface Functions]<br />

<footer>Handles to Objects / {{PAGENAME}} / Other Procedural Functions</footer>

Handles to Objects

2015-12-29T03:43:21Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

A handle is a pointer to a variable, function, module, or other object. Using a handle lets you write variables or functions that work with the object itself, for example to access its attributes — instead of just its value which is what you usually get when you mention a variable by identifier in an expression.

===Viewing handles===
In a table result, a handle in an index or content cell usually shows the title of the object. If you select '''Show by identifier''' from the '''Object''' menu (or press ''Control+y''), it toggles to show identifiers instead of titles (as it does in the node diagrams). If you double-click a cell containing a handle (title or identifier) it opens its '''Object''' window (as it does when you double-click a node in a diagram).

===Attributes that contain handles===
The attributes, '''inputs''', '''outputs''', and '''contains''' (the list of objects in a module) each consist of a list of handles to objects. The attribute isIn is a single handle to the module that contains this object — the inverse of '''contains'''.

==List of variables: [v1, v2, ... vn]==
If you define a variable as a list of variables, for example,

:<code>Variable A := [X, Y, Z]</code>

the variable will have a self index that is a list of handles to those variables. In a table result view of A (or other variable that uses this index), the index A will usually show the titles of the variables. See “List of variables” on page 175 for more. In an expression, the handles in the self index can be accessed using IndexValue(A). The main value of A (either mid value or a probabilistic view of A) contains the results of evaluating X, Y and Z.

== Handle(o) ==
Returns a handle to an Analytica object, given its identifier <code>o</code>.

:<code>Handle(Va1) ¨ Va1</code>

== HandleFromIdentifier(text) ==
Returns a handle to global object (i.e., not a local variable or parameter), given its identifier as <code>text</code>.

:<code>Variable B := 99</code>
:<code>HandleFromIdentifier("B") → Va1</code>

The dependency maintenance is unaware of the dependency on the object. Hence, any changes to the variable <code>B</code> above will not cause the result to recompute.

== ListOfHandles(identifiers...) ==
Returns a list of handles to the specified Analytica objects, given their identifiers.

:<code>ListOfHandles(Va1,Va2,Va3) ¨ [Va1,Va2,Va3]</code>

== Indexes of Handles ==

=== MetaOnly attribute ===
When an index object is defined as a list of identifiers, the MetaOnly attribute controls whether it is treated as a general index or a meta-index. Meta-indexes are useful when reasoning about the structure or contents of the model itself. A general index evaluates the variables appearing in
its definition to obtain its mid or sample value, and the values that are recognized by Subscript (i.e., a[i=x]), while a meta-index (having its metaOnly attribute set to 1) does not evaluate the objects in the list. The following comparisons demonstrates the similarities and differences.

:<code>Constant E:= exp(1)</code>
:<code>Variable X := -1</code>

:{| border="1";
! General Index
! Meta-Index
|-
| style="width:300px;" | Index I0 := [E,X,Pi,True]
| style="width:300px;" | Index I1 := [E,X,Pi,True]
|-
|style="width:300px;" | MetaOnly of I0 := 0 {or not set}
|style="width:300px;" | MetaOnly of I1 := 1
|-
|style="width:300px;" | Variable A0 := Table(I0)(1,2,3,4)
|style="width:300px;" | Variable A1 := Table(I1)(1,2,3,4)
|-
|style="width:300px;" | IndexValue(I0) → [E,X,Pi,True]
|style="width:300px;" |IndexValue(I1) → [E,X,Pi,True]
|-
|style="width:300px;" |Mid(I0) → 2.718,-1,3.142,1]
|style="width:300px;" |Mid(I1) →[E,X,Pi,True]
|-
|style="width:300px;" |A0[I0=Handle(E)] → 1
|style="width:300px;"|A1[I1=Handle(E)] → 1
|-
|style="width:300px;" |A0[I0=Handle(True)] → 4
|style="width:300px;" |A1[I1=Handle(True)] → 4
|-
|style="width:300px;" |A0[I0=E] → 1
|style="width:300px;" |A1[I1=E] → Error:-2.718 not in I1
|-
|style="width:300px;" |A0[I0=-1] → 2
|style="width:300px;" |A1[I1=-1] → Error:-1 not in I1
|-
|style="width:300px;" |A0[I0=True] → 4
|style="width:300px;" |A1[I1=True] → Error:1 not in I1
|}

== MetaIndex..Do ==
The construct, <code>MetaIndex i := indexExpr</code>, declares a local meta-index (see [http://wiki.analytica.com/index.php?title=Local_Indexes Local indexes]). This should generally be used in lieu of the Index <code>i := indexExpr</code> construct when <code>indexExpr</code> evaluates to a list of handles.

:<code>MetaIndex I := contains of Revenue_Module;</code>
:<code>Description of (I)</code>

== IndexesOf(X) ==
Returns the indexes of an array value as a list of handles. The first element of the list is null, rather than a handle, when <code>X</code> has an '''''implicit dimension''''' (also known as a '''''null-index''''').

== Local Variables and Handles ==
When you declare and use local variables that might hold handles, you should declare these local variables using <code>MetaVar..Do or LocalAlias..Do</code>, rather than <code>Var..Do or For..Do</code>. When local variables hold handles, there are two semantic interpretations — the local variable could either be a storage location for a handle to an object, or it could act as an alias to the object. The <code>Meta-Var..Do</code> or <code>LocalAlias..Do</code> declarations makes this distinction clear.

== MetaVar..Do ==
The construct, <code>MetaVar temp := expr</code>, declares a local variable named <code>temp</code> that holds an atomic value or an array of values, some of which might be handles. When the value is a handle, the handle is treated as just another entity, whose datatype happens to be a handle. If you assign another handle or value to temp, you simply change the contents of the local variable, and do not alter the object that the handle points to. Use this construct to manage collections of handles.

:<code>MetaVar hRevModule := Handle(Revenue_module);</code>
:<code>MetaVar hExpModule := Handle(Expense_module);</code>
:<code>MetaIndex m := [hRevModule,hExpModule];</code>
:<code>...</code>

For the next example, suppose a global variable named <code>Hy</code> exists with a definition of <code>Handle(Y)</code>.

:<code>MetaVar a := Handle(X);</code>
:<code>a := Hy</code>

Following the assignment, the local variable <code>a</code> contains a handle to <code>Y</code>. The variable <code>X</code> is unaltered. You should compare this to the same example using <code>LocalAlias..Do</code> in the following section.

When you need to iterate over a collection of handles, you can use, e.g.,

:<code>MetaVar h[ ] := Contains of Revenue_module;</code>

You can assign non-handle values, such as numbers or text, to a local variable declared with <code>MetaVar</code>. When you do so, there is no difference between <code>MetaVar..Do</code> and <code>Var..Do</code>.

== LocalAlias..Do ==
The construct, <code>LocalAlias temp := expr</code>, evaluates <code>expr</code> and declares a local variable named <code>temp</code> that holds a single atomic value. When <code>expr</code> evaluates to a handle, the local variable identifier acts as an exact alias to the object pointed to by the handle.

:<code>LocalAlias r := Handle(Rate_input) Do r := r * 1.1</code>

The preceding expression is functionally identical to<ref>This expression contains a side-effect to a global variable. Side-effects to global variables are only allowed in expressions or user-defined functions that are run directly from button scripts. This would cause an error if attempted from a variable’s definition.</ref>

:<code>Rate_input := Rate_input * 1.1</code>

For the next example, suppose a global variable named <code>Hy</code> exists with a definition of <code>Handle(Y)</code>.

:<code>LocalAlias a := Handle(X)</code>
:<code>a := Hy</code>

This expression is functionally identical to

:<code>X := Hy</code>

The expression, if evaluated in a context where side-effects are permitted, would alter the definition of <code>X</code>. Following the assignment to <code>a</code>, the local variable <code>a</code> continues to be an alias to <code>X</code>. You should compare this to the same example for <code>MetaVar..Do</code> in the preceding section.

When <code>expr</code> is an array of handles, then the body expression is iterated for each alias. The following expression increases the definition of every global variable within an indicated module to a value 1.1 times its initial value.

:<code>LocalAlias x := Contains of Input_module;</code>
:<code>x := x * 1.1</code>

The rule for <code>LocalAlias</code> is that the result for the expressions using <code>temp</code> are identical to what you would get if you replaced every occurrence of <code>temp</code> within those expressions with the identifier for the variable pointed to by the handle, and then evaluated the expressions<ref>Not every object in Analytica lives in the global namespace (e.g., local indexes), so this rule doesn’t literally apply for handles to objects not in the global namespace. For these, we cannot replace the local name with an identifier since no global identifier exists for the object pointed to by the handle.</ref>.

An easy mistake to make when using <code>LocalAlias</code> is to forget that <code>expr</code> is evaluated before the assignment. This feature allows you to compute the handle to the object that will be aliased, but it also means that you need to remember to surround an identifier with a call to <code>Handle()</code> when you
just want a simple alias. If you write

:<code>LocalAlias x := y</code>

then this assigns to <code>x</code> the value of <code>y</code>, not a handle to the object <code>y</code>. If <code>y</code> happens to hold a handle to <code>z</code>, then <code>x</code> becomes an alias to <code>z</code>, not an alias to <code>y</code>. To obtain an alias for <code>y</code>, you must use

:<code>LocalAlias x := Handle(y);</code>

You can assign non-handle values, such as numbers and text, to a <code>LocalAlias</code> variable. When you do so, the local variable identifier serves as an alias for a single value, and is the same as

:<code>Var temp[] := expr;.</code>

== Conversions between MetaVar and LocalAlias ==
When writing expressions that manipulate handles in local variables, you may sometimes need to convert between <code>MetaVar</code> and <code>LocalAlias</code> semantics. When a <code>MetaVar</code> holds a handle, its value is an entity with the data type of handle. Since subtraction is not defined for a handle, the
following expression is an error

:<code>MetaVar hr := Handle(Revenue) Do hr - Expenses { Error }</code>

The expression is attempting to subtract the value of expenses (a number) from a handle. In this example, we need the <code>LocalAlias</code> semantics instead, so given <code>hr</code> we can convert using

:<code>MetaVar hr := Handle(Revenue);</code>
:<code>LocalAlias r := hr;</code>
:<code>r - Expenses</code>

A <code>MetaVar</code> can also be dereferenced by using the [http://wiki.analytica.com/index.php?title=Evaluate Evaluate]() function:

:<code>MetaVar hr := Handle(Revenue) Do Evaluate(hr) - Expenses</code>

In the other direction, when a <code>LocalAlias</code>, <code>r</code>, is an alias for another object and you need the handle to the object, use <code>Handle(r)</code>. It is legal to use the <code>Handle()</code> function on a local variable declared using <code>LocalAlias</code>, but it is an error to apply the <code>Handle()</code> function to a local variable defined using <code>MetaVar</code>. This is because a local variable is not an object (it is just a name for a value), and since handles can only point to objects, there is no such thing as a handle to a local variable<ref>A local index is an object, so you can have a handle to a local index. The '''Index..Do''' and '''MetaIndex..Do''' constructs create an index object, along with a local variable name that has '''LocalAlias''' semantics for the index object.</ref>.

== See Also ==
* [http://wiki.analytica.com/index.php?title=Handle_Functions Handle Functions]
* [http://wiki.analytica.com/index.php?title=Local_Indexes Local indexes]<br />

<footer>References and Data Structures / {{PAGENAME}} / Dialog Functions</footer>

References and Data Structures

2015-12-29T03:41:57Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

A '''reference''' is an indirect link to a value, an atom or an array. A variable can contain a single reference to a value, or it can contain an array of references. Variables and arrays can themselves contain references, nested to any depth. This lets you create complex data structures, such as linked lists, trees, and non-rectangular structures. Use of references is provided by two operators:

* '''\e''' is the '''''reference operation'''''. It creates a reference to the value of expression <code>e</code>.
* '''#e''' is the '''''dereference operation'''''. It obtains the value referred to by e. If e is not a reference, it issues a warning and returns <code>Null</code>.

__TOC__

An example:

:<code>Variable M</code>
:<code>Definition: 100</code>

:<code>Variable Ref_to_M</code>

:<code>Definition: \ M</code>

The result of '''Ref_to_M''' looks like this:

:::[[File:result_ref-to-m.png|300px]]

You can double-click the cell containing «ref» to view the value referenced, in this case:

:::[[File:result_ref-to-m2.png|300px]]

You can also create an array of references. Suppose:

:<code>Index K</code>
:<code>Definition: 1..5</code>

:<code>Variable Ksquare</code>
:<code>Definition: K^2</code>

:<code>Ksquare →</code>

:::[[File:result-ksquare.png|250px]]

:<code>Variable Ref_to_Ksquare</code>
:<code>Definition: \ Ksquare</code>

:<code>Ref_to_Ksquare →</code>

:::[[File:result_ref_ksquare.png|250px]]

If you click the «ref» cell, it opens:

:::[[File:result_ref_ksquare2.png|250px]]

You can also create an array of references from an array, for example:

:<code>Variable Ref_Ksquare_array</code>
:<code>Definition: \ [] Ksquare</code>
:<code>Ksquare →</code>

The empty square brackets [ ] specify that the values referred to have no indexes, i.e., they are atoms. You can now click any of these cells to see what it refers to.

:::[[File:result_ref_ksquare_array.png|300px]]

Clicking the third cell, for example, gives:

:::[[File:result_ref_ksquare_array2.png|300px]]

==Managing indexes of referenced subarrays: \[i, j,...] e==

More generally, you can list in the square brackets any indexes of <code>e</code> that you want to be indexes of each subarray referenced by the result. The other indexes of <code>e</code> (if any) are used as indexes for the referencing array. Thus, in the example above, since there were no indexes in square brackets, the index <code>K</code> was used as an index of the reference array. If instead we write:

:<code>\ [K] Ksquare →</code>

:::[[File:result_ref_ksquare_array3.png|250px]]

It creates a similar result to <code>\ Ksquare</code>, since <code>K</code> is the only index of <code>Ksquare</code>.

To summarize:

:{| class="wikitable"
|-
|<code>\ e</code>
|Creates a reference to the value of expression <code>e</code>, whether it is an atom or an array.
|-
|<code>\ [] e</code>
|Creates an array indexed by all indexes of <code>e</code> containing references to all atoms from <code>e</code>.
|-
|<code>\ [i] e</code>
|Creates an array indexed by any indexes of <code>e</code> other than <code>i</code> of references to subarrays of <code>e</code> each indexed by <code>i</code>.
|-
|<code>\ [i, j…] e</code>
|Creates an array indexed by any indexes of <code>e</code> other than <code>i, j …</code> of references to subarrays of <code>e</code> each indexed by <code>i, j ….</code>
|}

In general, it is better to include the square brackets after the reference operator, and avoid the unadorned reference operator, as in the first row of the table. Being explicit about which indexes to include generally leads to expressions that array abstract as intended.

==IsReference(x)==

This Is a test to see whether its parameter x is a reference. It returns True (1) if x is a reference, False (0) otherwise.

==Using references for linked lists: Example functions==

Linked lists are a common way for programmers to represent an ordered set of items. They are more efficient than arrays when you want often to add or remove items, thereby changing the length of the list (which is more time consuming for arrays). In Analytica, we can represent a linked list as an element with two elements, the item — that is, a reference to the value of the item — and a link — that is, a reference, to the next item:

:<code>Index Linked_list</code>
:<code>Definition: ['Item', 'Link']</code>

:<code>Function LL_Put(x, LL)</code>
:<code>Description: Puts item x onto linked list LL.</code>
:<code>Definition: \Array(Linked_List, [\x, LL])</code>

:<code>Function LL_Get_Item(LL)</code>
:<code>Description: Gets the value of the first item from linked list LL.</code>
:<code>Definition: # Subscript(#LL, Linked_list, 'Item')</code>

:<code>Function LL_length(LL)</code>
:<code>Parameters: (LL: Atom)</code>
:<code>Description: Returns the number of items in linked list LL</code>
:<code>Definition: VAR len := 0;</code>
::WHILE (IsReference(LL)) BEGIN</code>
:::<code>LL := subscript(#LL, Linked_List, "Next");</code>
:::<code>len := len + 1</code>
::<code>END;</code>
::<code>len</code>

:<code>Function LL_from_array(a, i)</code>
:<code>Parameters: (a; i: Index)</code>
:<code>Description: Creates a linked list from the elements of array a over index i</code>
:<code>Definition:</code>
::<code>VAR LL := NULL;</code>
::<code>Index iRev := Size(i) .. 1;</code>
::<code>FOR j := iRev</code>
:::<code>DO LL := LL_Push(LL, Slice(a, i, j));</code>
::<code>LL</code>

See '''Linked List Library.ana''' in the '''Libraries''' folder for these and other functions for working with linked lists.

== See Also ==
* [http://wiki.analytica.com/index.php?title=Analytica_Libraries_and_Templates#Linked_Lists Linked Lists]
* [http://wiki.analytica.com/index.php?title=Using_References Using References]<br />

<footer>Ensuring Array Abstraction / {{PAGENAME}} / Handles to Objects</footer>
__FORCETOC__

Ensuring Array Abstraction

2015-12-29T03:40:29Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

The vast majority of the elements of the Analytica language (operators, functions, and control constructs) fully support Intelligent Arrays — that is, they can handle operands or parameters that are arrays with any number of indexes, and generate a result with the appropriate dimensions. Thus, most models automatically obtain the benefits of array abstraction with no special care.

There are just a few elements that do not inherently enable Intelligent Arrays — i.e., support array abstraction. They fall into these main types:

* '''Functions whose parameters must be atoms''' (not arrays), including [http://wiki.analytica.com/index.php?title=Sequence Sequence], m..n, and [http://wiki.analytica.com/index.php?title=SplitText SplitText]. See below.
* Functions whose parameter must be a vector (an array with just one index), such as [http://wiki.analytica.com/index.php?title=CopyIndex CopyIndex], [http://wiki.analytica.com/index.php?title=SortIndex SortIndex], [http://wiki.analytica.com/index.php?title=Subset Subset], [http://wiki.analytica.com/index.php?title=Unique Unique], and [http://wiki.analytica.com/index.php?title=Concat Concat] when called with two parameters.
* The [http://wiki.analytica.com/index.php?title=For_and_While_Loops#While.28Test.29_Do_Body While loop], which requires its termination condition to be an atom.
* If [http://wiki.analytica.com/index.php?title=Ensuring_Array_Abstraction#If_a_Then_b_Else_c_and_array_abstraction b Then c Else d], when condition <code>b</code> is an array, and <code>c</code> or <code>d</code> can give an evaluation error.
* Functions with an optional index parameter that is '''[http://wiki.analytica.com/index.php?title=Ensuring_Array_Abstraction#Omitted_index_parameters_and_array_abstraction omitted]''', such as [http://wiki.analytica.com/index.php?title=Sum Sum](x), [http://wiki.analytica.com/index.php?title=Product Product], [http://wiki.analytica.com/index.php?title=Functions_Min_and_Max Max], [http://wiki.analytica.com/index.php?title=Functions_Min_and_Max Min], [http://wiki.analytica.com/index.php?title=Average Average], [http://wiki.analytica.com/index.php?title=ArgMin_and_ArgMax Argmax], [http://wiki.analytica.com/index.php?title=SubIndex SubIndex], [http://wiki.analytica.com/index.php?title=ChanceDist ChanceDist], [http://wiki.analytica.com/index.php?title=CumDist CumDist], and [http://wiki.analytica.com/index.php?title=ProbDist ProbDist].<br />

When using these constructs, you must take special care to ensure that your model is fully arrayabstractable. Here we explain how to do this for each of these five types.

==Functions Expecting Atomic Parameters==

Consider this example:

:<code>Variable N := 1..3</code>
:<code>Variable B := 1..N</code>
:<code>B → Evaluation error:</code>
:<code>One or both parameters to Sequence(m, n) or m .. n are not scalars.</code>

The expression <code>1..N</code>, or equivalently, [http://wiki.analytica.com/index.php?title=Sequence <code>Sequence</code>]<code>(1, N)</code>, cannot work if <code>N</code> is an array, because it would have to create a nonrectangular array containing slices with 1, 2, and 3 elements. Analytica does not allow nonrectangular arrays, and so requires the parameters of [http://wiki.analytica.com/index.php?title=Sequence Sequence] to be atoms (single elements).

Most functions and expressions that, like [http://wiki.analytica.com/index.php?title=Sequence Sequence], are used to generate the definition of an index require atomic (or in some cases, vector) parameters, and so are not fully array abstractable. These include [http://wiki.analytica.com/index.php?title=Sequence Sequence], [http://wiki.analytica.com/index.php?title=Subset Subset], [http://wiki.analytica.com/index.php?title=SplitText SplitText], [http://wiki.analytica.com/index.php?title=SortIndex SortIndex] (if the second parameter is omitted), [http://wiki.analytica.com/index.php?title=Concat Concat], [http://wiki.analytica.com/index.php?title=CopyIndex CopyIndex], and [http://wiki.analytica.com/index.php?title=Unique Unique].

Why would you want array abstraction using such a function? Consider this approach to writing a function to compute a factorial:

:<code>Function Factorial2</code>
:<code>Parameters: (n)</code>
:<code>Definition: Product(1..n)</code>

It works if <code>n</code> is an atom, but not if it is an array, because <code>1..n</code> requires atom operands. In this version, however, using a '''For''' loop works fine:

:<code>Function Factorial3</code>
:<code>Parameters: (n)</code>
:<code>Definition: FOR m := n DO Product(1..m)</code>

The '''For''' loop repeats with the loop variable <code>m</code> set to each atom of <code>n</code>, and evaluates the body <code>Product(1..m)</code> for each value. Because <code>m</code> is guaranteed to be an atom, this works fine. The '''For''' loop reassembles the result of each evaluation of <code>Product(1..m)</code> to create an array with all the same dimensions as <code>n</code>.

==Atom parameters and array abstraction==

Another way to ensure array abstraction in a function is to use the '''Atom''' qualifier for its parameter( s). When you qualify a parameter <code>n</code> as an Atom, you are saying that it must be a single value — not an array — when the function is evaluated, but not when the function is used:

:<code>Function Factorial3</code>
:<code>Parameters: (n: Atom)</code>
:<code>Definition: Product(1..n)</code>

::[[File:factorial3.png|400px]]

:<code>Index K := 1 .. 6</code>
:<code>Factorial3(K) →</code>

::[[File:result-result.png|400px]]

Notice that '''Atom''' does not require the actual parameter <code>K</code> to be an atom when the function is called. If <code>K</code> is an array, as in this case, it repeatedly evaluates the function <code>Factorial3(n)</code> with <code>n</code> set to each atom of array <code>K</code>. It then reassembles the results back into an array with the same indexes as parameter K, like the '''For''' loop above. This scheme works fine even if you qualify several parameters of the function as '''Atom'''.

In some cases, a function might require a parameter to be an vector (have only one index), or have multiple dimensions with specified indexes. You can use [[Array Qualifiers|Array qualifiers]] to specify this. With this approach, you can ensure your function array abstracts when new dimensions are added to your model, or if parameters are probabilistic.

==While and array abstraction==

The <code>While b Do e</code> construct requires its termination condition <code>b</code> to evaluate to be an atom — that is, a single Boolean value, <code>True (1)</code> or <code>False (0)</code>. Otherwise, it would be ambiguous about whether to continue. Again, '''Atom''' is useful to ensure that a function using a '''While''' loop array abstracts, as it was for the [http://wiki.analytica.com/index.php?title=Sequence Sequence] function. Here’s a way to write a [http://wiki.analytica.com/index.php?title=Factorial Factorial] function using a While loop:

:<code>Function Factorial4</code>
:<code>Parameters: (n: Atom)</code>
:<code>Definition:</code>
::<code>VAR fact := 1; VAR a := 1;</code>
::<code>WHILE a < n DO (a := a + 1; fact := fact * a)</code>

In this example, the '''Atom''' qualifier assures that <code>n</code> and hence the '''While''' termination condition <code>a < n</code> is an atom during each evaluation of '''Factorial4'''.

==If a Then b Else c and array abstraction==

Consider this example:

:<code>Variable X := -2..2</code>
:<code>Sqrt(X) → [NAN, NAN, 0, 1, 1.414]</code>

The square root of negative numbers -2 and -1 returns '''NAN''' (not a number) after issuing a warning. Now consider the definition of '''Y''':

:<code>Variable Y := (IF X>0 THEN Sqrt(X) ELSE 0)</code>
:<code>Y → [0, 0, 0, 1 1.414]</code>

For the construct IF a THEN b ELSE c, <code>a</code> is an array of truth values, as in this case, so it evaluates both <code>b</code> and <code>c</code>. It returns the corresponding elements of <code>b</code> or <code>c</code>, according to the value of condition <code>a</code> for each index value. Thus, it still ends up evaluating [http://wiki.analytica.com/index.php?title=Sqrt Sqrt](X) even for negative values of <code>X</code>. In this case, it returns <code>0</code> for those values, rather than '''NAN''', and so it does not generate an error message.

A similar problem remains with text processing functions that require a parameter to be a text value. Consider this array:

:<code>Variable Z := [1000, '10,000', '100,000']</code>

This kind of array containing true numbers, e.g., 1000, and numbers with commas turned into text values, often arises when copying arrays of numbers from spreadsheets. The following function would seem helpful to remove the commas and convert the text values into numbers:

:<code>Function RemoveCommas(t)</code>
:<code>Parameters: (t)</code>
:<code>Definition: Evaluate(TextReplace(t, ',', ''))''</code>
:<code>RemoveCommas(Z) →</code>
:<code>Evaluation Error: The parameter of Pluginfunction TextReplace must be a text while evaluating function RemoveCommas.</code>

[http://wiki.analytica.com/index.php?title=TextReplace TextReplace] doesn’t like the first value of <code>z</code>, which is a number, where it’s expecting a text value. What if we test if <code>t</code> is text and only applies [http://wiki.analytica.com/index.php?title=TextReplace TextReplace] when it is?

:<code>Function RemoveCommas(t)</code>
:<code>Parameters: (t)</code>
:<code>Definition: IF IsText(t)
::THEN Evaluate(TextReplace(t, ',', '')) ELSE t''</code>
:<code>RemoveCommas(Z) → (same error message)</code>

It still doesn’t work because the '''IF''' construct still applies ReplaceText to all elements of <code>t</code>. Now, let’s add the parameter qualifier '''Atom''' to <code>t</code>:

:<code>Function RemoveCommas(t)</code>
:<code>Parameters: (t: Atom)</code>
:<code>Definition: IF IsText(t)</code>
::<code>THEN Evaluate(TextReplace(t, ',', '')) ELSE t''</code>
:<code>RemoveCommas(Z) →</code>

:::[[File:result3.png|200px]]

This works fine because the '''Atom''' qualifier means that '''<code>RemoveCommas</code>''' breaks its parameter <code>t</code> down into atomic elements before evaluating the function. During each evaluation of <code>Remove-Commas</code>, <code>t</code>, and hence [http://wiki.analytica.com/index.php?title=Data_Type_Functions#Function_IsText IsText](t), is atomic, either True or False. When False, the '''If''' construct evaluates the '''Else''' part but not the '''Then''' part, and so calls [http://wiki.analytica.com/index.php?title=TextReplace TextReplace] when t is truly a text value. After calling [http://wiki.analytica.com/index.php?title=TextReplace TextReplace] separately for each element, it reassembles the results into the array shown above with the same index as <code>Z</code>.

==Omitted index parameters and array abstraction==

Several functions have index parameters that are optional, including [http://wiki.analytica.com/index.php?title=Sum Sum], [http://wiki.analytica.com/index.php?title=Product Product], [http://wiki.analytica.com/index.php?title=Functions_Min_and_Max Max], [http://wiki.analytica.com/index.php?title=Functions_Min_and_Max Min], [http://wiki.analytica.com/index.php?title=Average Average], [http://wiki.analytica.com/index.php?title=ArgMin_and_ArgMax Argmax], [http://wiki.analytica.com/index.php?title=SubIndex SubIndex], [http://wiki.analytica.com/index.php?title=ChanceDist ChanceDist], [http://wiki.analytica.com/index.php?title=CumDist CumDist,] and [http://wiki.analytica.com/index.php?title=ProbDist ProbDist]. For example, with [http://wiki.analytica.com/index.php?title=Sum Sum](x, i), you can omit index <code>i</code>, and call it as [http://wiki.analytica.com/index.php?title=Sum Sum](x). But, if <code>x</code> has more than one index, it is hard to predict which index it sums over. Even if <code>x</code> has only one dimension now, you might add other dimensions later, for example for parametric analysis. This ambiguity makes the use of functions with omitted index parameters non-array abstractable.

There is a simple way to avoid this problem and maintain reliable array abstraction: '''''When using functions with optional index parameters, never omit the index!''''' Almost always, you know what you want to sum over, so mention it explicitly. If you add dimensions later, you’ll be glad you did.

<Tip Title="Tip"> When the optional index parameter is omitted, and the parameter has more than one dimension, these functions choose the '''''outer index''''', by default. Usually, the outer index is the index created most recently when the model was built. But, this is often not obvious. We designed Intelligent Arrays specifically to shield you from having to worry about this detail of the internal representation.</Tip>

==Selecting indexes for iterating with For and Var==

To provide detailed control over array abstraction, the '''For''' loop can specify exactly which indexes to use in the iterator <code>x</code>. The old edition of '''For''' still works. It requires that the expression <code>a</code> assigned to iterator <code>x</code> generate an index — that is, it must be a defined index variable, [http://wiki.analytica.com/index.php?title=Sequence Sequence](m, n), or m..n. The new forms of '''For''' are more flexible. They work for any array (or even atomic) value <code>a</code>. The loop iterates by assigning to x successive subarrays of <code>a</code>, dimensioned by the indexes listed in square brackets. If the square brackets are empty, as in the second line of the table, the successive values of iterator <code>x</code> are atoms. In the other cases, the indexes mentioned specify the dimensions of <code>x</code> to be used in each evaluation of <code>e</code>. In all cases, the final result of executing the '''For''' loop is a value with the same dimensions as <code>a</code>.

:{| class="wikitable"
|-
|'''For x := a DO e'''
|Assigns to loop variable <code>x</code> successive atoms from index expression <code>a</code> and repeats evaluation expression <code>e</code> for each value. Returns an array of values of <code>e</code> indexed by <code>a</code>.
|-
|'''For x := a DO e'''
'''For x[] := a DO e|D'''
|Assigns to loop variable <code>x</code>, successive atomic values from array <code>a</code>. It repeats evaluation of expression <code>e</code> for each value. It returns an array of values of <code>e</code> with the same indexes as <code>a</code>.
|-
|'''For x[i] := a DO e'''
|Assigns to loop variable <code>x</code> successive subarrays from array <code>a</code>, each indexed only by <code>i</code>. It repeats evaluation of expression <code>e</code> for each index value of <code>a</code> other than <code>i</code>. As before, the result has the same indexes as <code>a</code>.
|-
|'''For x[i, j …] := a DO e'''
|Assigns to loop variable <code>x</code> successive subarrays from array <code>a</code>, each indexed only by <code>i, j ….</code> It repeats evaluation of expression <code>e</code> for each index value of <code>a</code> other than <code>i, j ….</code> . As before, the result has the same indexes as <code>a</code>.
|}

The same approach also works using '''Var''' to define local variables. By putting square brackets listing indexes after the new variable, you can specify the exact dimensions of the variable. These indexes should be a subset (none, one, some, or all) of the indexes of the assigned value <code>a</code>. Any subsequent expressions in the context are automatically repeated as each subarray is assigned to the local variable. In this way, a local variable can act as an implicit iterator, like the '''For''' loop.

:<code>Var Temp[i1, i2, ...] := X;</code>

<footer>Local Indexes / {{PAGENAME}} / References and Data Structures</footer>

Local Indexes

2015-12-29T03:39:40Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

[[category:Concepts]]
[[Category:Doc Status C]] 

You can declare a local index in the definition of a variable or function. It is possible that the value of the variable or value returned by the function is an array using this index. This is handy because it lets you define a variable or function that creates an array without relying on an externally defined index.

The construct, <code>Index i := indexExpr</code> defines an index local to the definition in which it is used. The expression <code>indexExpr</code> can be a sequence, literal list, or other expression that generates an unindexed array, as used to define a global index. For example:

:<code>Variable PowersOf2 := Index j := 0..5; 2^j</code>

The new variable <code>PowersOf2</code> is an array of powers of two, indexed by the local index <code>j</code>, with values from 0 to 5:

:<code>PowersOf2 →</code>

[[File:result-powersof2.png|200px]]

==Dot operator: a . i==

The dot operator in <code>a . i</code> lets you access a local index <code>i</code> via an array <code>a</code> that it dimensions. If a local index identifies a dimension of an array that becomes the value of a global variable, it can persist long after evaluation of the expression — unlike other local variables which disappear after the expression is evaluated.

Even though local index <code>j</code> has no global identifier, you can access it via its parent variable with the dot operator (<code>.</code>), for example:

:<code>PowersOf2.j → [0,1,2,3,4,5]</code>

When using the subscript operation on a variable with a local index, you need to include the dot (<code>.</code>) operator, but do not need to repeat the name of the variable:

:<code>PowersOf2[.j=5] → 32</code>

Any other variables depending on <code>PowersOf2</code> can inherit <code>j</code> as a local index — for example:

:<code>Variable P2 := PowersOf2/2</code>

:<code>P2[.j=5] → 16</code>

== Example using a local index ==
In this example, <code>MatSqr</code> is a user-defined function that returns the square of a matrix — i.e., <code>A</code> x <code>A'</code>, where <code>A'</code> is the transpose of <code>A</code>. The result is a square matrix. Rather than require a third index as a parameter, <code>MatSqr</code> creates the local index, <code>i2</code>, as a copy of index <code>i</code>.

:<code>Function MatSqr(a: Array; i, j: Index)</code>
:<code>Definition := Index i2:=CopyIndex(i); Sum(a*a[i=i2], j)</code>

The local variable, <code>i2</code>, in <code>MatSqr</code> is not within lexical scope in the definition of <code>Z</code>, so we must use the dot operator (<code>.</code>) to access this dimension. In the example below, we <u>underline</u> the dot operator for clarity:

:<code>Variable Z := Var XX := MatSqr(X, Rows, Cols);</code>
::<code>Sum(XX * Y[I=XX<u>.</u>i2], XX<u>.</u>i2)</code>

Analytica's arrays are, in general, multi-dimensional, where each dimension is identified with an Index. An Index is an Analytica object with a list of [[IndexValue]]s. Indexes in Analytica come in three varieties:

:''Global Indexes'': These appear as parallelagrams on a diagram. (e.g., [[image:IndexNode.jpg]] )
:''[[Self-Indexed Arrays|Self Indexes]]'': A variable whose that can serve as an index, but also has a value.
:''Local Indexes'': Index objects that do not exist in the global namespace.

Local indexes may be temporary, disappearing after they fall out of lexical context, or they may continue to exist outside of the lexical context where they were declared if an array indexed by the local index is returned.

Local indexes are declared within expressions via the [[Index..Do]] declaration, as in this example:

[[Index..Do|Index]] X := [[Sequence]](x1,x2,(x2-x1)/1000) Do ArgMax( f(X^2), X )

In the above example, the identifier X exists as a local variable only within the body of the Do clause, and refers to the index defined as a sequence with 1000 points ranging from x1 to x2. ArgMax finds the maximum of f(X^2) and returns a single value, after which the index X ceases to exist.

Syntactically, an index can also be written using this syntax:

Index X := [[Sequence]](x1,x2,(x2-x1)/1000);
[[ArgMax]]( f(X^2), X )

Here the local variable X is recognized to the end of the current lexical context.

It is possible for an expression to return an array that is indexed by a local index. When this happens, the local index continues to exist, although no local variable or identifier refers to it directly. This happens, for example, in the following expression:

Index Bit := 7..0;
[[Mod]]( [[Floor]](N/2^Bit),2 )

which returns the following when N:=137:
{| border="1"
! .Bit → !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| || 1 || 0 || 0 || 0 || 1 || 0 || 0 || 1
|}

After this expression is evaluated, the local variable Bit no longer exists, but a 1-D array indexed by .Bit does exist. The only way to access this local index is through the array result. Suppose BinaryN is defined by the expression above. The syntax BinaryN.Bit identifies the index. So, for example, to count the number of bits:

[[Sum]]( BinaryN, BinaryN.Bit ) → 3

where the second parameter to [[Sum]] expects an index.

To access the 3rd bit of BinaryN (counting from 0), we could write
BinaryN[ BinaryN.Bit = 3 ]
or we can abbreviate in this case as
BinaryN[ .Bit = 3 ]
since it is clear that .Bit is refering to an index of BinaryN. This abbreviation is only possible within the [[Subscript/Slice Operator]], not in other contexts.

It is theoretically possible to create an array with more than one local index having the same name. In this case, the [[A.I]] syntax is ambiguous, and one index is identified.

Within an expression, if you have an array containing a local index, it is possible to define a local variable as an alias to refer to this index in order to avoid having to type, e.g., BinaryN.Bit every time. This is done using the [[Var..Do]] declaration, not the [[Index..Do]], since the Index..Do construct would create an entirely new index object, and is done as follows:

[[Var..Do|Var]] I := [[VarTerm]]( BinaryN.Bit, asIndex:True ) Do expr

where inside expr, the local variable I is an alias for the actual index object. Note that the local name used in expr does not have to be the same as the local index's object name. The optional asIndex parameter of VarTerm is not actually needed in the example here, but can optionally be included for clarity (it is necessary if you want to alias a [[Self-Indexed Arrays|self-index]], as opposed to aliasing the object having a self-index). As a full example, the following expression bit-shifts the complement of BinaryN (divides the complement by 2), note how using I as an alias for BinaryN.Bit helps with conciseness within the expression:

[[Var..Do|Var]] I := [[VarTerm]]( BinaryN.Bit ) Do
[[Index Position Operator::@|@I]]=1 [[Or]] ([[Not]] BinaryN)[@I=@I-1]

{| border="1"
! .Bit → !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| || 1 || 0 || 1 || 1 || 1 || 0 || 1 || 1
|}

The numeric equivalent is computed by

[[Var..Do|Var]] I := [[VarTerm]]( BinaryN.Bit ) Do
[[Sum]](2^I * ([[Index Position Operator::@|@I]]=1 [[Or]] ([[Not]] BinaryN)[@I=@I-1]), I )

which returns 187.

<footer>Recursion / {{PAGENAME}} / Ensuring Array Abstraction</footer>

Recursion

2015-12-29T03:39:04Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

A '''''recursive''''' function is a function that calls itself within its definition. This is often a convenient way to define a function, and sometimes the only way. As an example, consider this definition of factorial:

:<code>Function Factorial2(n: Positive Atom)</code>
:<code>Definition: IF n > 1 THEN N*Factorial2(n-1) ELSE 1</code>

If its parameter, <code>n</code>, is greater than 1, <code>Factorial2</code> calls itself with the actual parameter value <code>n-1</code>. Otherwise, it simply returns 1. Like any normal recursive function, it has a termination condition under which the recursion stops — when <code>n <= 1</code>.

<Tip Title="Tip"> The built-in function Factorial does the same, and is fully abstractable, to boot. We define Factorial2 here as a simple example to demonstrate key ideas.</Tip >

Normally, if you try to use a function in its own definition, it complains about a cyclic dependency loop. To enable recursion, you must display and set the '''Recursive''' attribute:

# Select '''Attributes''' from the '''Object''' menu.<br />

::[[File:procedure_attributes.png|200px]]<br />

<ol start="2"><li>Select '''Functions''' from the '''Class''' menu.</li></ol>
<ol start="3"><li>Scroll down the list of attributes and click '''Recursive''' twice, so that it shows √, meaning that the recursive attribute is displayed for each function in its '''Object''' window and the '''Attribute''' panel.</li></ol>
<ol start="4"><li>Check '''OK''' to close '''Attributes''' dialog.</li></ol><br />

For each function for which you wish to enable recursion:<br />

<ol start="5"><li>Open the '''Object Window''' for the function by double-clicking its node (or selecting the node and clicking the '''Object''' button).</li></ol>
<ol start="6"><li>Type '''<code>1</code>''' into its '''Recursive''' field.</li></ol><br />

::[[File:factorial2.png|400px]]<br />

As another example, consider this recursive function to compute a list of the prime factors of an integer, <code>x</code>, equal to or greater than <code>y</code>:

:<code>Function Prime_factors(x, y: Positive Atom)</code>
:<code>Definition:</code>
::<code>Var n := Floor(x/y);</code>
::<code>IF n<y THEN [x]</code>
::<code>ELSE IF x = n*y THEN Concat([y], Factors(n, y))</code>
::<code>ELSE Prime_factors(x, y+1)</code>
::<code>Factors(60, 2) → [2, 2, 3, 5]</code>

In essence, <code>Prime_factors</code> says to compute <code>n</code> as <code>x</code> divided by <code>y</code>, rounded down. If <code>y</code> is greater than <code>n</code>, then <code>x</code> is the last factor, so return <code>x</code> as a list. If <code>x</code> is an exact factor of <code>y</code>, then concatenate <code>x</code> with any factors of <code>n</code>, equal or greater than <code>n</code>. Otherwise, try <code>y+1</code> as a factor.

<Tip Title="Tip">To prevent accidental infinite recursion, it stops and gives a warning if the stack reaches a depth
of 256 function calls.</Tip >

<footer>For and while Loops / {{PAGENAME}} / Local Indexes</footer>

For and While Loops

2015-12-29T03:36:19Z

Jhernandez3: /* See Also */

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

== For i := a Do expr ==

The '''For''' loop successively assigns the next atom from array <code>a</code> to local index <code>i</code>, and evaluates expression <code>expr</code>. <code>expr</code> might refer to <code>i</code>, for xample to slice out a particular element of an array. <code>a</code> might be a list of values defined by <code>m..n</code> or <code>Sequence(m, n, dx)</code> or it might be a multidimensional array. Normally, it evaluates the body <code>expr</code> once for each atom in <code>a</code>.

The result of the '''For '''loop is an array with all the indexes of <code>a</code> containing the values of each evaluation of <code>expr</code>. If any or all evaluations of <code>expr</code> have any additional index(es), they are also indexes of the result.

Usually, the Intelligent Array features take care of iterating over indexes of arrays without the need for explicit looping.

<Tip Title="Tip> Analytica’s Intelligent Array features means that you rarely need explicit iteration using '''For''' loops to repeat operations over each dimensions of an array, often used in conventional computer language. If you find yourself using '''For''' loops a lot in Analytica, this might be a sign that you are not using '''Intelligent Arrays''' effectively. If so, please (re)read the sections on [[Intelligent_Arrays|Intelligent Arrays]].</Tip>

A '''For''' loop is sometimes useful in these specialized cases:

* To avoid selected evaluations of <code>expr</code> that might be invalid or out of range, and can be prevented by nesting an <code>If-Then-Else</code> inside a '''For'''.
* To apply an Analytica function that requires an atom or one- or two-dimensional array input to a higher-dimensioned array.
* To reduce the memory needed f or calculations with very large arrays by reducing the memory requirement for intermediate results.<br />

See below for an example of each of these three cases.

==== Library ====
Special

====Avoiding out-of-range errors====

Consider the following expression:

:<code>If x<0 Then 0 Else Sqrt(x)</code>

The <code>If-Then-Else</code> is included in this expression to avoid the warning “Square root of a negative number.” However, if <code>x</code> is an array of values, this expression cannot avoid the warning since [http://wiki.analytica.com/index.php?title=Sqrt Sqrt](x) is evaluated before <code>If-Then-Else</code> selects which elements of [http://wiki.analytica.com/index.php?title=Sqrt Sqrt](x) to include. To avoid the warning (assuming <code>x</code> is indexed by <code>i</code>), the expression can be rewritten as:

:<code>For j:=I do</code>

::<code>If x[i=j]<0 then 0 else Sqrt(x[i=j])</code>

Or as (see next section):

:<code>Using y:=x in i do</code>

::<code>If y<0 Then 0 else Sqrt(y)</code>

Situations like this can often occur during slicing operations. For example, to shift <code>x</code> one position to the right along <code>i</code>, the following expression would encounter an error:

:<code>if i<2 then x[i=1] else x[i=i-1]</code>

The error occurs when <code>x[i=i-1]</code> is evaluated since the value corresponding to <code>i-1=0</code> is out of range. The avoid the error, the expression can be rewritten as:

:<code>For j:=i do
::If j<2 then x[i=1] else x[i=j-1]</code>

Out-of-range errors can also be avoided without using '''For''' by placing the conditional inside an argument. For example, the two examples above can be written without '''For''' as follows:

:<code>Sqrt(if x<0 then 0 else x)</code>

:<code>x[i=(if i<2 then 1 else i-1)]</code>

===== Dimensionality reduction =====
'''For''' can be used to apply a function that requires an atom, one- or two- dimensional input to a multi-dimensional result. This usage is rare in Analytica since array abstraction normally does this automatically; however, the need occasionally arises in some circumstances.

Suppose you have an array <code>A</code> indexed by <code>I</code>, and you wish to apply a function <code>f(x)</code> to each element of <code>A</code> along <code>I</code>. In a conventional programming language, this would require a loop over the elements of <code>A</code>; however, in almost all cases, Analytica’s array abstraction does this automatically — the expression is simply <code>f(A)</code>, and the result remains indexed by <code>i</code>. However, there are a few cases where Analytica does not automatically array abstract, or it is possible to write a user-defined function that does not automatically array abstract (e.g., by declaring a parameter to be of type <code>Atom</code>, as detailed in [[Parameter Qualifiers]]). For example, Analytica does not array abstract over functions such as [http://wiki.analytica.com/index.php?title=Sequence Sequence], [http://wiki.analytica.com/index.php?title=Split Split], [http://wiki.analytica.com/index.php?title=Subset Subset], or [http://wiki.analytica.com/index.php?title=Unique Unique], since these return un-indexed lists of varying lengths that are unknown until the function evaluates. Suppose we have the following variables defined (note that <code>A</code> is an array of text values):

:A: Index_1 ▼
:{| class="wikitable"
|-
! <font color="#FFFFFF">1</font>
!
|-
!1
|A, B, C
|-
!2
|D, E, F
|-
!3
|G, H, I
|}

:Index_1 ▼
:{| class="wikitable"
|-
|1
|2
|3
|}

We wish to split the text values in A and obtain a two dimensional array of letters indexed by Index_1 and Index_2. Since Split does not array abstract, we must do each row separately and re-index by Index_2 before the result rows are recombined into a single array. This is accomplished by the following loop:

:<code>FOR Row := Index_1 DO Array(Index_2, SplitText(A[Index_1=Row], ','))</code>

This results in:

:Index_1 ▼, Index_2 ▶

:{| class="wikitable"
|-
!
! 1
! 2
! 3
|-
! 1
|A
|B
|C
|-
! style="width:100px;" |2
|style="width:100px;" |D
|style="width:100px;" |E
|style="width:100px;" |F
|-
! style="width:100px;" |3
|style="width:100px;" |G
|style="width:100px;" |H
|style="width:100px;" |I
|}

===Reducing memory requirements===

In some cases, it is possible to reduce the amount of memory required for intermediate results during the evaluation of expressions involving large arrays. For example, consider the following expression:

<code>MatrixA:</code> A two dimensional array indexed by M and N.

<code>MatrixB:</code> A two dimensional array indexed by N and P.

:<code>Average(MatrixA * MatrixB, N)</code>

During the calculation, Analytica needs memory to compute <code>MatrixA * MatrixB</code>, an array indexed by <code>M</code>, <code>N</code>, and <code>P</code>. If these indexes have sizes 100, 200, and 300 respectively, then <code>MatrixA * MatrixB</code> contains 6,000,000 numbers, requiring over 60 megabytes of memory at 10
bytes per number.

To reduce the memory required, use the following expression instead:

:<code>For L := M Do Average(MatrixA[M=L]*MatrixB, N)</code>

Each element <code>MatrixA[M=L]*MatrixB</code> has dimensions <code>N</code> and <code>P</code>, needing only 200x300x10= 600 kilobytes of memory at a time.

<tip title="Tip">For the special case of a [[Matrix_functions#Dot_product_of_two_matrices|dot product]], for an expression of the form <code>Sum(a*b, i)</code>, it performs a similar transformation internally.</tip>

===While(Test) Do Body===

<code>While</code> evaluates <code>Body</code> repeatedly as long as <code>Test <> 0</code>. For <code>While ...</code> to terminate, <code>Body</code> must produce a side-effect on a local variable that is used by <code>Test</code>, causing <code>Test</code> eventually to equal <code>0</code>. If <code>Test</code> never becomes False, <code>While</code> continues to loop indefinitely. If you suspect that might be happening, type ''Control+. (Control+period)'' to interrupt execution.

<code>Test</code> must evaluate to an atomic (non-array) value; therefore, it is a good idea to force any local variable used in <code>Test</code> to be atomic valued. <code>While</code> is one of the few constructs in Analytica that does not generalize completely to handle arrays. But, there are ways to ensure that variables and functions using <code>While</code> support Intelligent Arrays and probabilistic evaluation. See “While and
array abstraction” on page 386 for details.

<code>While</code> returns the final value found in the last iteration of <code>Body</code> or <code>Null</code> if no iterations occur. For example:

:<code>(Var x := 1; While x < 10 Do x := x+1) ¨ 10</code>

:<code>(Var x := 1; While x > 10 Do x := x+1) ¨ Null</code>

Using <code>While</code> often follows the following pattern:

:<code>Var x[]:= ...;</code>
:<code>While (FunctionOf(x)) Do (</code>
::<code>...</code>
::<code>x := expr;</code>
::<code>...</code>
:<code>);</code>
:<code>returnValue</code>

== Iterate (initial, expr, until, maxIter, ''warnFlag'') ==
Suppose the definition of variable x contains a call to [http://wiki.analytica.com/index.php?title=Iterate Iterate](). [http://wiki.analytica.com/index.php?title=Iterate Iterate]() initializes <code>x</code> to the value of <code>initial</code>. While stopping condition until is False (zero), it evaluates expression expr, and assigns the result to x. Given the optional parameter <code>maxIter</code>, it stops after <code>maxIter</code> iterations and, if <code>warnFlag</code> is True, issues a warning — unless it has already been stopped by <code>until</code> becoming True. If <code>until</code> is array-valued, it only stops when all elements of <code>until</code> are True.

[http://wiki.analytica.com/index.php?title=Iterate Iterate]() is designed for convergence algorithms where an expression must be recomputed an unknown number of iterations. [http://wiki.analytica.com/index.php?title=Iterate Iterate] (like [http://wiki.analytica.com/index.php?title=Dynamic Dynamic]) must be the main expression in a definition — it cannot be nested within another expression. But it can, and usually does, contain nested expressions as some of its parameters. [http://wiki.analytica.com/index.php?title=Iterate Iterate]() (again like [http://wiki.analytica.com/index.php?title=Dynamic Dynamic]() and unlike other functions) can, and usually does, mention the variable x that it defines within the expressions for initial and until. These expressions can also refer to variables that depend on <code>x</code>.

If you use [http://wiki.analytica.com/index.php?title=Iterate 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 [http://wiki.analytica.com/index.php?title=Iterate 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 [http://wiki.analytica.com/index.php?title=Iterate Iterate] and [http://wiki.analytica.com/index.php?title=Dynamic Dynamic] loops.

<Tip Title="Tip"> You can usually write convergence algorithms more cleanly using '''While'''. One difference is that '''While''' requires its stopping condition '''Test''' to be an atom, where [[Iterate]]() allows an array-valued stopping condition until. Nevertheless, it is usually better to use '''While''' because you want it to do an appropriate number of iterations for each element of '''until''', rather than continue until all its elements are '''True'''. But, with '''While''' you need to use one of the tricks described in “While and array abstraction” to ensure the expression fully supports array abstraction.</Tip>

== See Also ==
* [http://wiki.analytica.com/index.php?title=Intelligent_Arrays Intelligent Arrays]
<br />

<footer>Local Variables / {{PAGENAME}} / Recursion</footer>

For and While Loops

2015-12-29T03:35:52Z

Jhernandez3: /* See Also */

For and While Loops

2015-12-29T03:35:11Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

== For i := a Do expr ==

The '''For''' loop successively assigns the next atom from array <code>a</code> to local index <code>i</code>, and evaluates expression <code>expr</code>. <code>expr</code> might refer to <code>i</code>, for xample to slice out a particular element of an array. <code>a</code> might be a list of values defined by <code>m..n</code> or <code>Sequence(m, n, dx)</code> or it might be a multidimensional array. Normally, it evaluates the body <code>expr</code> once for each atom in <code>a</code>.

The result of the '''For '''loop is an array with all the indexes of <code>a</code> containing the values of each evaluation of <code>expr</code>. If any or all evaluations of <code>expr</code> have any additional index(es), they are also indexes of the result.

Usually, the Intelligent Array features take care of iterating over indexes of arrays without the need for explicit looping.

<Tip Title="Tip> Analytica’s Intelligent Array features means that you rarely need explicit iteration using '''For''' loops to repeat operations over each dimensions of an array, often used in conventional computer language. If you find yourself using '''For''' loops a lot in Analytica, this might be a sign that you are not using '''Intelligent Arrays''' effectively. If so, please (re)read the sections on [[Intelligent_Arrays|Intelligent Arrays]].</Tip>

A '''For''' loop is sometimes useful in these specialized cases:

* To avoid selected evaluations of <code>expr</code> that might be invalid or out of range, and can be prevented by nesting an <code>If-Then-Else</code> inside a '''For'''.
* To apply an Analytica function that requires an atom or one- or two-dimensional array input to a higher-dimensioned array.
* To reduce the memory needed f or calculations with very large arrays by reducing the memory requirement for intermediate results.<br />

See below for an example of each of these three cases.

==== Library ====
Special

====Avoiding out-of-range errors====

Consider the following expression:

:<code>If x<0 Then 0 Else Sqrt(x)</code>

The <code>If-Then-Else</code> is included in this expression to avoid the warning “Square root of a negative number.” However, if <code>x</code> is an array of values, this expression cannot avoid the warning since [http://wiki.analytica.com/index.php?title=Sqrt Sqrt](x) is evaluated before <code>If-Then-Else</code> selects which elements of [http://wiki.analytica.com/index.php?title=Sqrt Sqrt](x) to include. To avoid the warning (assuming <code>x</code> is indexed by <code>i</code>), the expression can be rewritten as:

:<code>For j:=I do</code>

::<code>If x[i=j]<0 then 0 else Sqrt(x[i=j])</code>

Or as (see next section):

:<code>Using y:=x in i do</code>

::<code>If y<0 Then 0 else Sqrt(y)</code>

Situations like this can often occur during slicing operations. For example, to shift <code>x</code> one position to the right along <code>i</code>, the following expression would encounter an error:

:<code>if i<2 then x[i=1] else x[i=i-1]</code>

The error occurs when <code>x[i=i-1]</code> is evaluated since the value corresponding to <code>i-1=0</code> is out of range. The avoid the error, the expression can be rewritten as:

:<code>For j:=i do
::If j<2 then x[i=1] else x[i=j-1]</code>

Out-of-range errors can also be avoided without using '''For''' by placing the conditional inside an argument. For example, the two examples above can be written without '''For''' as follows:

:<code>Sqrt(if x<0 then 0 else x)</code>

:<code>x[i=(if i<2 then 1 else i-1)]</code>

===== Dimensionality reduction =====
'''For''' can be used to apply a function that requires an atom, one- or two- dimensional input to a multi-dimensional result. This usage is rare in Analytica since array abstraction normally does this automatically; however, the need occasionally arises in some circumstances.

Suppose you have an array <code>A</code> indexed by <code>I</code>, and you wish to apply a function <code>f(x)</code> to each element of <code>A</code> along <code>I</code>. In a conventional programming language, this would require a loop over the elements of <code>A</code>; however, in almost all cases, Analytica’s array abstraction does this automatically — the expression is simply <code>f(A)</code>, and the result remains indexed by <code>i</code>. However, there are a few cases where Analytica does not automatically array abstract, or it is possible to write a user-defined function that does not automatically array abstract (e.g., by declaring a parameter to be of type <code>Atom</code>, as detailed in [[Parameter Qualifiers]]). For example, Analytica does not array abstract over functions such as [http://wiki.analytica.com/index.php?title=Sequence Sequence], [http://wiki.analytica.com/index.php?title=Split Split], [http://wiki.analytica.com/index.php?title=Subset Subset], or [http://wiki.analytica.com/index.php?title=Unique Unique], since these return un-indexed lists of varying lengths that are unknown until the function evaluates. Suppose we have the following variables defined (note that <code>A</code> is an array of text values):

:A: Index_1 ▼
:{| class="wikitable"
|-
! <font color="#FFFFFF">1</font>
!
|-
!1
|A, B, C
|-
!2
|D, E, F
|-
!3
|G, H, I
|}

:Index_1 ▼
:{| class="wikitable"
|-
|1
|2
|3
|}

We wish to split the text values in A and obtain a two dimensional array of letters indexed by Index_1 and Index_2. Since Split does not array abstract, we must do each row separately and re-index by Index_2 before the result rows are recombined into a single array. This is accomplished by the following loop:

:<code>FOR Row := Index_1 DO Array(Index_2, SplitText(A[Index_1=Row], ','))</code>

This results in:

:Index_1 ▼, Index_2 ▶

:{| class="wikitable"
|-
!
! 1
! 2
! 3
|-
! 1
|A
|B
|C
|-
! style="width:100px;" |2
|style="width:100px;" |D
|style="width:100px;" |E
|style="width:100px;" |F
|-
! style="width:100px;" |3
|style="width:100px;" |G
|style="width:100px;" |H
|style="width:100px;" |I
|}

===Reducing memory requirements===

In some cases, it is possible to reduce the amount of memory required for intermediate results during the evaluation of expressions involving large arrays. For example, consider the following expression:

<code>MatrixA:</code> A two dimensional array indexed by M and N.

<code>MatrixB:</code> A two dimensional array indexed by N and P.

:<code>Average(MatrixA * MatrixB, N)</code>

During the calculation, Analytica needs memory to compute <code>MatrixA * MatrixB</code>, an array indexed by <code>M</code>, <code>N</code>, and <code>P</code>. If these indexes have sizes 100, 200, and 300 respectively, then <code>MatrixA * MatrixB</code> contains 6,000,000 numbers, requiring over 60 megabytes of memory at 10
bytes per number.

To reduce the memory required, use the following expression instead:

:<code>For L := M Do Average(MatrixA[M=L]*MatrixB, N)</code>

Each element <code>MatrixA[M=L]*MatrixB</code> has dimensions <code>N</code> and <code>P</code>, needing only 200x300x10= 600 kilobytes of memory at a time.

<tip title="Tip">For the special case of a [[Matrix_functions#Dot_product_of_two_matrices|dot product]], for an expression of the form <code>Sum(a*b, i)</code>, it performs a similar transformation internally.</tip>

===While(Test) Do Body===

<code>While</code> evaluates <code>Body</code> repeatedly as long as <code>Test <> 0</code>. For <code>While ...</code> to terminate, <code>Body</code> must produce a side-effect on a local variable that is used by <code>Test</code>, causing <code>Test</code> eventually to equal <code>0</code>. If <code>Test</code> never becomes False, <code>While</code> continues to loop indefinitely. If you suspect that might be happening, type ''Control+. (Control+period)'' to interrupt execution.

<code>Test</code> must evaluate to an atomic (non-array) value; therefore, it is a good idea to force any local variable used in <code>Test</code> to be atomic valued. <code>While</code> is one of the few constructs in Analytica that does not generalize completely to handle arrays. But, there are ways to ensure that variables and functions using <code>While</code> support Intelligent Arrays and probabilistic evaluation. See “While and
array abstraction” on page 386 for details.

<code>While</code> returns the final value found in the last iteration of <code>Body</code> or <code>Null</code> if no iterations occur. For example:

:<code>(Var x := 1; While x < 10 Do x := x+1) ¨ 10</code>

:<code>(Var x := 1; While x > 10 Do x := x+1) ¨ Null</code>

Using <code>While</code> often follows the following pattern:

:<code>Var x[]:= ...;</code>
:<code>While (FunctionOf(x)) Do (</code>
::<code>...</code>
::<code>x := expr;</code>
::<code>...</code>
:<code>);</code>
:<code>returnValue</code>

== Iterate (initial, expr, until, maxIter, ''warnFlag'') ==
Suppose the definition of variable x contains a call to [http://wiki.analytica.com/index.php?title=Iterate Iterate](). [http://wiki.analytica.com/index.php?title=Iterate Iterate]() initializes <code>x</code> to the value of <code>initial</code>. While stopping condition until is False (zero), it evaluates expression expr, and assigns the result to x. Given the optional parameter <code>maxIter</code>, it stops after <code>maxIter</code> iterations and, if <code>warnFlag</code> is True, issues a warning — unless it has already been stopped by <code>until</code> becoming True. If <code>until</code> is array-valued, it only stops when all elements of <code>until</code> are True.

[http://wiki.analytica.com/index.php?title=Iterate Iterate]() is designed for convergence algorithms where an expression must be recomputed an unknown number of iterations. [http://wiki.analytica.com/index.php?title=Iterate Iterate] (like [http://wiki.analytica.com/index.php?title=Dynamic Dynamic]) must be the main expression in a definition — it cannot be nested within another expression. But it can, and usually does, contain nested expressions as some of its parameters. [http://wiki.analytica.com/index.php?title=Iterate Iterate]() (again like [http://wiki.analytica.com/index.php?title=Dynamic Dynamic]() and unlike other functions) can, and usually does, mention the variable x that it defines within the expressions for initial and until. These expressions can also refer to variables that depend on <code>x</code>.

If you use [http://wiki.analytica.com/index.php?title=Iterate 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 [http://wiki.analytica.com/index.php?title=Iterate 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 [http://wiki.analytica.com/index.php?title=Iterate Iterate] and [http://wiki.analytica.com/index.php?title=Dynamic Dynamic] loops.

<Tip Title="Tip"> You can usually write convergence algorithms more cleanly using '''While'''. One difference is that '''While''' requires its stopping condition '''Test''' to be an atom, where [[Iterate]]() allows an array-valued stopping condition until. Nevertheless, it is usually better to use '''While''' because you want it to do an appropriate number of iterations for each element of '''until''', rather than continue until all its elements are '''True'''. But, with '''While''' you need to use one of the tricks described in “While and array abstraction” to ensure the expression fully supports array abstraction.</Tip>

== See Also ==
[http://wiki.analytica.com/index.php?title=Intelligent_Arrays Intelligent Arrays]

<footer>Local Variables / {{PAGENAME}} / Recursion</footer>

Local Values

2015-12-29T03:34:10Z

Jhernandez3: /* See Also */

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

=== Defining a local variable: Var v := e ===
This construct creates a local variable <code>v</code> and initializes it with the value from evaluating expression <code>e</code>. You can then use <code>v</code> in subsequent expressions within this context — that is, in following expressions in this group, or nested within expressions in this group. You cannot refer to a local variable outside its context — for example, in the definition of another variable or function.

If <code>v</code> has the same identifier (name) as a global variable, any subsequent mention of <code>v</code> in this context refers to the just-defined local variable, not the global.

==== Examples ====
Instead of defining a variable as:

:<code>Sum(Array_a*Array_b, N)/(1 + Sum(Array_a*Array_b, N))</code>

Define it as:

:<code>VAR t := Sum(Array_a*Array*b, N); t/(1 + t)</code>

To compute a correlation between <code>Xdata</code> and <code>Ydata</code>, instead of:

:<code>Sum((Xdata - Sum(Xdata, Data_index)/Nopts)*(Ydata-</code>

::<code>Sum(Ydata, Data_index)/Nopts), Data_index)/</code>

::<code>Sqrt(Sum((Xdata-Sum(Xdata, Data_index)/</code>

::<code>Nopts)^2, Data_index) * Sum((Ydata -</code>

::<code>Sum(Ydata, Data_index)/Nopts)^2, Data_index))</code>

Define the correlation as:

:<code>VAR mx := Sum(Xdata, Data_index)/Nopts;</code>

:<code>VAR my := Sum(Ydata, Data_index)/Nopts;</code>

:<code>VAR dx := Xdata - mx;</code>

:<code>VAR dy := Ydata - my;</code>

:<code>Sum(dx*dy, Data_index)/Sqrt(Sum(dx^2, Data_index)*Sum(dy^2, Data_index))</code>

The latter expression is faster to execute and easier to read. The correlation expression in this example is an alternative to Analytica’s built-in [http://wiki.analytica.com/index.php?title=Correlation Correlation]() function when data is dimensioned by an index other than the system index '''<code>Run</code>'''.

=== Assigning to a local variable: v := e ===
The<code> :=</code> (assignment operator) sets the local variable <code>v</code> to the value of expression <code>e</code>.

The assignment expression also returns the value of <code>e</code>, although it is usually the effect of the assignment that is of primary interest.

The equal sign <code>=</code> does not do assignment. It tests for equality between two values.

Within the definition of a function, you can also assign a new value to any parameter. This only changes the parameter and does not affect any global variables used as actual parameters in the call to the function.

<Tip Title="Tip>Usually, '''''you cannot assign to a global variable''''' — that is, to a variable created as a diagram node. You can assign only to a local variable, declared in this definition using '''''Var''''' or '''''Index''''', in the current context — that is, at the same or enclosing level in this definition. In a function definition, you can also assign to a parameter.This prevents '''''side effects''''' — i.e., where evaluating a global variable or function changes a global variable, other than one that mentions this variable or function in its definition. Analytica’s lack of side effects makes models much easier to write, understand, and debug than normal computer languages that allow side effects. You can tell how a variable is computed just by looking at its definition, without having to worry about parts of the model not mentioned in the definition. There are a few exceptions to this rule of no assignments to globals: You can assign to globals in button scripts or functions called from button scripts. See [[Button_creation|Button Creation]] for details. You can also assign to a global variable '''V''' from the definition of '''X''' when '''V''' is defined as '''ComputedBy(X)'''.</Tip>

=== [http://wiki.analytica.com/index.php?title=ComputedBy ComputedBy](x) ===

This function indicates that the value of a variable is computed as a side-effect of another variable, <code>x</code>. Suppose <code>v</code> is defined as <code>[http://wiki.analytica.com/index.php?title=ComputedBy ComputedBy](x)</code>, and the value of <code>v</code> needs to be computed, then Analytica will evaluate <code>x</code>. During the evaluation of <code>x</code>, <code>x</code> must set the value of <code>v</code> using an assignment operator.

Even though <code>v</code> is a side-effect of <code>x</code>, its definition is still referentially transparent, which means that its definition completely describes its computed value.

<code>[http://wiki.analytica.com/index.php?title=ComputedBy ComputedBy]</code> is useful when multiple items are computed simultaneously within an expression. It is particularly useful from within an [[Iterate]]() function when several variables need to be updated in each iteration.

:<code>Variable rot := ... { a 2-D rotation matrix indexed by Dim and Dim2 }</code>

:<code>Variable X_rot := ComputedBy(Y_rot)</code>

:<code>Variable Y_rot :=</code>

::<code>BEGIN</code>

::<code>Var v := Array(Dim, [X, Y]);</code>

::<code>Var v_r := sum(rot*v, Dim);</code>

::<code>X_rot := v_r[Dim2 = 'x'];</code>

::<code>v_r[Dim2 = 'y'];</code>

::<code>END</code>

===Assigning to a slice of a local variable===

'''''Slice assignment''''' means assigning a value into an element or slice of an array contained by a local variable, for example:

:<code>x[i = n] := e</code>

<code>x</code> must be a local variable, <code>i</code> is an index (local or global), <code>n</code> evaluates to be a value or values of <code>i</code>, and <code>e</code> is any expression. If <code>x</code> was not array or was an array not indexed by <code>i</code>, the slice assignment adds i as a dimension of <code>x</code>. The result returned from the assignment operator is the value <code>e</code>, not the full value of <code>x</code>, which can be a source of confusion but is that way so you can chain assignments, e.g.:

:<code>x[i = 3] := x[i = 5] := 7</code>

You can write some algorithms much more easily and efficiently using slice assignment. For example:

:<code>Function Fibonacci_series(f1, f2, n: Number Atom) :=</code>

::<code>INDEX m := 1..n;</code>

::<code>VAR result := 0;</code>

::<code>result[m = 1] := f1;</code>

::<code>result[m = 2] := f2;</code>

::<code>FOR I := 3..n DO result[m = i] := result[m = i -1] + result[m = i - 2];</code>

::<code>result</code>

In the first slice assignment:

:<code>result[m = 1] := f1;</code>

<code>result</code> was not previously indexed by <code>m</code>. So the assignment adds the index <code>m</code> to result, making it into an array with value <code>f1 for m = 1</code> and its original value, 0, for all other values of <code>m</code>.

More generally, in a slice assignment:

:<code>x[i = n] := e</code>

If <code>x</code> was already indexed by <code>i</code>, it sets <code>x[i=n]</code> to the value of <code>e</code>. All other slices of <code>x</code> over <code>i</code> retain their previous values. If <code>x</code> was indexed by other indexes, say <code>j</code>, the result is indexed by <code>i</code> and <code>j</code>. The assigned slice <code>x[i = n]</code> has the value <code>e</code> for all values of the other index(es) <code>j</code>.

You can index by position as well as name in a slice assignment, for example:

:<code>x[@i = 2] := e</code>

This assigns the value of <code>e</code> as the second slice of <code>x</code> over index <code>i</code>.

To set a cell in a multi-dimensional array, include multiple subscript coordinates, e.g.:

:<code>x[i = 2, j = 5, k = 3] := 7</code>

Slice assignment array abstracts when <code>x</code>, <code>n</code>, or <code>e</code> have extra dimensions, and the abstraction is coordinated when an index is shared by <code>x</code>, <code>n</code>, or <code>e</code>. Using abstraction, it is possible to assign to many cells in a single assignment operation.

== See Also ==
* [http://wiki.analytica.com/index.php?title=Var..Do Var..Do]<br />

<footer>Begin-End for Grouping Expressions / {{PAGENAME}} / For and While Loops</footer>

Local Values

2015-12-29T03:33:44Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

=== Defining a local variable: Var v := e ===
This construct creates a local variable <code>v</code> and initializes it with the value from evaluating expression <code>e</code>. You can then use <code>v</code> in subsequent expressions within this context — that is, in following expressions in this group, or nested within expressions in this group. You cannot refer to a local variable outside its context — for example, in the definition of another variable or function.

If <code>v</code> has the same identifier (name) as a global variable, any subsequent mention of <code>v</code> in this context refers to the just-defined local variable, not the global.

==== Examples ====
Instead of defining a variable as:

:<code>Sum(Array_a*Array_b, N)/(1 + Sum(Array_a*Array_b, N))</code>

Define it as:

:<code>VAR t := Sum(Array_a*Array*b, N); t/(1 + t)</code>

To compute a correlation between <code>Xdata</code> and <code>Ydata</code>, instead of:

:<code>Sum((Xdata - Sum(Xdata, Data_index)/Nopts)*(Ydata-</code>

::<code>Sum(Ydata, Data_index)/Nopts), Data_index)/</code>

::<code>Sqrt(Sum((Xdata-Sum(Xdata, Data_index)/</code>

::<code>Nopts)^2, Data_index) * Sum((Ydata -</code>

::<code>Sum(Ydata, Data_index)/Nopts)^2, Data_index))</code>

Define the correlation as:

:<code>VAR mx := Sum(Xdata, Data_index)/Nopts;</code>

:<code>VAR my := Sum(Ydata, Data_index)/Nopts;</code>

:<code>VAR dx := Xdata - mx;</code>

:<code>VAR dy := Ydata - my;</code>

:<code>Sum(dx*dy, Data_index)/Sqrt(Sum(dx^2, Data_index)*Sum(dy^2, Data_index))</code>

The latter expression is faster to execute and easier to read. The correlation expression in this example is an alternative to Analytica’s built-in [http://wiki.analytica.com/index.php?title=Correlation Correlation]() function when data is dimensioned by an index other than the system index '''<code>Run</code>'''.

=== Assigning to a local variable: v := e ===
The<code> :=</code> (assignment operator) sets the local variable <code>v</code> to the value of expression <code>e</code>.

The assignment expression also returns the value of <code>e</code>, although it is usually the effect of the assignment that is of primary interest.

The equal sign <code>=</code> does not do assignment. It tests for equality between two values.

Within the definition of a function, you can also assign a new value to any parameter. This only changes the parameter and does not affect any global variables used as actual parameters in the call to the function.

<Tip Title="Tip>Usually, '''''you cannot assign to a global variable''''' — that is, to a variable created as a diagram node. You can assign only to a local variable, declared in this definition using '''''Var''''' or '''''Index''''', in the current context — that is, at the same or enclosing level in this definition. In a function definition, you can also assign to a parameter.This prevents '''''side effects''''' — i.e., where evaluating a global variable or function changes a global variable, other than one that mentions this variable or function in its definition. Analytica’s lack of side effects makes models much easier to write, understand, and debug than normal computer languages that allow side effects. You can tell how a variable is computed just by looking at its definition, without having to worry about parts of the model not mentioned in the definition. There are a few exceptions to this rule of no assignments to globals: You can assign to globals in button scripts or functions called from button scripts. See [[Button_creation|Button Creation]] for details. You can also assign to a global variable '''V''' from the definition of '''X''' when '''V''' is defined as '''ComputedBy(X)'''.</Tip>

=== [http://wiki.analytica.com/index.php?title=ComputedBy ComputedBy](x) ===

This function indicates that the value of a variable is computed as a side-effect of another variable, <code>x</code>. Suppose <code>v</code> is defined as <code>[http://wiki.analytica.com/index.php?title=ComputedBy ComputedBy](x)</code>, and the value of <code>v</code> needs to be computed, then Analytica will evaluate <code>x</code>. During the evaluation of <code>x</code>, <code>x</code> must set the value of <code>v</code> using an assignment operator.

Even though <code>v</code> is a side-effect of <code>x</code>, its definition is still referentially transparent, which means that its definition completely describes its computed value.

<code>[http://wiki.analytica.com/index.php?title=ComputedBy ComputedBy]</code> is useful when multiple items are computed simultaneously within an expression. It is particularly useful from within an [[Iterate]]() function when several variables need to be updated in each iteration.

:<code>Variable rot := ... { a 2-D rotation matrix indexed by Dim and Dim2 }</code>

:<code>Variable X_rot := ComputedBy(Y_rot)</code>

:<code>Variable Y_rot :=</code>

::<code>BEGIN</code>

::<code>Var v := Array(Dim, [X, Y]);</code>

::<code>Var v_r := sum(rot*v, Dim);</code>

::<code>X_rot := v_r[Dim2 = 'x'];</code>

::<code>v_r[Dim2 = 'y'];</code>

::<code>END</code>

===Assigning to a slice of a local variable===

'''''Slice assignment''''' means assigning a value into an element or slice of an array contained by a local variable, for example:

:<code>x[i = n] := e</code>

<code>x</code> must be a local variable, <code>i</code> is an index (local or global), <code>n</code> evaluates to be a value or values of <code>i</code>, and <code>e</code> is any expression. If <code>x</code> was not array or was an array not indexed by <code>i</code>, the slice assignment adds i as a dimension of <code>x</code>. The result returned from the assignment operator is the value <code>e</code>, not the full value of <code>x</code>, which can be a source of confusion but is that way so you can chain assignments, e.g.:

:<code>x[i = 3] := x[i = 5] := 7</code>

You can write some algorithms much more easily and efficiently using slice assignment. For example:

:<code>Function Fibonacci_series(f1, f2, n: Number Atom) :=</code>

::<code>INDEX m := 1..n;</code>

::<code>VAR result := 0;</code>

::<code>result[m = 1] := f1;</code>

::<code>result[m = 2] := f2;</code>

::<code>FOR I := 3..n DO result[m = i] := result[m = i -1] + result[m = i - 2];</code>

::<code>result</code>

In the first slice assignment:

:<code>result[m = 1] := f1;</code>

<code>result</code> was not previously indexed by <code>m</code>. So the assignment adds the index <code>m</code> to result, making it into an array with value <code>f1 for m = 1</code> and its original value, 0, for all other values of <code>m</code>.

More generally, in a slice assignment:

:<code>x[i = n] := e</code>

If <code>x</code> was already indexed by <code>i</code>, it sets <code>x[i=n]</code> to the value of <code>e</code>. All other slices of <code>x</code> over <code>i</code> retain their previous values. If <code>x</code> was indexed by other indexes, say <code>j</code>, the result is indexed by <code>i</code> and <code>j</code>. The assigned slice <code>x[i = n]</code> has the value <code>e</code> for all values of the other index(es) <code>j</code>.

You can index by position as well as name in a slice assignment, for example:

:<code>x[@i = 2] := e</code>

This assigns the value of <code>e</code> as the second slice of <code>x</code> over index <code>i</code>.

To set a cell in a multi-dimensional array, include multiple subscript coordinates, e.g.:

:<code>x[i = 2, j = 5, k = 3] := 7</code>

Slice assignment array abstracts when <code>x</code>, <code>n</code>, or <code>e</code> have extra dimensions, and the abstraction is coordinated when an index is shared by <code>x</code>, <code>n</code>, or <code>e</code>. Using abstraction, it is possible to assign to many cells in a single assignment operation.

== See Also ==
* [http://wiki.analytica.com/index.php?title=Var..Do Var..Do]

<footer>Begin-End for Grouping Expressions / {{PAGENAME}} / For and While Loops</footer>

Begin-End for Grouping Expressions

2015-12-29T03:32:47Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

As illustrated above, you can group several expressions (statements) as the definition of a variable or function simply by separating them by semicolons (<code>;</code>). To group several expressions as a condition or action of <code>If a Then b Else c</code> or <code>While a Do b</code>, or, indeed, anywhere a single expression
is valid, you should enclose the expressions between <code>Begin</code> and <code>End</code>, or between parentheses characters <code>(</code> and <code>)</code>.

The overall value of the group of statements is the value from evaluating the last expression. For example:

:<code>(VAR x := 10; x := x/2; x - 2) → 3</code>

Analytica also tolerates a semicolon (<code>;</code>) after the last expression in a group. It still returns the value of the last expression. For example:

:<code>(VAR x := 10; x := x/2; x/2;) → 2.5</code>

The statements can be grouped on one line, or over several lines. In fact, Analytica does not care where new-lines, spaces, or tabs occur within an expression or sequence of expressions — as long as they are not within a number or identifier.<br />

<footer>Summary of Programming Constructs / {{PAGENAME}} / Local Variables</footer>

Summary of Programming Constructs

2015-12-29T03:32:21Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

Please see the table below for a list of Analytica programming constructs, their meanings, and links to references with more details, if available.

{| class="wikitable"
! '''Construct'''
! '''Meaning:'''
! '''For more, see'''
|-
| <code>e1; e2; … ei</code>
| Semicolons join a group of expressions to be evaluated in sequence
|[http://wiki.analytica.com/index.php?title=Begin-End_for_Grouping_Expressions Begin-End for Grouping Expressions]
|-
| <code>BEGIN e1; e2; …</code>
<code>ei END</code>
| A group of expressions to be evaluated in sequence
|[http://wiki.analytica.com/index.php?title=Begin-End_for_Grouping_Expressions Begin-End for Grouping Expressions]
|-
| <code>(e1; e2; … ei)</code>
| Another way to group expressions
|[http://wiki.analytica.com/index.php?title=Begin-End_for_Grouping_Expressions Begin-End for Grouping Expressions]
|-
| <code>m .. n</code>
| Generates a list of successive integers from <code>m</code> to <code>n</code>
|[http://wiki.analytica.com/index.php?title=Ensuring_Array_Abstraction#Functions_Expecting_Atomic_Parameters Functions Expecting Atomic Parameters]
|-
| <code>Var x := e</code>
| Define local variable <code>x</code> and assign initial value <code>e</code>
|[http://wiki.analytica.com/index.php?title=Local_Variables#Defining_a_local_variable Defining a Local Variable]
|-
| <code>Index i := e</code>
| Define local index <code>i</code> and assign initial value <code>e</code>
|[http://wiki.analytica.com/index.php?title=Local_Indexes Local Indexes]
|-
|<code>x := e</code>
| Assigns value from evaluating <code>e</code> to local variable <code>x</code>.
Returns value <code>e</code>.
|[http://wiki.analytica.com/index.php?title=Local_Variables#Assigning_to_a_local_variable: Assigning to a Local Variable]
|-
| <code>While Test </code><code>Do Body</code>
| While <code>Test</code> is True, evaluate <code>Body</code> and repeat.
Returns last value of <code>Body</code>.
|[http://wiki.analytica.com/index.php?title=For_and_While_Loops#While.28Test.29_Do_Body While(Test) Do Body]
|-
| { comments }
/* comments */
| Curly brackets { } and /* */ are alternative ways to enclose comments to be ignored by the parser.
|[http://wiki.analytica.com/index.php?title=Procedural_Programming_Example Procedural Programming Example]
|-
| 'text'
"text"
| You can use single or double quotes to enclose a literal text value, but they must match.
|[http://wiki.analytica.com/index.php?title=Text_values Text Values]
|-
| <code>For x := a DO e</code>
| Assigns to loop variable <code>x</code>, successive atoms from array <code>a</code> and repeats evaluation expression <code>e</code> for each value of <code>x</code>.
Returns an array of values of <code>e</code> with the same indexes as <code>a</code>.
|[http://wiki.analytica.com/index.php?title=For_and_While_Loops#For_i_:.3D_a_Do_expr For i := a Do expr]
|-
| <code>For x[i, j…] := a DO e</code>
| Same, but it assigns to x successive sub-arrays of <code>a</code>, each indexed by the indices, <code>[i, j …</code>
|[http://wiki.analytica.com/index.php?title=For_and_While_Loops#For_i_:.3D_a_Do_expr For i := a Do expr]
|-
| <code>\ e</code>
| Creates a reference to the value of expression <code>e</code>.
|[http://wiki.analytica.com/index.php?title=References_and_Data_Structures References and Data Structures]
|-
| <code>\ [i, j …] e</code>
| Creates an array indexed by any indexes of <code>e</code> other than <code>i, j …</code> of references to sub-arrays of e each indexed by <code>i, j ….</code>
|[http://wiki.analytica.com/index.php?title=References_and_Data_Structures References and Data Structures]
|-
| <code># r</code>
| Returns the value referred to by reference <code>r</code>.
|[http://wiki.analytica.com/index.php?title=References_and_Data_Structures References and Data Structures]
|}

<footer>Procedural Programming Example / {{PAGENAME}} / Begin-End for Grouping Expressions</footer>

Procedural Programming Example

2015-12-29T03:31:48Z

Jhernandez3:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

The following function, <code>Factors()</code>, computes the prime factors of an integer x. It illustrates many of the key constructs of procedural programming.

::[[File:example1.png|400px]]

See below for an explanation of each of these constructs, and cross references to where they are.

::{| border="0;" style="width:400px;"
! '''Numbers identify<br />
features below'''
! '''Function Factors(x)<br />
Definition:'''
|-
| 1
| <code>VAR result := [1];</code>
|-
| 2
| <code>VAR n := 2;</code>
|-
| 3
|<code>WHILE n <= x DO</code>
|-
| 4
|<code>BEGIN</code>
|-
| 2
| <code>VAR r := Floor(x/n);</code>
<code>IF r*n = x THEN</code>
|-
| 5
|<code>(result := Concat(result, [n]);</code>
|-
| 6
| <code>x := r)</code>
<code>ELSE n := n + 1</code>
|-
| 4,7
|<code>END; /* End While loop */</code>
|-
| 7, 8
|<code>result /* End Definition */</code>
|}

This definition illustrates these features:

# <code>VAR x := e</code> construct defines a local variable x, and sets an initial value e. See [http://wiki.analytica.com/index.php?title=Local_Variables#Defining_a_local_variable Defining a Local Variable].
# You can group several expressions (statements) into a definition by separating them using “;” (semicolons). Expressions can be on the same line or successive lines. See [http://wiki.analytica.com/index.php?title=Begin-End_for_Grouping_Expressions Begin-End for Grouping Expressions].
# <code>While test Do body</code> construct tests condition <code>Test</code>, and, if True, evaluates <code>Body</code>, and repeats until condition <code>Test</code> is False. See [http://wiki.analytica.com/index.php?title=For_and_While_Loops#While.28Test.29_Do_Body While(Test) Do Body].
# Begin <code>e1; e2; … End</code> groups several expressions separated by semicolons “;” — in this case as the body of a While loop. See “Begin-End, (), and “;” for grouping expressions” on page 376.
# <code>(e1; e2; …)</code> is another way to group expressions — in this case, as the action to be taken in the Then case. See [http://wiki.analytica.com/index.php?title=Begin-End_for_Grouping_Expressions Begin-End for Grouping Expressions].
# <code>x := e</code> lets you assign the value of an expression <code>e</code> to a local variable <code>x</code> or, as in the first case, to a parameter of a function. See [http://wiki.analytica.com/index.php?title=Local_Variables#Assigning_to_a_local_variable: Assigning to a local variable].
# A comment is enclosed between /* and */ as an alternative to { and }.
# A group of expressions returns the value of the last expression — here the function <code>Factors</code> returns the value of <code>result</code> — whether the group is delimited by Begin and End, by parentheses marks ( and ), or, as here, by nothing.<br />

<footer>Procedural Programming / {{PAGENAME}} / Summary of Programming Constructs</footer>

Procedural Programming

2015-12-29T03:31:06Z

Jhernandez3: /* See Also */

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > {{PAGENAME}}</breadcrumbs><br />

A '''procedural program''' is a list of instructions to a computer. Each instruction tells the computer what to do, or it might change the sequence to execute the instructions. Most Analytica models are '''''non-procedural''''' — that is, they consist of an unsequenced set of definitions of variables. Each definition is a simple expression that contain functions, operators, constants, and other variables, but no procedural constructs controlling the sequence of execution. In this way, Analytica is like a standard spreadsheet application, in which each cell contains a simple formula with no procedural constructs. Analytica selects the sequence in which to evaluate variables based on the dependencies among them, somewhat in the same way spreadsheets determine the sequence to evaluate their cells. Controlling the evaluation sequence via conditional statements and loops is a large part of programming in a language like in Fortran, Visual Basic, or C++. Non-procedural languages like Analytica free you from having to worry about sequencing. Non-procedural models or programs are usually much easier to write and understand than procedural programs because you can understand each definition (or formula) without worrying about the sequence of execution.

However, procedural languages enable you to write more powerful functions that are hard or impossible without their procedural constructs. For this reason, Analytica offers a set of programming constructs, described in this chapter, providing a general procedural programming language for those who need it.

You can use these constructs to control the flow of execution only within the definition of a variable or function. Evaluating one variable or function cannot (usually) change the value of another variables or functions. Thus, these procedural constructs do not affect the simple non-procedural relationship among variables and functions. The only exception is that a function called from an event handler such as <code>OnChange</code> or a button <code>OnClick</code> attribute can change the definition of a global variable (see [[Button Creation]] for more details).

== Sections ==
* [[Procedural Programming Example|Procedural Programming Example]]
* [[Summary of Programming Constructs]]
* [[Begin-End for Grouping Expressions]]
* [[Local Variables]]
* [[For and While Loops]]
* [[Recursion]]
* [[Local Indexes]]
* [[Ensuring Array Abstraction]]
* [[References and Data Structures]]
* [[Handles to Objects]]
* [[Dialog Functions]]
* [[Other Procedural Functions]]

== See Also ==
* [http://wiki.analytica.com/index.php?title=Analytica.NET Analytica.NET]
* [http://wiki.analytica.com/index.php?title=Functions_By_Category#Conventions_for_parameters_and_operands Conventions for parameters and operands]
* [http://wiki.analytica.com/index.php?title=Functions_By_Category#Operators Operators][http://wiki.analytica.com/index.php?title=Analytica.NET]<br />

<footer>Building Functions and Libraries / {{PAGENAME}} / Analytica Enterprise</footer>