NLOPT_MINI...ONSTRAINED(3)

✨ NLOPT_MINI...ONSTRAINED(3) ✨

okay bestie, welcome to the NLopt programming manual, and buckle up because this one is a whole journey 💖 it's the page for nlopt_minimize_constrained, and she's a big one.

---

🌸 NAME 🌸

nlopt_minimize_constrained — minimize a multivariate nonlinear function subject to nonlinear constraints. yeah. she does both. main character energy fr 💅

---

🎀 SYNOPSIS 🎀

#include <nlopt.h>

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);

and like, you gotta link your program with the linker flags -lnlopt -lm on Unix. do not skip this. she will not compile without it and you'll be sad 😭

---

🦋 DESCRIPTION 🦋

so nlopt_minimize_constrained() is out here trying to minimize a nonlinear function f of n design variables, and it's doing that subject to m nonlinear constraints described by the function fc (more on her below), all using whatever algorithm you picked. the minimum function value it finds gets returned in minf, and the matching design variable values get returned in the array x of length n. 🫶

the values you put into x? those are your starting guess for the optimum. manifesting, basically. the inputs lb and ub are arrays of length n holding the lower and upper bounds (respectively) on the design variables x. and all the other parameters are about stopping criteria — tolerances, the maximum number of function evaluations, etcetera — described in more detail down below. the return value is an integer code that says success (positive) or failure (negative), also described below. no cap.

by changing the parameter algorithm among several predefined constants (below, bestie, keep reading), you can switch easily between a whole variety of minimization algorithms. some of these algorithms need the gradient (derivatives) of the function supplied via f, and others do not need derivatives at all. some of the algorithms attempt to find a global minimum within the given bounds, and others find only a local minimum. and here's the tea: most of the algorithms only handle the case where m is zero (no explicit nonlinear constraints). the only algorithms that currently support positive m are NLOPT_LD_MMA and NLOPT_LN_COBYLA. periodt. 👑

so nlopt_minimize_constrained is a wrapper around several free/open-source minimization packages, plus some new implementations of published optimization algorithms. like, you could of course compile and call these packages separately, and in some cases that'll give you greater flexibility than what's available through the nlopt_minimize_constrained interface. but depending on the specific function being minimized, the different algorithms will vary in effectiveness. the whole intent of nlopt_minimize_constrained is to let you quickly switch between algorithms so you can experiment with them for your problem — one simple unified interface to all these subroutines. iconic honestly ✨

---

💜 OBJECTIVE FUNCTION 💜

nlopt_minimize_constrained() minimizes an objective function f shaped like this:

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 of the design variables. the dimension n is identical to the one you passed to nlopt_minimize_constrained().

and also — 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 non-NULL. not all of the optimization algorithms (below) use the gradient info: for algorithms listed as "derivative-free," the grad argument will always be NULL and never needs to be computed. (but for algorithms that do use gradient information, grad may still be NULL for some calls. sneaky like that 🙈)

the f_data argument is the same one you passed to nlopt_minimize_constrained(), and you can use it to pass any additional data through to the function. (like, it may be a pointer to some caller-defined data structure/type holding info your function needs, which you convert from void* by a typecast. classic void pointer behavior 💅)

---

🌈 BOUND CONSTRAINTS 🌈

most of the algorithms in NLopt are designed for minimization of functions with simple bound constraints on the inputs. that means the input vectors x[i] are constrained to lie in a hyperrectangle lb[i] <= x[i] <= ub[i] for 0 <= i < n, where lb and ub are the two arrays passed to nlopt_minimize_constrained().

however — plot twist — a few of the algorithms support partially or totally unconstrained optimization, as noted below. 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 the ones that don't require derivative 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 input x. more generally, there are various ways to implement constraints by adding "penalty terms" to your objective function, which are described in the optimization literature. a much more efficient way to specify nonlinear constraints is described below — but it's only supported by a small subset of the algorithms. tragic but true 😭

---

⭐ NONLINEAR CONSTRAINTS ⭐

