NLopt Deprecated API Reference

From AbInitio

(Difference between revisions)
Jump to: navigation, search
Revision as of 23:52, 12 November 2008 (edit)
Stevenj (Talk | contribs)
(Nonlinear constraints)
← Previous diff
Revision as of 23:52, 12 November 2008 (edit)
Stevenj (Talk | contribs)
(Nonlinear constraints)
Next diff →
Line 125: Line 125:
The <code>fc_datum</code> argument is based on the <code>fc_data</code> argument passed to <code>nlopt_minimize_constrained</code>, and may be used to pass any additional data through to the function, and is used to distinguish between different constraints. The <code>fc_datum</code> argument is based on the <code>fc_data</code> argument passed to <code>nlopt_minimize_constrained</code>, and may be used to pass any additional data through to the function, and is used to distinguish between different constraints.
-In particular, the constraint function <code>fc</code> will be called (at most) <code>m</code> times for each <code>x</code>, and the ''i''-th constraint (0 &leq; ''i'' &lt; ''m'') will be passed an fc_datum argument equal to fc_data offset by ''i''&sdot;<code>fc_datum_size</code>. For example, suppose that you have a data structure of type <code>foo</code> that describes the data needed by each constraint, and you store the information for the constraints in an array <code>foo data[m]</code>. In this case, you would pass <code>data</code> as the <code>fc_data</code> parameter to <code>nlopt_minimize_constrained</code>, and <code>sizeof(foo)</code> as the <code>fc_datum_size</code> parameter. Then, your <code>fc</code> function would be called <code>m</code> times for each point, and be passed <code>&data[0]</code> through <code>&data[m-1]</code> in sequence.+In particular, the constraint function <code>fc</code> will be called (at most) <code>m</code> times for each <code>x</code>, and the ''i''-th constraint (0 &le; ''i'' &lt; ''m'') will be passed an fc_datum argument equal to fc_data offset by ''i''&sdot;<code>fc_datum_size</code>. For example, suppose that you have a data structure of type <code>foo</code> that describes the data needed by each constraint, and you store the information for the constraints in an array <code>foo data[m]</code>. In this case, you would pass <code>data</code> as the <code>fc_data</code> parameter to <code>nlopt_minimize_constrained</code>, and <code>sizeof(foo)</code> as the <code>fc_datum_size</code> parameter. Then, your <code>fc</code> function would be called <code>m</code> times for each point, and be passed <code>&data[0]</code> through <code>&data[m-1]</code> in sequence.
==Fortran programming interface== ==Fortran programming interface==

Revision as of 23:52, 12 November 2008

NLopt
Download
Release notes
FAQ
NLopt manual
Introduction
Installation
Tutorial
Reference
Algorithms
License and Copyright

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 programming interface (API) of NLopt.

Other sources of information include the Unix man pages 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.

Contents

Linking your program to NLopt

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:

compiler ...source/object files... -lnlopt -lm -o myprogram

where compiler is cc, f77, g++, or whatever is appropriate for your machine/language.

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.

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.

C/C++ programming interface

To use NLopt from C or C++, you should first include the NLopt header file:

#include <nlopt.h>

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.

nlopt_minimize_constrained

nlopt_result nlopt_minimize_constrained(nlopt_algorithm algorithm,
                                        int n,
                                        nlopt_func f, void* f_data,
                                        int m,
                                        nlopt_func fc, void* fc_data, ptrdiff_t fc_datum_size,
                                        const double* lb, const double* ub,
                                        double* x,
                                        double* minf,
                                        double minf_max,
                                        double ftol_rel, double ftol_abs,
                                        double xtol_rel, const double* xtol_abs,
                                        int maxeval, double maxtime);

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.

Parameters

The parameters specifying the optimization problem are:

  • 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 page.
  • n — the dimension n of the optimization problem, the number of optimization parameters.
  • f — the objective function (see below)
  • f_data — a pointer to any data you want to pass to the the objective function (see below)
  • m — the number of nonlinear inequality constraints (zero for no such constraints).
  • fc — the nonlinear inequality constraint function (see below). Ignored if m = 0.
  • fc_data, fc_datum_sizefc_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.
  • 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] &geq; 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 +∞.)
  • 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] &leq; ub[i]. If you don't want a particular variable to be bounded above, just set the corresponding lb[i] to be +HUGE_VAL.

Starting guess and returned optimum:

  • 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.)
  • minf — on output, the minimum value of the objective function that was found (corresponding to the output value of the parameters x).

The remaining parameters specify the termination conditions. Please read the introduction to the termination conditions for a general overview of these criteria.

  • minf_max — stop if the objective function value drops below minf_max. (Set to -HUGE_VAL to ignore.)
  • ftol_rel, ftol_abs — relative and absolute tolerances in the objective function value. (Set to zero to ignore.)
  • 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.
  • maxeval — stop if the objective function is evaluated maxeval times. Set to zero to ignore.
  • maxtime — stop if the elapsed wall-clock time, in seconds, exceeds maxtime. Set to zero to ignore.

Return value

The value returned is one of the following enumerated constants.

Successful termination (positive return values):

  • NLOPT_SUCCESS — Generic success return value.
  • NLOPT_MINF_MAX_REACHED — Optimization stopped because minf_max (above) was reached.
  • NLOPT_FTOL_REACHED — Optimization stopped because ftol_rel or ftol_abs (above) was reached.
  • NLOPT_XTOL_REACHED — Optimization stopped because xtol_rel or xtol_abs (above) was reached.
  • NLOPT_MAXEVAL_REACHED — Optimization stopped because maxeval (above) was reached.
  • NLOPT_MAXTIME_REACHED — Optimization stopped because maxtime (above) was reached.

Error codes (negative return values):

  • NLOPT_FAILURE — Generic failure code.
  • NLOPT_INVALID_ARGS — Invalid arguments (e.g. lower bounds are bigger than upper bounds, an unknown algorithm was specified, etcetera).
  • NLOPT_OUT_OF_MEMORY — Ran out of memory.

nlopt_minimize

nlopt_result nlopt_minimize(nlopt_algorithm algorithm,
                            int n,
                            nlopt_func f, void* f_data,
                            const double* lb, const double* ub,
                            double* x,
                            double* minf,
                            double minf_max,
                            double ftol_rel, double ftol_abs,
                            double xtol_rel, const double* xtol_abs,
                            int maxeval, double maxtime);

This function is exactly equivalent to calling nlopt_minimize_constrained with m = 0 (no nonlinear inequality constraints).

Objective function

You should define your objective function (the function you want to minimize) as a function of the following form:

double f(int n, const double *x, double *grad, void *f_data)
{
    ....
}

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.

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 derivatives ∂f/∂x[i]. Mot all of the optimization algorithms 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.)

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.)

Nonlinear constraints

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.

In particular, the nonlinear constraints are of the form fc(x) &leq; 0, where the function fc is of the same form as the objective function described above:

double fc(int n, const double* x, double* grad, void* fc_datum);

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.)

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.

In particular, the constraint function fc will be called (at most) m times for each x, and the i-th constraint (0 ≤ i < m) will be passed an fc_datum argument equal to fc_data offset by ifc_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.

Fortran programming interface

GNU Octave and Matlab interface

Personal tools