# FreeBSD Manual Pages

NLOPT(3) NLopt programming manual NLOPT(3)NAMEnlopt - Nonlinear optimization librarySYNOPSIS#include<nlopt.h>nlopt_optopt=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_relis 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 functionfofndesign vari- ables, using the specifiedalgorithm, possibly subject to linear or nonlinear constraints. The optimum function value found is returned inopt_f(type double) with the corresponding design variable values re- turned in the (double) arrayxof lengthn. The input values inxshould be a starting guess for the optimum. The parameters of the optimization are controlled via the objectoptof typenlopt_opt, which is created by the functionnlopt_createand dis- posed of bynlopt_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 bynlopt_set_ftol_rel), upper and/or lower bounds on the design parametersx, and even arbi- trary nonlinear inequality and equality constraints. By changing the parameteralgorithmamong several predefined constants described below, one can switch easily between a variety of minimiza- tion algorithms. Some of these algorithms require the gradient (deriv- atives) of the function to be supplied viaf, 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 sev- eral free/open-source minimization packages, as well as some new imple- mentations 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, de- pending upon the specific function being optimized, the different algo- rithms 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 sub- routines.OBJECTIVE FUNCTIONThe objective function is specified by calling one of:nlopt_resultnlopt_set_min_objective(nlopt_optopt,nlopt_funcf,void*f_data);nlopt_resultnlopt_set_max_objective(nlopt_optopt,nlopt_funcf,void*f_data);depending on whether one wishes to minimize or maximize the objective functionf, respectively. The functionfshould be of the form:doublef(unsignedn,constdouble*x,double*grad,void*f_data);The return value should be the value of the function at the pointx, wherexpoints to an array of lengthnof the design variables. The dimensionnis identical to the one passed tonlopt_create. In addition, if the argumentgradis not NULL, thengradpoints to an array of lengthnwhich should (upon return) be set to the gradient of the function with respect to the design variables atx. That is,grad[i]should upon return contain the partial derivative df/dx[i], for 0 <= i < n, ifgradis non-NULL. Not all of the optimization algo- rithms (below) use the gradient information: for algorithms listed as "derivative-free," thegradargument will always be NULL and need never be computed. (For algorithms that do use gradient information, how- ever,gradmay still be NULL for some calls.) Thef_dataargument is the same as the one passed tonlopt_set_min_ob-jectiveornlopt_set_max_objective, and may be used to pass any addi- tional 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.)BOUND CONSTRAINTSMost of the algorithms in NLopt are designed for minimization of func- tions 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 arrayslbandubof lengthnto one or both of the functions:nlopt_resultnlopt_set_lower_bounds(nlopt_optopt,constdouble*lb);nlopt_resultnlopt_set_upper_bounds(nlopt_optopt,constdouble*ub);If a lower/upper bound is not set, the default is no bound (uncon- strained, 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 floating-point infinity, found in the math.h header file.) Note, however, that some of the algorithms in NLopt, in particular most of the global-optimization algorithms, do not support unconstrained op- timization 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 con- stant (so that you don't have to fill an array with a constant value):nlopt_resultnlopt_set_lower_bounds1(nlopt_optopt,doublelb);nlopt_resultnlopt_set_upper_bounds1(nlopt_optopt,doubleub);NONLINEAR CONSTRAINTSSeveral of the algorithms in NLopt (MMA and ORIG_DIRECT) also support arbitrary nonlinear inequality constraints, and some also allow nonlin- ear 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 formfc(x) <= 0, where the functionfcis of the same form as the objective function described above, can be specified by calling:nlopt_resultnlopt_add_inequality_constraint(nlopt_optopt,nlopt_funcfc,void*fc_data,doubletol);Just as for the objective function,fc_datais a pointer to arbitrary user data that will be passed through to thefcfunction whenever it is called. The parametertolis a tolerance that is used for the purpose of stopping criteria only: a pointxis considered feasible for judging whether to stop the optimization iffc(x) <=tol. A tolerance of zero means that NLopt will try not to consider anyxto be converged unlessfcis strictly non-positive; generally, at least a small positive tol- erance is advisable to reduce sensitivity to rounding errors. A nonlinear equality constraint of the formh(x) = 0, where the func- tionhis of the same form as the objective function described above, can be specified by calling:nlopt_resultnlopt_add_equality_constraint(nlopt_optopt,nlopt_funch,void*h_data,doubletol);Just as for the objective function,h_datais a pointer to arbitrary user data that will be passed through to thehfunction whenever it is called. The parametertolis a tolerance that is used for the purpose of stopping criteria only: a pointxis considered feasible for judging whether to stop the optimization if |h(x)| <=tol. For equality con- straints, 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 "derivative-free" below, thegradargument tofcorhwill always be NULL and need never be computed.) To remove all of the inequality and/or equality constraints from a given problemopt, you can call the following functions:nlopt_resultnlopt_remove_inequality_constraints(nlopt_optopt);nlopt_resultnlopt_remove_equality_constraints(nlopt_optopt);ALGORITHMSThealgorithmparameter specifies the optimization algorithm (for more detail on these, see the README files in the source-code subdirecto- ries), 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 guessx). Con- stants with _{G,L}N_ refer to non-gradient (derivative-free) algorithms that do not require the objective function to supply a gradient, whereas _{G,L}D_ refers to derivative-based algorithms that require the objective function to supply a gradient. (Especially for local opti- mization, derivative-based algorithms are generally superior to deriva- tive-free ones: the gradient is good to haveifyou can compute it cheaply, e.g. via an adjoint method.) The algorithm specified for a given problemoptis returned by the function:nlopt_algorithmnlopt_get_algorithm(nlopt_optopt);The available algorithms are:NLOPT_GN_DIRECT_LPerform a global (G) derivative-free (N) optimization using the DIRECT-L search algorithm by Jones et al. as modified by Gablon- sky et al. to be more weighted towards local search. Does not support unconstrainted optimization. There are also several other variants of the DIRECT algorithm that are supported:NLOPT_GN_DIRECT, which is the original DIRECT algorithm;NLOPT_GN_DIRECT_L_RAND, a slightly randomized version of DIRECT- L that may be better in high-dimensional search spaces;NLOPT_GN_DIRECT_NOSCAL,NLOPT_GN_DIRECT_L_NOSCAL, andNLOPT_GN_DIRECT_L_RAND_NOSCAL, which are versions of DIRECT where the dimensions are not rescaled to a unit hypercube (which means that dimensions with larger bounds are given more weight).NLOPT_GN_ORIG_DIRECT_LA global (G) derivative-free optimization using the DIRECT-L al- gorithm as above, along withNLOPT_GN_ORIG_DIRECTwhich is the original DIRECT algorithm. UnlikeNLOPT_GN_DIRECT_Labove, these two algorithms refer to code based on the original Fortran code of Gablonsky et al., which has some hard-coded limitations on the number of subdivisions etc. and does not support all of the NLopt stopping criteria, but on the other hand it supports arbitrary nonlinear inequality constraints.NLOPT_GD_STOGOGlobal (G) optimization using the StoGO algorithm by Madsen et al. StoGO exploits gradient information (D) (which must be sup- plied by the objective) for its local searches, and performs the global search by a branch-and-bound technique. Only bound-con- strained optimization is supported. There is also another vari- ant of this algorithm,NLOPT_GD_STOGO_RAND, which is a random- ized version of the StoGO search scheme. The StoGO algorithms are only available if NLopt is compiled with C++ code enabled, and should be linked via -lnlopt_cxx instead of -lnlopt (via a C++ compiler, in order to link the C++ standard libraries).NLOPT_LN_NELDERMEADPerform a local (L) derivative-free (N) optimization, starting atx, using the Nelder-Mead simplex algorithm, modified to sup- port bound constraints. Nelder-Mead, while popular, is known to occasionally fail to converge for some objective functions, so it should be used with caution. Anecdotal evidence, on the other hand, suggests that it works fairly well for some cases that are hard to handle otherwise, e.g. noisy/discontinuous ob- jectives. See alsoNLOPT_LN_SBPLXbelow.NLOPT_LN_SBPLXPerform a local (L) derivative-free (N) optimization, starting atx, using an algorithm based on the Subplex algorithm of Rowan et al., which is an improved variant of Nelder-Mead (above). Our implementation does not use Rowan's original code, and has some minor modifications such as explicit support for bound con- straints. (Like Nelder-Mead, Subplex often works well in prac- tice, even for noisy/discontinuous objectives, but there is no rigorous guarantee that it will converge.)NLOPT_LN_PRAXISLocal (L) derivative-free (N) optimization using the principal- axis method, based on code by Richard Brent. Designed for un- constrained optimization, although bound constraints are sup- ported too (via the inefficient method of returning +Inf when the constraints are violated).NLOPT_LD_LBFGSLocal (L) gradient-based (D) optimization using the limited-mem- ory BFGS (L-BFGS) algorithm. (The objective function must sup- ply the gradient.) Unconstrained optimization is supported in addition to simple bound constraints (see above). Based on an implementation by Luksan et al.NLOPT_LD_VAR2Local (L) gradient-based (D) optimization using a shifted lim- ited-memory variable-metric method based on code by Luksan et al., supporting both unconstrained and bound-constrained opti- mization.NLOPT_LD_VAR2uses a rank-2 method, while.BNLOPT_LD_VAR1is another variant using a rank-1 method.NLOPT_LD_TNEWTON_PRECOND_RESTARTLocal (L) gradient-based (D) optimization using an LBFGS-precon- ditioned truncated Newton method with steepest-descent restart- ing, based on code by Luksan et al., supporting both uncon- strained and bound-constrained optimization. There are several other variants of this algorithm:NLOPT_LD_TNEWTON_PRECOND(same without restarting),NLOPT_LD_TNEWTON_RESTART(same without pre- conditioning), andNLOPT_LD_TNEWTON(same without restarting or preconditioning).NLOPT_GN_CRS2_LMGlobal (G) derivative-free (N) optimization using the controlled random search (CRS2) algorithm of Price, with the "local muta- tion" (LM) modification suggested by Kaelo and Ali.NLOPT_GN_ISRESGlobal (G) derivative-free (N) optimization using a genetic al- gorithm (mutation and differential evolution), using a stochas- tic ranking to handle nonlinear inequality and equality con- straints as suggested by Runarsson and Yao.NLOPT_G_MLSL_LDS,NLOPT_G_MLSLGlobal (G) optimization using the multi-level single-linkage (MLSL) algorithm with a low-discrepancy sequence (LDS) or pseu- dorandom numbers, respectively. This algorithm executes a low- discrepancy or pseudorandom sequence of local searches, with a clustering heuristic to avoid multiple local searches for the same local optimum. The local search algorithm must be speci- fied, along with termination criteria/tolerances for the local searches, bynlopt_set_local_optimizer. (This subsidiary algo- rithm can be with or without derivatives, and determines whether the objective function needs gradients.)NLOPT_LD_MMA,NLOPT_LD_CCSAQLocal (L) gradient-based (D) optimization using the method of moving asymptotes (MMA), or rather a refined version of the al- gorithm as published by Svanberg (2002). (NLopt uses an inde- pendent free-software/open-source implementation of Svanberg's algorithm.) CCSAQ is a related algorithm from Svanberg's paper which uses a local quadratic approximation rather than the more- complicated MMA model; the two usually have similar convergence rates. TheNLOPT_LD_MMAalgorithm supports both bound-con- strained and unconstrained optimization, and also supports an arbitrary number (m) of nonlinear inequality (not equality) con- straints as described above.NLOPT_LD_SLSQPLocal (L) gradient-based (D) optimization using sequential qua- dratic programming and BFGS updates, supporting arbitrary non- linear inequality and equality constraints, based on the code by Dieter Kraft (1988) adapted for use by the SciPy project. Note that this algorithm uses dense-matrix methods requiring O(n^2) storage and O(n^3) time, making it less practical for problems involving more than a few thousand parameters.NLOPT_LN_COBYLALocal (L) derivative-free (N) optimization using the COBYLA al- gorithm of Powell (Constrained Optimization BY Linear Approxima- tions). TheNLOPT_LN_COBYLAalgorithm supports both bound-con- strained and unconstrained optimization, and also supports an arbitrary number (m) of nonlinear inequality/equality con- straints as described above.NLOPT_LN_NEWUOALocal (L) derivative-free (N) optimization using a variant of the NEWUOA algorithm of Powell, based on successive quadratic approximations of the objective function. We have modified the algorithm to support bound constraints. The original NEWUOA al- gorithm is also available, asNLOPT_LN_NEWUOA, but this algo- rithm ignores the bound constraintslbandub, and so it should only be used for unconstrained problems. Mostly superseded by BOBYQA.NLOPT_LN_BOBYQALocal (L) derivative-free (N) optimization using the BOBYQA al- gorithm of Powell, based on successive quadratic approximations of the objective function, supporting bound constraints.NLOPT_AUGLAGOptimize an objective with nonlinear inequality/equality con- straints via an unconstrained (or bound-constrained) optimiza- tion algorithm, using a gradually increasing "augmented La- grangian" penalty for violated constraints. Requires you to specify another optimization algorithm for optimizing the objec- tive+penalty function, usingnlopt_set_local_optimizer. (This subsidiary algorithm can be global or local and with or without derivatives, but you must specify its own termination criteria.) A variant,NLOPT_AUGLAG_EQ, only uses the penalty approach for equality constraints, while inequality constraints are handled directly by the subsidiary algorithm (restricting the choice of subsidiary algorithms to those that can handle inequality con- straints).STOPPING CRITERIAMultiple stopping criteria for the optimization are supported, as spec- ified by the functions to modify a given optimization problemopt. The optimization halts whenever any one of these criteria is satisfied. In some cases, the precise interpretation of the stopping criterion de- pends 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).nlopt_resultnlopt_set_stopval(nlopt_optopt,doublestopval);Stop when an objective value of at leaststopvalis found: stop minimizing when a value <=stopvalis found, or stop maximizing when a value >=stopvalis found. (Settingstopvalto -HUGE_VAL for minimizing or +HUGE_VAL for maximizing disables this stop- ping criterion.)nlopt_resultnlopt_set_ftol_rel(nlopt_optopt,doubletol);Set relative tolerance on function value: stop when an optimiza- tion step (or an estimate of the optimum) changes the function value by less thantolmultiplied by the absolute value of the function value. (If there is any chance that your optimum func- tion value is close to zero, you might want to set an absolute tolerance withnlopt_set_ftol_absas well.) Criterion is dis- abled iftolis non-positive.nlopt_resultnlopt_set_ftol_abs(nlopt_optopt,doubletol);Set absolute tolerance on function value: stop when an optimiza- tion step (or an estimate of the optimum) changes the function value by less thantol. Criterion is disabled iftolis non- positive.nlopt_resultnlopt_set_xtol_rel(nlopt_optopt,doubletol);Set relative tolerance on design variables: stop when an opti- mization step (or an estimate of the optimum) changes every de- sign variable by less thantolmultiplied by the absolute value of the design variable. (If there is any chance that an optimal design variable is close to zero, you might want to set an abso- lute tolerance withnlopt_set_xtol_absas well.) Criterion is disabled iftolis non-positive.nlopt_resultnlopt_set_xtol_abs(nlopt_optopt,constdouble*tol);Set absolute tolerances on design variables.tolis a pointer to an array of lengthngivingthetolerances:stopwhenanop- timization step (or an estimate of the optimum) changes every design variablex[i] by less thantol[i]. For convenience, the following function may be used to set the absolute tolerances in allndesign variables to the same value:nlopt_resultnlopt_set_xtol_abs1(nlopt_optopt,doubletol);Criterion is disabled iftolis non-positive.nlopt_resultnlopt_set_maxeval(nlopt_optopt,intmaxeval);Stop when the number of function evaluations exceedsmaxeval. (This is not a strict maximum: the number of function evalua- tions may exceedmaxevalslightly, depending upon the algo- rithm.) Criterion is disabled ifmaxevalis non-positive.nlopt_resultnlopt_set_maxtime(nlopt_optopt,doublemaxtime);Stop when the optimization time (in seconds) exceedsmaxtime. (This is not a strict maximum: the time may exceedmaxtimeslightly, depending upon the algorithm and on how slow your function evaluation is.) Criterion is disabled ifmaxtimeis non-positive.RETURN VALUEMost of the NLopt functions return an enumerated constant of typenlopt_result, which takes on one of the following values:Successfultermination(positivereturnvalues):NLOPT_SUCCESSGeneric success return value.NLOPT_STOPVAL_REACHEDOptimization stopped becausestopval(above) was reached.NLOPT_FTOL_REACHEDOptimization stopped becauseftol_relorftol_abs(above) was reached.NLOPT_XTOL_REACHEDOptimization stopped becausextol_relorxtol_abs(above) was reached.NLOPT_MAXEVAL_REACHEDOptimization stopped becausemaxeval(above) was reached.NLOPT_MAXTIME_REACHEDOptimization stopped becausemaxtime(above) was reached.Errorcodes(negativereturnvalues):NLOPT_FAILUREGeneric failure code.NLOPT_INVALID_ARGSInvalid arguments (e.g. lower bounds are bigger than upper bounds, an unknown algorithm was specified, etcetera).NLOPT_OUT_OF_MEMORYRan out of memory.NLOPT_ROUNDOFF_LIMITEDHalted because roundoff errors limited progress.NLOPT_FORCED_STOPHalted because the user callednlopt_force_stop(opt) on the op- timization'snlopt_optobjectoptfrom the user's objective function.LOCAL OPTIMIZERSome of the algorithms, especially MLSL and AUGLAG, use a different op- timization algorithm as a subroutine, typically for local optimization. You can change the local search algorithm and its tolerances by call- ing:nlopt_resultnlopt_set_local_optimizer(nlopt_optopt,constnlopt_optlocal_opt);Here,local_optis anothernlopt_optobject whose parameters are used to determine the local search algorithm and stopping criteria. (The objective function, bounds, and nonlinear-constraint parameters oflo-cal_optare ignored.) The dimensionnoflocal_optmust match that ofopt. This function makes a copy of thelocal_optobject, so you can freely destroy your originallocal_optafterwards.INITIAL STEP SIZEFor derivative-free local-optimization algorithms, the optimizer must somehow decide on some initial step size to perturbxby 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 tox. 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_resultnlopt_set_initial_step(nlopt_optopt,constdouble*dx);Here,dxis an array of lengthncontaining the (nonzero) initial step size for each component of the design parametersx. For convenience, if you want to set the step sizes in every direction to be the same value, you can instead call:nlopt_resultnlopt_set_initial_step1(nlopt_optopt,doubledx);STOCHASTIC POPULATIONSeveral of the stochastic search algorithms (e.g., CRS, MLSL, and IS- RES) start by generating some initial "population" of random pointsx. By default, this initial population size is chosen heuristically in some algorithm-specific way, but the initial population can by changed by calling:nlopt_resultnlopt_set_population(nlopt_optopt,unsignedpop);(Apopof 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:voidnlopt_srand(unsignedlongseed);Some of the algorithms also support using low-discrepancy sequences (LDS), sometimes known as quasi-random numbers. NLopt uses the Sobol LDS, which is implemented for up to 1111 dimensions.AUTHORSWritten by Steven G. Johnson. Copyright (c) 2007-2014 Massachusetts Institute of Technology.SEE ALSOnlopt_minimize(3) MIT 2007-08-23 NLOPT(3)

NAME | SYNOPSIS | DESCRIPTION | OBJECTIVE FUNCTION | BOUND CONSTRAINTS | NONLINEAR CONSTRAINTS | ALGORITHMS | STOPPING CRITERIA | RETURN VALUE | LOCAL OPTIMIZER | INITIAL STEP SIZE | STOCHASTIC POPULATION | PSEUDORANDOM NUMBERS | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:

<https://www.freebsd.org/cgi/man.cgi?query=nlopt&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>