Language Reference

Nonlinear Optimization and Related Subroutines

The following list shows the syntax for nonlinear optimization subroutines. Subsequent sections describe each subroutine in detail.

  • conjugate gradient optimization method: CALL NLPCG (rc, xr, "fun", x0 <*>, opt <*>, blc <*>, tc <*>, par <*>, "ptit" <*>, "grd" );

  • double-dogleg optimization method: CALL NLPDD (rc, xr, "fun", x0 <*>, opt <*>, blc <*>, tc <*>, par <*>, "ptit" <*>, "grd" );

  • Nelder-Mead simplex optimization method: CALL NLPNMS (rc, xr, "fun", x0 <*>, opt <*>, blc <*>, tc <*>, par <*>, "ptit" <*>, "nlc" );

  • Newton-Raphson optimization method: CALL NLPNRA (rc, xr, "fun", x0 <*>, opt <*>, blc <*>, tc <*>, par <*>, "ptit", <*>, "grd" <*>, "es" );

  • Newton-Raphson ridge optimization method: CALL NLPNRR (rc, xr, "fun", x0 <*>, opt <*>, blc <*>, tc <*>, par <*>, "ptit" <*>, "grd" <*>, "hes" );

  • (dual) quasi-Newton optimization method: CALL NLPQN (rc, xr, "fun", x0 <*>, opt <*>, blc <*>, tc <*>, par <*>, "ptit" <*>, "grd" <*>, "nlc" <*>, "jacnlc" );

  • quadratic optimization method: CALL NLPQUA (rc, xr, quad, x0 <, opt> <*>, blc <*>, tc <*>, par <*>, "ptit" <*>, lin );

  • trust-region optimization method: CALL NLPTR (rc, xr, "fun", x0 <*>, opt <*>, blc <*>, tc <*>, par <*>, "ptit" <*>, "grd" <*>, "hes" );

The following list shows the syntax for optimization subroutines that use least squares methods. Subsequent sections describe each subroutine in detail.

  • hybrid quasi-Newton least squares methods: CALL NLPHQN (rc, xr, "fun", x0, opt <, blc> <*>, tc <*>, par <*>, "ptit" <*>, "jac" );

  • Levenberg-Marquardt least squares method: CALL NLPLM (rc, xr, "fun", x0, opt <*>, blc <*>, tc <*>, par <*>, "ptit" <*>, "jac" );

The following list shows the syntax for supplementary subroutines that are often used in conjunction with optimization subroutines. Subsequent sections describe each subroutine in detail.

  • approximate derivatives by finite differences: CALL NLPFDD (f, g, h, "fun", x0 <*>, par <*>, "grd" );

  • feasible point subject to constraints: CALL NLPFEA (xr, x0, blc <*>, par );

Note: The names of the optional arguments can be used as keywords. For example, the following statements are equivalent: 

call nlpnrr(rc,xr,"fun",x0,,,ter,,,"grad");
call nlpnrr(rc,xr,"fun",x0) tc=ter grd="grad";

All the optimization subroutines require at least two input arguments:

  • The NLPQUA subroutine requires the quad matrix argument, which specifies the symmetric matrix $\mb{G}$ of the quadratic problem. The input can be dense or sparse.

  • Other optimization subroutines require the "fun" argument, which specifies a module that defines the objective function or functions. For least squares subroutines, the FUN module must return a column vector of length m that corresponds to the values of the m functions $f_1(x),\ldots ,f_ m(x)$, each evaluated at the point $x=(x_1,\ldots ,x_ n)$. For other subroutines, the FUN module must return the value of the objective function $f=f(x)$ evaluated at the point x.

  • The argument x0 specifies a row vector that defines the number of parameters n. If x0 is a feasible point, it represents a starting point for the iterative optimization process. Otherwise, a linear programming algorithm is called at the start of each optimization subroutine to replace the input x0 by a feasible starting point.

The other arguments that can be used as input are described in the following list. As indicated in the previous lists, not all input arguments apply to each subroutine.

Note that you can specify optional arguments with the keyword=argument syntax.

The following list describes each argument:

opt

indicates an options vector that specifies details of the optimization process, such as particular updating techniques and whether the objective function is to be maximized instead of minimized. See the section Options Vector for details.

blc

specifies a constraint matrix that defines lower and upper bounds for the n parameters in addition to general linear equality and inequality constraints. For details, see the section Parameter Constraints.

tc

specifies a vector of thresholds that correspond to the termination criteria tested in each iteration. See the section Termination Criteria for details.

par

specifies a vector of control parameters that can be used to modify the algorithms if the default settings do not complete the optimization process successfully. For details, see the section Control Parameters Vector.

"ptit"

specifies a module that replaces the subroutine used to print the iteration history and test the termination criteria. If the "ptit" module is specified, the matrix specified by the tc argument has no effect. See the section Termination Criteria for details.

"grd"

specifies a module that computes the gradient vector, $g = \nabla f$, at a given input point x. See the section Objective Function and Derivatives for details.

"hes"

specifies a module that computes the $n \times n$ Hessian matrix, $\mb{G} = \nabla ^2 f$, at a given input point x. See the section Objective Function and Derivatives for details.

"jac"

specifies a module that computes the $m \times n$ Jacobian matrix, $\mb{J} = (\nabla f_ i)$, of the m least squares functions at a given input point x. See the section Objective Function and Derivatives for details.

"nlc"

specifies a module that computes general equality and inequality constraints. This is the method by which nonlinear constraints must be specified. For details, see the section Parameter Constraints.

"jacnlc"

specifies a module that computes the Jacobian matrix of first-order derivatives of the equality and inequality constraints specified by the NLC module. For details, see the section Parameter Constraints.

lin

specifies the linear part of the quadratic optimization problem. See the section NLPQUA Call for details.

The modules that can be used as input arguments for the subroutines ("fun," "grd," "hes," "jac," "ptit," "nlc," and "jacnlc") accept only a single input parameter $x=(x_1,\ldots ,x_ n)$. You can provide more input parameters for these modules by using the GLOBAL clause. See the section Using the GLOBAL Clause for an example.

All the optimization subroutines return the following results:

  • The scalar return code rc indicates the reason for the termination of the optimization process. A return code rc $ > 0$ indicates a successful termination that corresponds to one of the specified termination criteria. A return code rc $ < 0$ indicates unsuccessful termination—that is, that the result xr is unreliable. See the section Definition of Return Codes for more details.

  • The row vector xr, which has length n, contains the optimal point when rc $>0$.