SolvOpt 1.1. Reference Manual: SOLVOPT function

solvopt

Purpose

Find a local optimum for a nonlinear (non-smooth) continuous function or solve a nonlinear optimization problem in the standard form (NLP)

Usage

Matlab:
[x,f,options] = solvopt(x,fun,grad, options,func,gradc)

FORTRAN:
call solvopt(n,x,f,fun,flg,grad,options,flfc,func,flgc,gradc)

C:
f = solvopt ( n,x,fun,grad,options,func,gradc );

Language specific descriptions

The algorithm is described in Description of the algorithm (see the complete manual).

Matlab

The necessary parameters to the function are boldface, the optional ones are normalface.

x is a vector (row or column) of the coordinates of the starting point.
fun provides the name (valid character string) of the M-file (M-function) that returns the objective function value f at a point x (f may also take the values Inf, -Inf, NaN).
Synopsis: f=fun(x)
grad provides the name (valid character string) of the M-file (M-function) that returns the gradient vector g (row or column) of an objective function at a point x (g may also take the values Inf, -Inf, NaN).
Synopsis: g=grad(x)
func provides the name (valid character string) of the M-file (M-function) that returns the maximal residual fc for a set of constraints at a point x (fc may not take the values Inf, -Inf, NaN). By passing this parameter to the solver, the user specifies the constrained optimization mode.
Synopsis: fc=func(x)
gradc provides the name (valid character string) of the M-file (M-function) that returns the gradient vector gc (row or column) of a constraint function with the maximal residual at a point x (gc may not take the values Inf, -Inf, NaN, it also may not be zero at an infeasible point).
Synopsis: gc=gradc(x)
options is a vector of the optional parameters:
options(1)
controls the specific optimization mode and provides a factor for the first trial step size (minimization if sign(options(1))=-1, maximization if sign(options(1))=1). The default value is -1. Exception: Maximization is not allowed for a constrained problem.
options(2)
is the relative error for the argument at the solution point in terms of max-norm (=1.e-4 by default).
options(3)
is the required relative error for the objective function value at the solution (=1.e-6 by default).
options(4)
is a limit for the number of iterations (=15000 by default).
options(5)
controls the output during the optimization process: 0 means that no intermediate results are displayed, -1 means no output (suppresses error and warning messages), N means that the results for each N-th iteration are displayed. The default value is 0.
options(6)
is the upper bound admissible value for the maximal residual of a set of constraints. This means that if the maximal residual at a point is less then options(6), the point is assumed to be feasible. The default is 1.e-8.
Changing the following is somewhat delicate:
options(7)
is the coefficient of space dilation (=2.5 by default)
options(8)
is the relative lower bound for the step size used in the difference approximation of gradients. (=1.e-11 by default).

Values to be returned:
x is the solution point (row or column, depending on how the routine is called).
f is the value of the objective function at the solution point.
options returns the values of the following counters: options(9), the number of iterations made, options(9)<0 means that the termination was abnormal and provides a specific termination code (these codes are listed below),
options(10), the number of objective function evaluations,
options(11), the number of gradient evaluations for the objective function,
options(12), the number of constraints evaluations (equals to options(10)),
options(13), the number of gradient evaluations for the constraints.

More information on the use of the optional parameters may be found in the section Parameters as arguments (see also Default parameter settings) of the Tutorial. As the routine solvopt passes to both the <fun> and the <grad> M-functions only the current point x, one has to use Matlab global declaration to pass the needed parameters to these M-functions. One can find an example of the use of global constants in the section Examples of the Tutorial. One cannot pass to solvopt any other string, except the names of M-functions, by arguments fun or grad. The routine solvopt cannot be used for optimization of expressions if they are passed to the routine as arguments.

FORTRAN

