Purpose
Usage
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 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 Mfile (Mfunction)
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 Mfile (Mfunction)
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 Mfile (Mfunction)
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 Mfile (Mfunction)
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)
options(7)

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 ndimensional 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
userdefined 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 
Synopsis:
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 ndimensional 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). 
Notes:
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.
No function name and/or starting point passed to the function. (Matlab specific)
Check the call to the function solvopt.m.
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.
Function value does not exist (NaN is returned). (Matlab
specific)
Function equals infinity at the point.
Choose another starting point.
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.
<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.
<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.
The following warning messages may be printed during a run to inform the user on irregular cases:
Ravine with a flat bottom is detected.
Rerun 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 resetting of a transformation matrix.
Resetting due to the use of a new penalty coefficient.
Calls
Examples