octave/nlopt_optimize_usage.h

   1 #define NLOPT_OPTIMIZE_USAGE \
   2 "Usage: [xopt, fopt, retcode] = nlopt_optimize(opt, xinit)\n" \
   3 "\n" \
   4 "Optimizes (minimizes or maximizes) a nonlinear function under\n" \
   5 "nonlinear constraints from the starting guess xinit, where the\n" \
   6 "objective, constraints, stopping criteria, and other options are \n" \
   7 "specified in the structure opt described below.  A variety of local\n" \
   8 "and global optimization algorithms can be used, as specified by the \n" \
   9 "opt.algorithm parameter described below.  Returns the optimum\n" \
  10 "function value fopt, the location xopt of the optimum, and a\n" \
  11 "return code retcode described below (> 0 on success).\n" \
  12 "\n" \
  13 "The dimension (n) of the problem, i.e. the number of design variables,\n" \
  14 "is specified implicitly via the length of xinit.\n" \
  15 "\n" \
  16 "This function is a front-end for the external routine nlopt_optimize\n" \
  17 "in the free NLopt nonlinear-optimization library, which is a wrapper\n" \
  18 "around a number of free/open-source optimization subroutines.  More\n" \
  19 "details can be found on the NLopt web page (ab-initio.mit.edu/nlopt)\n" \
  20 "and also under 'man nlopt_minimize' on Unix.\n" \
  21 "\n" \
  22 "OBJECTIVE FUNCTION:\n" \
  23 "\n" \
  24 "The objective function f is specified via opt.min_objective or\n" \
  25 "opt.max_objective for minimization or maximization, respectively.\n" \
  26 "opt.min/max_objective should be a handle (@) to a function of the form:\n" \
  27 "\n" \
  28 "   [val, gradient] = f(x)\n" \
  29 "\n" \
  30 "where x is a row vector, val is the function value f(x), and gradient\n" \
  31 "is a row vector giving the gradient of the function with respect to x.\n" \
  32 "The gradient is only used for gradient-based optimization algorithms;\n" \
  33 "some of the algorithms (below) are derivative-free and only require\n" \
  34 "f to return val (its value).\n" \
  35 "\n" \
  36 "BOUND CONSTRAINTS:\n" \
  37 "\n" \
  38 "Lower and/or upper bounds for the design variables x are specified\n" \
  39 "via opt.lower_bounds and/or opt.upper_bounds, respectively: these\n" \
  40 "are vectors (of the same length as xinit, above) giving the bounds\n" \
  41 "in each component. An unbounded component may be specified by a\n" \
  42 "lower/upper bound of -inf/+inf, respectively.  If opt.lower_bounds\n" \
  43 "and/or opt.upper_bounds are not specified, the default bounds are\n" \
  44 "-inf/+inf (i.e. unbounded), respectively.\n" \
  45 "\n" \
  46 "NONLINEAR CONSTRAINTS:\n" \
  47 "\n" \
  48 "Several of the algorithms in NLopt (MMA, COBYLA, and ORIG_DIRECT) also\n" \
  49 "support arbitrary nonlinear inequality constraints, and some also allow\n" \
  50 "nonlinear equality constraints (ISRES and AUGLAG). For these \n" \
  51 "algorithms, you can specify as many nonlinear constraints as you wish.\n" \
  52 "(The default is no nonlinear constraints.)\n" \
  53 "\n" \
  54 "Inequality constraints of the form fc{i}(x) <= 0 are specified via opt.fc,\n" \
  55 "which is a cell array of function handles (@) of the same form as\n" \
  56 "the objective function above (i.e., returning the value and optionally\n" \
  57 "the gradient of the constraint function fc{i}, where the gradient is\n" \
  58 "only needed for gradient-based algorithms).\n" \
  59 "\n" \
  60 "Equality constraints of the form h{i}(x) = 0 are specified via opt.h,\n" \
  61 "which is a cell array of function handles (@) of the same form as\n" \
  62 "the objective function above (i.e., returning the value and optionally\n" \
  63 "the gradient of the constraint function h{i}, where the gradient is\n" \
  64 "only needed for gradient-based algorithms).\n" \
  65 "\n" \
  66 "For both inequality and equality constraints, you can supply a\n" \
  67 "\"tolerance\" for each constraint: this tolerance is used for convergence\n" \
  68 "tests only, and a point x is considered feasible for purposes of\n" \
  69 "convergence if the constraint is violated by the given tolerance.\n" \
  70 "The tolerances are specified via opt.fc_tol and opt.h_tol, respectively,\n" \
  71 "which must be vectors of the same length as opt.fc and opt.h, so\n" \
  72 "that opt.fc_tol(i) is the tolerance for opt.fc{i} and opt.h_tol(i)\n" \
  73 "is the tolerance for opt.h{i}.  These tolerances default to zero; a\n" \
  74 "small nonzero tolerance is recommended, however, especially for h_tol.\n" \
  75 "\n" \
  76 "ALGORITHMS\n" \
  77 "\n" \
  78 "The optimization algorithm must be specified via opt.algorithm.\n" \
  79 "\n" \
  80 "The algorithm should be one of the following constants (name and\n" \
  81 "interpretation are the same as for the C language interface).  Names\n" \
  82 "with _G*_ are global optimization, and names with _L*_ are local\n" \
  83 "optimization.  Names with _*N_ are derivative-free, while names\n" \
  84 "with _*D_ are gradient-based algorithms.  Algorithms:\n" \
  85 "\n" \
  86 "NLOPT_GD_MLSL_LDS, NLOPT_GD_MLSL, NLOPT_GD_STOGO, NLOPT_GD_STOGO_RAND, \n" \
  87 "NLOPT_GN_CRS2_LM, NLOPT_GN_DIRECT_L, NLOPT_GN_DIRECT_L_NOSCAL, \n" \
  88 "NLOPT_GN_DIRECT_L_RAND, NLOPT_GN_DIRECT_L_RAND_NOSCAL, NLOPT_GN_DIRECT, \n" \
  89 "NLOPT_GN_DIRECT_NOSCAL, NLOPT_GN_ISRES, NLOPT_GN_MLSL_LDS, NLOPT_GN_MLSL, \n" \
  90 "NLOPT_GN_ORIG_DIRECT_L, NLOPT_GN_ORIG_DIRECT, NLOPT_LD_AUGLAG_EQ, \n" \
  91 "NLOPT_LD_AUGLAG, NLOPT_LD_LBFGS, NLOPT_LD_LBFGS_NOCEDAL, NLOPT_LD_MMA, \n" \
  92 "NLOPT_LD_TNEWTON, NLOPT_LD_TNEWTON_PRECOND, \n" \
  93 "NLOPT_LD_TNEWTON_PRECOND_RESTART, NLOPT_LD_TNEWTON_RESTART, \n" \
  94 "NLOPT_LD_VAR1, NLOPT_LD_VAR2, NLOPT_LN_AUGLAG_EQ, NLOPT_LN_AUGLAG, \n" \
  95 "NLOPT_LN_BOBYQA, NLOPT_LN_COBYLA, NLOPT_LN_NELDERMEAD, \n" \
  96 "NLOPT_LN_NEWUOA_BOUND, NLOPT_LN_NEWUOA, NLOPT_LN_PRAXIS, NLOPT_LN_SBPLX\n" \
  97 "\n" \
  98 "For more information on individual algorithms, see their individual\n" \
  99 "help pages (e.g. \"help NLOPT_LN_SBPLX\").\n" \
 100 "\n" \
 101 "STOPPING CRITERIA:\n" \
 102 "\n" \
 103 "Multiple stopping criteria can be specified by setting one or more of\n" \
 104 "the following fields of opt.  The optimization halts whenever any\n" \
 105 "one of the given criteria is satisfied.\n" \
 106 "\n" \
 107 "opt.stopval: Stop when an objective value of at least stopval is found.\n" \
 108 "   That is, stop minimizing when a value <= stopval is found, or stop\n" \
 109 "   maximizing when a value >= stopval is found.\n" \
 110 "\n" \
 111 "opt.ftol_rel: Relative tolerance on function value, to stop when\n" \
 112 "   an optimization step (or an estimate of the optimum) changes\n" \
 113 "   the function value by less than opt.ftol_rel multiplied by\n" \
 114 "   the absolute value of the function.\n" \
 115 "\n" \
 116 "opt.ftol_abs: Absolute tolerance on function value, to stop when\n" \
 117 "   an optimization step (or an estimate of the optimum) changes\n" \
 118 "   the function value by less than opt.ftol_abs.\n" \
 119 "\n" \
 120 "opt.xtol_rel: Relative tolerance on function value, to stop when\n" \
 121 "   an optimization step (or an estimate of the optimum) changes\n" \
 122 "   every component of x by less than opt.xtol_rel multiplied by\n" \
 123 "   the absolute value of that component of x.\n" \
 124 "\n" \
 125 "opt.xtol_abs: Absolute tolerance on function value, to stop when\n" \
 126 "   an optimization step (or an estimate of the optimum) changes\n" \
 127 "   every component of x by less than that component of opt.xtol_abs\n" \
 128 "   -- should be a vector of same length as x.\n" \
 129 "\n" \
 130 "opt.maxeval: Maximum number of function evaluations.\n" \
 131 "\n" \
 132 "opt.maxtime: Maximum runtime (in seconds) for the optimization.\n" \
 133 "\n" \
 134 "RETURN CODE:\n" \
 135 "\n" \
 136 "The retcode result is positive upon successful completion, and\n" \
 137 "negative for an error.  The specific values are:\n" \
 138 "\n" \
 139 "generic success code: +1\n" \
 140 "     stopval reached: +2\n" \
 141 "        ftol reached: +3\n" \
 142 "        xtol reached: +4\n" \
 143 "     maxeval reached: +5\n" \
 144 "     maxtime reached: +6\n" \
 145 "generic failure code: -1\n" \
 146 "   invalid arguments: -2\n" \
 147 "       out of memory: -3\n" \
 148 "    roundoff-limited: -4\n" \
 149 "\n" \
 150 "LOCAL OPTIMIZER:\n" \
 151 "\n" \
 152 "Some of the algorithms, especially MLSL and AUGLAG, use a different\n" \
 153 "optimization algorithm as a subroutine, typically for local optimization.\n" \
 154 "By default, they use MMA or COBYLA for gradient-based or derivative-free\n" \
 155 "searching, respectively.  However, you can change this by specifying\n" \
 156 "opt.local_optimizer: this is a structure with the same types of fields as opt\n" \
 157 "(stopping criteria, algorithm, etcetera).  The objective function\n" \
 158 "and nonlinear constraint parameters of opt.local_optimizer are ignored.\n" \
 159 "\n" \
 160 "INITIAL STEP SIZE:\n" \
 161 "\n" \
 162 "For derivative-free local-optimization algorithms, the optimizer must\n" \
 163 "somehow decide on some initial step size to perturb x by when it begins\n" \
 164 "the optimization. This step size should be big enough that the value\n" \
 165 "of the objective changes significantly, but not too big if you want to\n" \
 166 "find the local optimum nearest to x. By default, NLopt chooses this\n" \
 167 "initial step size heuristically from the bounds, tolerances, and other\n" \
 168 "information, but this may not always be the best choice.\n" \
 169 "\n" \
 170 "You can modify the initial step by setting opt.initial_step, which\n" \
 171 "is a vector of the same length as x containing the (nonzero) initial\n" \
 172 "step size for each component of x.\n" \
 173 "\n" \
 174 "STOCHASTIC POPULATION:\n" \
 175 "\n" \
 176 "Several of the stochastic search algorithms (e.g., CRS, MLSL, and\n" \
 177 "ISRES) start by generating some initial \"population\" of random points\n" \
 178 "x. By default, this initial population size is chosen heuristically in\n" \
 179 "some algorithm-specific way, but the initial population can by changed\n" \
 180 "by setting opt.population to the desired initial population size.\n" \
 181 "\n" \
 182 "VERBOSE OUTPUT:\n" \
 183 "\n" \
 184 "If opt.verbose is set to a nonzero value, then nlopt_optimize\n" \
 185 "will print out verbose output; for example, it will print the\n" \
 186 "value of the objective function after each evaluation.\n" \
 187 "\n" \
 188 "MORE INFORMATION:\n" \
 189 "\n" \
 190 "For more documentation, such as a detailed description of all the\n" \
 191 "algorithms, see the NLopt home page: http://ab-initio.mit.edu/nlopt\n" \
 192