n is the number of variables.
Type: integer
x is an n-dimensional vector of the coordinates of the starting point at a call to the subroutine and the optimizer at a regular return.
Type: double precision
f is the objective function value at the solution point at a regular return. Type: double precision
fun provides the entry name to the subroutine that calculates the objective function value f at a point x. If the absolute value of f is greater then 1.d100, it is assumed (+|-) infinity. The actual entry name, which is passed as a parameter to the solver, must be declared as external in the calling routine.
Synopsis:
subroutine fun(x,f)
double precision f
flg is a flag pointing to the way the gradient of the objective function is calculated: .true. means that the gradients are calculated analytically by use of subroutine <grad>, .false. means that the gradients are approximated by the finite differences.
Type: logical
grad provides the entry name to the subroutine that calculates the gradient g of the objective function value at a point x. The actual entry name, which is passed as a parameter to the solver, must be declared as external in the calling routine. If analytically calculated gradients are not supplied, the entry name null is used at a call to the solver.
Synopsis:
subroutine grad(x,g)
double precision g(*)
flfc is a flag used to indicate the constrained optimization mode: .true. means that the problem is constrained and the maximal residual of a set of constraints is calculated in the subroutine <func>, .false. means that the problem is unconstrained or the user-defined penalty function is minimized.
Type: logical
func provides the entry name to the subroutine that calculates the maximal residual fc for a set of constraints at a point x. The actual entry name, which is passed as a parameter to the solver, must be declared as external in the calling routine. If the problem is unconstrained, the entry name null is used at a call to the solver.
Synopsis:
subroutine func(x,fc)
double precision fc
flgc is a flag pointing to the way the gradients of constraints are calculated: .true. means that the gradients are calculated analytically by use of subroutine <gradc>, .false. means that the gradients are approximated by the finite differences. flgc may not take the value .true., if flfc=.false..
Type: logical
gradc provides the entry name to the subroutine that calculates the gradient gc of the constraint function with the maximal residual at a point x. The actual entry name, which is passed as a parameter to the solver, must be declared as external in the calling routine. If analytically calculated gradients are not supplied, the entry name null is used at a call to the solver.
Synopsis:
subroutine gradc(x,gc)
double precision gc(*)
options is a vector of the optional parameters. See the description of the elements in the Matlab specific section.
Type: double precision

More information on the use of the optional parameters may be found in the section Parameters as arguments (see also Default parameter settings) of the Tutorial. Note: The user must take care about possible domain errors in the FORTRAN intrinsic math-library functions log, log10, sqrt, etc., if they are used in the user's code, to prevent an abnormal stop.

Synopsis:

double solvopt(: unsigned short n,; double x[],; double far fun(),; void far grad(),; double options[],; double far func(),; void far gradc() )

The declaration far is used only in the MS Visual C source code. Using far with any UNIX C compiler will cause an error.

The function solvopt returns the objective function value at the solution.

n is the number of variables.
x is an n-dimensional vector of the coordinates of the starting point at a call to the subroutine and the optimizer at a regular return.
fun provides the entry to the function that calculates the objective function value f at a point x. If the absolute value of f is greater then 1.e100, it is assumed (+|-) infinity. The actual function name, which is passed as a parameter to the solver, must be declared as far in the calling routine, if the MS VC compiler is used.
Synopsis: double fun( double x[])
grad provides the entry to the function that calculates the gradient g of the objective function value at a point x. The actual function name, which is passed as a parameter to the solver, must be declared as far in the calling routine, if the MS VC compiler is used. If analytically calculated gradients are not supplied, the function name null_entry is used at a call to the solver.
Synopsis:void grad(double x[], double g[])
func provides the entry to the function that returns the maximal residual fc for a set of constraints at a point x. The actual function name, which is passed as a parameter to the solver, must be declared as far in the calling routine, if the MS VC compiler is used. If the problem is unconstrained, the function name null_entry is used at a call to the solver.
Synopsis: double func(double x[])
gradc provides the entry to the function that calculates the gradient gc of the constraint function with the maximal residual at a point x. The actual function name, which is passed as a parameter to the solver, must be declared as far in the calling routine, if the MS VC compiler is used. If analytically calculated gradients are not supplied, the entry name null_entry is used at a call to the solver.
Synopsis: void gradc(double x[], double gc[])
options is a vector of the optional parameters. See the description of the elements in the Matlab specific section (take into account that the index starts at 0 in C, therefore, everywhere subtract a unit from the index).

