
NAMEnlopt  Nonlinear optimization librarySYNOPSIS#include <nlopt.h> nlopt_opt opt = nlopt_create(algorithm, n); nlopt_set_min_objective(opt, f, f_data); nlopt_set_ftol_rel(opt, tol); ... nlopt_optimize(opt, x , &opt_f); nlopt_destroy(opt); The "..." indicates any number of calls to NLopt functions, below, to set parameters of the optimization, constraints, and stopping criteria. Here, nlopt_set_ftol_rel is merely an example of a possible stopping criterion. You should link the resulting program with the linker flags lnlopt lm on Unix. DESCRIPTIONNLopt is a library for nonlinear optimization. It attempts to minimize (or maximize) a given nonlinear objective function f of n design variables, using the specified algorithm, possibly subject to linear or nonlinear constraints. The optimum function value found is returned in opt_f (type double) with the corresponding design variable values returned in the (double) array x of length n. The input values in x should be a starting guess for the optimum.The parameters of the optimization are controlled via the object opt of type nlopt_opt, which is created by the function nlopt_create and disposed of by nlopt_destroy. By calling various functions in the NLopt library, one can specify stopping criteria (e.g., a relative tolerance on the objective function value is specified by nlopt_set_ftol_rel), upper and/or lower bounds on the design parameters x, and even arbitrary nonlinear inequality and equality constraints. By changing the parameter algorithm among several predefined constants described below, one can switch easily between a variety of minimization algorithms. Some of these algorithms require the gradient (derivatives) of the function to be supplied via f, and other algorithms do not require derivatives. Some of the algorithms attempt to find a global optimum within the given bounds, and others find only a local optimum. Most of the algorithms only handle the case where there are no nonlinear constraints. The NLopt library is a wrapper around several free/opensource minimization packages, as well as some new implementations of published optimization algorithms. You could, of course, compile and call these packages separately, and in some cases this will provide greater flexibility than is available via NLopt. However, depending upon the specific function being optimized, the different algorithms will vary in effectiveness. The intent of NLopt is to allow you to quickly switch between algorithms in order to experiment with them for your problem, by providing a simple unified interface to these subroutines. OBJECTIVE FUNCTIONThe objective function is specified by calling one of: nlopt_result nlopt_set_min_objective(nlopt_opt
opt,
depending on whether one wishes to minimize or maximize the objective function f, respectively. The function f should be of the form: double f(unsigned n,
The return value should be the value of the function at the point x, where x points to an array of length n of the design variables. The dimension n is identical to the one passed to nlopt_create. In addition, 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 function with respect to the design variables at x. That is, grad[i] should upon return contain the partial derivative df/dx[i], for 0 <= i < n, if grad is nonNULL. Not all of the optimization algorithms (below) use the gradient information: for algorithms listed as "derivativefree," 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_set_min_objective or nlopt_set_max_objective, and may be used to pass any additional data through to the function. (That is, it may be a pointer to some callerdefined data structure/type containing information your function needs, which you convert from void* by a typecast.) BOUND CONSTRAINTSMost of the algorithms in NLopt are designed for minimization of functions with simple bound constraints on the inputs. That is, the input vectors x[i] are constrainted to lie in a hyperrectangle lb[i] <= x[i] <= ub[i] for 0 <= i < n. These bounds are specified by passing arrays lb and ub of length n to one or both of the functions: nlopt_result nlopt_set_lower_bounds(nlopt_opt
opt,
If a lower/upper bound is not set, the default is no bound (unconstrained, i.e. a bound of infinity); it is possible to have lower bounds but not upper bounds or vice versa. Alternatively, the user can call one of the above functions and explicitly pass a lower bound of HUGE_VAL and/or an upper bound of +HUGE_VAL for some design variables to make them have no lower/upper bound, respectively. (HUGE_VAL is the standard C constant for a floatingpoint infinity, found in the math.h header file.) Note, however, that some of the algorithms in NLopt, in particular most of the globaloptimization algorithms, do not support unconstrained optimization and will return an error if you do not supply finite lower and upper bounds. For convenience, the following two functions are supplied in order to set the lower/upper bounds for all design variables to a single constant (so that you don't have to fill an array with a constant value): nlopt_result nlopt_set_lower_bounds1(nlopt_opt
opt,
NONLINEAR CONSTRAINTSSeveral of the algorithms in NLopt (MMA and ORIG_DIRECT) also support arbitrary nonlinear inequality constraints, and some also allow nonlinear equality constraints (COBYLA, SLSQP, ISRES, and AUGLAG). For these algorithms, you can specify as many nonlinear constraints as you wish by calling the following functions multiple times.In particular, a nonlinear inequality constraint of the form fc(x) <= 0, where the function fc is of the same form as the objective function described above, can be specified by calling: nlopt_result nlopt_add_inequality_constraint(nlopt_opt
opt,
Just as for the objective function, fc_data is a pointer to arbitrary user data that will be passed through to the fc function whenever it is called. The parameter tol is a tolerance that is used for the purpose of stopping criteria only: a point x is considered feasible for judging whether to stop the optimization if fc(x) <= tol. A tolerance of zero means that NLopt will try not to consider any x to be converged unless fc is strictly nonpositive; generally, at least a small positive tolerance is advisable to reduce sensitivity to rounding errors. A nonlinear equality constraint of the form h(x) = 0, where the function h is of the same form as the objective function described above, can be specified by calling: nlopt_result nlopt_add_equality_constraint(nlopt_opt
opt,
Just as for the objective function, h_data is a pointer to arbitrary user data that will be passed through to the h function whenever it is called. The parameter tol is a tolerance that is used for the purpose of stopping criteria only: a point x is considered feasible for judging whether to stop the optimization if h(x) <= tol. For equality constraints, a small positive tolerance is strongly advised in order to allow NLopt to converge even if the equality constraint is slightly nonzero. (For any algorithm listed as "derivativefree" below, the grad argument to fc or h will always be NULL and need never be computed.) To remove all of the inequality and/or equality constraints from a given problem opt, you can call the following functions: nlopt_result nlopt_remove_inequality_constraints(nlopt_opt
opt);
ALGORITHMSThe algorithm parameter specifies the optimization algorithm (for more detail on these, see the README files in the sourcecode subdirectories), and can take on any of the following constant values.Constants with _G{N,D}_ in their names refer to global optimization methods, whereas _L{N,D}_ refers to local optimization methods (that try to find a local optimum starting from the starting guess x). Constants with _{G,L}N_ refer to nongradient (derivativefree) algorithms that do not require the objective function to supply a gradient, whereas _{G,L}D_ refers to derivativebased algorithms that require the objective function to supply a gradient. (Especially for local optimization, derivativebased algorithms are generally superior to derivativefree ones: the gradient is good to have if you can compute it cheaply, e.g. via an adjoint method.) The algorithm specified for a given problem opt is returned by the function: nlopt_algorithm nlopt_get_algorithm(nlopt_opt opt); The available algorithms are:
STOPPING CRITERIAMultiple stopping criteria for the optimization are supported, as specified by the functions to modify a given optimization problem opt. The optimization halts whenever any one of these criteria is satisfied. In some cases, the precise interpretation of the stopping criterion depends on the optimization algorithm above (although we have tried to make them as consistent as reasonably possible), and some algorithms do not support all of the stopping criteria.Important: you do not need to use all of the stopping criteria! In most cases, you only need one or two, and can omit the remainder (all criteria are disabled by default).
RETURN VALUEMost of the NLopt functions return an enumerated constant of type nlopt_result, which takes on one of the following values:Successful termination (positive return values):
Error codes (negative return values):
LOCAL OPTIMIZERSome of the algorithms, especially MLSL and AUGLAG, use a different optimization algorithm as a subroutine, typically for local optimization. You can change the local search algorithm and its tolerances by calling: nlopt_result nlopt_set_local_optimizer(nlopt_opt
opt,
Here, local_opt is another nlopt_opt object whose parameters are used to determine the local search algorithm and stopping criteria. (The objective function, bounds, and nonlinearconstraint parameters of local_opt are ignored.) The dimension n of local_opt must match that of opt. This function makes a copy of the local_opt object, so you can freely destroy your original local_opt afterwards. INITIAL STEP SIZEFor derivativefree localoptimization algorithms, the optimizer must somehow decide on some initial step size to perturb x by when it begins the optimization. This step size should be big enough that the value of the objective changes significantly, but not too big if you want to find the local optimum nearest to x. By default, NLopt chooses this initial step size heuristically from the bounds, tolerances, and other information, but this may not always be the best choice.You can modify the initial step size by calling: nlopt_result nlopt_set_initial_step(nlopt_opt
opt,
Here, dx is an array of length n containing the (nonzero) initial step size for each component of the design parameters x. For convenience, if you want to set the step sizes in every direction to be the same value, you can instead call: nlopt_result nlopt_set_initial_step1(nlopt_opt
opt,
STOCHASTIC POPULATIONSeveral of the stochastic search algorithms (e.g., CRS, MLSL, and ISRES) start by generating some initial "population" of random points x. By default, this initial population size is chosen heuristically in some algorithmspecific way, but the initial population can by changed by calling: nlopt_result nlopt_set_population(nlopt_opt
opt,
(A pop of zero implies that the heuristic default will be used.) PSEUDORANDOM NUMBERSFor stochastic optimization algorithms, we use pseudorandom numbers generated by the Mersenne Twister algorithm, based on code from Makoto Matsumoto. By default, the seed for the random numbers is generated from the system time, so that they will be different each time you run the program. If you want to use deterministic random numbers, you can set the seed by calling:void nlopt_srand(unsigned long seed); Some of the algorithms also support using lowdiscrepancy sequences (LDS), sometimes known as quasirandom numbers. NLopt uses the Sobol LDS, which is implemented for up to 1111 dimensions. AUTHORSWritten by Steven G. Johnson.Copyright (c) 20072014 Massachusetts Institute of Technology. SEE ALSOnlopt_minimize(3)
Visit the GSP FreeBSD Man Page Interface. 