# SOL NPSOL

## Direct Solver Call

A direct solver call is not recommended unless the user is 100 % sure that no other solvers will be used for the problem. Please refer to #Using TOMLAB for information on how to use NPSOL with TOMLAB.

### Purpose

npsol solves dense nonlinear optimization problems defined as

$\begin{array}{ll} \min\limits_{x} & f(x) \\ & \\ s/t & \begin{array}{lcccl} x_{L} & \leq & x & \leq & x_{U}, \\ b_{L} & \leq & A x & \leq & b_{U} \\ c_{L} & \leq & c(x) & \leq & c_{U} \\ \end{array} \end{array}$

where $x, x_L, x_U \in \mathbb{R}^n$, $f(x) \in \mathbb{R}$, $A \in \mathbb{R}^{m_1 \times n}$, $b_L,b_U \in \mathbb{R}^{m_1}$ and $c_L,c(x),c_U \in \mathbb{R}^{m_2}$.

### Calling Syntax

The file 'funfdf.m' must be defined and contain: function [mode, f, g] = funfdf(x, Prob, mode, nstate) to compute the objective function f and the gradient g at the point x.

The file 'funcdc.m' must be defined and contain: function [mode, c ,dcS] = funcdc(x, Prob, mode, nstate) to compute the nonlinear constraint value c and the constraint Jacobian dcS for the nonlinear constraints at the point x.

[x, Inform, iState, cLamda, iwCount, fObj, gObj, fCon, gCon, H] = npsol( A, bl, bu, x,
Prob, optPar, Warm, H, iState, cLamda, SpecsFile, PrintFile,  SummFile, PriLev, ProbName );


### Description of Inputs

The following fields are used:
AConstraint matrix, m x n. (DENSE).
bl Lower bounds on (x,Ax,c(x)).
bu Upper bounds on (x,Ax,c(x)).
x Initial x vector (n x 1). If Warm start x must correspond to values in H and iState.
Prob Must be a structure. No check is made in the MEX interface.

If TOMLAB calls npsol, then Prob is the standard TOMLAB problem struc- ture, otherwise the user should set:

Prob.P = ProblemNumber, where ProblemNumber is some integer. Two user written routines must be written:

funfdf, actual name stored in Prob.FUNCS.fg, with syntax [mode, f, g] = funfdf(x, Prob, mode, nstate).

funcdc, actual name stored in Prob.FUNCS.cdc, with syntax [mode, c, dc] = funcdc(x, Prob, mode, nstate).

NPSOL is calling the TOMLAB routines nlp fg.m and nlp cdc.m in the call- back, and they call funfdf and funcdc, respectively.

If these fields in Prob are empty (Prob.FUNCS.fg, Prob.FUNCS.cdc), the TOMLAB callback routines calls the usual function routines. Then the Prob struct should be normally defined, and the fields Prob.FUNCS.f, Prob.FUNCS.g, Prob.FUNCS.c, Prob.FUNCS.dc be set in the normal way (e.g. by the routine mFiles.m, or one of the Assign-routines like conAssign.m).

If the mode parameter is 0, funfdf should return f, otherwise both f and the gradient vector g. If the mode parameter is 0, funcdc should return c, otherwise both c and dc. Note that each row in dc corresponds to a constraint, and that dc should be a dense matrix. If the matrix dc is returned as a sparse Matlab matrix, nlp cdc will do full(dc) to get a dense matrix.

The user could also write his own versions of the routines nlp fg.m and nlp cdc.m and put them before in the path.

optPar Vector with optimization parameters overriding defaults and the optionally specified SPECS file. Set empty if only using default parameters.
Warm Flag for Warm start (==1) or Cold Start (==0 ), i.e. normal mode. If 'WarmStart', iState, cLamda, H and x must supply correct values.
H Hessian matrix, only accessed if Warm start. Must select: Hessian = Yes in order to do a warm start. Hessian Yes is equivalent to optPar(50) = 1 (default is 0).
iState Working set (if Warm start) (nb = n+nclin+ncnln) x 1 (DENSE). If length(iState) < nb, setting iState(1:nb)=0;

iState(i)=0: Corresponding constraint not in the initial working set.

