NLopt Deprecated API Reference
From AbInitio
| Revision as of 23:02, 12 November 2008 (edit) Stevenj (Talk | contribs) (→C/C++ programming interface) ← Previous diff |
Revision as of 23:07, 12 November 2008 (edit) Stevenj (Talk | contribs) (→<code>nlopt_minimize_constrained</code>) Next diff → |
||
| Line 25: | Line 25: | ||
| ===<code>nlopt_minimize_constrained</code>=== | ===<code>nlopt_minimize_constrained</code>=== | ||
| - | nlopt_minimize_constrained(nlopt_algorithm algorithm, | + | nlopt_result nlopt_minimize_constrained(nlopt_algorithm algorithm, |
| - | int n, | + | int n, |
| - | nlopt_func f, void* f_data, | + | nlopt_func f, void* f_data, |
| - | int m, | + | int m, |
| - | nlopt_func fc, void* fc_data, ptrdiff_t fc_datum_size, | + | nlopt_func fc, void* fc_data, ptrdiff_t fc_datum_size, |
| - | const double* lb, const double* ub, | + | const double* lb, const double* ub, |
| - | double* x, | + | double* x, |
| - | double* minf, | + | double* minf, |
| - | double minf_max, | + | double minf_max, |
| - | double ftol_rel, double ftol_abs, | + | double ftol_rel, double ftol_abs, |
| - | double xtol_rel, const double* xtol_abs, | + | double xtol_rel, const double* xtol_abs, |
| - | int maxeval, double maxtime); | + | int maxeval, double maxtime); |
| + | |||
| + | This function attempts to minimize a nonlinear function <code>f</code> of <code>n</code> optimization parameters, subject to <code>m</code> nonlinear constraints described by the function <code>fc</code>, using the specified algorithm. The minimum function value found is returned in <code>minf</code>, with the corresponding optimization parameter values returned in the array <code>x</code> of length <code>n</code>. The input values in <code>x</code> should be a starting guess for the minimum. The inputs <code>lb</code> and <code>ub</code> are arrays of length <code>n</code> containing lower and upper bounds, respectively, on the design variables <code>x</code>. 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. | ||
| ===Objective function=== | ===Objective function=== | ||
Revision as of 23:07, 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.
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 B must come after A 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.
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.)