the nlopt_minimize_constrained function also lets you specify m nonlinear constraints via the function fc, where m is any nonnegative integer. however, nonzero m is currently only supported by the NLOPT_LD_MMA and NLOPT_LN_COBYLA algorithms below. so like, don't try it with anything else, bestie. 🙏

specifically, the nonlinear constraints are of the form fc(x) <= 0, where the function fc is the same shape as the objective function described above:

double fc(int n,
          const double* x,
          double* grad,
          void* fc_datum);

the return value should be the value of the constraint at the point x, where the dimension n is identical to the one passed to nlopt_minimize_constrained(). same deal as the objective function: 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 x. (and for any algorithm listed as "derivative-free" below, the grad argument will always be NULL and never needs to be computed. free pass. 😌)

the fc_datum argument is based on the fc_data argument passed to nlopt_minimize_constrained(), and you can use it to pass any additional data through to the function — it's how you distinguish between different constraints.

here's the detail that matters, so listen up: the constraint function fc will be called (at most) m times for each x, and the i-th constraint (0 <= i < m) will be passed an fc_datum argument equal to fc_data offset by i * fc_datum_size. for example, suppose you have a data structure of type "foo" that describes the data needed by each constraint, and you store the info for the constraints in an array "foo data[m]". in that case, you would pass "data" as the fc_data parameter to nlopt_minimize_constrained, and "sizeof(foo)" as the fc_datum_size parameter. then your fc function would be called m times for each point, and be passed &data[0] through &data[m-1] in sequence. slay, pointer arithmetic actually working out 💖

---

✨ ALGORITHMS ✨

Okay bestie, so the algorithm parameter is the one that picks which optimization algorithm you're running (want the deep lore? the README files in the source-code subdirectories have you covered 💅), and it can take on any of these constant values. Let's decode the naming scheme real quick because it's giving secret code:

• Constants with _G{N,D}_ in the name = global optimization methods 🌍
• Constants with _L{N,D}_ = local optimization methods (they try to find a local minimum starting from your starting guess x)
• Constants with _{G,L}N_ = non-gradient (aka derivative-free) algorithms, which do not need the objective function to hand over a gradient 🚫📉
• Constants with _{G,L}D_ = derivative-based algorithms, which do require the objective function to supply a gradient

fr fr, especially for local optimization, derivative-based algorithms are generally superior to derivative-free ones — the gradient is genuinely good to have if you can compute it cheaply, like via an adjoint method. No cap. 🫶

---