iState(i)=1: Inequality constraint at its lower bound in working set.

iState(i)=2: Inequality constraint at its upper bound in working set.

iState(i)=3: Equality constraint in the initial working set, bl(i)==bu(i).

cLamda Lagrangian multipliers for the n + nclin + ncnln constraints. If Warm start, cLamda(n+nclin+1:n+nclin+ncnln), the nonlinear Lagrange multipliers, must correspond to values in iState.
SpecsFile Name of the input parameter file, see TOMLAB Guide.
PrintFile Name of the Print file. Name includes the path, maximal number of characters = 500.
SummFile Name of the Summary file. Name includes the path, maximal number of characters = 500.
PriLev Print level in the npsol MEX-interface.

= 0 Silent

= 10 Dimensions are printed.

ProbName Name of the problem. ¡=100 characters are used in the MEX interface. (Not used by MEX-interface).

### Description of Outputs

The following fields are used:
x Solution vector (n by 1) with n decision variable values.
Inform Result of NPSOL run.

0 = Optimal solution found.

1 = Optimal solution found but not to requested accuracy.

2 = No feasible point for the linear constraints.

3 = No feasible point for the nonlinear constraints.

4 = Too many major iterations.

6 = The current point cannot be improved on.

7 = Large errors found in the derivatives.

9 = An input parameter is invalid. Other = User requested termination

iState Status of working set, se input description of iState.
cLamda Lagrangian multipliers (dual solution vector) (m x 1 vector).
iwCount Number of iterations (iwCount(1)), function evaluations (iwCount(2)) and constraint evaluations (iwCount(3)).
fObj Objective function value at optimum. gObj Gradient of the nonlinear objective.
fCon Nonlinear constraint vector.
gCon Gradient matrix of the nonlinear constraint vector.
H Cholesky factor of Hessian approximation. Hessian no-reordered variables. Hessian yes - natural order of variables, used for Warm start.

## Using TOMLAB

### Purpose

npsolTL solves dense nonlinear optimization problems defined as

$\begin{array}{ll} \min\limits_{x} & f(x) \\ & \\ s/t & \begin{array}{lcccl} x_{L} & \leq & x & \leq & x_{U}, \\ b_{L} & \leq & A x & \leq & b_{U} \\ c_{L} & \leq & c(x) & \leq & c_{U} \\ \end{array} \end{array}$

where $x, x_L, x_U \in \mathbb{R}^n$, $f(x) \in \mathbb{R}$, $A \in \mathbb{R}^{m_1 \times n}$, $b_L,b_U \in \mathbb{R}^{m_1}$ and $c_L,c(x),c_U \in \mathbb{R}^{m_2}$.

### Calling Syntax

Using the driver routine tomRun :

Prob = ''o''Assign( ... );
Result = tomRun('npsol', Prob ... );


### Description of Inputs

Prob, The following fields are used:
x_L, x_UBounds on variables.
b_L, b_UBounds on linear constraints.
c_L, c_UBounds on nonlinear constraints. A Linear constraint matrix.
PriLevOptPrint level.
WarmStartIf true, use warm start, otherwise cold start.
SOL.xsSolution from previous run, elements xs[1:n].
SOL.iStateWorking set (if Warm start) (n+m) x 1 (DENSE) If length(iState) ¡ n+m, setting iState(1:n+m)=0;

iState(i)=0: Corresponding constraint not in the initial QP working set.

iState(i)=1: Inequality constraint at its lower bound in QP working set.

iState(i)=2: Inequality constraint at its upper bound in QP working set.

iState(i)=3: Equality constraint in the initial QP working set, bl(i)==bu(i).

SOL.cLamdaLagrangian multipliers (dual solution vector) (nb x 1 vector).
SOL.HCholesky factor of Hessian approximation Hessian no - reordered variables. Hessian yes - natural order of variables, used for Warm start.
SOL.SpecsFile Name of user defined SPECS file, read BEFORE optPar() is used.
SOL.PrintFile Name of SOL Print file. Amount and type of printing determined by SPECS parameters or optPar parameters.
SOL.SummFile Name of SOL Summary File.
SOL.optPar Elements > -999 takes precedence over corresponding TOMLAB params. See Table 50.

