TOMLAB
SOCS offers a big number of options to control printing output and trim the solution process. The SOCS software consists of two inner solver parts:
Options for these two parts are set separately and they have a separate set of available options. For both types of options, setting an option is done by assigning a value to a field of a structure, where the field name is the name of the option to set and the value is the value to assign the option.
OC options are set in the structure problem.options.OC and NLP options are set in the structure problem.options.NLP. An example of setting options is:
problem.options.OC.MITODE = 10; % maximum mesh refinements
problem.options.NLP.IOFLAG = 20; % NLP solver print level
There are also two options that are not set through these structures. See problem.options.method and problem.options.nstg (3.3.39).
A complete description of the available options follows.
The optimal control options are set in problem.options.OC.
Table 2: User options for the TOMLAB /SOCS OC solver.
Option Desription Default Strings KEYDPL Dynamic Status Display Key. A string that defines the key for the dynamic status display. KEYDPL(1:1) defines the symbol that will be displayed when an inequality constraint is satisfied. KEYDPL(2:2) defines the symbol that will be displayed when an inequality is active at its lower bound. Thus, to denote active upper bounds by a 'U', and display nothing for all other constraints, the input string should be 'KEYDPL= U '. The default display key has the following interpretation:
. Satisfied Inequality l Active Lower Bound u Active Upper Bound e Equality i Ignored L Violated Lower Bound U Violated Upper Bound E Violated Equality .lueiLUE RHSTMP Character variable name of right hand side sparsity template file. rhstemplate.fil RSTFIL Character variable name of restart file. socs.restart SOCOUT Character variable defining the SOCS output control menu. The complete SOCS output is divided into distinct portions. Each portion of the SOCS output is defined by an alphabetic character. The level of output for each portion is specified by a number from 0 to 9, where 0 specifies no output, and more detailed output is obtained by a larger number. A default output configuration is defined by the quantities IPGRD and IPODE. For example the options IPGRD=20 IPODE=20are equivalent to the single optionSOCOUT=['a0b0c1d1e1f1g0' ... 'h1i2j2k2l1m1n1o1p1q1r1s1']Thus, to alter the default output such that the variables, constraints, and objective function are printed at every iteration, the following options can be set:
IPGRD=20 IPODE=20 SOCOUT='I4J4K4'The distinct portions of the SOCS output are identified as follows:
A Mathematical Optimal Control Interpretation B Right Hand Side Sparsity C Transcription Summary D SOCS I/O Parameters E Variable Grid Map F Constraint Grid Map G Optimal Control Scale H Index Sets and Sparsity I Variables J Objective Function K Constraints L Control Analysis Constraint M Relative DAE Error N Dynamic Status Display O Dynamic Constraint Adjoints P Dynamic Variable Adjoints Q Control Analysis Lagrangian Errors R Control Analysis Optimality Error S Grid Refinement Summary NLPALG Nonlinear Programming Algorithm (HDSNLP, HDBLSQ, HDSLSQ or HDBNLP). HDSNLP SPRTHS Right Hand Side Sparsity Option.
SPARSE Compute and use sparsity for right hand sides of the user supplied functions. DENSE Assume user supplied functions are dense. FILE Right Hand Side Sparsity Defined by User Supplied File SPARSE Reals OBJTOL Relative error in the performance index between final value and predicted optimum. 10−5 ODETOL Relative error in the solution of the differential equations on any phase. 10−3 PGDTOL Relative error in the projected gradient (optimality conditions). 10−3 RESTOL Resolution tolerance between dynamic variable values from one mesh refinement iteration to the next. 10−5 SMLTOL ODE variable absolute tolerance. є1 /2 PRTMSD Minimum perturbation size for sparse finite difference derivatives. 10−8 PRTMXD Maximum perturbation size for sparse finite difference derivatives. 10−3 PRTSFD Relative perturbation size for sparse finite difference derivatives. 10−5 TOLJSD Jacobian row and column tolerance for print. 10−6 TOLM5A Absolute integration tolerance. Ignored when method ≠ 5. є1 /2 TOLM5R Relative integration tolerance. Ignored when method ≠ 5. є1 /2 Integers IDTSFD Default derivative type and index set construction algorithm for sparse finite differences (may be superceded by NLP).
IDTSFD>0 Curtis-Powell-Reid (greedy) algorithm. IDTSFD<0 Coleman-Moré (graph coloring) algorithm. |IDTSFD|=1 forward difference (1-sided) derivatives. |IDTSFD|=2 central difference (2-sided) derivatives. 1 IPRSFD Pertubation size option.
IPRSFD=0 Pertubation size fixed at PRTSFD. IPRSFD=+1 Pertubation size between PRTMSD and PRTMXD computed to minimze truncation and roundoff error. 1 INCORE Flag determining “in core” usage. Large hold arrays are saved on scratch files in out of core mode.
INCORE=−1 Out of core mode. INCORE=0 Out of core if necessary. INCORE=+1 Do not go out of core. 0 ISCALE Automatic scaling option.
ISCALE= 0 Automatic row and column scaling. ISCALE= 1 Automatic row, simple column scaling. ISCALE= 2 Simple row and column scaling. 0 IRSTRT Flag determining usage of restart file RSTFIL.
IRSTRT=−1 Save file during solution process (write only). IRSTRT=0 Do not use file. IRSTRT=+1 Use file to start problem and update during solution process (read and write). IRSTRT=+2 Use file to start problem but do not update during solution process (read only). 0 ITSWCH Mesh refinement iteration number to switch discretization from low order to high order. 2 MITODE Maximum number of mesh refinement iterations (grids). 5 MORDOC Maximum order of optimal control solution analysis.
MORDOC=0 No analysis associated with first order necessary conditions (adjoint variables). MORDOC=1 First order analysis (necessary conditions). 0 MTSWCH High order discretization method for mesh refinement. If MTSWCH < 0 and NSSWCH < 0, high order discretization will be selected to minimize predicted solution time. -1 M5DTYP Method 5 Derivative Type.
M5DTYP=0 Internal (variational) derivatives. M5DTYP=+1 External (finite difference) derivatives. 0 NSSWCH High order stage number for mesh refinement. -1 IDSCPH Discontinuity diagnostic phase number. Display diagnostic information on phase IDSCPH, where 1 ≤ IDSCPH ≤ N (number of phases). No diagnostic information is displayed unless IPGRD ≥ 10, and the inputs IDSCND, IDSCVR, and IDSCFN are also set. 0 IDSCND Discontinuity diagnostic phase end. Display diagnostic information at the beginning of the phase when IDSCND = − 1, during the phase when IDSCND = 0, and at the end of the phase when IDSCND = + 1. No diagnostic information is displayed unless IPGRD ≥ 10, and the inputs IDSCPH, IDSCVR, and IDSCFN are also set. 0 IDSCVR Discontinuity diagnostic variable number. Display diagnostic information for variable IDSCVR, where 1 ≤ IDSCVR ≤ ns + nc + np. To display state variable k, set IDSCVR = k. To display control variable k, set IDSCVR = k + ns. To display parameter k, set IDSCVR = k + nc + ns. No diagnostic information is displayed unless IPGRD ≥ 10, and the inputs IDSCPH, IDSCND, and IDSCFN are also set. 0 IDSCFN Discontinuity diagnostic function number. When IDSCND = +1, or -1, set IDSCND = k to display point function k. When IDSCND = 0, set IDSCFN = k to display differential equation k. When IDSCND = 0, set IDSCFN = ns + k to display algebraic equation k. When IDSCND = 0, set IDSCFN = ns + npcon (nonlinear) + k to display quadrature equation k. No diagnostic information is displayed unless IPGRD ≥ 10, and the inputs IDSCPH, IDSCND, and IDSCVR are also set. 0 IPFSFD Sparse finite difference output level.
0=IPFSFD No Output. 1=IPFSFD Error messages and summary statistics. 2=IPFSFD Complete statistics. 3=IPFSFD Diagnostic output. 0 IPGRD Optimal control output level.
IPGRD=0 No Output. 0<IPGRD<10 Terse Output. 10≤IPGRD<20 Phase level grid and errors. 20≤IPGRD State level errors, mathematical input interpretation, NLP variable and constraint maps. 10 IPNLP Sparse NLP output level (equivalent to IOFLAG in NLP options); 0≤IPNLP≤30.
IPNLP=0 No Output. 0<IPNLP<10 Terse Output. 10≤IPNLP<20 Standard Output. 20≤IPNLP<30 Interpretive Output. 30=IPNLP Diagnostic Output. 10 IPODE Differential equation output level; ; 0≤IPODE≤40.
0≤IPODE<10 No Output. 10≤IPODE<20 Phase end states, max constraint error. 20≤IPODE<30 States/Constraints at every grid point. 30≤IPODE<40 Gradient, Jacobian, and Hessian. 40≤IPODE Debug print at initial point. 0
The non-linear programming options are set in problem.options.NLP.
Table 3: User options for the TOMLAB /SOCS NLP solver.
Option Desription Default Convergence and Termination Tolerances CONTOL Constraint tolerance. є 1/2 OBJTOL Objective function tolerance. 10−7 PGDTOL Projected gradient tolerance. 10−5 MAXNFE Maximum number of function evaluations. 10000 NITMAX Maximum number of iterations. 100 NITMIN Minimum number of iterations. 0 Line Search IT1MAX Maximum number of steps for line search. 20 SLPTOL Slope tolerance δs for line search during optimization phase, where 10−5 < δs < 1. (SQP Only) 0.9 SFZTOL Slope tolerance δs for line search during feasibility phase, where 10−5 < δs < 1. (SQP Only) 0.01 Dense Algorithm Options The following inputs can be used to control the calculation of gradient and Hessian information for the dense algorithms HDNLPD, HDBNPD, HDNLPR and HDBNPR EPSRLF Relative perturbation size parameter, єR. The forward difference perturbation size is δF = (1 + |x|)|єR|.9 and the central difference perturbation size is δC = (1 + |x|)|єR|.6. For analytic functions it is appropriate to set єR = є1 /2 where є = machine epsilon. For EPSRLF ≥ є1 /2 finite difference perturbation sizes are fixed for all iterations. For EPSRLF ≤ −є1 /2 finite difference perturbation sizes are adjusted from iteration to iteration to minimize the finite difference error. EPSRLF is only used by the forward communication algorithm HDNLPD. є1 /2 IHESHN Hessian matrix evaluation option; 0≤ |IHESHN| ≤3. When IHESHN ≤ 0, the Hessian diagonal elements are initialized to finite difference estimates.
IHESHN=0 Finite difference or analytic. IHESHN=1 SR1 (Symmetric Rank One); the default for HDNLPD. IHESHN=2 BFGS (Symmetric Positive Definite). IHESHN=3 SSQN (Self-Scaling Quasi-Newton). 0 Barrier Algorithm Options The following control the behavior of the barrier algorithms HDBNPD, HDBNPR, HDBNLP and HDBLPQ. BIGCON Upper Bound on Equality Constraint Error. 100 FEATOL Initial Variable Offset for Feasibility. .001 PMULWR Lower Bound on Initial Barrier Parameter. .1 PTHTOL Central Path Convergence Tolerance. 10 RHOLWR Lower Bound on Initial Relaxation Parameter. ρ 100 IMAXMU Maximum Number of Iterations Nu with Fixed Barrier Parameter. 10 MUCALC Barrier/Multiplier Initialization Option.; MUCALC 1,± 2, ± 3. There are three basic options where the symbol ∼ denotes the minimum norm least squares solution. Option 1 (MUCALC = 1). Solve
µ = PMULWR λ = µ Db−1 e CTη ∼ g − BTλ. Option 2 (MUCALC = ± 2). Solve
CT BTDb−1 e
η µ
∼ g
λ = max[µ, PMULWR ]Db−1 e. If MUCALC = 2 and µ < PMULWR, recompute using Option 1.
Option 3 (MUCALC = ± 3). Solve
CT BT 0 0 Db −e
η λ µ
∼
g 0
λ = max[є, λ]. where є = machine epsilon. If MUCALC = 3 and µ < PMULWR, recompute using Option 1.
3 MXQPIT Maximum Number of Barrier QP Iterations. 1 Algorithm Strategy Control TOLFIL Tolerance used to detect excessive fill in the multifrontal method. A larger value of TOLFIL will permit additional fill. 2 TOLKTC Tolerance for the condition number of the KKT matrix. Iterative refinement is initiated when the condition number exceeds TOLKTC. є−1.6 TOLPVT Multifrontal pivot tolerance used to balance between sparsity and numeric stability. A small value reduces fill, and a large value improves stability. 10−3 IRELAX Constraint relaxation strategy option flag.
IRELAX=0 Do not switch to relaxation strategy. IRELAX=1 Switch to relaxation strategy if necessary to make progress. IRELAX=2 Always use relaxation strategy. (Barrier Only) 1 NEWTON Newton method option flag.
NEWTON=0 Evaluate Hessian as needed to make good progress (not necessarily each optimization iteration). NEWTON=1 Evaluate Hessian on each optimization iteration. NEWTON=2 Do not evaluate Hessian on any iteration. (Barrier Only) 0 ALGOPT Algorithm control option.
ALGOPT=FM Find feasible point then minimize (SQP Default). ALGOPT=FME Find feasible point then minimize with equalities binding. (SQP Only) ALGOPT=M Minimize from the initial point (Barrier Default). ALGOPT=F Find feasible point only. ALGOPT=MWRM Minimize from the initial point (warm start). (SQP Only) ALGOPT=MHOT Minimize from the initial point (hot start). (SQP Only) ALGOPT=FWRM Find feasible point only (warm start). (SQP Only) ALGOPT=FHOT Find feasible point only (hot start). (SQP Only) ALGOPT=LLSQ Linear Least Squares (only valid for HDSLSQ). FM KTOPTN KKT Matrix Factorization option.
KTOPTN=SMALL Factor KKT matrix consisting of active contraints (SQP Default). This is the default and is recommended for problems with many inequality constraints. Factor the condensed KKT matrix (Barrier Default). KTOPTN=LARGE Factor the augmented KKT matrix with all constraints. SMALL QPOPTN Quadratic Programming Algorithm option.
QPOPTN=SPARSE Solve QP subproblem using sparse Schur-complement method. This is the default for HDSNLP and HDSLSQ. QPOPTN=DENSE Solve QP subproblem using dense null-space method. This is the default for HDNLPD and HDNLPR. (SQP Only) SPARSE Postoptimality Options Additional analysis of the Kuhn-Tucker optimality conditions can be invoked for diagnostic and/or interpretative purposes. This analysis utilizes the rank revealing sparse QR (RRQR) software (cf BCSLIB-EXT), and can be invoked only when QPOPTN=SPARSE. Two types of postoptimality analysis are possible. A first order analysis constructs information using gradient and Jacobian matrices (i.e. first derivative information). A second order analysis constructs information from the Jacobian and Hessian matrices. A second order analysis is performed when the active set and Lagrange multipliers are available, otherwise the analysis is first order. Execution of the postoptimality analysis is controlled by the following option. IPOSTO Postoptimality analysis flag.
IPOSTO=0 No Postoptimality Analysis. IPOSTO=1 Conditional Postoptimality Analysis. An analysis is performed at the final point when the NLP terminates with one of the following (nonstandard) values: IER = −131, −132, −133, +101, +105, +107, +108, +110, +111, +112, +113, +114. IPOSTO=2 Postoptimality Analysis at Termination. An analysis is performed at the final point regardless of the value of IER. IPOSTO=3 Postoptimality Analysis at Initial Point. An analysis is performed at the initial point, and the NLP is terminated with IER = +121. The postoptimality algorithm displays diagnostic information in the print file.
0 Output Control Options IOFLAG Output level.
IOFLAG=0 No Output. 0<IOFLAG<10 Terse Output. 10≤IOFLAG<20 Standard Output. 20≤IOFLAG<30 Interpretive Output. 30=IOFLAG Diagnostic Output.
10
