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 /* constraints: */
 213
 214 NLOPT_EXTERN(nlopt_result) nlopt_set_lower_bounds(nlopt_opt opt,
 215                                                  const double *lb);
 216 NLOPT_EXTERN(nlopt_result) nlopt_set_lower_bounds1(nlopt_opt opt, double lb);
 217 NLOPT_EXTERN(nlopt_result) nlopt_get_lower_bounds(const nlopt_opt opt,
 218                                                  double *lb);
 219 NLOPT_EXTERN(nlopt_result) nlopt_set_upper_bounds(nlopt_opt opt,
 220                                                  const double *ub);
 221 NLOPT_EXTERN(nlopt_result) nlopt_set_upper_bounds1(nlopt_opt opt, double ub);
 222 NLOPT_EXTERN(nlopt_result) nlopt_get_upper_bounds(const nlopt_opt opt,
 223                                                  double *ub);
 224
 225 NLOPT_EXTERN(nlopt_result) nlopt_remove_inequality_constraints(nlopt_opt opt);
 226 NLOPT_EXTERN(nlopt_result) nlopt_add_inequality_constraint(nlopt_opt opt,
 227                                                           nlopt_func fc,
 228                                                           void *fc_data,
 229                                                           double tol);
 230 NLOPT_EXTERN(nlopt_result) nlopt_add_precond_inequality_constraint(
 231      nlopt_opt opt, nlopt_func fc, nlopt_precond pre, void *fc_data,
 232      double tol);
 233 NLOPT_EXTERN(nlopt_result) nlopt_add_inequality_mconstraint(nlopt_opt opt,
 234                                                             unsigned m,
 235                                                             nlopt_mfunc fc,
 236                                                             void *fc_data,
 237                                                             const double *tol);
 238
 239 NLOPT_EXTERN(nlopt_result) nlopt_remove_equality_constraints(nlopt_opt opt);
 240 NLOPT_EXTERN(nlopt_result) nlopt_add_equality_constraint(nlopt_opt opt,
 241                                                         nlopt_func h,
 242                                                         void *h_data,
 243                                                         double tol);
 244 NLOPT_EXTERN(nlopt_result) nlopt_add_precond_equality_constraint(
 245      nlopt_opt opt, nlopt_func h, nlopt_precond pre, void *h_data,
 246      double tol);
 247 NLOPT_EXTERN(nlopt_result) nlopt_add_equality_mconstraint(nlopt_opt opt,
 248                                                           unsigned m,
 249                                                           nlopt_mfunc h,
 250                                                           void *h_data,
 251                                                           const double *tol);
 252
 253 /* stopping criteria: */
 254
 255 NLOPT_EXTERN(nlopt_result) nlopt_set_stopval(nlopt_opt opt, double stopval);
 256 NLOPT_EXTERN(double) nlopt_get_stopval(const nlopt_opt opt);
 257
 258 NLOPT_EXTERN(nlopt_result) nlopt_set_ftol_rel(nlopt_opt opt, double tol);
 259 NLOPT_EXTERN(double) nlopt_get_ftol_rel(const nlopt_opt opt);
 260 NLOPT_EXTERN(nlopt_result) nlopt_set_ftol_abs(nlopt_opt opt, double tol);
 261 NLOPT_EXTERN(double) nlopt_get_ftol_abs(const nlopt_opt opt);
 262
 263 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_rel(nlopt_opt opt, double tol);
 264 NLOPT_EXTERN(double) nlopt_get_xtol_rel(const nlopt_opt opt);
 265 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_abs1(nlopt_opt opt, double tol);
 266 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_abs(nlopt_opt opt, const double *tol);
 267 NLOPT_EXTERN(nlopt_result) nlopt_get_xtol_abs(const nlopt_opt opt,
 268                                              double *tol);
 269
 270 NLOPT_EXTERN(nlopt_result) nlopt_set_maxeval(nlopt_opt opt, int maxeval);
 271 NLOPT_EXTERN(int) nlopt_get_maxeval(const nlopt_opt opt);
 272
 273 NLOPT_EXTERN(nlopt_result) nlopt_set_maxtime(nlopt_opt opt, double maxtime);
 274 NLOPT_EXTERN(double) nlopt_get_maxtime(const nlopt_opt opt);
 275
 276 NLOPT_EXTERN(nlopt_result) nlopt_force_stop(nlopt_opt opt);
 277 NLOPT_EXTERN(nlopt_result) nlopt_set_force_stop(nlopt_opt opt, int val);
 278 NLOPT_EXTERN(int) nlopt_get_force_stop(const nlopt_opt opt);
 279
 280 /* more algorithm-specific parameters */
 281
 282 NLOPT_EXTERN(nlopt_result) nlopt_set_local_optimizer(nlopt_opt opt,
 283                                                     const nlopt_opt local_opt);
 284
 285 NLOPT_EXTERN(nlopt_result) nlopt_set_population(nlopt_opt opt, unsigned pop);
 286 NLOPT_EXTERN(unsigned) nlopt_get_population(const nlopt_opt opt);
 287
 288 NLOPT_EXTERN(nlopt_result) nlopt_set_vector_storage(nlopt_opt opt, unsigned dim);
 289 NLOPT_EXTERN(unsigned) nlopt_get_vector_storage(const nlopt_opt opt);
 290
 291 NLOPT_EXTERN(nlopt_result) nlopt_set_default_initial_step(nlopt_opt opt,
 292                                                          const double *x);
 293 NLOPT_EXTERN(nlopt_result) nlopt_set_initial_step(nlopt_opt opt,
 294                                                  const double *dx);
 295 NLOPT_EXTERN(nlopt_result) nlopt_set_initial_step1(nlopt_opt opt, double dx);
 296 NLOPT_EXTERN(nlopt_result) nlopt_get_initial_step(const nlopt_opt opt,
 297                                                  const double *x, double *dx);
 298
 299 /* the following are functions mainly designed to be used internally
 300    by the Fortran and SWIG wrappers, allow us to tel nlopt_destroy and
 301    nlopt_copy to do something to the f_data pointers (e.g. free or
 302    duplicate them, respectively) */
 303 typedef void* (*nlopt_munge)(void *p);
 304 NLOPT_EXTERN(void) nlopt_set_munge(nlopt_opt opt,
 305                                   nlopt_munge munge_on_destroy,
 306                                   nlopt_munge munge_on_copy);
 307 typedef void* (*nlopt_munge2)(void *p, void *data);
 308 NLOPT_EXTERN(void) nlopt_munge_data(nlopt_opt opt,
 309                                     nlopt_munge2 munge, void *data);
 310
 311 /*************************** DEPRECATED API **************************/
 312 /* The new "object-oriented" API is preferred, since it allows us to
 313    gracefully add new features and algorithm-specific options in a
 314    re-entrant way, and we can automatically assume reasonable defaults
 315    for unspecified parameters. */
 316
 317 /* Where possible (e.g. for gcc >= 3.1), enable a compiler warning
 318    for code that uses a deprecated function */
 319 #if defined(__GNUC__) && (__GNUC__ > 3 || (__GNUC__==3 && __GNUC_MINOR__ > 0))
 320 #  define NLOPT_DEPRECATED __attribute__((deprecated))
 321 #else
 322 #  define NLOPT_DEPRECATED
 323 #endif
 324
 325 typedef double (*nlopt_func_old)(int n, const double *x,
 326                                  double *gradient, /* NULL if not needed */
 327                                  void *func_data);
 328
 329 NLOPT_EXTERN(nlopt_result) nlopt_minimize(
 330      nlopt_algorithm algorithm,
 331      int n, nlopt_func_old f, void *f_data,
 332      const double *lb, const double *ub, /* bounds */
 333      double *x, /* in: initial guess, out: minimizer */
 334      double *minf, /* out: minimum */
 335      double minf_max, double ftol_rel, double ftol_abs,
 336      double xtol_rel, const double *xtol_abs,
 337      int maxeval, double maxtime) NLOPT_DEPRECATED;
 338
 339 NLOPT_EXTERN(nlopt_result) nlopt_minimize_constrained(
 340      nlopt_algorithm algorithm,
 341      int n, nlopt_func_old f, void *f_data,
 342      int m, nlopt_func_old fc, void *fc_data, ptrdiff_t fc_datum_size,
 343      const double *lb, const double *ub, /* bounds */
 344      double *x, /* in: initial guess, out: minimizer */
 345      double *minf, /* out: minimum */
 346      double minf_max, double ftol_rel, double ftol_abs,
 347      double xtol_rel, const double *xtol_abs,
 348      int maxeval, double maxtime) NLOPT_DEPRECATED;
 349
 350 NLOPT_EXTERN(nlopt_result) nlopt_minimize_econstrained(
 351      nlopt_algorithm algorithm,
 352      int n, nlopt_func_old f, void *f_data,
 353      int m, nlopt_func_old fc, void *fc_data, ptrdiff_t fc_datum_size,
 354      int p, nlopt_func_old h, void *h_data, ptrdiff_t h_datum_size,
 355      const double *lb, const double *ub, /* bounds */
 356      double *x, /* in: initial guess, out: minimizer */
 357      double *minf, /* out: minimum */
 358      double minf_max, double ftol_rel, double ftol_abs,
 359      double xtol_rel, const double *xtol_abs,
 360      double htol_rel, double htol_abs,
 361      int maxeval, double maxtime) NLOPT_DEPRECATED;
 362
 363 NLOPT_EXTERN(void) nlopt_get_local_search_algorithm(nlopt_algorithm *deriv,
 364                                              nlopt_algorithm *nonderiv,
 365                                              int *maxeval) NLOPT_DEPRECATED;
 366 NLOPT_EXTERN(void) nlopt_set_local_search_algorithm(nlopt_algorithm deriv,
 367                                              nlopt_algorithm nonderiv,
 368                                              int maxeval) NLOPT_DEPRECATED;
 369
 370 NLOPT_EXTERN(int) nlopt_get_stochastic_population(void) NLOPT_DEPRECATED;
 371 NLOPT_EXTERN(void) nlopt_set_stochastic_population(int pop) NLOPT_DEPRECATED;
 372
 373 /*********************************************************************/
 374
 375 #ifdef __cplusplus
 376 }  /* extern "C" */
 377 #endif /* __cplusplus */
 378
 379 #endif