Difference between revisions of "SolverInfo"

(engine info table)
 
(27 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
[[Category:Deprecated Optimization Functions]]
 +
[[Category:Doc Status C]] <!-- For Lumina use, do not change -->
 +
 +
''Deprecated as of [[Analytica 4.3]].  This function has been split into the new functions [[OptInfo]] and [[OptEngineInfo]].''
 +
 +
==SolverInfo(item, ''lp, LpType, engine, ref'')==
 
The SolverInfo function provides information about a specific optimizer engine, or about a previously-defined LP, QP or NLP.  Its declaration is:
 
The SolverInfo function provides information about a specific optimizer engine, or about a previously-defined LP, QP or NLP.  Its declaration is:
  
−
SolverInfo( lp : optional LP_TYPE ; item : atomic text ; engine : optional atomic text ;  
+
:[[SolverInfo]](item: atomic text; lp: optional atomic LpType; engine: optional atomic text; ref: optional boolean = False )
−
            ref : optional boolean = False )
 
  
 
Where:
 
Where:
−
* lp : A problem instance previously defined by LpDefine, QpDefine or NlpDefine, or returned by FindIIS.
+
;«lp»: A problem instance previously defined by [[LpDefine]], [[QpDefine]] or [[NlpDefine]], [[LpRead]], or returned by [[LpFindIIS]].
−
* item : A description of the desired item(s).  See below.
+
;«item»: A description of the desired item(s).  Case insensitive.  See below for possible values.
−
* engine: The name of a Solver engine.
+
;«engine»: The name of a Solver engine.
−
* ref : A flag indicating whether a reference to the result should be returned.
+
;«ref»: A flag indicating whether a reference to the result should be returned.
  
−
The Lp and Engine parameters cannot both be specified in the same call. 
+
== Obtaining Information about a Problem Instance ==
 +
You can obtain information about a previously-defined optimization problem using the two-parameter form of SolverInfo:
 +
:<code>SolverInfo(item, lp)</code>
  
−
= Obtaining Information about a Problem Instance =
 
−
 
−
You can obtain information about a previously-defined optimization problem using the two-parameter form of SolverInfo:
 
−
  SolverInfo( lp, item )
 
 
For example, to get the variable lower bounds use:
 
For example, to get the variable lower bounds use:
−
  SolverInfo( lp, "lb" )
+
:<code>SolverInfo("lb", lp)</code>
  
−
Possible values for the Item are
+
Possible values for «Item» are
−
{| border="1"
+
:{| class="wikitable"
−
! "Item" !! Valid For !! Dimensionality || Type
+
! «Item» !! Valid For !! Dimensionality || Type || Description
 +
|-
 +
! <code>"objcoef"</code>
 +
| LP, QP || Vars || numeric ||
 +
|-
 +
!<code>"Q"</code>
 +
| QP || Vars, Vars2 || numeric ||
 +
|-
 +
! <code>"lhs"</code>
 +
| LP, QP || Vars, Constraints || numeric ||
 +
|-
 +
! <code>"lhsQ",</code>
 +
| QP || Vars, Vars2, Constraints || numeric ||
 +
|-
 +
! <code>"rhs"</code>
 +
| LP, QP, NLP || Constraints || numeric ||
 +
|-
 +
! <code>"constraintUb"</code>
 +
| LP, QP, NLP || Constraints || numeric || Upper bound for each constraint
 
|-
 
|-
−
| "objcoef" || LP, QP || Vars || numeric
+
! <code>"constraintLb"</code>
 +
| LP, QP, NLP || Constraints || numeric || Lower bound for each constraint
 
|-
 
|-
−
|"Q" || QP || Vars, Vars2 || numeric
+
! <code>"sense"</code>
 +
| LP, QP, NLP || Constraints || '>=', '<=', '=', 'R' || inequality for each constraint. 'R' for range (lb &amp; ub)
 
|-
 
|-
−
| "lhs" || LP, QP || Vars, Constraints || numeric
+
! <code>"lb"</code>
 +
| LP, QP, NLP || Vars || numeric || lower bound for each variable
 
|-
 
|-
−
| "rhs" || LP,QP,NLP || Constraints || numeric
+
! <code>"ub"</code>
 +
| LP, QP, NLP || Vars || numeric || upper bound for each variable
 
|-
 
|-
−
| "lb" || LP,QP,NLP || Vars || numeric
+
! <code>"ctype"</code>
 +
| LP, QP, NLP || Vars || 'C', 'I', or 'B' ||
 
|-
 
|-
−
| "sense" || LP,QP,NLP || Constraints || '>=','<=', or '='
+
!<code>"group"</code>
 +
| LP, QP, NLP || Vars || numeric ||
 
|-
 
|-
−
| "ub" || LP,QP,NLP || Vars || numeric
+
! <code>"maximize"</code>
 +
| LP, QP, NLP || atomic || True, False ||
 
|-
 
|-
−
| "ctype" || LP,QP,NLP || Vars || 'C', 'I', or 'B'
+
! <code>"engine"</code>
 +
| LP, QP, NLP || atomic || text ||
 
|-
 
|-
−
| "maximize" || LP,QP,NLP || atomic || True, False
+
! <code>"setting"</code>
 +
| LP, QP, NLP || local .Parameter || numeric ||
 
|-
 
|-
−
| "engine" || LP,QP,NLP || atomic || text
+
! <code>"type"</code>
 +
| LP, QP, NLP || atomic || "LP", "QP", "QCP" or "NLP" ||
 
|-
 
|-
−
| "setting" || LP,QP,NLP || local .Parameter || numeric
+
! <code>"vars"</code>
 +
| LP, QP, NLP || Vars || elements of the Vars index ||
 
|-
 
|-
−
| "type" || LP,QP,NLP || atomic || "LP","QP", "QCP" or "NLP"
+
! <code>"constraints"</code>
 +
| LP, QP, NLP || Constraints || the constraint names ||
 
|}
 
|}
  
−
= Obtaining Information about a Solver Engine =
+
If any of these «item»s are specified, but the «lp» parameter is not provided, an error results.
  
 +
== Obtaining Information about a Solver Engine ==
 
The usage:
 
The usage:
−
SolverInfo( engine: atomic text ; Item : atomic text )
+
:<code>SolverInfo(item, Engine: engineName)</code>
−
returns information about a solver engine.  The possible values for Item in this usage are:
 
  
−
{| border="1"
+
returns information about a solver engine.  The possible values for «item» in this usage are:
−
! Item !! Dimensionality !! Type !! Description
+
 
 +
:{| class="wikitable"
 +
! «Item» !! Dimensionality !! Type !! Description
 
|-
 
|-
−
| "Setting" || Local .Parameter || numeric || Array of control parameters
+
! <code>"SettingNames"</code>
 +
| List || numeric || Array of control setting names.
 
|-
 
|-
−
| "MaxSetting" || Local .Parameter || numeric || upper bounds for setting
+
! <code>"MaxSetting"</code>
 +
| Local .Parameter || numeric || upper bounds for setting
 
|-
 
|-
−
| "MinSetting" || Local .Parameter || numeric || lower bounds for setting
+
! <code>"MinSetting"</code>
 +
| Local .Parameter || numeric || lower bounds for setting
 
|-
 
|-
−
| "Name" || atomic || text || The engine name
+
! <code>"Defaults"</code>
 +
| Local .Parameter || numeric || default value for setting
 
|-
 
|-
−
| "DLL" || atomic || text || File path to solver engine's DLL
+
! <code>"EngineName"</code>
 +
| atomic || text || The engine name (null without error if engine not installed)
 
|-
 
|-
−
| "TrialPeriod" || atomic || numeric || number of days until Frontline solver trial license expires
+
! <code>"DLL"</code>
 +
| atomic || text || File path to solver engine's DLL, "" for bulit-in engines.
 
|-
 
|-
−
| "MaxVars" || atomic || numeric || Maximum number of decision variables supported by engine
+
! <code>"TrialPeriod"</code>
 +
| atomic || numeric || number of days until Frontline solver trial license expires
 
|-
 
|-
−
| "MaxIntVars" || atomic || numeric || Maximum number of integer variables supported by engine
+
! <code>"ProblemTypes"</code>
 +
| Local .ProblemType || boolean || A list of the problem types handled by each engine
 
|-
 
|-
−
| "MaxConstraints" || atomic || numeric || Maximum number of constraints supported by engine
+
! <code>"MaxVars"</code>
 +
| Local .ProblemType || numeric || Maximum number of decision variables supported by engine
 
|-
 
|-
−
| "MaxVarBounds" || atomic || numeric || Maximum number of variable bounds supported by engine.
+
! <code>"MaxIntVars"</code>
 +
| Local .ProblemType || numeric || Maximum number of integer variables supported by engine
 
|-
 
|-
−
| "Milliseconds" || atomic || numeric || Time spent in computation.
+
! <code>"MaxConstraints"</code>
 +
| Local .ProblemType || numeric || Maximum number of constraints supported by engine
 
|-
 
|-
−
| "Iterations" || atomic || numeric || # of iterations engine has performed
+
! <code>"MaxVarBounds"</code>
 +
| Local .ProblemType || numeric || Maximum number of variable bounds supported by engine
 
|-
 
|-
−
| "Calls" || atomic || numeric || # of function evaluations that have occurred
+
! <code>"Milliseconds"</code>
 +
| atomic || numeric || Time spent in computation.
 
|-
 
|-
−
| "Jacobians" || atomic || numeric || # of jacobians evaluations that have occurred
+
! <code>"Iterations"</code>
 +
| atomic || numeric || # of iterations engine has performed
 
|-
 
|-
−
| "Hessians" || atomic || numeric || # of hessians evaluations that have occurred
+
! <code>"Calls"</code>
 +
| atomic || numeric || # of function evaluations that have occurred
 
|-
 
|-
 +
! <code>"Jacobians"</code>
 +
| atomic || numeric || # of jacobians evaluations that have occurred
 +
|-
 +
! <code>"Hessians"</code>
 +
| atomic || numeric || # of hessians evaluations that have occurred
 +
|}
 +
 +
If the «Engine» parameter is omitted, but the «Lp» parameter is present, then the setting for the engine used by «Lp» is returned.  If both the «LP» and «Engine» parameters are specified, then these settings will be returned for the specified «Engine» (in the case that these differ).
 +
 +
== General Information ==
 +
Some information can be obtained without specifying any problem instance or engine using the syntax, e.g.:
 +
:<code>SolverInfo("AvailEngines")</code>
 +
 +
The possible Items not pertaining to any engine or problem instance are:
 +
:{| class="wikitable"
 +
! «Item» !! Dimensionality !! Type !! Description
 +
|-
 +
! <code>"AvailEngines"</code>
 +
| List || Text || The names the Solver engines available for use.
 +
|}
 +
 +
== Obtaining Multiple Items in a Single Call ==
 +
Multiple items can be obtained from [[SolverInfo]] in a single call by array abstracting over the Item parameter.  For example:
 +
 +
:<code>Index SettingInfo := ["Name", "Max", "Min", "Value"]</code>
 +
:<code>Variable TheSettings := SolverInfo(Lp: the_lp, Item: SettingInfo)</code>
 +
 +
This example would return two dimensional arrays indexed by <code>SettingInfo</code> and by a local index named <code>.Parameters</code>.
 +
 +
Since many of the possible Item values return results with different dimensionality, using the function in this way would cause the dimensionalities to be combined undesirably.  Thus, when obtaining items having different dimensionality in a single call, the ref parameter can be set to true, and a reference to each setting is returned.  For example, the following would compute slack:
 +
 +
:<code>Var info := SolverInfo(lp: lp, Item: ["lhs","rhs"], Ref: true);</code>
 +
:<code>Var x := LpSolution(lp);</code>
 +
:<code>#info[.Parameter="rhs"] - sum(#info[.Parameter = 'lhs']*x, Vars)</code>
 +
 +
== Testing for the presence of an Engine ==
 +
Suppose you have an external solver engine, such as Knitro, which you use.  However, your colleague who also uses the model has Analyica Optimizer but not the Knitro add-in.  Your model may need to test whether Knitro is present on the machine and then fall back to the default solver if it is not present.
 +
 +
The preferred method for testing whether an external solver engine (Knitro in this example) is installed is:
 +
:<code>SolverInfo( "EngineName", Engine: "Knitro" ) <> Null</code>
 +
 +
<code>SolverInfo("Name",Engine:eng)</code> returns the engine name (e.g., <code>"Knitro"</code>) if the engine is fully installed.  If it is installed, the engine DLL is loaded into the processes memory.  If the engine is not present, or not correctly installed, [[Null]] is returned.  All other items that require an engine issue an error if the engine is not present.  <code>"EngineName"</code> does not issue an error.
 +
 +
== Diagnostics ==
 +
This section details some problems you might encounter while using SolverInfo, why they occur, and what to do about them.
 +
 +
=== Result has multiple .Parameter dimensions ===
 +
If you array abstract across multiple solver engines with an Item returning a <code>.Parameter</code>-indexed result (such as "Defaults", "MinSettings", etc), the result of [[SolverInfo]] may contain multiple local <code>.Parameter</code> indexes.  This occurs because different solver engines have different sets of possible parameters, so a separate local index is created for each one.  This can also occur if you abstract over multiple problem instances, if each problem instance uses a different engine.
 +
 +
If you do not specify the <code>Ref: True</code> parameter to SolverInfo in this case, you'll end up with a very large array, indexes by all the <code>.Parameter</code> indexes.  For example, if <code>engine1</code> has 70 parameters, <code>engine2</code> has 75 parameters, and <code>engine3</code> has 65 parameters, you'll have an array with 70*75*65 = 341K elements after abstracting over the three engines.  So, if you are abstracting a settings parameter over multiple problems, or over multiple engines, you probably want to use <code>Ref: True</code>.
 +
 +
=== Takes excessively long time ===
 +
If [[SolverInfo]] is taking a very long time to compute, possibly giving the impression that it is hanging (although it should abort with ''Ctrl+break''), a likely cause is that you may be inadvertently combining many multi-dimensional results into a very large high-dimensional result array.  This situation can occur if you are array abstracting over multiple items, LPs or engines, and if some or all of the atomic cases are returning array-valued results.  In such a case, you will want to use <code>Ref: True</code> so that these results are not combined.
 +
 +
=== Exhausting memory ===
 +
If [[SolverInfo]] unexpectedly consumes all available memory, it is likely that you are array abstracting over many array-valued results with different dimensionalities.  These dimensionalities get combined, and may result in an excessively large array.  The remedy is to specify <code>Ref: True</code> so that individual results are returned as references and dimensionalities are not combined.
 +
 +
=== Error: "Engine library could not be found" ===
 +
This error may result if an external add-on engine is not correctly installed.  You may find that the name of an external engine appears in the result returned by <code>SolverInfo("AvailEngines")</code>, but when you try to use this same value for the Engine parameter, the error message appears.
 +
 +
To fix, use regedit to modify the value
 +
:<code>HKLM/Software/Lumina Decision Systems/Analytica/4.0/SolverEngines/''engName''</code>
 +
 +
where <code>''engName''</code> is the engine name.  The value of this key should be a string value with a fully qualified path to the DLL containing the engine.  For example, it should not contain just <code>"Knitro.DLL"</code>, but rather it should contain <code>"C:\Program Files\Frontline Systems\Knitro\Knitro.DLL"</code>, for example.  The quotations marks should not be in the value.  To test whether this fixes the problem, it is not necessary to exit and restart Analytica - you can simply attempt to re-evaluate the [[SolverInfo]] call.
 +
 +
==History==
 +
Introduced in [[What's new in Analytica 4.0?|Analytica 4.0]].
 +
 +
Superseded by  [[OptInfo]] and [[OptEngineInfo]] in [[Analytica 4.3]]
 +
 +
==See Also==
 +
* [[OptInfo]]
 +
* [[OptEngineInfo]]
 +
* [[DefineOptimization]]
 +
* [[Using a Solver Add-on Engine]]
 +
* [[Using SetContext to efficiently solve NLPs]]
 +
* [[NlpDefine]]

Latest revision as of 21:29, 29 March 2016


Deprecated as of Analytica 4.3. This function has been split into the new functions OptInfo and OptEngineInfo.

SolverInfo(item, lp, LpType, engine, ref)

The SolverInfo function provides information about a specific optimizer engine, or about a previously-defined LP, QP or NLP. Its declaration is:

SolverInfo(item: atomic text; lp: optional atomic LpType; engine: optional atomic text; ref: optional boolean = False )

Where:

«lp»
A problem instance previously defined by LpDefine, QpDefine or NlpDefine, LpRead, or returned by LpFindIIS.
«item»
A description of the desired item(s). Case insensitive. See below for possible values.
«engine»
The name of a Solver engine.
«ref»
A flag indicating whether a reference to the result should be returned.

Obtaining Information about a Problem Instance

You can obtain information about a previously-defined optimization problem using the two-parameter form of SolverInfo:

SolverInfo(item, lp)

For example, to get the variable lower bounds use:

SolverInfo("lb", lp)

Possible values for «Item» are

«Item» Valid For Dimensionality Type Description
"objcoef" LP, QP Vars numeric
"Q" QP Vars, Vars2 numeric
"lhs" LP, QP Vars, Constraints numeric
"lhsQ", QP Vars, Vars2, Constraints numeric
"rhs" LP, QP, NLP Constraints numeric
"constraintUb" LP, QP, NLP Constraints numeric Upper bound for each constraint
"constraintLb" LP, QP, NLP Constraints numeric Lower bound for each constraint
"sense" LP, QP, NLP Constraints '>=', '<=', '=', 'R' inequality for each constraint. 'R' for range (lb & ub)
"lb" LP, QP, NLP Vars numeric lower bound for each variable
"ub" LP, QP, NLP Vars numeric upper bound for each variable
"ctype" LP, QP, NLP Vars 'C', 'I', or 'B'
"group" LP, QP, NLP Vars numeric
"maximize" LP, QP, NLP atomic True, False
"engine" LP, QP, NLP atomic text
"setting" LP, QP, NLP local .Parameter numeric
"type" LP, QP, NLP atomic "LP", "QP", "QCP" or "NLP"
"vars" LP, QP, NLP Vars elements of the Vars index
"constraints" LP, QP, NLP Constraints the constraint names

If any of these «item»s are specified, but the «lp» parameter is not provided, an error results.

Obtaining Information about a Solver Engine

The usage:

SolverInfo(item, Engine: engineName)

returns information about a solver engine. The possible values for «item» in this usage are:

«Item» Dimensionality Type Description
"SettingNames" List numeric Array of control setting names.
"MaxSetting" Local .Parameter numeric upper bounds for setting
"MinSetting" Local .Parameter numeric lower bounds for setting
"Defaults" Local .Parameter numeric default value for setting
"EngineName" atomic text The engine name (null without error if engine not installed)
"DLL" atomic text File path to solver engine's DLL, "" for bulit-in engines.
"TrialPeriod" atomic numeric number of days until Frontline solver trial license expires
"ProblemTypes" Local .ProblemType boolean A list of the problem types handled by each engine
"MaxVars" Local .ProblemType numeric Maximum number of decision variables supported by engine
"MaxIntVars" Local .ProblemType numeric Maximum number of integer variables supported by engine
"MaxConstraints" Local .ProblemType numeric Maximum number of constraints supported by engine
"MaxVarBounds" Local .ProblemType numeric Maximum number of variable bounds supported by engine
"Milliseconds" atomic numeric Time spent in computation.
"Iterations" atomic numeric # of iterations engine has performed
"Calls" atomic numeric # of function evaluations that have occurred
"Jacobians" atomic numeric # of jacobians evaluations that have occurred
"Hessians" atomic numeric # of hessians evaluations that have occurred

If the «Engine» parameter is omitted, but the «Lp» parameter is present, then the setting for the engine used by «Lp» is returned. If both the «LP» and «Engine» parameters are specified, then these settings will be returned for the specified «Engine» (in the case that these differ).

General Information

Some information can be obtained without specifying any problem instance or engine using the syntax, e.g.:

SolverInfo("AvailEngines")

The possible Items not pertaining to any engine or problem instance are:

«Item» Dimensionality Type Description
"AvailEngines" List Text The names the Solver engines available for use.

Obtaining Multiple Items in a Single Call

Multiple items can be obtained from SolverInfo in a single call by array abstracting over the Item parameter. For example:

Index SettingInfo := ["Name", "Max", "Min", "Value"]
Variable TheSettings := SolverInfo(Lp: the_lp, Item: SettingInfo)

This example would return two dimensional arrays indexed by SettingInfo and by a local index named .Parameters.

Since many of the possible Item values return results with different dimensionality, using the function in this way would cause the dimensionalities to be combined undesirably. Thus, when obtaining items having different dimensionality in a single call, the ref parameter can be set to true, and a reference to each setting is returned. For example, the following would compute slack:

Var info := SolverInfo(lp: lp, Item: ["lhs","rhs"], Ref: true);
Var x := LpSolution(lp);
#info[.Parameter="rhs"] - sum(#info[.Parameter = 'lhs']*x, Vars)

Testing for the presence of an Engine

Suppose you have an external solver engine, such as Knitro, which you use. However, your colleague who also uses the model has Analyica Optimizer but not the Knitro add-in. Your model may need to test whether Knitro is present on the machine and then fall back to the default solver if it is not present.

The preferred method for testing whether an external solver engine (Knitro in this example) is installed is:

SolverInfo( "EngineName", Engine: "Knitro" ) <> Null

SolverInfo("Name",Engine:eng) returns the engine name (e.g., "Knitro") if the engine is fully installed. If it is installed, the engine DLL is loaded into the processes memory. If the engine is not present, or not correctly installed, Null is returned. All other items that require an engine issue an error if the engine is not present. "EngineName" does not issue an error.

Diagnostics

This section details some problems you might encounter while using SolverInfo, why they occur, and what to do about them.

Result has multiple .Parameter dimensions

If you array abstract across multiple solver engines with an Item returning a .Parameter-indexed result (such as "Defaults", "MinSettings", etc), the result of SolverInfo may contain multiple local .Parameter indexes. This occurs because different solver engines have different sets of possible parameters, so a separate local index is created for each one. This can also occur if you abstract over multiple problem instances, if each problem instance uses a different engine.

If you do not specify the Ref: True parameter to SolverInfo in this case, you'll end up with a very large array, indexes by all the .Parameter indexes. For example, if engine1 has 70 parameters, engine2 has 75 parameters, and engine3 has 65 parameters, you'll have an array with 70*75*65 = 341K elements after abstracting over the three engines. So, if you are abstracting a settings parameter over multiple problems, or over multiple engines, you probably want to use Ref: True.

Takes excessively long time

If SolverInfo is taking a very long time to compute, possibly giving the impression that it is hanging (although it should abort with Ctrl+break), a likely cause is that you may be inadvertently combining many multi-dimensional results into a very large high-dimensional result array. This situation can occur if you are array abstracting over multiple items, LPs or engines, and if some or all of the atomic cases are returning array-valued results. In such a case, you will want to use Ref: True so that these results are not combined.

Exhausting memory

If SolverInfo unexpectedly consumes all available memory, it is likely that you are array abstracting over many array-valued results with different dimensionalities. These dimensionalities get combined, and may result in an excessively large array. The remedy is to specify Ref: True so that individual results are returned as references and dimensionalities are not combined.

Error: "Engine library could not be found"

This error may result if an external add-on engine is not correctly installed. You may find that the name of an external engine appears in the result returned by SolverInfo("AvailEngines"), but when you try to use this same value for the Engine parameter, the error message appears.

To fix, use regedit to modify the value

HKLM/Software/Lumina Decision Systems/Analytica/4.0/SolverEngines/engName

where engName is the engine name. The value of this key should be a string value with a fully qualified path to the DLL containing the engine. For example, it should not contain just "Knitro.DLL", but rather it should contain "C:\Program Files\Frontline Systems\Knitro\Knitro.DLL", for example. The quotations marks should not be in the value. To test whether this fixes the problem, it is not necessary to exit and restart Analytica - you can simply attempt to re-evaluate the SolverInfo call.

History

Introduced in Analytica 4.0.

Superseded by OptInfo and OptEngineInfo in Analytica 4.3

See Also

Comments


You are not allowed to post comments.