More information on the use of the optional parameters may be found in the section Parameters as arguments (see also Default parameter settings) of the Tutorial.

Notes:

The user must include the directive
#include <solvopt.h>
to the calling C-function.
The user must take care about possible domain errors in the C intrinsic math-library functions log, log10, sqrt, etc., if they are used in the user's code, by providing a function that process these errors and prevents an abnormal stop.

Return codes, error and warning messages

The solver prints an error message at a premature stop, unless printing messages is suppressed by setting options(5) (options(4) in C) to a negative value. It starts with the line

SolvOpt error:

A termination warning message is printed at an abnormal stop (when regular stopping criteria are not fulfilled or the solver detected an irregular case) and starts with the line

SolvOpt: Termination warning:

Warning messages are printed also during the optimization process, when it is worth to warn the user about the case. These messages start with the line

SolvOpt warning:

At a regular return from the solver, the program prints the message

SolvOpt: Normal termination

and returns the number of iteration made in options(9) (options(8) in C).

The return codes are listed below together with the corresponding error and warning messages.

-1:

Allocation Error = number (FORTRAN and C only )
Check the memory available and the parameter n to the solver.

No function name and/or starting point passed to the function. (Matlab specific)

Check the call to the function solvopt.m.

-2:

Improper space dimension. (FORTRAN and C only )
Check the parameter n to the solver.

Argument X has to be a row or column vector of dimension >1. (Matlab specific)
Check the parameter x to the function solvopt.m. The argument must not be a scalar.

-3:

<fun> returns an empty string. (Matlab specific )
Check the M-function <fun>.

Function value does not exist (NaN is returned). (Matlab specific)
Function equals infinity at the point.
Choose another starting point.

-4:

<grad> returns an empty string. (Matlab specific )
Check the M-function <grad>.

Gradient does not exist (NaN is returned by <grad>). (Matlab specific)
Gradient equals infinity at the starting point.

Gradient equals zero at the starting point.
Choose another starting point.

-5:

<func> returns an empty string. (Matlab specific )
Check the M-function <func>.

<func> returns NaN at the point. (Matlab specific )
<func> returns infinite value at the point.
Check the routine calculating the maximal residual for a set of constraints.

-6:

<gradc> returns an improper vector. Check the dimension. (Matlab specific)
Check the M-function <gradc>.

<gradc> returns NaN at the point. (Matlab specific )
<gradc> returns infinite vector at the point.
<gradc> returns zero vector at an infeasible point.
Check the routine calculating gradients of the constraints.

-7:

Function is unbounded.
Usually, this means that the user-defined penalty coefficient is smaller then the appropriate one, therefore, the penalty function is not lower bounded.

-8:

Gradient is zero at the point, but stopping criteria are not fulfilled.
This means that the solver fails to pass through a (possibly) flat area. The returned point may not provide the optimizer.

-9:

Iterations limit exceeded.
This may be caused by setting the optional parameter options(4) (options(3) in C) to a number smaller then the default value. If the default value is used, this also may be caused by demanding a very small absolute error for the constraints or by errors in the gradient calculating routine(s). Finally, the default number of iterations may not be sufficiently large for a huge-scaled problem.

-11:

Premature stop is possible. Try to re-run the routine from the obtained point.
The solver returns the code -11 whenever detects a "ravine" with steep walls and a flat bottom, meaning the level surfaces are almost parallel and the two successive gradients are opposite to each other. Neither the solver has managed to pass through a "nasty" area nor it has, the program returns an abnormal code and prints this message. This is done because of the highest difficulty of the case for the solver.

-12:

Result may not provide the optimum. The function apparently has many extremum points.
The solver returns the code -12, if the stopping criteria are fulfilled at a point, which is not the "best" recorded one and sufficiently far from the recorded point. This also may happen, if the objective function is flat at the optimum, but more likely the function has many locally extreme points.

-13:

