NLopt Deprecated API Reference
From AbInitio
| Revision as of 20:01, 12 November 2008 (edit) Stevenj (Talk | contribs) ← Previous diff |
Revision as of 22:59, 12 November 2008 (edit) Stevenj (Talk | contribs) (→C/C++ programming interface) Next diff → |
||
| Line 16: | Line 16: | ||
| ==C/C++ programming interface== | ==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 <code>nlopt_minimize_constrained</code> (for nonlinearly constrained optimization) or <code>nlopt_minimize</code> (for unconstrained or box-constrained optimization) to perform the optimization. There are also a couple of other utility routines 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 <code>x</code> points to an array of length <code>n</code> containing the optimization parameters. (That is, the optimization parameters are <code>x[0]</code>, <code>x[1]</code>, ..., <code>x[n-1]</code>.) The dimension <code>n</code> is the same as the one passed to <code>nlopt_minimize</code> or <code>nlopt_minimize_constrained</code>. | ||
| + | |||
| + | In addition, if the argument <code>grad</code> is not <code>NULL</code>, then <code>grad</code> points to an array of length <code>n</code> that should (upon return) be set to the gradient of your function ''f'' with respect to the design variables ''x''. that is, <code>grad[i]</code> should upon return contain the partial derivatives ∂''f''/∂<code>x[i]</code>. Mot all of the [[NLopt Algorithms|optimization algorithms]] use the gradient information: for algorithms listed as "derivative-free," the <code>grad</code> argument will always be <code>NULL</code> and need never be computed. (For algorithms that do use gradient information, however, <code>grad</code> may still be <code>NULL</code> for some calls.) | ||
| + | |||
| + | The <code>f_data</code> argument is the same as the one passed to <code>nlopt_minimize</code> or <code>nlopt_minimize_constrained</code>, 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 <code>void*</code> by a typecast.) | ||
| ==Fortran programming interface== | ==Fortran programming interface== | ||
Revision as of 22:59, 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.
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.)
