doc/docs/NLopt_Deprecated_API_Reference.md

   1 ---
   2 # NLopt Deprecated API Reference
   3 ---
   4
   5 NLopt is a library, not a stand-alone program—it is designed to be called from your own program in C, C++, Fortran, Matlab, GNU Octave, or other languages. This reference section describes the original programming interface (API) of NLopt, used in versions of NLopt prior to 2.0. This interface is still supported in NLopt 2.0 (and will continue to be supported indefinitely if possible), for backwards compatibility, but is now deprecated in favor of the new object-style API in the [NLopt Reference](NLopt_Reference.md).
   6
   7 The reason why this API is deprecated is that it is not easily extensible. A single optimization function was appropriate when NLopt started out as a library just handling bound constraints, but as more and more optimization parameters were added it became difficult to do this in a backwards-compatible way. (Also, functions with dozens of parameters at some point become unreadable.)
   8
   9 Other sources of information include the Unix [man pages](https://en.wikipedia.org/wiki/Manual_page_(Unix)) for the functions. On Unix, you can run e.g. `man` `nlopt_minimize` for documentation of the `nlopt_minimize` function. In Matlab and GNU Octave, the corresponding command is to type `help` `nlopt_minimize`.
  10
  11 Linking your program to NLopt
  12 -----------------------------
  13
  14 For programs in compiled languages like C or Fortran, when you compile your program you will have to link it to the NLopt library. This is *in addition* to including the header file (`#include` <nlopt.h> in C/C++). On Unix, you would normally link with a command something like:
  15
  16 *`compiler`*` `*`...source/object` `files...`*` -lnlopt -lm -o myprogram`
  17
  18 where *compiler* is `cc`, `f77`, `g++`, or whatever is appropriate for your machine/language.
  19
  20 *Note:* the `-lnlopt` `-lm` options, which link to the NLopt library (and the math library, which it requires), must come *after* your source/object files. In general, the rule is that if *A* depends upon *B*, then *A* must come before *B* in the link command.
  21
  22 *Note:* the above example assumes that you have installed the NLopt library in a place where the compiler knows to find it (e.g. in a standard directory like `/usr/lib` or `/usr/local/lib`). If you installed somewhere else (e.g. in your home directory if you are not a system administrator), then you will need to use a `-L` flag to tell the compiler where to find the library. See [the installation manual](NLopt_Installation#Changing_the_installation_directory.md).
  23
  24 C/C++ programming interface
  25 ---------------------------
  26
  27 To use NLopt from C or C++, you should first include the NLopt header file:
  28
  29 `#include `<nlopt.h>
  30
  31 Then, you should write functions to express your objective and constraints. Finally, you should call the function `nlopt_minimize_constrained` (for nonlinearly constrained optimization) or `nlopt_minimize` (for unconstrained or box-constrained optimization) to perform the optimization. There are also a couple of other utility routines described below.
  32
  33 ### `nlopt_minimize_constrained`
  34
  35 ```
  36 nlopt_result nlopt_minimize_constrained(nlopt_algorithm algorithm,
  37                                         int n,
  38                                         nlopt_func f, void* f_data,
  39                                         int m,
  40                                         nlopt_func fc, void* fc_data, ptrdiff_t fc_datum_size,
  41                                         const double* lb, const double* ub,
  42                                         double* x,
  43                                         double* minf,
  44                                         double minf_max,
  45                                         double ftol_rel, double ftol_abs,
  46                                         double xtol_rel, const double* xtol_abs,
  47                                         int maxeval, double maxtime);
  48 ```
  49
  50
  51 This function attempts to minimize a nonlinear function `f` of `n` optimization parameters, subject to `m` nonlinear constraints described by the function `fc`, using the specified algorithm. The minimum function value found is returned in `minf`, with the corresponding optimization parameter values returned in the array `x` of length `n`. The input values in `x` should be a starting guess for the minimum. The inputs `lb` and `ub` are arrays of length `n` containing lower and upper bounds, respectively, on the design variables `x`. The other parameters specify termination criteria (tolerances, the maximum number of function evaluations, etcetera) and other information described in more detail below. The return value is an integer code indicating success (positive) or failure (negative), as described below.
  52
  53 #### Parameters
  54
  55 The parameters specifying the optimization problem are:
  56
  57 -   `algorithm` — which optimization algorithm to use; its values are one of a set of predefined constants like`NLOPT_LD_MMA`, `NLOPT_GN_DIRECT`, etcetera, as described on the [NLopt Algorithms](NLopt_Algorithms.md) page.
  58 -   `n` — the dimension *n* ≥ 0 of the optimization problem, the number of optimization parameters.
  59 -   `f` — the objective function (see below)
  60 -   `f_data` — a pointer to any data you want to pass to the the objective function (see below)
  61 -   `m` — the number of nonlinear inequality constraints (zero for no such constraints).
  62 -   `fc` — the nonlinear inequality constraint function (see below). Ignored if `m` = 0.
  63 -   `fc_data`, `fc_datum_size` — `fc_data` is a pointer to an array of data to pass to the constraint function `fc`. The array should of length `m`, and each element of the array should have size `fc_datum_size` bytes. (See below for more information on constraint functions.) Ignored if `m` = 0.
  64 -   `lb` — pointer to an array of length `n` of lower bounds on each optimization variable. That is, the optimization variables are constrained to have `x[i]` ≥ `lb[i]`. If you don't want a particular variable to be bounded below, just set the corresponding `lb[i]` to be `-HUGE_VAL`. (`HUGE_VAL` is a standard C constant, usually giving +∞.)
  65 -   `ub` — pointer to an array of length `n` of upper bounds on each optimization variable. That is, the optimization variables are constrained to have `x[i]` ≤ `ub[i]`. If you don't want a particular variable to be bounded above, just set the corresponding `ub[i]` to be `+HUGE_VAL`.
  66
  67 Starting guess and returned optimum:
  68
  69 -   `x` — an array of length `n` of the optimization parameters `x[0]`, ..., `x[n-1]`. On input, a starting guess for the optimum parameters; on output, the best found values of the parameters. (For a *local* optimization routine, the starting guess `x` determines which local optimum is found.) The starting guess is required to satisfy the bound constraints `lb` and `ub`; it need not satisfy the nonlinear inequality constraints `fc` (although it might be more efficient if you have a feasible starting guess.)
  70 -   `minf` — on output, the minimum value of the objective function that was found (corresponding to the output value of the parameters `x`).
  71
  72 The remaining parameters specify the termination conditions. Please read the [introduction to the termination conditions](NLopt_Introduction#Termination_conditions.md) for a general overview of these criteria. (In particular, note that you do *not* need to use *all* of these conditions; typically, you will use only one or two, and set the remainder to innocuous values.)
  73
  74 -   `minf_max` — stop if the objective function value drops below `minf_max`. (Set to `-HUGE_VAL` to ignore.)
  75 -   `ftol_rel`, `ftol_abs` — relative and absolute tolerances in the objective function value. (Set to zero to ignore.)
  76 -   `xtol_rel`, `xtol_abs` — relative and absolute tolerances in the optimization parameter values. `xtol_abs` should either be `NULL`, in which case it is ignored (equivalent to zero tolerance), or otherwise it should point to an array of length `n` containing absolute tolerances in each parameter `x[i]`. Set any tolerance to zero for it to be ignored.
  77 -   `maxeval` — stop if the objective function is evaluated at least `maxeval` times. Set to zero to ignore.
  78 -   `maxtime` — stop if the elapsed wall-clock time, in seconds, exceeds `maxtime`. Set to zero to ignore.
  79
  80 #### Return value
  81
  82 The value returned is one of the following enumerated constants.
  83
  84 Successful termination (positive return values):
  85
  86 -   `NLOPT_SUCCESS` (= +1) — Generic success return value.
  87 -   `NLOPT_MINF_MAX_REACHED` (= +2) — Optimization stopped because `minf_max` (above) was reached.
  88 -   `NLOPT_FTOL_REACHED` (= +3) — Optimization stopped because `ftol_rel` or `ftol_abs` (above) was reached.
  89 -   `NLOPT_XTOL_REACHED` (= +4) — Optimization stopped because `xtol_rel` or `xtol_abs` (above) was reached.
  90 -   `NLOPT_MAXEVAL_REACHED` (= +5) — Optimization stopped because `maxeval` (above) was reached.
  91 -   `NLOPT_MAXTIME_REACHED` (= +6) — Optimization stopped because `maxtime` (above) was reached.
  92
  93 Error codes (negative return values):
  94
  95 -   `NLOPT_FAILURE` (= −1) — Generic failure code.
  96 -   `NLOPT_INVALID_ARGS` (= −2) — Invalid arguments (e.g. lower bounds are bigger than upper bounds, an unknown algorithm was specified, etcetera).
  97 -   `NLOPT_OUT_OF_MEMORY` (= −3) — Ran out of memory.
  98 -   `NLOPT_ROUNDOFF_LIMITED` (= −4) — Roundoff errors led to a breakdown of the optimization algorithm. In this case, the returned minimum may still be useful. (e.g. this error occurs in NEWUOA if one tries to achieve a tolerance too close to machine precision.)
  99
 100 ### `nlopt_minimize`
 101
 102 ```
 103 nlopt_result nlopt_minimize(nlopt_algorithm algorithm,
 104                             int n,
 105                             nlopt_func f, void* f_data,
 106                             const double* lb, const double* ub,
 107                             double* x,
 108                             double* minf,
 109                             double minf_max,
 110                             double ftol_rel, double ftol_abs,
 111                             double xtol_rel, const double* xtol_abs,
 112                             int maxeval, double maxtime);
 113 ```
 114
 115
 116 This function is exactly equivalent to calling `nlopt_minimize_constrained` with `m` = 0. That is, this is minimization with no nonlinear inequality constraints (although there may still be bound constraints `lb` and `ub`).
 117
 118 ### Objective function
 119
 120 You should define your objective function (the function you want to minimize) as a function of the following form:
 121
 122 ```
 123 double f(int n, const double *x, double *grad, void *f_data)
 124 {
 125     ....
 126 }
 127 ```
 128
 129
 130 The return value should be the value of the function at the point **x**, where `x` points to an array of length `n` containing the optimization parameters. (That is, the optimization parameters are `x[0]`, `x[1]`, ..., `x[n-1]`.) The dimension `n` is the same as the one passed to `nlopt_minimize` or `nlopt_minimize_constrained`.
 131
 132 In addition, if the argument `grad` is not `NULL`, then `grad` points to an array of length `n` that should (upon return) be set to the gradient of your function *f* with respect to the design variables *x*. That is, `grad[i]` should upon return contain the partial derivative ∂`f`/∂`x[i]`, for `i`=0,...,`n-1`. Not all of the [optimization algorithms](NLopt_Algorithms.md) use the gradient information: for algorithms listed as "derivative-free," the `grad` argument will always be `NULL` and need never be computed. (For algorithms that do use gradient information, however, `grad` may still be `NULL` for some calls.)
 133
 134 The `f_data` argument is the same as the one passed to `nlopt_minimize` or `nlopt_minimize_constrained`, and may be used to pass any additional data through to the function. (That is, it may be a pointer to some caller-defined data structure/type containing information your function needs, which you convert from `void*` by a typecast.)
 135
 136 ### Nonlinear constraints
 137
 138 The `nlopt_minimize_constrained` function allows you to specify `m` nonlinear constraints via the function `fc`, where `m` is any nonnegative integer. However, nonzero `m` is currently only supported by the `NLOPT_LD_MMA` and `NLOPT_LN_COBYLA` [algorithms](NLopt_Algorithms.md).
 139
 140 In particular, the nonlinear constraints are of the form *fc*(*x*) ≤ 0, where the function fc is of the same form as the objective function described above:
 141
 142 ```
 143 double fc(int n, const double* x, double* grad, void* fc_datum);
 144 ```
 145
 146
 147 The return value should be the value of the constraint function at the point `x` (an array of length `n`), where the dimension `n` is identical to the one passed to `nlopt_minimize_constrained`. As for the objective function, if the argument `grad` is not `NULL`, then `grad` points to an array of length `n` which should (upon return) be set to the gradient of the constraint function with respect to **x**. (For any algorithm listed as "derivative-free", the `grad` argument will always be `NULL` and need never be computed.)
 148
 149 The `fc_datum` argument is based on the `fc_data` argument passed to `nlopt_minimize_constrained`, and may be used to pass any additional data through to the function, and is used to distinguish between different constraints.
 150
 151 In particular, the constraint function `fc` will be called (at most) `m` times for each `x`, and the *i*-th constraint (0 ≤ *i* &lt; *m*) will be passed an `fc_datum` argument equal to `fc_data` offset by *i*⋅`fc_datum_size`. For example, suppose that you have a data structure of type `foo` that describes the data needed by each constraint, and you store the information for the constraints in an array `foo` `data[m]`. In this case, you would pass `data` as the `fc_data` parameter to `nlopt_minimize_constrained`, and `sizeof(foo)` as the `fc_datum_size` parameter. Then, your `fc` function would be called `m` times for each point, and be passed `&data[0]` through `&data[m-1]` in sequence.
 152
 153 ### Mixed global/local search algorithm
 154
 155 Some of the [global optimization algorithms](NLopt_Algorithms#Global_optimization.md) (currently, only MLSL) combine some global search scheme with a separate local optimization algorithm for local searches. For example, MLSL performs a sequence of local searches from semi-random starting points.
 156
 157 Using the following functions, you can control *which* local search algorithm is used for MLSL (and any similar algorithm that is added in the future), as well as specifying a maximum number of function evaluations for the local search:
 158
 159 ```
 160 void nlopt_set_local_search_algorithm(nlopt_algorithm deriv, nlopt_algorithm nonderiv, int maxeval);
 161 ```
 162
 163
 164 Set the local gradient-based search algorithm to `deriv` (default is `NLOPT_LD_MMA`), the local derivative-free search algorithm to `nonderiv` (default is `NLOPT_LN_COBYLA`), and the maximum number of function evaluations on each local search to `maxeval` (default is `-1`, for no maximum). Conversely, you can get the current values of these parameters by calling:
 165
 166 ```
 167 void nlopt_get_local_search_algorithm(nlopt_algorithm *deriv, nlopt_algorithm *nonderiv, int *maxeval)
 168 ```
 169
 170
 171 *Note:* these parameters have no effect on local searches that you perform yourself; they are *only* for local searches that are performed *within* another algorithm like MLSL.
 172
 173 ### Population size for stochastic algorithms
 174
 175 Stochastic (randomized) optimization algorithms are often parameterized by some initial "population" size (a set of sample points where the function is evaluated). NLopt tries to pick a reasonable default value for these population sizes, but in some cases the use may want finer control. This is achieved by the following two functions:
 176
 177 ```
 178 void nlopt_set_stochastic_population(int pop);
 179 int nlopt_get_stochastic_population(void);
 180 ```
 181
 182
 183 which set and get the current (global) setting of the population parameter for stochastic algorithms. The default value of this population parameter is *zero*: a zero population is specially interpreted to mean that the algorithm should choose an algorithm-specific default value. These algorithm-specific defaults are documented with the [algorithms](NLopt_Algorithms.md) that use the population parameter.
 184
 185 Fortran programming interface
 186 -----------------------------
 187
 188 NLopt is callable from Fortran 77 (and later Fortran dialects), via special Fortran-callable wrapper subroutines that are included in the NLopt library.
 189
 190 Although the functionality is the same as that of the C routines, the Fortran routines have different names and the arguments are passed in slightly different ways, as explained below.
 191
 192 The most noticeable difference is that all function return values in C are changed into the first argument in Fortran, because there is no portable way to call C functions that return a value from Fortran or vice versa. The other noticeable difference is that, because there is no (portable) way to pass `NULL` in Fortran, any C argument that can optionally be `NULL` is converted to two arguments in Fortran, where the second argument is a flag to say whether that argument should be treated as `NULL` (i.e., ignored).
 193
 194 ### Constants and include files
 195
 196 In C/C++, the `nlopt.h` header file declares the various constants (`NLOPT_LN_NELDERMEAD`, `NLOPT_FAILURE`, etcetera) used to specify the optimization algorithm, return codes, and so forth. In Fortran, the corresponding definitions are located in the `nlopt.f` file, which is installed into the same directory as `nlopt.h` (in `/usr/local/include` by default).
 197
 198 That is, in any Fortran subroutine where you want to use NLopt subroutines, you should do:
 199
 200 ```
 201 include 'nlopt.f'
 202 ```
 203
 204
 205 to include the constant definitions. (Like in C, most Fortran compilers allow you to pass `-I` options to specify search directories for include files, if you did not install NLopt in a standard location; see the [installation instructions](NLopt_Installation.md).) If you have some ancient Fortran compiler that does not support the `include` directive (which technically was nonstandard until Fortran 90, although most Fortran 77 compilers implement it), then I suppose you could also copy-and-paste the `nlopt.f` file directly into your source code.
 206
 207 ### `nloptc`
 208
 209 The Fortran analogue to the `nlopt_minimize_constrained` function is:
 210
 211 ```
 212 call nloptc(info, algorithm, n,
 213             f, f_data,
 214             m, fc, fc_data, fc_second_datum,
 215             lb, ub,
 216             x, minf,
 217             minf_max, ftol_rel, ftol_abs, xtol_rel, xtol_abs, have_xtol_abs, maxeval, maxtime)
 218 ```
 219
 220
 221 The parameters are similar to those of `nlopt_minimize_constrained` (see also the documentation above):
 222
 223 -   `info` (integer, OUT) — on output, the return value, positive on success and negative on failure (see above for the specific return codes `NLOPT_SUCCESS` etcetera).
 224
 225 <!-- -->
 226
 227 -   `algorithm` (integer, IN) — integer constant (`NLOPT_LN_NELDERMEAD`, etcetera) indicating the optimization algorithm to use (defined in `nlopt.f` include file as described above)
 228 -   `n` (integer, IN) — the dimension of the problem (the number of optimization parameters, as in C)
 229 -   `f` (subroutine, IN) — the objective function, actually a subroutine as described below
 230 -   `f_data` (any type, IN) — any additional data to pass to the objective function
 231 -   `m` (integer, IN) — the number of nonlinear inequality constraints (zero if none).
 232 -   `fc` (subroutine, IN) — the constraint subroutine, as described below (ignored if *m*=0)
 233 -   `fc_data`, `fc_second_datum` (arbitrary types, IN) — data to pass to the constraint subroutine, as described below (ignored if *m*=0)
 234 -   `lb` (double precision array(`n`), IN) — lower bounds on the optimization parameters. (For unbounded dimensions, use `-Infinity` or `-Inf` in the Fortran 2003 standard; I don't know of a standard way to do it in earlier Fortran versions, maybe `-1.0/0.0`?)
 235 -   `ub` (double precision array(`n`), IN) — upper bounds on the optimization parameters. (For unbounded dimensions, use `+Infinity` or `+Inf` in the Fortran 2003 standard; I don't know of a standard way to do it in earlier Fortran versions, maybe `+1.0/0.0`?)
 236
 237 <!-- -->
 238
 239 -   `x` (double precision array(`n`), IN/OUT) — on input, an initial guess for the optimization parameters; on output, the best parameters found
 240 -   `minf` (double precision, OUT) — on output, the minimum value of the objective function that was found
 241
 242 Termination conditions (see [introduction](NLopt_Introduction#Termination_conditions.md)):
 243
 244 -   `minf_max` (double precision, IN) — stop if the an objective function value ≤ `minf_max` is found (set to `-Infinity`, or a huge negative number, to ignore).
 245 -   `ftol_rel`, `ftol_abs` (double precision, IN) — relative and absolute tolerances in the objective function value (ignored if zero).
 246 -   `xtol_rel` (double precision, IN) — relative tolerance in the optimization parameters (ignored if zero)
 247 -   `xtol_abs` (double precision array(`n`), IN) — if `have_xtol_abs` is nonzero, then `xtol_abs` is an array of the absolute tolerances in each optimization parameter (ignored if zero).
 248 -   `have_xtol_abs` (integer, IN) — if zero, then `xtol_abs` is ignored
 249 -   `maxeval` (integer, IN) — stop if the objective function is evaluated at least `maxeval` times (set to zero to ignore)
 250 -   `maxtime` (double precision, IN) — stop if the elapsed wall-clock time exceeds `maxtime` seconds (set to zero to ignore)
 251
 252 ### `nloptm`
 253
 254 The Fortran analogue to the `nlopt_minimize` function is:
 255
 256 ```
 257 call nloptm(info, algorithm, n,
 258             f, f_data,
 259             lb, ub,
 260             x, minf,
 261             minf_max, ftol_rel, ftol_abs, xtol_rel, xtol_abs, have_xtol_abs, maxeval, maxtime)
 262 ```
 263
 264
 265 This is exactly equivalent to calling `nloptc` with `m`=0.
 266
 267 ### Objective function in Fortran
 268
 269 You should define your objective function (the function you want to minimize) as a subroutine of the following form:
 270
 271 ```
 272 subroutine f(val, n, x, grad, need_gradient, f_data)
 273 double precision val
 274 integer n
 275 double precision x(n)
 276 double precision grad(n)
 277 integer need_gradient
 278 ```
 279
 280
 281 The `n`, `x`, `need_gradient`, and `f_data` parameters are inputs, and the `val` and `grad` parameters are outputs.
 282
 283 Upon return, `val` should be set to the value of your objective function at the point **x**. The dimension `n` is the same as the one passed to `nloptm` or `nloptc`.
 284
 285 In addition, if the argument `need_gradient` is not zero, then `grad` is an array of length `n` that should (upon return) be set to the gradient of your function *f* with respect to the design variables *x*. That is, `grad(i)` should upon return contain the partial derivative ∂`f`/∂`x(i)`, for `i`=1,...,`n`. Not all of the [optimization algorithms](NLopt_Algorithms.md) use the gradient information: for algorithms listed as "derivative-free," the `need_gradient` argument will always be zero and need never be computed. (For algorithms that do use gradient information, however, `need_gradient` may still be zero for some calls.) You should *not* access the `grad` array *at all* if `need_gradient` is zero.
 286
 287 The `f_data` argument is the same as the one passed to `nloptm` or `nloptc`, and may be used to pass any additional data through to the function. It can be declared as any arbitrary type that you want, as long as it is the same type as the variable you passed to `nloptm` or `nloptc`
 288
 289 ### Nonlinear constraints in Fortran
 290
 291 The `nloptc` function allows you to specify `m` nonlinear constraints via the subroutine `fc`, where `m` is any nonnegative integer. However, nonzero `m` is currently only supported by the `NLOPT_LD_MMA` and `NLOPT_LN_COBYLA` [algorithms](NLopt_Algorithms.md).
 292
 293 In particular, the nonlinear constraints are of the form *fc*(*x*) ≤ 0, where the function fc is of the same form as the objective function described above:
 294
 295 ```
 296 subroutine fc(val, n, x, grad, need_gradient, fc_datum)
 297 ```
 298
 299
 300 As above, upon return `val` should be the value of the constraint function at the point `x` (an array of length `n`), where the dimension `n` is identical to the one passed to `nloptc`. As for the objective function, if the argument `need_gradient` is not zero, then `grad` is an array of length `n` that should (upon return) be set to the gradient of the constraint function with respect to **x**. (For any algorithm listed as "derivative-free", the `need_gradient` argument will always be zero and the gradient need never be computed.)
 301
 302 The `fc_datum` argument is based on the `fc_data` argument passed to `nloptc`, and may be used to pass any additional data through to the function, and is used to distinguish between different constraints.
 303
 304 In particular, the constraint subroutine `fc` will be called (at most) `m` times for each `x`, and the *i*-th constraint (1 ≤ *i* ≤ *m*) will be passed an `fc_datum` argument equal to `fc_data` offset by the difference between `fc_data` and `fc_second_datum`. For example, suppose that your constraint function `fc` is parameterized by three numbers for each constraint, so you want your `fc_data` to be an array of length 3*m*: `double` `precision` `fc_data(3*m)`. Then, as the `fc_second_datum` argument to `nloptc`, you would pass `fc_data(4)`, which is the first data element for the second constraint. When `fc` is called the first time, it will be passed `fc_data(1:3)`; when it is called the second time it will be passed `fc_data(4:6)`, and so on in sequence.
 305
 306 ### Pseudorandom numbers in Fortran
 307
 308 The Fortran equivalent of `nlopt_srand` (above), is:
 309
 310 ```
 311 call nlosr(seed)
 312 ```
 313
 314
 315 where `seed` is an `integer`. The Fortran equivalent of `nlopt_srand_time` (above) is:
 316
 317 ```
 318 call nlosrt
 319 ```
 320
 321
 322 ### Version number in Fortran
 323
 324 To determine the version number of NLopt at runtime, you can call:
 325
 326 ```
 327 call nloptv(major, minor, bugfix)
 328 ```
 329
 330
 331 where the three arguments are `integer`s, as in `nlopt_version` above. For example, NLopt version 3.1.4 would return `major=3`, `minor=1`, and `bugfix=4`.
 332
 333 ### Mixed global/local search algorithm in Fortran
 334
 335 The Fortran analogues of `nlopt_set_local_search_algorithm` and `nlopt_get_local_search_algorithm` are:
 336
 337 ```
 338 call nlosls(deriv, nonderiv, maxeval)
 339 call nlogls(deriv, nonderiv, maxeval)
 340 ```
 341
 342
 343 where the arguments are all `integer`s and have the same meaning as those of `nlopt_set_local_search_algorithm` and `nlopt_get_local_search_algorithm`, above.
 344
 345 ### Population size for stochastic algorithms in Fortran
 346
 347 The Fortran analogues of `nlopt_set_stochastic_population` and `nlopt_get_stochastic_population` are:
 348
 349 ```
 350 call nlossp(pop)
 351 call nlogsp(pop)
 352 ```
 353
 354
 355 where the arguments are `integer`s and have the same meaning as the parameter of `nlopt_set_stochastic_population` and the return value of `nlopt_get_stochastic_population`, respectively.
 356
 357 GNU Octave and Matlab interface
 358 -------------------------------
 359
 360 We also provide an interface to NLopt that is callable from Matlab and [GNU Octave](https://en.wikipedia.org/wiki/GNU_Octave) (a free Matlab clone). This interface consists of two functions, `nlopt_minimize_constrained` and `nlopt_minimize`, which parallel the corresponding C functions above.
 361
 362 ### `nlopt_minimize_constrained` in Matlab
 363
 364 ```
 365 [xopt, fmin, retcode] = nlopt_minimize_constrained(algorithm, f, f_data, fc, fc_data, lb, ub, xinit, stop)
 366 ```
 367
 368
 369 Minimize a nonlinear multivariable function `f(x,` `f_data{:})`, subject to optional nonlinear constraints described by `fc` and `fc_data` (see below), where `x` is a row vector of the optimization parameters, returning the optimal parameters found (`xopt`) along with the minimum function value (`fmin`) and a return code (`retcode`, positive on success and negative on failure). A variety of local and global optimization algorithms can be used, as specified by the `algorithm` parameter. `lb` and `ub` are row vectors giving the upper and lower bounds on `x`, `xinit` is a row vector giving the initial guess for `x`, and `stop` is a structure containing termination conditions (see below).
 370
 371 Parameters:
 372
 373 -   `algorithm` — constant indicating the [optimization algorithm](NLopt_Algorithms.md) (predefined constants NLOPT_LN_NELDERMEAD etcetera are supplied as in C).
 374 -   `f` — function handle (e.g. `@sin`) of the objective function being minimized, described below
 375 -   `f_data` — cell array `{...}` of any additional arguments to pass to f (see below)
 376 -   `fc` — cell array `{...}` of function handles to nonlinear inequality constraints (see below); can be empty `{}` for no nonlinear constraints
 377 -   `fc_data` — cell array `{...}` of cell arrays: each element `fc_data{i}` is a cell array of additional arguments to pass to the function `fc{i}`; `length(fc_data)` must equal `length(fc)`
 378 -   `lb` — row vector of lower bounds on each optimization parameter (set any component of `lb` to `-inf` for a parameter that is not bounded below)
 379 -   `ub` — row vector of lower bounds on each optimization parameter (set any component of `ub` to `+inf` for a parameter that is not bounded above)
 380 -   `xinit` — row vector containing a starting guess for the optimization parameters
 381 -   `stop` — structure describing the termination conditions via a number of optional fields (see below)
 382
 383 Notice that, unlike in C and Fortran, we do not explicitly pass the dimension *n* of the parameter space: *n* is implicitly the length of the `lb`, `ub`, and `xinit` vectors (which must all be the same length).
 384
 385 #### Matlab objective function
 386
 387 The parameter `f` should be a handle (`@`) to a function of the form:
 388
 389 ```
 390   [val, gradient] = f(x, ...)
 391 ```
 392
 393
 394 where `x` is a row vector, `val` is the function value *f*(**x**), and `gradient` is a row vector giving the gradient of the function with respect to `x`. The gradient is only used for gradient-based optimization algorithms; some of the algorithms are derivative-free and only require f to return val (its value), so for these algorithms you need not return the gradient. f can take additional arguments `(...)` which are passed via the argument `f_data`: `f_data` is a cell array of the additional arguments to pass to `f`. (Recall that cell arrays are specified by curly brackets { ... }. For example, pass `f_data={}` for functions that require no additional arguments.)
 395
 396 #### Matlab nonlinear constraints
 397
 398 Some of the algorithms (currently `NLOPT_LD_MMA` and `NLOPT_LN_COBYLA`) support nonlinear constraints. These (if any) are specified by `fc` and `fc_data`. `fc` is a cell array of function handles, and `fc_data` is a cell array of cell arrays of the corresponding arguments. Both must have the same length m, the number of nonlinear constraints. That is, `fc{i}` is a handle to a function of the form:
 399
 400 ```
 401  [val, gradient] = fc(x, ...)
 402 ```
 403
 404
 405 (where the `gradient` return value is only used for gradient-based algorithms), and the `...` arguments are given by `fc_data{i}{:}`.
 406
 407 If you have no nonlinear constraints, i.e. `fc` = `fc_data` = `{}`, then it is equivalent to calling the the `nlopt_minimize` function below, which omits the `fc` and `fc_data` arguments.
 408
 409 #### Matlab termination conditions
 410
 411 `stop` describes the termination criteria, and is a structure with a number of optional fields:
 412
 413 -   `stop.fmin_max` — stop when *f* ≤ `fmin_max` is found
 414 -   `stop.ftol_rel` — fractional tolerance on function value
 415 -   `stop.ftol_abs` — absolute tolerance on function value
 416 -   `stop.xtol_rel` — fractional tolerance on **x**
 417 -   `stop.xtol_abs` — row vector of absolute tolerances on **x** components
 418 -   `stop.maxeval` — maximum number of function evaluations
 419 -   `stop.maxtime` — maximum run time in seconds
 420 -   `stop.verbose` — &gt; 0 indicates verbose output
 421
 422 You do *not* need to set all of these fields; termination conditions corresponding to any fields that you do not set are ignored. As discussed in the [introduction](NLopt_Introduction#Termination_conditions.md), normally you only want one or two of these conditions. For example to set a relative **x** tolerance of 10<sup>−4</sup> and run for no more than 5 minutes, you would do:
 423
 424 ```
 425 stop.xtol_rel = 1e-4;
 426 stop.maxtime = 5 * 60;
 427 ```
 428
 429
 430 and not create any other fields of `stop`.
 431
 432 ### `nlopt_minimize` in Matlab
 433
 434 ```
 435 [xopt, fmin, retcode] = nlopt_minimize(algorithm, f, f_data, lb, ub, xinit, stop)
 436 ```
 437
 438
 439 This is equivalent to calling `nlopt_minimize_constrained` with no nonlinear constraints, i.e. `fc` = `fc_data` = `{}`.
 440
 441 [Category:NLopt](index.md)