api/nlopt.h

   1 /* Copyright (c) 2007-2011 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_NUM_ALGORITHMS /* not an algorithm, just the number of them */
 154 } nlopt_algorithm;
 155
 156 NLOPT_EXTERN(const char *) nlopt_algorithm_name(nlopt_algorithm a);
 157
 158 typedef enum {
 159      NLOPT_FAILURE = -1, /* generic failure code */
 160      NLOPT_INVALID_ARGS = -2,
 161      NLOPT_OUT_OF_MEMORY = -3,
 162      NLOPT_ROUNDOFF_LIMITED = -4,
 163      NLOPT_FORCED_STOP = -5,
 164      NLOPT_SUCCESS = 1, /* generic success code */
 165      NLOPT_STOPVAL_REACHED = 2,
 166      NLOPT_FTOL_REACHED = 3,
 167      NLOPT_XTOL_REACHED = 4,
 168      NLOPT_MAXEVAL_REACHED = 5,
 169      NLOPT_MAXTIME_REACHED = 6
 170 } nlopt_result;
 171
 172 #define NLOPT_MINF_MAX_REACHED NLOPT_STOPVAL_REACHED
 173
 174 NLOPT_EXTERN(void) nlopt_srand(unsigned long seed);
 175 NLOPT_EXTERN(void) nlopt_srand_time(void);
 176
 177 NLOPT_EXTERN(void) nlopt_version(int *major, int *minor, int *bugfix);
 178
 179 /*************************** OBJECT-ORIENTED API **************************/
 180 /* The style here is that we create an nlopt_opt "object" (an opaque pointer),
 181    then set various optimization parameters, and then execute the
 182    algorithm.  In this way, we can add more and more optimization parameters
 183    (including algorithm-specific ones) without breaking backwards
 184    compatibility, having functions with zillions of parameters, or
 185    relying non-reentrantly on global variables.*/
 186
 187 struct nlopt_opt_s; /* opaque structure, defined internally */
 188 typedef struct nlopt_opt_s *nlopt_opt;
 189
 190 /* the only immutable parameters of an optimization are the algorithm and
 191    the dimension n of the problem, since changing either of these could
 192    have side-effects on lots of other parameters */
 193 NLOPT_EXTERN(nlopt_opt) nlopt_create(nlopt_algorithm algorithm, unsigned n);
 194 NLOPT_EXTERN(void) nlopt_destroy(nlopt_opt opt);
 195 NLOPT_EXTERN(nlopt_opt) nlopt_copy(const nlopt_opt opt);
 196
 197 NLOPT_EXTERN(nlopt_result) nlopt_optimize(nlopt_opt opt, double *x,
 198                                          double *opt_f);
 199
 200 NLOPT_EXTERN(nlopt_result) nlopt_set_min_objective(nlopt_opt opt, nlopt_func f,
 201                                                   void *f_data);
 202 NLOPT_EXTERN(nlopt_result) nlopt_set_max_objective(nlopt_opt opt, nlopt_func f,
 203                                                   void *f_data);
 204
 205 NLOPT_EXTERN(nlopt_result) nlopt_set_precond_min_objective(nlopt_opt opt, nlopt_func f, nlopt_precond pre, void *f_data);
 206 NLOPT_EXTERN(nlopt_result) nlopt_set_precond_max_objective(nlopt_opt opt, nlopt_func f, nlopt_precond pre, void *f_data);
 207
 208 NLOPT_EXTERN(nlopt_algorithm) nlopt_get_algorithm(const nlopt_opt opt);
 209 NLOPT_EXTERN(unsigned) nlopt_get_dimension(const nlopt_opt opt);
 210
 211 /* constraints: */
 212
 213 NLOPT_EXTERN(nlopt_result) nlopt_set_lower_bounds(nlopt_opt opt,
 214                                                  const double *lb);
 215 NLOPT_EXTERN(nlopt_result) nlopt_set_lower_bounds1(nlopt_opt opt, double lb);
 216 NLOPT_EXTERN(nlopt_result) nlopt_get_lower_bounds(const nlopt_opt opt,
 217                                                  double *lb);
 218 NLOPT_EXTERN(nlopt_result) nlopt_set_upper_bounds(nlopt_opt opt,
 219                                                  const double *ub);
 220 NLOPT_EXTERN(nlopt_result) nlopt_set_upper_bounds1(nlopt_opt opt, double ub);
 221 NLOPT_EXTERN(nlopt_result) nlopt_get_upper_bounds(const nlopt_opt opt,
 222                                                  double *ub);
 223
 224 NLOPT_EXTERN(nlopt_result) nlopt_remove_inequality_constraints(nlopt_opt opt);
 225 NLOPT_EXTERN(nlopt_result) nlopt_add_inequality_constraint(nlopt_opt opt,
 226                                                           nlopt_func fc,
 227                                                           void *fc_data,
 228                                                           double tol);
 229 NLOPT_EXTERN(nlopt_result) nlopt_add_precond_inequality_constraint(
 230      nlopt_opt opt, nlopt_func fc, nlopt_precond pre, void *fc_data,
 231      double tol);
 232 NLOPT_EXTERN(nlopt_result) nlopt_add_inequality_mconstraint(nlopt_opt opt,
 233                                                             unsigned m,
 234                                                             nlopt_mfunc fc,
 235                                                             void *fc_data,
 236                                                             const double *tol);
 237
 238 NLOPT_EXTERN(nlopt_result) nlopt_remove_equality_constraints(nlopt_opt opt);
 239 NLOPT_EXTERN(nlopt_result) nlopt_add_equality_constraint(nlopt_opt opt,
 240                                                         nlopt_func h,
 241                                                         void *h_data,
 242                                                         double tol);
 243 NLOPT_EXTERN(nlopt_result) nlopt_add_precond_equality_constraint(
 244      nlopt_opt opt, nlopt_func h, nlopt_precond pre, void *h_data,
 245      double tol);
 246 NLOPT_EXTERN(nlopt_result) nlopt_add_equality_mconstraint(nlopt_opt opt,
 247                                                           unsigned m,
 248                                                           nlopt_mfunc h,
 249                                                           void *h_data,
 250                                                           const double *tol);
 251
 252 /* stopping criteria: */
 253
 254 NLOPT_EXTERN(nlopt_result) nlopt_set_stopval(nlopt_opt opt, double stopval);
 255 NLOPT_EXTERN(double) nlopt_get_stopval(const nlopt_opt opt);
 256
 257 NLOPT_EXTERN(nlopt_result) nlopt_set_ftol_rel(nlopt_opt opt, double tol);
 258 NLOPT_EXTERN(double) nlopt_get_ftol_rel(const nlopt_opt opt);
 259 NLOPT_EXTERN(nlopt_result) nlopt_set_ftol_abs(nlopt_opt opt, double tol);
 260 NLOPT_EXTERN(double) nlopt_get_ftol_abs(const nlopt_opt opt);
 261
 262 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_rel(nlopt_opt opt, double tol);
 263 NLOPT_EXTERN(double) nlopt_get_xtol_rel(const nlopt_opt opt);
 264 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_abs1(nlopt_opt opt, double tol);
 265 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_abs(nlopt_opt opt, const double *tol);
 266 NLOPT_EXTERN(nlopt_result) nlopt_get_xtol_abs(const nlopt_opt opt,
 267                                              double *tol);
 268
 269 NLOPT_EXTERN(nlopt_result) nlopt_set_maxeval(nlopt_opt opt, int maxeval);
 270 NLOPT_EXTERN(int) nlopt_get_maxeval(const nlopt_opt opt);
 271
 272 NLOPT_EXTERN(nlopt_result) nlopt_set_maxtime(nlopt_opt opt, double maxtime);
 273 NLOPT_EXTERN(double) nlopt_get_maxtime(const nlopt_opt opt);
 274
 275 NLOPT_EXTERN(nlopt_result) nlopt_force_stop(nlopt_opt opt);
 276 NLOPT_EXTERN(nlopt_result) nlopt_set_force_stop(nlopt_opt opt, int val);
 277 NLOPT_EXTERN(int) nlopt_get_force_stop(const nlopt_opt opt);
 278
 279 /* more algorithm-specific parameters */
 280
 281 NLOPT_EXTERN(nlopt_result) nlopt_set_local_optimizer(nlopt_opt opt,
 282                                                     const nlopt_opt local_opt);
 283
 284 NLOPT_EXTERN(nlopt_result) nlopt_set_population(nlopt_opt opt, unsigned pop);
 285 NLOPT_EXTERN(unsigned) nlopt_get_population(const nlopt_opt opt);
 286
 287 NLOPT_EXTERN(nlopt_result) nlopt_set_vector_storage(nlopt_opt opt, unsigned dim);
 288 NLOPT_EXTERN(unsigned) nlopt_get_vector_storage(const nlopt_opt opt);
 289
 290 NLOPT_EXTERN(nlopt_result) nlopt_set_default_initial_step(nlopt_opt opt,
 291                                                          const double *x);
 292 NLOPT_EXTERN(nlopt_result) nlopt_set_initial_step(nlopt_opt opt,
 293                                                  const double *dx);
 294 NLOPT_EXTERN(nlopt_result) nlopt_set_initial_step1(nlopt_opt opt, double dx);
 295 NLOPT_EXTERN(nlopt_result) nlopt_get_initial_step(const nlopt_opt opt,
 296                                                  const double *x, double *dx);
 297
 298 /* the following are functions mainly designed to be used internally
 299    by the Fortran and SWIG wrappers, allow us to tel nlopt_destroy and
 300    nlopt_copy to do something to the f_data pointers (e.g. free or
 301    duplicate them, respectively) */
 302 typedef void* (*nlopt_munge)(void *p);
 303 NLOPT_EXTERN(void) nlopt_set_munge(nlopt_opt opt,
 304                                   nlopt_munge munge_on_destroy,
 305                                   nlopt_munge munge_on_copy);
 306
 307 /*************************** DEPRECATED API **************************/
 308 /* The new "object-oriented" API is preferred, since it allows us to
 309    gracefully add new features and algorithm-specific options in a
 310    re-entrant way, and we can automatically assume reasonable defaults
 311    for unspecified parameters. */
 312
 313 /* Where possible (e.g. for gcc >= 3.1), enable a compiler warning
 314    for code that uses a deprecated function */
 315 #if defined(__GNUC__) && (__GNUC__ > 3 || (__GNUC__==3 && __GNUC_MINOR__ > 0))
 316 #  define NLOPT_DEPRECATED __attribute__((deprecated))
 317 #else
 318 #  define NLOPT_DEPRECATED
 319 #endif
 320
 321 typedef double (*nlopt_func_old)(int n, const double *x,
 322                                  double *gradient, /* NULL if not needed */
 323                                  void *func_data);
 324
 325 NLOPT_EXTERN(nlopt_result) nlopt_minimize(
 326      nlopt_algorithm algorithm,
 327      int n, nlopt_func_old f, void *f_data,
 328      const double *lb, const double *ub, /* bounds */
 329      double *x, /* in: initial guess, out: minimizer */
 330      double *minf, /* out: minimum */
 331      double minf_max, double ftol_rel, double ftol_abs,
 332      double xtol_rel, const double *xtol_abs,
 333      int maxeval, double maxtime) NLOPT_DEPRECATED;
 334
 335 NLOPT_EXTERN(nlopt_result) nlopt_minimize_constrained(
 336      nlopt_algorithm algorithm,
 337      int n, nlopt_func_old f, void *f_data,
 338      int m, nlopt_func_old fc, void *fc_data, ptrdiff_t fc_datum_size,
 339      const double *lb, const double *ub, /* bounds */
 340      double *x, /* in: initial guess, out: minimizer */
 341      double *minf, /* out: minimum */
 342      double minf_max, double ftol_rel, double ftol_abs,
 343      double xtol_rel, const double *xtol_abs,
 344      int maxeval, double maxtime) NLOPT_DEPRECATED;
 345
 346 NLOPT_EXTERN(nlopt_result) nlopt_minimize_econstrained(
 347      nlopt_algorithm algorithm,
 348      int n, nlopt_func_old f, void *f_data,
 349      int m, nlopt_func_old fc, void *fc_data, ptrdiff_t fc_datum_size,
 350      int p, nlopt_func_old h, void *h_data, ptrdiff_t h_datum_size,
 351      const double *lb, const double *ub, /* bounds */
 352      double *x, /* in: initial guess, out: minimizer */
 353      double *minf, /* out: minimum */
 354      double minf_max, double ftol_rel, double ftol_abs,
 355      double xtol_rel, const double *xtol_abs,
 356      double htol_rel, double htol_abs,
 357      int maxeval, double maxtime) NLOPT_DEPRECATED;
 358
 359 NLOPT_EXTERN(void) nlopt_get_local_search_algorithm(nlopt_algorithm *deriv,
 360                                              nlopt_algorithm *nonderiv,
 361                                              int *maxeval) NLOPT_DEPRECATED;
 362 NLOPT_EXTERN(void) nlopt_set_local_search_algorithm(nlopt_algorithm deriv,
 363                                              nlopt_algorithm nonderiv,
 364                                              int maxeval) NLOPT_DEPRECATED;
 365
 366 NLOPT_EXTERN(int) nlopt_get_stochastic_population(void) NLOPT_DEPRECATED;
 367 NLOPT_EXTERN(void) nlopt_set_stochastic_population(int pop) NLOPT_DEPRECATED;
 368
 369 /*********************************************************************/
 370
 371 #ifdef __cplusplus
 372 }  /* extern "C" */
 373 #endif /* __cplusplus */
 374
 375 #endif