api/nlopt_minimize.3

   1 .\"
   2 .\" Copyright (c) 2007 Massachusetts Institute of Technology
   3 .\"
   4 .\" Copying and distribution of this file, with or without modification,
   5 .\" are permitted in any medium without royalty provided the copyright
   6 .\" notice and this notice are preserved.
   7 .\"
   8 .TH NLOPT_MINIMIZE 3  2007-08-23 "MIT" "NLopt programming manual"
   9 .SH NAME
  10 nlopt_minimize \- Minimize a multivariate nonlinear function
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <nlopt.h>
  14 .sp
  15 .BI "nlopt_result nlopt_minimize(nlopt_algorithm " "algorithm" ,
  16 .br
  17 .BI "                            int " "n" ,
  18 .BI "                            nlopt_func " "f" ,
  19 .BI "                            void* " "f_data" ,
  20 .BI "                            const double* " "lb" ,
  21 .BI "                            const double* " "ub" ,
  22 .BI "                            double* " "x" ,
  23 .BI "                            double* " "fmin" ,
  24 .BI "                            double " "fmin_max" ,
  25 .BI "                            double " "ftol_rel" ,
  26 .BI "                            double " "ftol_abs" ,
  27 .BI "                            double " "xtol_rel" ,
  28 .BI "                            const double* " "xtol_abs" ,
  29 .BI "                            int " "maxeval" ,
  30 .BI "                            double " "maxtime" );
  31 .sp
  32 You should link the resulting program with the linker flags
  33 -lnlopt -lm on Unix.
  34 .fi
  35 .SH DESCRIPTION
  36 .BR nlopt_minimize ()
  37 attempts to minimize a nonlinear function
  38 .I f
  39 of
  40 .I n
  41 design variables using the specified
  42 .IR algorithm .
  43 The minimum function value found is returned in
  44 .IR fmin ,
  45 with the corresponding design variable values stored in the array
  46 .I x
  47 of length
  48 .IR n .
  49 The inputs
  50 .I lb
  51 and
  52 .I ub
  53 are arrays of length
  54 .I n
  55 containing lower and upper bounds, respectively, on the design variables
  56 .IR x .
  57 The other parameters specify stopping criteria (tolerances, the maximum
  58 number of function evaluations, etcetera) and other information as described
  59 in more detail below.  The return value is a integer code indicating success
  60 (positive) or failure (negative), as described below.
  61 .PP
  62 By changing the parameter
  63 .I algorithm
  64 among several predefined constants described below, one can switch easily
  65 between a variety of minimization algorithms.  Some of these algorithms
  66 require the gradient (derivatives) of the function to be supplied via
  67 .IR f ,
  68 and other algorithms do not require derivatives.  Some of the
  69 algorithms attempt to find a global minimum within the given bounds,
  70 and others find only a local minimum (with the initial value of
  71 .I x
  72 as a starting guess).
  73 .PP
  74 The
  75 .B nlopt_minimize
  76 function is a wrapper around several free/open-source minimization packages.
  77 You could, of course, compile and call these packages separately, and in
  78 some cases this will provide greater flexibility than is available via the
  79 .B nlopt_minimize
  80 interface.  However, depending upon the specific function being minimized,
  81 the different algorithms will vary in effectiveness.  The intent of
  82 .B nlopt_minimize
  83 is to allow you to quickly switch between algorithms in order to experiment
  84 with them for your problem, by providing a simple unified interface to
  85 these subroutines.
  86 .SH OBJECTIVE FUNCTION
  87 .BR nlopt_minimize ()
  88 minimizes an objective function
  89 .I f
  90 of the form:
  91 .sp
  92 .BI "      double f(int " "n" ,
  93 .br
  94 .BI "               const double* " "x" ,
  95 .br
  96 .BI "               double* " "grad" ,
  97 .br
  98 .BI "               void* " "f_data" );
  99 .sp
 100 The return value should be the value of the function at the point
 101 .IR x ,
 102 where
 103 .I x
 104 points to an array of length
 105 .I n
 106 of the design variables.  The dimension
 107 .I n
 108 is identical to the one passed to
 109 .BR nlopt_minimize ().
 110 .sp
 111 In addition, if the argument
 112 .I grad
 113 is not NULL, then
 114 .I grad
 115 points to an array of length
 116 .I n
 117 which should (upon return) be set to the gradient of the function with
 118 respect to the design variables at
 119 .IR x .
 120 That is,
 121 .IR grad[i]
 122 should upon return contain the partial derivative df/dx[i],
 123 for 0 <= i < n, if
 124 .I grad
 125 is non-NULL.
 126 Not all of the optimization algorithms (below) use the gradient information:
 127 for algorithms listed as "derivative-free," the
 128 .I grad
 129 argument will always be NULL and need never be computed.  (For
 130 algorithms that do use gradient information, however,
 131 .I grad
 132 may still be NULL for some calls.)
 133 .sp
 134 The
 135 .I f_data
 136 argument is the same as the one passed to
 137 .BR nlopt_minimize (),
 138 and may be used to pass any additional data through to the function.
 139 (That is, it may be a pointer to some caller-defined data
 140 structure/type containing information your function needs, which you
 141 convert from void* by a typecast.)
 142 .SH ALGORITHMS
 143 The
 144 .I algorithm
 145 parameter can take on any of the following values:
 146 .TP
 147 .B NLOPT_GLOBAL_DIRECT
 148 Perform a global derivative-free optimization using the DIRECT search
 149 algorithm by Jones et al., based on the free implementation by Gablonsky
 150 et al.
 151 .SH RETURN VALUE
 152 The value returned is one of the following enumerated constants.
 153 (Positive return values indicate successful termination, while negative
 154 return values indicate an error condition.)
 155 .SH BUGS
 156 Currently the NLopt library is in pre-alpha stage.  Most algorithms
 157 currently do not support all termination conditions: the only
 158 termination condition that is consistently supported right now is
 159 .BR maxeval .
 160 .SH AUTHORS
 161 Written by Steven G. Johnson.
 162 .PP
 163 Copyright (c) 2007 Massachusetts Institute of Technology.