# FreeBSD Manual Pages

NLOPT_MINIMIZE_CONSTRAINED(NLopt programming manuNLOPT_MINIMIZE_CONSTRAINED(3)NAMEnlopt_minimize_constrained - Minimize a multivariate nonlinear function subject to nonlinear constraintsSYNOPSIS#include<nlopt.h>nlopt_resultnlopt_minimize_constrained(nlopt_algorithmalgorithm,intn,nlopt_funcf,void*f_data,intm,nlopt_funcfc,void*fc_data,ptrdiff_tfc_datum_size,constdouble*lb,constdouble*ub,double*x,double*minf,doubleminf_max,doubleftol_rel,doubleftol_abs,doublextol_rel,constdouble*xtol_abs,intmaxeval,doublemaxtime);You should link the resulting program with the linker flags -lnlopt -lm on Unix.DESCRIPTIONnlopt_minimize_constrained() attempts to minimize a nonlinear functionfofndesign variables, subject tomnonlinear constraints described by the functionfc(see below), using the specifiedalgorithm. The minimum function value found is returned inminf, with the correspond- ing design variable values returned in the arrayxof lengthn. The input values inxshould be a starting guess for the optimum. The in- putslbandubare arrays of lengthncontaining lower and upper bounds, respectively, on the design variablesx. The other parameters specify stopping criteria (tolerances, the maximum number of function evaluations, etcetera) and other information as described in more de- tail below. The return value is a integer code indicating success (positive) or failure (negative), as described below. 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 minimum within the given bounds, and others find only a local minimum. Most of the algorithms only handle the case wheremis zero (no explicit nonlinear constraints); the only algorithms that currently support positivemareNLOPT_LD_MMAandNLOPT_LN_COBYLA. Thenlopt_minimize_constrainedfunction is a wrapper around several free/open-source minimization packages, as well as some new implementa- tions of published optimization algorithms. You could, of course, com- pile and call these packages separately, and in some cases this will provide greater flexibility than is available via thenlopt_mini-mize_constrainedinterface. However, depending upon the specific func- tion being minimized, the different algorithms will vary in effective- ness. The intent ofnlopt_minimize_constrainedis 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 subrou- tines.OBJECTIVE FUNCTIONnlopt_minimize_constrained() minimizes an objective functionfof the form:doublef(intn,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_minimize_con-strained(). 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_mini-mize_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.)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, wherelbandubare the two arrays passed tonlopt_minimize_constrained(). However, a few of the algorithms support partially or totally uncon- strained optimization, as noted below, where a (totally or partially) unconstrained design variable is indicated by a lower bound equal to -Inf and/or an upper bound equal to +Inf. Here, Inf is the IEEE-754 floating-point infinity, which (in ANSI C99) is represented by the macro INFINITY in math.h. Alternatively, for older C versions you may also use the macro HUGE_VAL (also in math.h). With some of the algorithms, especially those that do not require de- rivative information, a simple (but not especially efficient) way to implement arbitrary nonlinear constraints is to return Inf (see above) whenever the constraints are violated by a given inputx. More gener- ally, there are various ways to implement constraints by adding "pen- alty terms" to your objective function, which are described in the op- timization literature. A much more efficient way to specify nonlinear constraints is described below, but is only supported by a small subset of the algorithms.NONLINEAR CONSTRAINTSThenlopt_minimize_constrainedfunction also allows you to specifymnonlinear constraints via the functionfc, wheremis any nonnegative integer. However, nonzeromis currently only supported by theNLOPT_LD_MMAandNLOPT_LN_COBYLAalgorithms below. In particular, the nonlinear constraints are of the formfc(x) <= 0, where the functionfcis of the same form as the objective function de- scribed above:doublefc(intn,constdouble*x,double*grad,void*fc_datum);The return value should be the value of the constraint at the pointx, where the dimensionnis identical to the one passed tonlopt_mini-mize_constrained(). As for the objective function, if the argumentgradis not NULL, thengradpoints to an array of lengthnwhich should (upon return) be set to the gradient of the function with respect tox. (For any algorithm listed as "derivative-free" below, thegradargument will always be NULL and need never be computed.) Thefc_datumargument is based on thefc_dataargument passed tonlopt_minimize_constrained(), and may be used to pass any additional data through to the function, and is used to distinguish between dif- ferent constraints. In particular, the constraint functionfcwill be called (at most)mtimes for eachx, and the i-th constraint (0 <= i <m) will be passed anfc_datumargument equal tofc_dataoffset by i *fc_datum_size. For example, suppose that you have a data structure of type "foo" that de- scribes the data needed by each constraint, and you store the informa- tion for the constraints in an array "foo data[m]". In this case, you would pass "data" as thefc_dataparameter tonlopt_minimize_con-strained, and "sizeof(foo)" as thefc_datum_sizeparameter. Then, yourfcfunction would be calledmtimes for each point, and be passed &data[0] through &data[m-1] in sequence.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 minimum starting from the starting guessx). Constants 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 func- tion to supply a gradient. (Especially for local optimization, deriva- tive-based algorithms are generally superior to derivative-free ones: the gradient is good to haveifyou can compute it cheaply, e.g. via an adjoint method.)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 supports ar- bitrary nonlinear constraints as described above.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++ enabled, and should be linked via -lnlopt_cxx (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 discontinuous objectives. 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 discontinuous objectives, but there is no rigor- ous guarantee that it will converge.) Nonlinear constraints can be crudely supported by returning +Inf when the constraints are violated, as explained above.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_GD_MLSL_LDS,NLOPT_GN_MLSL_LDSGlobal (G) derivative-based (D) or derivative-free (N) optimiza- tion using the multi-level single-linkage (MLSL) algorithm with a low-discrepancy sequence (LDS). This algorithm executes a quasi-random (LDS) sequence of local searches, with a clustering heuristic to avoid multiple local searches for the same local minimum. The local search uses the derivative/nonderivative al- gorithm set bynlopt_set_local_search_algorithm(currently de- faulting toNLOPT_LD_MMAandNLOPT_LN_COBYLAfor derivative/non- derivative searches, respectively). There are also two other variants,NLOPT_GD_MLSLandNLOPT_GN_MLSL, which use pseudo-ran- dom numbers (instead of an LDS) as in the original MLSL algo- rithm.NLOPT_LD_MMALocal (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.) TheNLOPT_LD_MMAalgorithm supports both bound-con- strained and unconstrained optimization, and also supports an arbitrary number (m) of nonlinear constraints as described above.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 constraints as described above.NLOPT_LN_NEWUOALocal (L) derivative-free (N) optimization using a variant of the the NEWUOA algorithm of Powell, based on successive qua- dratic approximations of the objective function. We have modi- fied the algorithm to support bound constraints. The original NEWUOA algorithm is also available, asNLOPT_LN_NEWUOA, but this algorithm ignores the bound constraintslbandub, and so it should only be used for unconstrained problems.STOPPING CRITERIAMultiple stopping criteria for the optimization are supported, as spec- ified by the following arguments tonlopt_minimize_constrained(). 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 set the remainder to val- ues where they do nothing (as described below).minf_maxStop when a function value less than or equal tominf_maxis found. Set to -Inf or NaN (see constraints section above) to disable.ftol_relRelative tolerance on function value: stop when an optimization step (or an estimate of the minimum) changes the function value by less thanftol_relmultiplied by the absolute value of the function value. (If there is any chance that your minimum func- tion value is close to zero, you might want to set an absolute tolerance withftol_absas well.) Disabled if non-positive.ftol_absAbsolute tolerance on function value: stop when an optimization step (or an estimate of the minimum) changes the function value by less thanftol_abs. Disabled if non-positive.xtol_relRelative tolerance on design variables: stop when an optimiza- tion step (or an estimate of the minimum) changes every design variable by less thanxtol_relmultiplied 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 withxtol_absas well.) Disabled if non-posi- tive.xtol_absPointer to an array of lengthngivingabsolutetolerancesondesignvariables:stopwhenanoptimization step (or an estimate of the minimum) changes every design variablex[i] by less thanxtol_abs[i]. Disabled if non-positive, or ifxtol_absis NULL.maxevalStop 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.) Disabled if non-positive.maxtimeStop 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.) Disabled if non-positive.RETURN VALUEThe value returned is one of the following enumerated constants.Successfultermination(positivereturnvalues):NLOPT_SUCCESSGeneric success return value.NLOPT_MINF_MAX_REACHEDOptimization stopped becauseminf_max(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.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_MINIMIZE_CONSTRAINED(3)

NAME | SYNOPSIS | DESCRIPTION | OBJECTIVE FUNCTION | BOUND CONSTRAINTS | NONLINEAR CONSTRAINTS | ALGORITHMS | STOPPING CRITERIA | RETURN VALUE | PSEUDORANDOM NUMBERS | AUTHORS | SEE ALSO

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

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