From: stevenj Date: Wed, 12 May 2010 02:14:54 +0000 (-0400) Subject: replace Octave nlopt_minimize_constrained with wrapper around new nlopt_optimize... X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=cfdea70b69f5b13cc1d109be883c9e2258382ecd;p=nlopt.git replace Octave nlopt_minimize_constrained with wrapper around new nlopt_optimize, and document the latter darcs-hash:20100512021454-c8de0-d8c1513f66476aa316e32561e5dc648aca70e06f.gz --- diff --git a/octave/Makefile.am b/octave/Makefile.am index 53708dd..c03c40c 100644 --- a/octave/Makefile.am +++ b/octave/Makefile.am @@ -12,7 +12,7 @@ dummy_SOURCES = dummy.c octdir = $(OCT_INSTALL_DIR) mdir = $(M_INSTALL_DIR) if WITH_OCTAVE -oct_DATA = nlopt_minimize_constrained.oct nlopt_optimize.oct +oct_DATA = nlopt_optimize.oct m_DATA = $(MFILES) nlopt_minimize.m nlopt_minimize_constrained.m nlopt_optimize.m endif @@ -35,7 +35,7 @@ nlopt_optimize_usage.h: $(srcdir)/nlopt_optimize.m ####################################################################### mexdir = $(MEX_INSTALL_DIR) if WITH_MATLAB -mex_DATA = nlopt_minimize_constrained.$(MEXSUFF) $(MFILES) nlopt_minimize.m nlopt_minimize_constrained.m +mex_DATA = $(MFILES) nlopt_minimize.m nlopt_minimize_constrained.m endif nlopt_minimize_constrained.$(MEXSUFF): nlopt_minimize_constrained-mex.c $(top_builddir)/.libs/libnlopt@NLOPT_SUFFIX@.la diff --git a/octave/nlopt_minimize_constrained.m b/octave/nlopt_minimize_constrained.m index 2704807..fb9d503 100644 --- a/octave/nlopt_minimize_constrained.m +++ b/octave/nlopt_minimize_constrained.m @@ -87,3 +87,17 @@ % % For more information on individual algorithms, see their individual % help pages (e.g. "help NLOPT_LN_SBPLX"). +function [xopt, fmin, retcode] = nlopt_minimize_constrained(algorithm, f, f_data, fc, fc_data, lb, ub, xinit, stop) + +opt = stop; +if (isfield(stop, 'minf_max')) + opt.stopval = stop.minf_max; +end +opt.algorithm = algorithm; +opt.min_objective = @(x) f(x, f_data{:}); +opt.lb = lb; +opt.ub = ub; +for i = 1:length(fc) + opt.fc{i} = @(x) fc{i}(x, fc_data{i}{:}); +end +[xopt, fmin, retcode] = nlopt_optimize(opt, xinit); diff --git a/octave/nlopt_optimize-oct.cc b/octave/nlopt_optimize-oct.cc index 5a393cf..3ec290c 100644 --- a/octave/nlopt_optimize-oct.cc +++ b/octave/nlopt_optimize-oct.cc @@ -205,7 +205,7 @@ nlopt_opt make_opt(Octave_map &opts, int n) return opt; } -#define CHECK(cond, msg) if (!(cond)) { fprintf(stderr, msg "\n\n"); print_usage("nlopt_optimize"); nlopt_destroy(opt); return retval; } +#define CHECK(cond, msg) if (!(cond)) { fprintf(stderr, msg "\n\n"); nlopt_destroy(opt); return retval; } DEFUN_DLD(nlopt_optimize, args, nargout, NLOPT_OPTIMIZE_USAGE) { diff --git a/octave/nlopt_optimize.m b/octave/nlopt_optimize.m index c2e486f..4230e22 100644 --- a/octave/nlopt_optimize.m +++ b/octave/nlopt_optimize.m @@ -9,8 +9,181 @@ % function value fopt, the location xopt of the optimum, and a % return code retcode described below (> 0 on success). % +% The dimension (n) of the problem, i.e. the number of design variables, +% is specified implicitly via the length of xinit. +% % This function is a front-end for the external routine nlopt_optimize % in the free NLopt nonlinear-optimization library, which is a wrapper % around a number of free/open-source optimization subroutines. More % details can be found on the NLopt web page (ab-initio.mit.edu/nlopt) % and also under 'man nlopt_minimize' on Unix. +% +% OBJECTIVE FUNCTION: +% +% The objective function f is specified via opt.min_objective or +% opt.max_objective for minimization or maximization, respectively. +% opt.min/max_objective should be a handle (@) to a function of the form: +% +% [val, gradient] = f(x) +% +% where x is a row vector, val is the function value f(x), and gradient +% is a row vector giving the gradient of the function with respect to x. +% The gradient is only used for gradient-based optimization algorithms; +% some of the algorithms (below) are derivative-free and only require +% f to return val (its value). +% +% BOUND CONSTRAINTS: +% +% Lower and/or upper bounds for the design variables x are specified +% via opt.lb and/or opt.ub, respectively: these are vectors (of the +% same length as xinit, above) giving the bounds in each component. +% An unbounded component may be specified by a lower/upper bound of +% -inf/+inf, respectively. If opt.lb and/or opt.ub are not specified, +% the default bounds are -inf/+inf (i.e. unbounded), respectively. +% +% 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. +% (The default is no nonlinear constraints.) +% +% Inequality constraints of the form fc{i}(x) <= 0 are specified via opt.fc, +% which is a cell array of function handles (@) of the same form as +% the objective function above (i.e., returning the value and optionally +% the gradient of the constraint function fc{i}, where the gradient is +% only needed for gradient-based algorithms). +% +% Equality constraints of the form h{i}(x) = 0 are specified via opt.h, +% which is a cell array of function handles (@) of the same form as +% the objective function above (i.e., returning the value and optionally +% the gradient of the constraint function h{i}, where the gradient is +% only needed for gradient-based algorithms). +% +% For both inequality and equality constraints, you can supply a +% "tolerance" for each constraint: this tolerance is used for convergence +% tests only, and a point x is considered feasible for purposes of +% convergence if the constraint is violated by the given tolerance. +% The tolerances are specified via opt.fc_tol and opt.h_tol, respectively, +% which must be vectors of the same length as opt.fc and opt.h, so +% that opt.fc_tol(i) is the tolerance for opt.fc{i} and opt.h_tol(i) +% is the tolerance for opt.h{i}. These tolerances default to zero; a +% small nonzero tolerance is recommended, however, especially for h_tol. +% +% ALGORITHMS +% +% The optimization algorithm must be specified via opt.algorithm. +% +% The algorithm should be one of the following constants (name and +% interpretation are the same as for the C language interface). Names +% with _G*_ are global optimization, and names with _L*_ are local +% optimization. Names with _*N_ are derivative-free, while names +% with _*D_ are gradient-based algorithms. Algorithms: +% +% NLOPT_GD_MLSL_LDS, NLOPT_GD_MLSL, NLOPT_GD_STOGO, NLOPT_GD_STOGO_RAND, +% NLOPT_GN_CRS2_LM, NLOPT_GN_DIRECT_L, NLOPT_GN_DIRECT_L_NOSCAL, +% NLOPT_GN_DIRECT_L_RAND, NLOPT_GN_DIRECT_L_RAND_NOSCAL, NLOPT_GN_DIRECT, +% NLOPT_GN_DIRECT_NOSCAL, NLOPT_GN_ISRES, NLOPT_GN_MLSL_LDS, NLOPT_GN_MLSL, +% NLOPT_GN_ORIG_DIRECT_L, NLOPT_GN_ORIG_DIRECT, NLOPT_LD_AUGLAG_EQ, +% NLOPT_LD_AUGLAG, NLOPT_LD_LBFGS, NLOPT_LD_LBFGS_NOCEDAL, NLOPT_LD_MMA, +% NLOPT_LD_TNEWTON, NLOPT_LD_TNEWTON_PRECOND, +% NLOPT_LD_TNEWTON_PRECOND_RESTART, NLOPT_LD_TNEWTON_RESTART, +% NLOPT_LD_VAR1, NLOPT_LD_VAR2, NLOPT_LN_AUGLAG_EQ, NLOPT_LN_AUGLAG, +% NLOPT_LN_BOBYQA, NLOPT_LN_COBYLA, NLOPT_LN_NELDERMEAD, +% NLOPT_LN_NEWUOA_BOUND, NLOPT_LN_NEWUOA, NLOPT_LN_PRAXIS, NLOPT_LN_SBPLX +% +% For more information on individual algorithms, see their individual +% help pages (e.g. "help NLOPT_LN_SBPLX"). +% +% STOPPING CRITERIA: +% +% Multiple stopping criteria can be specified by setting one or more of +% the following fields of opt. The optimization halts whenever any +% one of the given criteria is satisfied. +% +% opt.stopval: Stop when an objective value of at least stopval is found. +% That is, stop minimizing when a value <= stopval is found, or stop +% maximizing when a value >= stopval is found. +% +% opt.ftol_rel: Relative tolerance on function value, to stop when +% an optimization step (or an estimate of the optimum) changes +% the function value by less than opt.ftol_rel multiplied by +% the absolute value of the function. +% +% opt.ftol_abs: Absolute tolerance on function value, to stop when +% an optimization step (or an estimate of the optimum) changes +% the function value by less than opt.ftol_abs. +% +% opt.xtol_rel: Relative tolerance on function value, to stop when +% an optimization step (or an estimate of the optimum) changes +% every component of x by less than opt.xtol_rel multiplied by +% the absolute value of that component of x. +% +% opt.xtol_abs: Absolute tolerance on function value, to stop when +% an optimization step (or an estimate of the optimum) changes +% every component of x by less than that component of opt.xtol_abs +% -- should be a vector of same length as x. +% +% opt.maxeval: Maximum number of function evaluations. +% +% opt.maxtime: Maximum runtime (in seconds) for the optimization. +% +% RETURN CODE: +% +% The retcode result is positive upon successful completion, and +% negative for an error. The specific values are: +% +% generic success code: +1 +% stopval reached: +2 +% ftol reached: +3 +% xtol reached: +4 +% maxeval reached: +5 +% maxtime reached: +6 +% generic failure code: -1 +% invalid arguments: -2 +% out of memory: -3 +% roundoff-limited: -4 +% +% 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 this by specifying +% opt.local_opt: this is a structure with the same types of fields as opt +% (stopping criteria, algorithm, etcetera). The objective function +% and nonlinear constraint parameters of opt.local_opt are ignored. +% +% INITIAL STEP SIZE: +% +% For derivative-free local-optimization 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 by setting opt.initial_step, which +% is a vector of the same length as x containing the (nonzero) initial +% step size for each component of x. +% +% STOCHASTIC POPULATION: +% +% Several 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 algorithm-specific way, but the initial population can by changed +% by setting opt.population to the desired initial population size. +% +% VERBOSE OUTPUT: +% +% If opt.verbose is set to a nonzero value, then nlopt_optimize +% will print out verbose output; for example, it will print the +% value of the objective function after each evaluation. +% +% MORE INFORMATION: +% +% For more documentation, such as a detailed description of all the +% algorithms, see the NLopt home page: http://ab-initio.mit.edu/nlopt