### Description of Outputs

Result, The following fields are used:
ResultThe structure with results (see ResultDef.m).
f_k Function value at optimum.
x_k Solution vector.
x_0 Initial solution vector.
c_k Nonlinear constraint residuals.
xStateState of variables. Free == 0; On lower == 1; On upper == 2; Fixed == 3;
bStateState of linear constraints. Free == 0; Lower == 1; Upper == 2; Equality == 3;
cStateState of nonlinear constraints. Free == 0; Lower == 1; Upper == 2; Equality == 3;
v_kLagrangian multipliers (for bounds + dual solution vector).
ExitFlagExit status from npsol.m (similar to TOMLAB).
Inform NPSOL information parameter.

0 = Optimal solution found.

1 = Optimal solution found but not to requested accuracy.

2 = No feasible point for the linear constraints.

3 = No feasible point for the nonlinear constraints.

4 = Too many major iterations.

6 = The current point cannot be improved on.

7 = Large errors found in the derivatives.

9 = An input parameter is invalid. Other = User requested termination

rcReduced costs. If ninf=0, last m == -v k.
IterNumber of iterations.
FuncEvNumber of function evaluations.
ConstrEvNumber of constraint evaluations.
QP.B Basis vector in TOMLAB QP standard.
MinorIterNumber of minor iterations.
SolverName of the solver (npsol).
SolverAlgorithmDescription of the solver.
SOL.xSolution vector (n by 1) with n decision variable values.
SOL.iStatebasis status of constraints + variables, (m + n x 1 vector). State of variables:

0=nonbasic (on bl), 1=nonbasic (on bu), 2=superbasic (between bounds),

3=basic (between bounds).

SOL.cLamdaLagrangian multipliers (dual solution vector) (m x 1 vector).
SOL.HCholesky factor of Hessian approximation. Hessian no - reordered variables. Hessian yes - natural order of variables, used for Warm start.

## optPar

### Description

Use missing value (-999 or less), when no change of parameter setting is wanted. The default value will then be used by NPSOL, if not the value is altered in the SPECS file (input SpecsFile).

### Description of Inputs

#### Table: The following fields are used:

#SPECS keyword text Lower Default Upper Comment
Printing
1.PRINT LEVEL

or MAJOR PRINT LEVEL

0100,1,5,10,20,30
2.MINOR PRINT LEVEL000,1,5,10,20,30
Convergence Tolerances
9.NONLINEAR FEASIBILITY TOLERANCE> 01.1E-8sqrt(eps)
10.OPTIMALITY TOLERANCE> 03.0E-13eps0.8
11.LINEAR FEASIBILITY TOLERANCE> 01.1E-8sqrt(eps)
Derivative checking
13.VERIFY LEVEL-1-13-1,0,1,2,3
14.START OBJECTIVE CHECK AT COL01n
15.STOP OBJECTIVE CHECK AT COL0nn
16.START CONSTRAINT CHECK AT COL01n
17.STOP CONSTRAINT CHECK AT COL0nn
Other Tolerances
21.CRASH TOLERANCE

Note: Decision variables will be set to the closest bound to the starting point based on this tolerance before running the optimization.

> 00.01< 1
22.LINESEARCH TOLERANCE> 00.9< 1
30.ITERATIONS LIMIT> 0max(50,3(n+m_L)+10*m_N)
36.MINOR ITERATIONS LIMIT> 0max(50,3(n+m_L+m_N))
37.STEP LIMIT> 02
39.DERIVATIVE LEVEL

Is set by npsolTL dependent on Prob.ConsDiff, Prob.NumDiff

0330,1,2,3
41.FUNCTION PRECISION> 03.0E-13eps0.8 = epsR
42.DIFFERENCE INTERVAL> 05.48E-8eps0.4
43.CENTRAL DIFFERENCE INTERVAL> 06.70E-5eps0.8/3
45.INFINITE STEP SIZE> 0max(BIGBND,1E10)
46.INFINITE BOUND SIZE> 01E10= BIGBND
50.HESSIAN YES or NO001 = YES