Result may be inaccurate in the coordinates. The function is flat at the optimum.
The solver returns the code -13, if the stopping criteria are fulfilled at a point, where one or more partial derivatives are zero.

-14:

Result may be inaccurate in a function value. The function is extremely steep at the optimum
The solver returns the code -14, if the stopping criterion (TERMF) is not fulfilled at a point, but the stepsize is approximately zero. This may be caused by the use of a very large penalty coefficient and by inaccurate gradient approximation as well.

The following warning messages may be printed during a run to inform the user on irregular cases:

Ravine with a flat bottom is detected.
Re-run from recorded point.
The function is flat in certain directions.
Trying to recover by shifting insensitive variables.

Finally, the following warnings provide an additional information on a run, but do not point to anything abnormal.

Normal re-setting of a transformation matrix.
Re-setting due to the use of a new penalty coefficient.

Calls

apprgrdn, user-supplied routines <fun>, <func>, <grad> and <gradc>.

Examples

See Tutorial.

Online reference SolvOpt homepage

`x`	is a vector (row or column) of the coordinates of the starting point.
`fun`	provides the name (valid character string) of the M-file (M-function) that returns the objective function value `f` at a point `x` (`f` may also take the values `Inf, -Inf, NaN`). Synopsis: `f=fun(x)`
`grad`	provides the name (valid character string) of the M-file (M-function) that returns the gradient vector `g` (row or column) of an objective function at a point `x` (`g` may also take the values `Inf, -Inf, NaN`). Synopsis: `g=grad(x)`
`func`	provides the name (valid character string) of the M-file (M-function) that returns the maximal residual `fc` for a set of constraints at a point `x` (`fc` may not take the values `Inf, -Inf, NaN`). By passing this parameter to the solver, the user specifies the constrained optimization mode. Synopsis: `fc=func(x)`
`gradc`	provides the name (valid character string) of the M-file (M-function) that returns the gradient vector `gc` (row or column) of a constraint function with the maximal residual at a point `x` (gc may not take the values `Inf, -Inf, NaN`, it also may not be zero at an infeasible point). Synopsis: `gc=gradc(x)`
`options`	is a vector of the optional parameters: `options(1)` controls the specific optimization mode and provides a factor for the first trial step size (minimization if `sign(options(1))=-1`, maximization if `sign(options(1))=1)`. The default value is `-1`. Exception: Maximization is not allowed for a constrained problem. `options(2)` is the relative error for the argument at the solution point in terms of max-norm (=`1.e-4` by default). `options(3)` is the required relative error for the objective function value at the solution (=`1.e-6` by default). `options(4)` is a limit for the number of iterations (=`15000` by default). `options(5)` controls the output during the optimization process: `0` means that no intermediate results are displayed, `-1` means no output (suppresses error and warning messages), `N` means that the results for each `N`-th iteration are displayed. The default value is `0`. `options(6)` is the upper bound admissible value for the maximal residual of a set of constraints. This means that if the maximal residual at a point is less then `options(6)`, the point is assumed to be feasible. The default is `1.e-8`. Changing the following is somewhat delicate: `options(7)` is the coefficient of space dilation (=`2.5` by default) `options(8)` is the relative lower bound for the step size used in the difference approximation of gradients. (=`1.e-11` by default).
Values to be returned:
`x`	is the solution point (row or column, depending on how the routine is called).
`f`	is the value of the objective function at the solution point.
`options`	returns the values of the following counters: `options(9)`, the number of iterations made, `options(9)<0` means that the termination was abnormal and provides a specific termination code (these codes are listed below), `options(10)`, the number of objective function evaluations, `options(11)`, the number of gradient evaluations for the objective function, `options(12)`, the number of constraints evaluations (equals to `options(10)`), `options(13)`, the number of gradient evaluations for the constraints.

`n`	is the number of variables. Type: `integer`
`x`	is an `n`-dimensional vector of the coordinates of the starting point at a call to the subroutine and the optimizer at a regular return. Type: `double precision`
`f`	is the objective function value at the solution point at a regular return. Type: `double precision`
`fun`	provides the entry name to the subroutine that calculates the objective function value `f` at a point `x`. If the absolute value of `f` is greater then `1.d100`, it is assumed (+\|-) infinity. The actual entry name, which is passed as a parameter to the solver, must be declared as `external` in the calling routine. Synopsis: `subroutine fun(x,f)` `double precision f`
`flg`	is a flag pointing to the way the gradient of the objective function is calculated: `.true.` means that the gradients are calculated analytically by use of subroutine `<grad>`, `.false.` means that the gradients are approximated by the finite differences. Type: `logical`
`grad`	provides the entry name to the subroutine that calculates the gradient `g` of the objective function value at a point `x`. The actual entry name, which is passed as a parameter to the solver, must be declared as `external` in the calling routine. If analytically calculated gradients are not supplied, the entry name `null` is used at a call to the solver. Synopsis: `subroutine grad(x,g)` `double precision g(*)`
`flfc`	is a flag used to indicate the constrained optimization mode: `.true.` means that the problem is constrained and the maximal residual of a set of constraints is calculated in the subroutine `<func>`, `.false.` means that the problem is unconstrained or the user-defined penalty function is minimized. Type: `logical`
`func`	provides the entry name to the subroutine that calculates the maximal residual `fc` for a set of constraints at a point `x`. The actual entry name, which is passed as a parameter to the solver, must be declared as `external` in the calling routine. If the problem is unconstrained, the entry name `null` is used at a call to the solver. Synopsis: `subroutine func(x,fc)` `double precision fc`
`flgc`	is a flag pointing to the way the gradients of constraints are calculated: `.true.` means that the gradients are calculated analytically by use of subroutine `<gradc>`, `.false.` means that the gradients are approximated by the finite differences. `flgc` may not take the value `.true.`, if `flfc=.false.`. Type: `logical`
`gradc`	provides the entry name to the subroutine that calculates the gradient `gc` of the constraint function with the maximal residual at a point `x`. The actual entry name, which is passed as a parameter to the solver, must be declared as `external` in the calling routine. If analytically calculated gradients are not supplied, the entry name `null` is used at a call to the solver. Synopsis: `subroutine gradc(x,gc)` `double precision gc(*)`
`options`	is a vector of the optional parameters. See the description of the elements in the Matlab specific section. Type: `double precision`

`n`	is the number of variables.
`x`	is an `n`-dimensional vector of the coordinates of the starting point at a call to the subroutine and the optimizer at a regular return.
`fun`	provides the entry to the function that calculates the objective function value `f` at a point `x`. If the absolute value of `f` is greater then `1.e100`, it is assumed (+\|-) infinity. The actual function name, which is passed as a parameter to the solver, must be declared as `far` in the calling routine, if the MS VC compiler is used. Synopsis: `double fun( double x[])`
`grad`	provides the entry to the function that calculates the gradient `g` of the objective function value at a point `x`. The actual function name, which is passed as a parameter to the solver, must be declared as `far` in the calling routine, if the MS VC compiler is used. If analytically calculated gradients are not supplied, the function name `null_entry` is used at a call to the solver. Synopsis:`void grad(double x[], double g[])`
`func`	provides the entry to the function that returns the maximal residual `fc` for a set of constraints at a point `x`. The actual function name, which is passed as a parameter to the solver, must be declared as `far` in the calling routine, if the MS VC compiler is used. If the problem is unconstrained, the function name `null_entry` is used at a call to the solver. Synopsis: `double func(double x[])`
`gradc`	provides the entry to the function that calculates the gradient `gc` of the constraint function with the maximal residual at a point `x`. The actual function name, which is passed as a parameter to the solver, must be declared as `far` in the calling routine, if the MS VC compiler is used. If analytically calculated gradients are not supplied, the entry name `null_entry` is used at a call to the solver. Synopsis: `void gradc(double x[], double gc[])`
`options`	is a vector of the optional parameters. See the description of the elements in the Matlab specific section (take into account that the index starts at 0 in C, therefore, everywhere subtract a unit from the index).