api/nlopt.h

   1 /* Copyright (c) 2007-2014 Massachusetts Institute of Technology
   2  *
   3  * Permission is hereby granted, free of charge, to any person obtaining
   4  * a copy of this software and associated documentation files (the
   5  * "Software"), to deal in the Software without restriction, including
   6  * without limitation the rights to use, copy, modify, merge, publish,
   7  * distribute, sublicense, and/or sell copies of the Software, and to
   8  * permit persons to whom the Software is furnished to do so, subject to
   9  * the following conditions:
  10  *
  11  * The above copyright notice and this permission notice shall be
  12  * included in all copies or substantial portions of the Software.
  13  *
  14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  15  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  17  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  18  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  19  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  20  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21  */
  22
  23 #ifndef NLOPT_H
  24 #define NLOPT_H
  25
  26 #include <stddef.h> /* for ptrdiff_t and size_t */
  27
  28 /* Change 0 to 1 to use stdcall convention under Win32 */
  29 #if 0 && (defined(_WIN32) || defined(__WIN32__))
  30 #  if defined(__GNUC__)
  31 #    define NLOPT_STDCALL __attribute__((stdcall))
  32 #  elif defined(_MSC_VER) || defined(_ICC) || defined(_STDCALL_SUPPORTED)
  33 #    define NLOPT_STDCALL __stdcall
  34 #  else
  35 #    define NLOPT_STDCALL
  36 #  endif
  37 #else
  38 #  define NLOPT_STDCALL
  39 #endif
  40
  41 /* for Windows compilers, you should add a line
  42            #define NLOPT_DLL
  43    when using NLopt from a DLL, in order to do the proper
  44    Windows importing nonsense. */
  45 #if defined(NLOPT_DLL) && (defined(_WIN32) || defined(__WIN32__)) && !defined(__LCC__)
  46 /* annoying Windows syntax for calling functions in a DLL */
  47 #  if defined(NLOPT_DLL_EXPORT)
  48 #    define NLOPT_EXTERN(T) extern __declspec(dllexport) T NLOPT_STDCALL
  49 #  else
  50 #    define NLOPT_EXTERN(T) extern __declspec(dllimport) T NLOPT_STDCALL
  51 #  endif
  52 #else
  53 #  define NLOPT_EXTERN(T) extern T NLOPT_STDCALL
  54 #endif
  55
  56 #ifdef __cplusplus
  57 extern "C"
  58 {
  59 #endif /* __cplusplus */
  60
  61 typedef double (*nlopt_func)(unsigned n, const double *x,
  62                              double *gradient, /* NULL if not needed */
  63                              void *func_data);
  64
  65 typedef void (*nlopt_mfunc)(unsigned m, double *result,
  66                             unsigned n, const double *x,
  67                              double *gradient, /* NULL if not needed */
  68                              void *func_data);
  69
  70 /* A preconditioner, which preconditions v at x to return vpre.
  71    (The meaning of "preconditioning" is algorithm-dependent.) */
  72 typedef void (*nlopt_precond)(unsigned n, const double *x, const double *v,
  73                               double *vpre, void *data);
  74
  75 typedef enum {
  76      /* Naming conventions:
  77
  78         NLOPT_{G/L}{D/N}_*
  79             = global/local derivative/no-derivative optimization,
  80               respectively
  81
  82         *_RAND algorithms involve some randomization.
  83
  84         *_NOSCAL algorithms are *not* scaled to a unit hypercube
  85                  (i.e. they are sensitive to the units of x)
  86         */
  87
  88      NLOPT_GN_DIRECT = 0,
  89      NLOPT_GN_DIRECT_L,
  90      NLOPT_GN_DIRECT_L_RAND,
  91      NLOPT_GN_DIRECT_NOSCAL,
  92      NLOPT_GN_DIRECT_L_NOSCAL,
  93      NLOPT_GN_DIRECT_L_RAND_NOSCAL,
  94
  95      NLOPT_GN_ORIG_DIRECT,
  96      NLOPT_GN_ORIG_DIRECT_L,
  97
  98      NLOPT_GD_STOGO,
  99      NLOPT_GD_STOGO_RAND,
 100
 101      NLOPT_LD_LBFGS_NOCEDAL,
 102
 103      NLOPT_LD_LBFGS,
 104
 105      NLOPT_LN_PRAXIS,
 106
 107      NLOPT_LD_VAR1,
 108      NLOPT_LD_VAR2,
 109
 110      NLOPT_LD_TNEWTON,
 111      NLOPT_LD_TNEWTON_RESTART,
 112      NLOPT_LD_TNEWTON_PRECOND,
 113      NLOPT_LD_TNEWTON_PRECOND_RESTART,
 114
 115      NLOPT_GN_CRS2_LM,
 116
 117      NLOPT_GN_MLSL,
 118      NLOPT_GD_MLSL,
 119      NLOPT_GN_MLSL_LDS,
 120      NLOPT_GD_MLSL_LDS,
 121
 122      NLOPT_LD_MMA,
 123
 124      NLOPT_LN_COBYLA,
 125
 126      NLOPT_LN_NEWUOA,
 127      NLOPT_LN_NEWUOA_BOUND,
 128
 129      NLOPT_LN_NELDERMEAD,
 130      NLOPT_LN_SBPLX,
 131
 132      NLOPT_LN_AUGLAG,
 133      NLOPT_LD_AUGLAG,
 134      NLOPT_LN_AUGLAG_EQ,
 135      NLOPT_LD_AUGLAG_EQ,
 136
 137      NLOPT_LN_BOBYQA,
 138
 139      NLOPT_GN_ISRES,
 140
 141      /* new variants that require local_optimizer to be set,
 142         not with older constants for backwards compatibility */
 143      NLOPT_AUGLAG,
 144      NLOPT_AUGLAG_EQ,
 145      NLOPT_G_MLSL,
 146      NLOPT_G_MLSL_LDS,
 147
 148      NLOPT_LD_SLSQP,
 149
 150      NLOPT_LD_CCSAQ,
 151
 152      NLOPT_GN_ESCH,
 153
 154      NLOPT_NUM_ALGORITHMS /* not an algorithm, just the number of them */
 155 } nlopt_algorithm;
 156
 157 NLOPT_EXTERN(const char *) nlopt_algorithm_name(nlopt_algorithm a);
 158
 159 typedef enum {
 160      NLOPT_FAILURE = -1, /* generic failure code */
 161      NLOPT_INVALID_ARGS = -2,
 162      NLOPT_OUT_OF_MEMORY = -3,
 163      NLOPT_ROUNDOFF_LIMITED = -4,
 164      NLOPT_FORCED_STOP = -5,
 165      NLOPT_SUCCESS = 1, /* generic success code */
 166      NLOPT_STOPVAL_REACHED = 2,
 167      NLOPT_FTOL_REACHED = 3,
 168      NLOPT_XTOL_REACHED = 4,
 169      NLOPT_MAXEVAL_REACHED = 5,
 170      NLOPT_MAXTIME_REACHED = 6
 171 } nlopt_result;
 172
 173 #define NLOPT_MINF_MAX_REACHED NLOPT_STOPVAL_REACHED
 174
 175 NLOPT_EXTERN(void) nlopt_srand(unsigned long seed);
 176 NLOPT_EXTERN(void) nlopt_srand_time(void);
 177
 178 NLOPT_EXTERN(void) nlopt_version(int *major, int *minor, int *bugfix);
 179
 180 /*************************** OBJECT-ORIENTED API **************************/
 181 /* The style here is that we create an nlopt_opt "object" (an opaque pointer),
 182    then set various optimization parameters, and then execute the
 183    algorithm.  In this way, we can add more and more optimization parameters
 184    (including algorithm-specific ones) without breaking backwards
 185    compatibility, having functions with zillions of parameters, or
 186    relying non-reentrantly on global variables.*/
 187
 188 struct nlopt_opt_s; /* opaque structure, defined internally */
 189 typedef struct nlopt_opt_s *nlopt_opt;
 190
 191 /* the only immutable parameters of an optimization are the algorithm and
 192    the dimension n of the problem, since changing either of these could
 193    have side-effects on lots of other parameters */
 194 NLOPT_EXTERN(nlopt_opt) nlopt_create(nlopt_algorithm algorithm, unsigned n);
 195 NLOPT_EXTERN(void) nlopt_destroy(nlopt_opt opt);
 196 NLOPT_EXTERN(nlopt_opt) nlopt_copy(const nlopt_opt opt);
 197
 198 NLOPT_EXTERN(nlopt_result) nlopt_optimize(nlopt_opt opt, double *x,
 199                                          double *opt_f);
 200
 201 NLOPT_EXTERN(nlopt_result) nlopt_set_min_objective(nlopt_opt opt, nlopt_func f,
 202                                                   void *f_data);
 203 NLOPT_EXTERN(nlopt_result) nlopt_set_max_objective(nlopt_opt opt, nlopt_func f,
 204                                                   void *f_data);
 205
 206 NLOPT_EXTERN(nlopt_result) nlopt_set_precond_min_objective(nlopt_opt opt, nlopt_func f, nlopt_precond pre, void *f_data);
 207 NLOPT_EXTERN(nlopt_result) nlopt_set_precond_max_objective(nlopt_opt opt, nlopt_func f, nlopt_precond pre, void *f_data);
 208
 209 NLOPT_EXTERN(nlopt_algorithm) nlopt_get_algorithm(const nlopt_opt opt);
 210 NLOPT_EXTERN(unsigned) nlopt_get_dimension(const nlopt_opt opt);
 211
 212 NLOPT_EXTERN(const char*) nlopt_get_errmsg(nlopt_opt opt);
 213
 214 /* constraints: */
 215
 216 NLOPT_EXTERN(nlopt_result) nlopt_set_lower_bounds(nlopt_opt opt,
 217                                                  const double *lb);
 218 NLOPT_EXTERN(nlopt_result) nlopt_set_lower_bounds1(nlopt_opt opt, double lb);
 219 NLOPT_EXTERN(nlopt_result) nlopt_get_lower_bounds(const nlopt_opt opt,
 220                                                  double *lb);
 221 NLOPT_EXTERN(nlopt_result) nlopt_set_upper_bounds(nlopt_opt opt,
 222                                                  const double *ub);
 223 NLOPT_EXTERN(nlopt_result) nlopt_set_upper_bounds1(nlopt_opt opt, double ub);
 224 NLOPT_EXTERN(nlopt_result) nlopt_get_upper_bounds(const nlopt_opt opt,
 225                                                  double *ub);
 226
 227 NLOPT_EXTERN(nlopt_result) nlopt_remove_inequality_constraints(nlopt_opt opt);
 228 NLOPT_EXTERN(nlopt_result) nlopt_add_inequality_constraint(nlopt_opt opt,
 229                                                           nlopt_func fc,
 230                                                           void *fc_data,
 231                                                           double tol);
 232 NLOPT_EXTERN(nlopt_result) nlopt_add_precond_inequality_constraint(
 233      nlopt_opt opt, nlopt_func fc, nlopt_precond pre, void *fc_data,
 234      double tol);
 235 NLOPT_EXTERN(nlopt_result) nlopt_add_inequality_mconstraint(nlopt_opt opt,
 236                                                             unsigned m,
 237                                                             nlopt_mfunc fc,
 238                                                             void *fc_data,
 239                                                             const double *tol);
 240
 241 NLOPT_EXTERN(nlopt_result) nlopt_remove_equality_constraints(nlopt_opt opt);
 242 NLOPT_EXTERN(nlopt_result) nlopt_add_equality_constraint(nlopt_opt opt,
 243                                                         nlopt_func h,
 244                                                         void *h_data,
 245                                                         double tol);
 246 NLOPT_EXTERN(nlopt_result) nlopt_add_precond_equality_constraint(
 247      nlopt_opt opt, nlopt_func h, nlopt_precond pre, void *h_data,
 248      double tol);
 249 NLOPT_EXTERN(nlopt_result) nlopt_add_equality_mconstraint(nlopt_opt opt,
 250                                                           unsigned m,
 251                                                           nlopt_mfunc h,
 252                                                           void *h_data,
 253                                                           const double *tol);
 254
 255 /* stopping criteria: */
 256
 257 NLOPT_EXTERN(nlopt_result) nlopt_set_stopval(nlopt_opt opt, double stopval);
 258 NLOPT_EXTERN(double) nlopt_get_stopval(const nlopt_opt opt);
 259
 260 NLOPT_EXTERN(nlopt_result) nlopt_set_ftol_rel(nlopt_opt opt, double tol);
 261 NLOPT_EXTERN(double) nlopt_get_ftol_rel(const nlopt_opt opt);
 262 NLOPT_EXTERN(nlopt_result) nlopt_set_ftol_abs(nlopt_opt opt, double tol);
 263 NLOPT_EXTERN(double) nlopt_get_ftol_abs(const nlopt_opt opt);
 264
 265 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_rel(nlopt_opt opt, double tol);
 266 NLOPT_EXTERN(double) nlopt_get_xtol_rel(const nlopt_opt opt);
 267 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_abs1(nlopt_opt opt, double tol);
 268 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_abs(nlopt_opt opt, const double *tol);
 269 NLOPT_EXTERN(nlopt_result) nlopt_get_xtol_abs(const nlopt_opt opt,
 270                                              double *tol);
 271
 272 NLOPT_EXTERN(nlopt_result) nlopt_set_maxeval(nlopt_opt opt, int maxeval);
 273 NLOPT_EXTERN(int) nlopt_get_maxeval(const nlopt_opt opt);
 274
 275 NLOPT_EXTERN(nlopt_result) nlopt_set_maxtime(nlopt_opt opt, double maxtime);
 276 NLOPT_EXTERN(double) nlopt_get_maxtime(const nlopt_opt opt);
 277
 278 NLOPT_EXTERN(nlopt_result) nlopt_force_stop(nlopt_opt opt);
 279 NLOPT_EXTERN(nlopt_result) nlopt_set_force_stop(nlopt_opt opt, int val);
 280 NLOPT_EXTERN(int) nlopt_get_force_stop(const nlopt_opt opt);
 281
 282 /* more algorithm-specific parameters */
 283
 284 NLOPT_EXTERN(nlopt_result) nlopt_set_local_optimizer(nlopt_opt opt,
 285                                                     const nlopt_opt local_opt);
 286
 287 NLOPT_EXTERN(nlopt_result) nlopt_set_population(nlopt_opt opt, unsigned pop);
 288 NLOPT_EXTERN(unsigned) nlopt_get_population(const nlopt_opt opt);
 289
 290 NLOPT_EXTERN(nlopt_result) nlopt_set_vector_storage(nlopt_opt opt, unsigned dim);
 291 NLOPT_EXTERN(unsigned) nlopt_get_vector_storage(const nlopt_opt opt);
 292
 293 NLOPT_EXTERN(nlopt_result) nlopt_set_default_initial_step(nlopt_opt opt,
 294                                                          const double *x);
 295 NLOPT_EXTERN(nlopt_result) nlopt_set_initial_step(nlopt_opt opt,
 296                                                  const double *dx);
 297 NLOPT_EXTERN(nlopt_result) nlopt_set_initial_step1(nlopt_opt opt, double dx);
 298 NLOPT_EXTERN(nlopt_result) nlopt_get_initial_step(const nlopt_opt opt,
 299                                                  const double *x, double *dx);
 300
 301 /* the following are functions mainly designed to be used internally
 302    by the Fortran and SWIG wrappers, allow us to tel nlopt_destroy and
 303    nlopt_copy to do something to the f_data pointers (e.g. free or
 304    duplicate them, respectively) */
 305 typedef void* (*nlopt_munge)(void *p);
 306 NLOPT_EXTERN(void) nlopt_set_munge(nlopt_opt opt,
 307                                   nlopt_munge munge_on_destroy,
 308                                   nlopt_munge munge_on_copy);
 309 typedef void* (*nlopt_munge2)(void *p, void *data);
 310 NLOPT_EXTERN(void) nlopt_munge_data(nlopt_opt opt,
 311                                     nlopt_munge2 munge, void *data);
 312
 313 /*************************** DEPRECATED API **************************/
 314 /* The new "object-oriented" API is preferred, since it allows us to
 315    gracefully add new features and algorithm-specific options in a
 316    re-entrant way, and we can automatically assume reasonable defaults
 317    for unspecified parameters. */
 318
 319 /* Where possible (e.g. for gcc >= 3.1), enable a compiler warning
 320    for code that uses a deprecated function */
 321 #if defined(__GNUC__) && (__GNUC__ > 3 || (__GNUC__==3 && __GNUC_MINOR__ > 0))
 322 #  define NLOPT_DEPRECATED __attribute__((deprecated))
 323 #else
 324 #  define NLOPT_DEPRECATED
 325 #endif
 326
 327 typedef double (*nlopt_func_old)(int n, const double *x,
 328                                  double *gradient, /* NULL if not needed */
 329                                  void *func_data);
 330
 331 NLOPT_EXTERN(nlopt_result) nlopt_minimize(
 332      nlopt_algorithm algorithm,
 333      int n, nlopt_func_old f, void *f_data,
 334      const double *lb, const double *ub, /* bounds */
 335      double *x, /* in: initial guess, out: minimizer */
 336      double *minf, /* out: minimum */
 337      double minf_max, double ftol_rel, double ftol_abs,
 338      double xtol_rel, const double *xtol_abs,
 339      int maxeval, double maxtime) NLOPT_DEPRECATED;
 340
 341 NLOPT_EXTERN(nlopt_result) nlopt_minimize_constrained(
 342      nlopt_algorithm algorithm,
 343      int n, nlopt_func_old f, void *f_data,
 344      int m, nlopt_func_old fc, void *fc_data, ptrdiff_t fc_datum_size,
 345      const double *lb, const double *ub, /* bounds */
 346      double *x, /* in: initial guess, out: minimizer */
 347      double *minf, /* out: minimum */
 348      double minf_max, double ftol_rel, double ftol_abs,
 349      double xtol_rel, const double *xtol_abs,
 350      int maxeval, double maxtime) NLOPT_DEPRECATED;
 351
 352 NLOPT_EXTERN(nlopt_result) nlopt_minimize_econstrained(
 353      nlopt_algorithm algorithm,
 354      int n, nlopt_func_old f, void *f_data,
 355      int m, nlopt_func_old fc, void *fc_data, ptrdiff_t fc_datum_size,
 356      int p, nlopt_func_old h, void *h_data, ptrdiff_t h_datum_size,
 357      const double *lb, const double *ub, /* bounds */
 358      double *x, /* in: initial guess, out: minimizer */
 359      double *minf, /* out: minimum */
 360      double minf_max, double ftol_rel, double ftol_abs,
 361      double xtol_rel, const double *xtol_abs,
 362      double htol_rel, double htol_abs,
 363      int maxeval, double maxtime) NLOPT_DEPRECATED;
 364
 365 NLOPT_EXTERN(void) nlopt_get_local_search_algorithm(nlopt_algorithm *deriv,
 366                                              nlopt_algorithm *nonderiv,
 367                                              int *maxeval) NLOPT_DEPRECATED;
 368 NLOPT_EXTERN(void) nlopt_set_local_search_algorithm(nlopt_algorithm deriv,
 369                                              nlopt_algorithm nonderiv,
 370                                              int maxeval) NLOPT_DEPRECATED;
 371
 372 NLOPT_EXTERN(int) nlopt_get_stochastic_population(void) NLOPT_DEPRECATED;
 373 NLOPT_EXTERN(void) nlopt_set_stochastic_population(int pop) NLOPT_DEPRECATED;
 374
 375 /*********************************************************************/
 376
 377 #ifdef __cplusplus
 378 }  /* extern "C" */
 379 #endif /* __cplusplus */
 380
 381 #endif