api/nlopt.h

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