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:

FORTRAN:

C:

Language specific descriptions

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

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

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.

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(),
double options[],
double far func(),

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:

1. The user must include the directive
#include <solvopt.h>
to the calling C-function.
2. 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 )

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)

<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