--- /dev/null
+.\"
+.\" Copyright (c) 2007 Massachusetts Institute of Technology
+.\"
+.\" Copying and distribution of this file, with or without modification,
+.\" are permitted in any medium without royalty provided the copyright
+.\" notice and this notice are preserved.
+.\"
+.TH NLOPT 3 2007-08-23 "MIT" "NLopt programming manual"
+.SH NAME
+nlopt \- Nonlinear optimization library
+.SH SYNOPSIS
+.nf
+.B #include <nlopt.h>
+.sp
+.BI "nlopt_opt " "opt" " = nlopt_create(" "algorithm" , " n" );
+.BI "nlopt_set_min_objective(" "opt" , " f" , " f_data" );
+.BI "nlopt_set_ftol_rel(" "opt" , " tol");
+.BI "..."
+.BI "nlopt_optimize(" "opt" , " x " , " &opt_f" );
+.BI "nlopt_destroy(" "opt" );
+.sp
+The "..." indicates any number of calls to NLopt functions, below, to
+set parameters of the optimization, constraints, and stopping
+criteria. Here, \fBnlopt_set_ftol_rel\fR is merely an example of a
+possible stopping criterion. You should link the resulting program
+with the linker flags -lnlopt -lm on Unix.
+.fi
+.SH DESCRIPTION
+NLopt is a library for nonlinear optimization. It attempts to
+minimize (or maximize) a given nonlinear objective function
+.I f
+of
+.I n
+design variables, using the specified
+.IR algorithm ,
+possibly subject to linear or nonlinear constraints. The minimum
+function value found is returned in \fIopt_f\fR (type double) with the
+corresponding design variable values returned in the (double) array
+.I x
+of length
+.IR n .
+The input values in
+.I x
+should be a starting guess for the optimum.
+.sp
+The parameters of the optimization are controlled via the object
+.I opt
+of type
+.BR nlopt_opt ,
+which is created by the function
+.B nlopt_create
+and disposed of by
+.BR 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
+.BR nlopt_set_ftol_rel ),
+upper and/or lower bounds on the design parameters
+.IR x ,
+and even arbitrary nonlinear inequality and equality constraints.
+.sp
+By changing the parameter
+.I 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
+.IR f ,
+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 where there are no nonlinear constraints. The NLopt
+library is a wrapper around several free/open-source 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.
+.SH OBJECTIVE FUNCTION
+The objective function is specified by calling one of:
+.sp
+.BI " nlopt_result nlopt_set_min_objective(nlopt_opt " "opt" ,
+.br
+.BI " nlopt_func " "f" ,
+.br
+.BI " void* " "f_data" );
+.br
+.BI " nlopt_result nlopt_set_max_objective(nlopt_opt " "opt" ,
+.br
+.BI " nlopt_func " "f" ,
+.br
+.BI " void* " "f_data" );
+.sp
+depending on whether one wishes to minimize or maximize the objective
+function
+.IR f ,
+respectively. The function
+.I f
+should be of the form:
+.sp
+.BI " double f(int " "n" ,
+.br
+.BI " const double* " "x" ,
+.br
+.BI " double* " "grad" ,
+.br
+.BI " void* " "f_data" );
+.sp
+The return value should be the value of the function at the point
+.IR x ,
+where
+.I x
+points to an array of length
+.I n
+of the design variables. The dimension
+.I n
+is identical to the one passed to
+.BR nlopt_create .
+.sp
+In addition, if the argument
+.I grad
+is not NULL, then
+.I grad
+points to an array of length
+.I n
+which should (upon return) be set to the gradient of the function with
+respect to the design variables at
+.IR x .
+That is,
+.IR grad[i]
+should upon return contain the partial derivative df/dx[i],
+for 0 <= i < n, if
+.I grad
+is non-NULL.
+Not all of the optimization algorithms (below) use the gradient information:
+for algorithms listed as "derivative-free," the
+.I grad
+argument will always be NULL and need never be computed. (For
+algorithms that do use gradient information, however,
+.I grad
+may still be NULL for some calls.)
+.sp
+The
+.I f_data
+argument is the same as the one passed to
+.B nlopt_set_min_objective
+or
+.BR 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 caller-defined data
+structure/type containing information your function needs, which you
+convert from void* by a typecast.)
+.SH BOUND CONSTRAINTS
+Most 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
+.I lb
+and
+.I ub
+of length
+.I n
+to one or both of the functions:
+.sp
+.BI " nlopt_result nlopt_set_lower_bounds(nlopt_opt " "opt" ,
+.br
+.BI " const double* " "lb" );
+.br
+.BI " nlopt_result nlopt_set_upper_bounds(nlopt_opt " "opt" ,
+.br
+.BI " const double* " "ub" );
+.sp
+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 floating-point infinity,
+found in the math.h header file.)
+.sp
+Note, however, that some of the algorithms in NLopt, in particular
+most of the global-optimization algorithms, do not support unconstrained
+optimization and will return an error if you do not supply finite lower
+and upper bounds.
+.sp
+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):
+.sp
+.BI " nlopt_result nlopt_set_lower_bounds1(nlopt_opt " "opt" ,
+.br
+.BI " double " "lb" );
+.br
+.BI " nlopt_result nlopt_set_upper_bounds1(nlopt_opt " "opt" ,
+.br
+.BI " double " "ub" );
+.sp
+.SH NONLINEAR CONSTRAINTS
+Several of the algorithms in NLopt (MMA, COBYLA, and ORIG_DIRECT) also
+support arbitrary nonlinear inequality constraints, and some also
+allow nonlinear equality constraints (ISRES and AUGLAG). For these
+algorithms, you can specify as many nonlinear constraints as you wish
+by calling the following functions multiple times.
+.sp
+In particular, a nonlinear inequality constraint of the form
+\fIfc\fR(\fIx\fR) <= 0, where the function
+.I fc
+is of the same form as the objective function described above,
+can be specified by calling:
+.sp
+.BI " nlopt_result nlopt_add_inequality_constraint(nlopt_opt " "opt" ,
+.br
+.BI " nlopt_func " "fc" ,
+.br
+.BI " void* " "fc_data" ,
+.br
+.BI " double " "tol" );
+.sp
+Just as for the objective function,
+.I fc_data
+is a pointer to arbitrary user data that will be passed through to the
+.I fc
+function whenever it is called. The parameter
+.I tol
+is a tolerance that is used for the purpose of stopping criteria only:
+a point
+.I x
+is considered feasible for judging whether to stop the optimization if
+\fIfc\fR(\fIx\fR) <= \fItol\fR. A tolerance of zero means that NLopt
+will try not to consider any \fIx\fR to be converged unless
+.I fc
+is strictly non-positive; generally, at least a small positive tolerance is
+advisable to reduce sensitivity to rounding errors.
+
+A nonlinear equality constraint of the form
+\fIh\fR(\fIx\fR) = 0, where the function
+.I h
+is of the same form as the objective function described above,
+can be specified by calling:
+.sp
+.BI " nlopt_result nlopt_add_equality_constraint(nlopt_opt " "opt" ,
+.br
+.BI " nlopt_func " "h" ,
+.br
+.BI " void* " "h_data" ,
+.br
+.BI " double " "tol" );
+.sp
+Just as for the objective function,
+.I h_data
+is a pointer to arbitrary user data that will be passed through to the
+.I h
+function whenever it is called. The parameter
+.I tol
+is a tolerance that is used for the purpose of stopping criteria only:
+a point
+.I x
+is considered feasible for judging whether to stop the optimization if
+|\fIh\fR(\fIx\fR)| <= \fItol\fR. 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.
+.sp
+(For any algorithm listed as "derivative-free" below, the
+.I grad
+argument to \fIfc\fR or \fIh\fR will always be NULL and need never be
+computed.)
+.sp
+To remove all of the inequality and/or equality constraints from
+a given problem \fIopt\fR, you can call the following functions:
+.sp
+.BI " nlopt_result nlopt_remove_inequality_constraints(nlopt_opt " "opt" );
+.br
+.BI " nlopt_result nlopt_remove_equality_constraints(nlopt_opt " "opt" );
+.SH ALGORITHMS
+The
+.I algorithm
+parameter specifies the optimization algorithm (for more detail on
+these, see the README files in the source-code subdirectories), and
+can take on any of the following constant values.
+.sp
+Constants with
+.B _G{N,D}_
+in their names
+refer to global optimization methods, whereas
+.B _L{N,D}_
+refers to local optimization methods (that try to find a local minimum
+starting from the starting guess
+.IR x ).
+Constants with
+.B _{G,L}N_
+refer to non-gradient (derivative-free) algorithms that do not require the
+objective function to supply a gradient, whereas
+.B _{G,L}D_
+refers to derivative-based algorithms that require the objective
+function to supply a gradient. (Especially for local optimization,
+derivative-based algorithms are generally superior to derivative-free
+ones: the gradient is good to have
+.I if
+you can compute it cheaply, e.g. via an adjoint method.)
+.sp
+The algorithm specified for a given problem
+.I opt
+is returned by the function:
+.sp
+.BI " nlopt_algorithm nlopt_get_algorithm(nlopt_opt " "opt" );
+.sp
+The available algorithms are:
+.TP
+.B NLOPT_GN_DIRECT_L
+Perform 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. Does not support
+unconstrainted optimization. There are also several other variants of
+the DIRECT algorithm that are supported:
+.BR NLOPT_GLOBAL_DIRECT ,
+which is the original DIRECT algorithm;
+.BR NLOPT_GLOBAL_DIRECT_L_RAND ,
+a slightly randomized version of DIRECT-L that may be better in
+high-dimensional search spaces;
+.BR NLOPT_GLOBAL_DIRECT_NOSCAL ,
+.BR NLOPT_GLOBAL_DIRECT_L_NOSCAL ,
+and
+.BR NLOPT_GLOBAL_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).
+.TP
+.B NLOPT_GN_ORIG_DIRECT_L
+A global (G) derivative-free optimization using the DIRECT-L algorithm
+as above, along with
+.B NLOPT_GN_ORIG_DIRECT
+which is the original DIRECT algorithm. Unlike
+.B NLOPT_GN_DIRECT_L
+above, 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.
+.TP
+.B 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 performs the global search by a
+branch-and-bound technique. Only bound-constrained optimization
+is supported. There is also another variant of this algorithm,
+.BR NLOPT_GD_STOGO_RAND ,
+which is a randomized 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).
+.TP
+.B NLOPT_LN_NELDERMEAD
+Perform a local (L) derivative-free (N) optimization, starting at
+.IR 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 some cases that are hard to handle otherwise,
+e.g. noisy/discontinuous objectives. See also
+.B NLOPT_LN_SBPLX
+below.
+.TP
+.B NLOPT_LN_SBPLX
+Perform a local (L) derivative-free (N) optimization, starting at
+.IR 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
+noisy/discontinuous objectives, but there is no rigorous guarantee that it
+will converge.)
+.TP
+.B 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).
+.TP
+.B 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.
+.TP
+.B 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.
+.B NLOPT_LD_VAR2
+uses a rank-2 method, while
+.B .B NLOPT_LD_VAR1
+is another variant using a rank-1 method.
+.TP
+.B 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. There are several
+other variants of this algorithm:
+.B NLOPT_LD_TNEWTON_PRECOND
+(same without restarting),
+.B NLOPT_LD_TNEWTON_RESTART
+(same without preconditioning), and
+.B NLOPT_LD_TNEWTON
+(same without restarting or preconditioning).
+.TP
+.B 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.
+.TP
+.B NLOPT_GN_ISRES
+Global (G) derivative-free (N) optimization using a genetic algorithm
+(mutation and differential evolution), using a stochastic ranking to
+handle nonlinear inequality and equality constraints as suggested by
+Runarsson and Yao.
+.TP
+\fBNLOPT_GD_MLSL_LDS\fR, \fBNLOPT_GN_MLSL_LDS\fR
+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 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 algorithm set by
+.I nlopt_set_local_optimizer
+(currently defaulting to
+.I NLOPT_LD_MMA
+and
+.I NLOPT_LN_COBYLA
+for derivative/nonderivative searches, respectively). There are also
+two other variants, \fBNLOPT_GD_MLSL\fR and \fBNLOPT_GN_MLSL\fR, which use
+pseudo-random numbers (instead of an LDS) as in the original MLSL algorithm.
+.TP
+.B 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.)
+The
+.B NLOPT_LD_MMA
+algorithm supports both bound-constrained and unconstrained optimization,
+and also supports an arbitrary number (\fIm\fR) of nonlinear constraints
+as described above.
+.TP
+.B NLOPT_LN_COBYLA
+Local (L) derivative-free (N) optimization using the COBYLA algorithm
+of Powell (Constrained Optimization BY Linear Approximations).
+The
+.B NLOPT_LN_COBYLA
+algorithm supports both bound-constrained and unconstrained optimization,
+and also supports an arbitrary number (\fIm\fR) of nonlinear constraints
+as described above.
+.TP
+.B NLOPT_LN_NEWUOA
+Local (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 algorithm
+is also available, as
+.BR NLOPT_LN_NEWUOA ,
+but this algorithm ignores the bound constraints
+.I lb
+and
+.IR ub ,
+and so it should only be used for unconstrained problems. Mostly
+superseded by BOBYQA.
+.TP
+.B NLOPT_LN_BOBYQA
+Local (L) derivative-free (N) optimization using the BOBYQA algorithm
+of Powell, based on successive quadratic approximations of the
+objective function, supporting bound constraints.
+.SH STOPPING CRITERIA
+Multiple stopping criteria for the optimization are supported, as
+specified by the functions to modify a given optimization problem
+.BR 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.
+.sp
+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).
+.TP
+.BI "nlopt_result nlopt_set_stopval(nlopt_opt " "opt" ,
+.br
+.BI " double " stopval );
+.sp
+Stop when an objective value of at least
+.I stopval
+is found: stop minimizing when a value <= \fIstopval\fR is found, or
+stop maximizing when a value >= \fIstopval\fR is found. (Setting
+\fIstopval\fR to -HUGE_VAL for minimizing or +HUGE_VAL for maximizing
+disables this stopping criterion.)
+.TP
+.BI "nlopt_result nlopt_set_ftol_rel(nlopt_opt " "opt" ,
+.br
+.BI " double " tol );
+.sp
+Set relative tolerance on function value: stop when an optimization step
+(or an estimate of the minimum) changes the function value by less
+than
+.I tol
+multiplied by the absolute value of the function value. (If there is any chance that your minimum function value is close to zero, you might want to set an absolute tolerance with
+.B nlopt_set_ftol_abs
+as well.) Criterion is disabled if \fItol\fR is non-positive.
+.TP
+.BI "nlopt_result nlopt_set_ftol_abs(nlopt_opt " "opt" ,
+.br
+.BI " double " tol );
+.sp
+Set absolute tolerance on function value: stop when an optimization step
+(or an estimate of the minimum) changes the function value by less
+than
+.IR tol .
+Criterion is disabled if \fItol\fR is non-positive.
+.TP
+.BI "nlopt_result nlopt_set_xtol_rel(nlopt_opt " "opt" ,
+.br
+.BI " double " tol );
+.sp
+Set relative tolerance on design variables: stop when an optimization step
+(or an estimate of the minimum) changes every design variable by less
+than
+.I tol
+multiplied 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 absolute tolerance with
+.B nlopt_set_xtol_abs
+as well.) Criterion is disabled if \fItol\fR is non-positive.
+.TP
+.BI "nlopt_result nlopt_set_xtol_abs(nlopt_opt " "opt" ,
+.br
+.BI " const double* " tol );
+.sp
+Set absolute tolerances on design variables. \fItol\fR is a pointer
+to an array of length
+.I
+n giving the tolerances: stop when an
+optimization step (or an estimate of the minimum) changes every design
+variable
+.IR x [i]
+by less than
+.IR tol [i].
+.sp
+For convenience, the following function may be used to set the absolute tolerances in all \fIn\fR design variables to the same value:
+.sp
+.BI " nlopt_result nlopt_set_xtol_abs1(nlopt_opt " "opt" ,
+.br
+.BI " double " tol );
+.sp
+Criterion is disabled if \fItol\fR is non-positive.
+.TP
+.BI "nlopt_result nlopt_set_maxeval(nlopt_opt " "opt" ,
+.br
+.BI " int " maxeval );
+.sp
+Stop when the number of function evaluations exceeds
+.IR maxeval .
+(This is not a strict maximum: the number of function evaluations may
+exceed
+.I maxeval
+slightly, depending upon the algorithm.) Criterion is disabled
+if \fImaxeval\fR is non-positive.
+.TP
+.BI "nlopt_result nlopt_set_maxtime(nlopt_opt " "opt" ,
+.br
+.BI " double " maxtime );
+.sp
+Stop when the optimization time (in seconds) exceeds
+.IR maxtime .
+(This is not a strict maximum: the time may
+exceed
+.I maxtime
+slightly, depending upon the algorithm and on how slow your function
+evaluation is.) Criterion is disabled if \fImaxtime\fR is non-positive.
+.SH RETURN VALUE
+Most of the NLopt functions return an enumerated constant
+of type
+.BR nlopt_result ,
+which takes on one of the following values:
+.SS Successful termination (positive return values):
+.TP
+.B NLOPT_SUCCESS
+Generic success return value.
+.TP
+.B NLOPT_STOPVAL_REACHED
+Optimization stopped because
+.I stopval
+(above) was reached.
+.TP
+.B NLOPT_FTOL_REACHED
+Optimization stopped because
+.I ftol_rel
+or
+.I ftol_abs
+(above) was reached.
+.TP
+.B NLOPT_XTOL_REACHED
+Optimization stopped because
+.I xtol_rel
+or
+.I xtol_abs
+(above) was reached.
+.TP
+.B NLOPT_MAXEVAL_REACHED
+Optimization stopped because
+.I maxeval
+(above) was reached.
+.TP
+.B NLOPT_MAXTIME_REACHED
+Optimization stopped because
+.I maxtime
+(above) was reached.
+.SS Error codes (negative return values):
+.TP
+.B NLOPT_FAILURE
+Generic failure code.
+.TP
+.B NLOPT_INVALID_ARGS
+Invalid arguments (e.g. lower bounds are bigger than upper bounds, an
+unknown algorithm was specified, etcetera).
+.TP
+.B NLOPT_OUT_OF_MEMORY
+Ran out of memory.
+.SH LOCAL OPTIMIZER
+Some of the algorithms, especially MLSL and AUGLAG, use a different
+optimization algorithm as a subroutine, typically for local
+optimization. By default, they use MMA or COBYLA for gradient-based
+or derivative-free searching, respectively. However, you can change
+the local search algorithm and its tolerances by calling:
+.sp
+.BI " nlopt_result nlopt_set_local_optimizer(nlopt_opt " "opt" ,
+.br
+.BI " const nlopt_opt " "local_opt" );
+.sp
+Here, \fIlocal_opt\fR is another \fBnlopt_opt\fB object whose
+parameters are used to determine the local search algorithm and
+stopping criteria. (The objective function and nonlinear-constraint
+parameters of \fIlocal_opt\fR are ignored.) The dimension \fIn\fR of
+\fIlocal_opt\fR must match that of \fIopt\fR.
+.sp
+This function makes a copy of the \fIlocal_opt\fR object, so you can
+freely destroy your original \fIlocal_opt\fR afterwards.
+.SH INITIAL STEP SIZE
+For derivative-free local-optimization algorithms, the optimizer must
+somehow decide on some initial step size to perturb \fIx\fR 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 \fIx\fR. 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.
+.sp
+You can modify the initial step size by calling:
+.sp
+.BI " nlopt_result nlopt_set_initial_step(nlopt_opt " "opt" ,
+.br
+.BI " const double* " "dx" );
+.sp
+Here, \fIdx\fR is an array of length \fIn\fR containing the (nonzero)
+initial step size for each component of the design parameters \fIx\fR.
+For convenience, if you want to set the step sizes in every direction
+to be the same value, you can instead call:
+.sp
+.BI " nlopt_result nlopt_set_initial_step1(nlopt_opt " "opt" ,
+.br
+.BI " double " "dx" );
+.SH STOCHASTIC POPULATION
+Several of the stochastic search algorithms (e.g., CRS, MLSL, and
+ISRES) start by generating some initial "population" of random points
+\fIx\fR. By default, this initial population size is chosen
+heuristically in some algorithm-specific way, but the initial
+population can by changed by calling:
+.sp
+.BI " nlopt_result nlopt_set_population(nlopt_opt " "opt" ,
+.br
+.BI " unsigned " "pop" );
+.sp
+(A \fIpop\fR of zero implies that the heuristic default will be used.)
+.SH PSEUDORANDOM NUMBERS
+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 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:
+.sp
+.BI " void nlopt_srand(unsigned long " "seed" );
+.sp
+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.
+.SH AUTHORS
+Written by Steven G. Johnson.
+.PP
+Copyright (c) 2007-2010 Massachusetts Institute of Technology.
+.SH "SEE ALSO"
+nlopt_minimize(3)
~ianmdlvl / nlopt.git / commitdiff