• NLOPT_GN_DIRECT_L — a global (G) derivative-free (N) optimization using the DIRECT-L search algorithm by Jones et al., as modified by Gablonsky et al. to be more weighted towards local search. Heads up: it does not support unconstrainted optimization. And it's not alone — there are several other DIRECT variants riding along: 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; and NLOPT_GN_DIRECT_NOSCAL, NLOPT_GN_DIRECT_L_NOSCAL, and NLOPT_GN_DIRECT_L_RAND_NOSCAL, which are versions of DIRECT where the dimensions are not rescaled to a unit hypercube (which means dimensions with larger bounds are given more weight). 👑
• NLOPT_GN_ORIG_DIRECT_L — a global (G) derivative-free optimization using the DIRECT-L algorithm as above, along with NLOPT_GN_ORIG_DIRECT which is the original DIRECT algorithm. But here's the tea: unlike NLOPT_GN_DIRECT_L above, these two 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 constraints as described above. Trade-offs, bestie. ⚖️
• NLOPT_GD_STOGO — global (G) optimization using the StoGO algorithm by Madsen et al. StoGO exploits gradient information (D) (which must be supplied by the objective) for its local searches, and does the global search via a branch-and-bound technique. Only bound-constrained optimization is supported. There's also another variant, NLOPT_GD_STOGO_RAND, which is a randomized version of the StoGO search scheme. ⚠️ Important: 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_NELDERMEAD — a local (L) derivative-free (N) optimization, starting at x, using the Nelder-Mead simplex algorithm, modified to support 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 also NLOPT_LN_SBPLX below.
• NLOPT_LN_SBPLX — a local (L) derivative-free (N) optimization, starting at x, 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 constraints. (Like Nelder-Mead, Subplex often works well in practice, even for discontinuous objectives, but there is no rigorous guarantee that it will converge.) Nonlinear constraints can be crudely supported by returning +Inf when the constraints are violated, as explained above. 💀
• NLOPT_LN_PRAXIS — local (L) derivative-free (N) optimization using the principal-axis method, based on code by Richard Brent. Designed for unconstrained optimization, although bound constraints are supported too (via the inefficient method of returning +Inf when the constraints are violated).
• NLOPT_LD_LBFGS — local (L) gradient-based (D) optimization using the limited-memory BFGS (L-BFGS) algorithm. (The objective function must supply the gradient.) Unconstrained optimization is supported in addition to simple bound constraints (see above). Based on an implementation by Luksan et al.
• NLOPT_LD_VAR2 — local (L) gradient-based (D) optimization using a shifted limited-memory variable-metric method based on code by Luksan et al., supporting both unconstrained and bound-constrained optimization. NLOPT_LD_VAR2 uses a rank-2 method, while NLOPT_LD_VAR1 is another variant using a rank-1 method. ✨
• NLOPT_LD_TNEWTON_PRECOND_RESTART — local (L) gradient-based (D) optimization using an LBFGS-preconditioned truncated Newton method with steepest-descent restarting, based on code by Luksan et al., supporting both unconstrained and bound-constrained optimization. And there's a whole little squad of variants: NLOPT_LD_TNEWTON_PRECOND (same without restarting), NLOPT_LD_TNEWTON_RESTART (same without preconditioning), and NLOPT_LD_TNEWTON (same without restarting or preconditioning). Pick your fighter 🎀
• NLOPT_GN_CRS2_LM — global (G) derivative-free (N) optimization using the controlled random search (CRS2) algorithm of Price, with the "local mutation" (LM) modification suggested by Kaelo and Ali.
• NLOPT_GD_MLSL_LDS, NLOPT_GN_MLSL_LDS — global (G) derivative-based (D) or derivative-free (N) optimization using the multi-level single-linkage (MLSL) algorithm with a low-discrepancy sequence (LDS). This one 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 algorithm set by nlopt_set_local_search_algorithm (currently defaulting to NLOPT_LD_MMA and NLOPT_LN_COBYLA for derivative/nonderivative searches, respectively). There are also two other variants, NLOPT_GD_MLSL and NLOPT_GN_MLSL, which use pseudo-random numbers (instead of an LDS) as in the original MLSL algorithm.
• NLOPT_LD_MMA — local (L) gradient-based (D) optimization using the method of moving asymptotes (MMA), or rather a refined version of the algorithm as published by Svanberg (2002). (NLopt uses an independent free-software/open-source implementation of Svanberg's algorithm. Respect.) The NLOPT_LD_MMA algorithm supports both bound-constrained and unconstrained optimization, and also supports an arbitrary number (m) of nonlinear constraints as described above. 🔥
• NLOPT_LN_COBYLA — local (L) derivative-free (N) optimization using the COBYLA algorithm of Powell (Constrained Optimization BY Linear Approximations). The NLOPT_LN_COBYLA algorithm supports both bound-constrained and unconstrained optimization, and also supports an arbitrary number (m) of nonlinear constraints as described above.
• NLOPT_LN_NEWUOA — local (L) derivative-free (N) optimization using a variant of the 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 algorithm is also available, as NLOPT_LN_NEWUOA, but this algorithm ignores the bound constraints lb and ub, and so it should only be used for unconstrained problems. 🙈

---

🛑 STOPPING CRITERIA 🛑

okay bestie so here's the thing: you get multiple stopping criteria for your optimization, and they come in as arguments to nlopt_minimize_constrained(). The optimization dips out the second any one of them is satisfied. 💅

A lil heads-up tho: sometimes the exact vibe of a stopping criterion depends on which optimization algorithm you picked (we tried to keep them consistent, fr), and some algorithms straight-up don't support all of them. 🤷

⚠️ Important: you do NOT need to use all of the stopping criteria! In most cases you need like one or two, and you can set the rest to values where they do literally nothing (details below). No pressure, babe.

• minf_max — Stop when a function value less than or equal to minf_max is found. Set it to -Inf or NaN (yes, like in the constraints section above) to disable it. 🚫
• ftol_rel — Relative tolerance on function value: stop when an optimization step (or an estimate of the minimum) changes the function value by less than ftol_rel multiplied by the absolute value of the function value. 💫 (If there's any chance your minimum function value is close to zero, you might wanna set an absolute tolerance with ftol_abs too.) Disabled if non-positive.
• ftol_abs — Absolute tolerance on function value: stop when an optimization step (or an estimate of the minimum) changes the function value by less than ftol_abs. Disabled if non-positive. 📏
• xtol_rel — Relative tolerance on design variables: stop when an optimization step (or an estimate of the minimum) changes every design variable by less than xtol_rel multiplied by the absolute value of the design variable. 🦋 (If there's any chance an optimal design variable is close to zero, maybe set an absolute tolerance with xtol_abs too.) Disabled if non-positive.
• xtol_abs — Pointer to an array of length n giving absolute tolerances on design variables: stop when an optimization step (or an estimate of the minimum) changes every design variable x[i] by less than xtol_abs[i]. Disabled if non-positive, or if xtol_abs is NULL. 🎯
• maxeval — Stop when the number of function evaluations exceeds maxeval. (Not a strict maximum btw — the number of function evaluations may exceed maxeval slightly, depending on the algorithm.) Disabled if non-positive. 🔢
• maxtime — Stop when the optimization time (in seconds) exceeds maxtime. (Also not a strict maximum: the time may exceed maxtime slightly, depending on the algorithm and on how slow your function evaluation is.) Disabled if non-positive. ⏰

---

💖 RETURN VALUE 💖

What you get back is one of these enumerated constants, and they're giving very much pass/fail energy.

✅ Successful termination (positive return values):

• NLOPT_SUCCESS — Generic success return value. iconic.
• NLOPT_MINF_MAX_REACHED — Optimization stopped because minf_max (above) was reached. 🏁
• NLOPT_FTOL_REACHED — Optimization stopped because ftol_rel or ftol_abs (above) was reached. ✨
• NLOPT_XTOL_REACHED — Optimization stopped because xtol_rel or xtol_abs (above) was reached. 🌸
• NLOPT_MAXEVAL_REACHED — Optimization stopped because maxeval (above) was reached. 🔥
• NLOPT_MAXTIME_REACHED — Optimization stopped because maxtime (above) was reached. ⏳

💀 Error codes (negative return values):

• NLOPT_FAILURE — Generic failure code. not the vibe. 😭
• NLOPT_INVALID_ARGS — Invalid arguments (e.g. lower bounds are bigger than upper bounds, an unknown algorithm was specified, etcetera). 🙈
• NLOPT_OUT_OF_MEMORY — Ran out of memory. 💀

---

🎲 PSEUDORANDOM NUMBERS 🎲

So for 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 comes from the system time, so they'll be different every time you run the program. spicy. 🌶️ But if you want deterministic random numbers, you can set the seed by calling:

void nlopt_srand(unsigned long seed);

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. 🧚✨

---

👑 AUTHORS 👑

Written by Steven G. Johnson.

Copyright (c) 2007-2014 Massachusetts Institute of Technology.

---

🌈 SEE ALSO 🌈

• nlopt_minimize(3)

---

and that's a wrap on the whole page bestie!! 🫶 this manual page ships as MIT, dated 2007-08-23, and yes the title line is still doing its lil truncated NLOPT_MINI...ONSTRAINED(3) thing 💅 go forth and optimize, you absolute main character 🎀