src/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 #endif /* __cplusplus */
  59
  60 typedef double (*nlopt_func) (unsigned n, const double *x,
  61                               double *gradient, /* NULL if not needed */
  62                               void *func_data);
  63
  64 typedef void (*nlopt_mfunc) (unsigned m, double *result, unsigned n, const double *x,
  65                              double *gradient, /* NULL if not needed */
  66                              void *func_data);
  67
  68 /* A preconditioner, which preconditions v at x to return vpre.
  69    (The meaning of "preconditioning" is algorithm-dependent.) */
  70 typedef void (*nlopt_precond) (unsigned n, const double *x, const double *v, double *vpre, void *data);
  71
  72 typedef enum {
  73     /* Naming conventions:
  74
  75        NLOPT_{G/L}{D/N}_*
  76        = global/local derivative/no-derivative optimization,
  77        respectively
  78
  79        *_RAND algorithms involve some randomization.
  80
  81        *_NOSCAL algorithms are *not* scaled to a unit hypercube
  82        (i.e. they are sensitive to the units of x)
  83      */
  84
  85     NLOPT_GN_DIRECT = 0,
  86     NLOPT_GN_DIRECT_L,
  87     NLOPT_GN_DIRECT_L_RAND,
  88     NLOPT_GN_DIRECT_NOSCAL,
  89     NLOPT_GN_DIRECT_L_NOSCAL,
  90     NLOPT_GN_DIRECT_L_RAND_NOSCAL,
  91
  92     NLOPT_GN_ORIG_DIRECT,
  93     NLOPT_GN_ORIG_DIRECT_L,
  94
  95     NLOPT_GD_STOGO,
  96     NLOPT_GD_STOGO_RAND,
  97
  98     NLOPT_LD_LBFGS_NOCEDAL,
  99
 100     NLOPT_LD_LBFGS,
 101
 102     NLOPT_LN_PRAXIS,
 103
 104     NLOPT_LD_VAR1,
 105     NLOPT_LD_VAR2,
 106
 107     NLOPT_LD_TNEWTON,
 108     NLOPT_LD_TNEWTON_RESTART,
 109     NLOPT_LD_TNEWTON_PRECOND,
 110     NLOPT_LD_TNEWTON_PRECOND_RESTART,
 111
 112     NLOPT_GN_CRS2_LM,
 113
 114     NLOPT_GN_MLSL,
 115     NLOPT_GD_MLSL,
 116     NLOPT_GN_MLSL_LDS,
 117     NLOPT_GD_MLSL_LDS,
 118
 119     NLOPT_LD_MMA,
 120
 121     NLOPT_LN_COBYLA,
 122
 123     NLOPT_LN_NEWUOA,
 124     NLOPT_LN_NEWUOA_BOUND,
 125
 126     NLOPT_LN_NELDERMEAD,
 127     NLOPT_LN_SBPLX,
 128
 129     NLOPT_LN_AUGLAG,
 130     NLOPT_LD_AUGLAG,
 131     NLOPT_LN_AUGLAG_EQ,
 132     NLOPT_LD_AUGLAG_EQ,
 133
 134     NLOPT_LN_BOBYQA,
 135
 136     NLOPT_GN_ISRES,
 137
 138     /* new variants that require local_optimizer to be set,
 139        not with older constants for backwards compatibility */
 140     NLOPT_AUGLAG,
 141     NLOPT_AUGLAG_EQ,
 142     NLOPT_G_MLSL,
 143     NLOPT_G_MLSL_LDS,
 144
 145     NLOPT_LD_SLSQP,
 146
 147     NLOPT_LD_CCSAQ,
 148
 149     NLOPT_GN_ESCH,
 150
 151     NLOPT_GN_AGS,
 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, double *opt_f);
 198
 199 NLOPT_EXTERN(nlopt_result) nlopt_set_min_objective(nlopt_opt opt, nlopt_func f, void *f_data);
 200 NLOPT_EXTERN(nlopt_result) nlopt_set_max_objective(nlopt_opt opt, nlopt_func f, void *f_data);
 201
 202 NLOPT_EXTERN(nlopt_result) nlopt_set_precond_min_objective(nlopt_opt opt, nlopt_func f, nlopt_precond pre, void *f_data);
 203 NLOPT_EXTERN(nlopt_result) nlopt_set_precond_max_objective(nlopt_opt opt, nlopt_func f, nlopt_precond pre, void *f_data);
 204
 205 NLOPT_EXTERN(nlopt_algorithm) nlopt_get_algorithm(const nlopt_opt opt);
 206 NLOPT_EXTERN(unsigned) nlopt_get_dimension(const nlopt_opt opt);
 207
 208 NLOPT_EXTERN(const char *) nlopt_get_errmsg(nlopt_opt opt);
 209
 210 /* constraints: */
 211
 212 NLOPT_EXTERN(nlopt_result) nlopt_set_lower_bounds(nlopt_opt opt, const double *lb);
 213 NLOPT_EXTERN(nlopt_result) nlopt_set_lower_bounds1(nlopt_opt opt, double lb);
 214 NLOPT_EXTERN(nlopt_result) nlopt_get_lower_bounds(const nlopt_opt opt, double *lb);
 215 NLOPT_EXTERN(nlopt_result) nlopt_set_upper_bounds(nlopt_opt opt, const double *ub);
 216 NLOPT_EXTERN(nlopt_result) nlopt_set_upper_bounds1(nlopt_opt opt, double ub);
 217 NLOPT_EXTERN(nlopt_result) nlopt_get_upper_bounds(const nlopt_opt opt, double *ub);
 218
 219 NLOPT_EXTERN(nlopt_result) nlopt_remove_inequality_constraints(nlopt_opt opt);
 220 NLOPT_EXTERN(nlopt_result) nlopt_add_inequality_constraint(nlopt_opt opt, nlopt_func fc, void *fc_data, double tol);
 221 NLOPT_EXTERN(nlopt_result) nlopt_add_precond_inequality_constraint(nlopt_opt opt, nlopt_func fc, nlopt_precond pre, void *fc_data, double tol);
 222 NLOPT_EXTERN(nlopt_result) nlopt_add_inequality_mconstraint(nlopt_opt opt, unsigned m, nlopt_mfunc fc, void *fc_data, const double *tol);
 223
 224 NLOPT_EXTERN(nlopt_result) nlopt_remove_equality_constraints(nlopt_opt opt);
 225 NLOPT_EXTERN(nlopt_result) nlopt_add_equality_constraint(nlopt_opt opt, nlopt_func h, void *h_data, double tol);
 226 NLOPT_EXTERN(nlopt_result) nlopt_add_precond_equality_constraint(nlopt_opt opt, nlopt_func h, nlopt_precond pre, void *h_data, double tol);
 227 NLOPT_EXTERN(nlopt_result) nlopt_add_equality_mconstraint(nlopt_opt opt, unsigned m, nlopt_mfunc h, void *h_data, const double *tol);
 228
 229 /* stopping criteria: */
 230
 231 NLOPT_EXTERN(nlopt_result) nlopt_set_stopval(nlopt_opt opt, double stopval);
 232 NLOPT_EXTERN(double) nlopt_get_stopval(const nlopt_opt opt);
 233
 234 NLOPT_EXTERN(nlopt_result) nlopt_set_ftol_rel(nlopt_opt opt, double tol);
 235 NLOPT_EXTERN(double) nlopt_get_ftol_rel(const nlopt_opt opt);
 236 NLOPT_EXTERN(nlopt_result) nlopt_set_ftol_abs(nlopt_opt opt, double tol);
 237 NLOPT_EXTERN(double) nlopt_get_ftol_abs(const nlopt_opt opt);
 238
 239 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_rel(nlopt_opt opt, double tol);
 240 NLOPT_EXTERN(double) nlopt_get_xtol_rel(const nlopt_opt opt);
 241 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_abs1(nlopt_opt opt, double tol);
 242 NLOPT_EXTERN(nlopt_result) nlopt_set_xtol_abs(nlopt_opt opt, const double *tol);
 243 NLOPT_EXTERN(nlopt_result) nlopt_get_xtol_abs(const nlopt_opt opt, double *tol);
 244
 245 NLOPT_EXTERN(nlopt_result) nlopt_set_maxeval(nlopt_opt opt, int maxeval);
 246 NLOPT_EXTERN(int) nlopt_get_maxeval(const nlopt_opt opt);
 247
 248 NLOPT_EXTERN(int) nlopt_get_numevals(const nlopt_opt opt);
 249
 250 NLOPT_EXTERN(nlopt_result) nlopt_set_maxtime(nlopt_opt opt, double maxtime);
 251 NLOPT_EXTERN(double) nlopt_get_maxtime(const nlopt_opt opt);
 252
 253 NLOPT_EXTERN(nlopt_result) nlopt_force_stop(nlopt_opt opt);
 254 NLOPT_EXTERN(nlopt_result) nlopt_set_force_stop(nlopt_opt opt, int val);
 255 NLOPT_EXTERN(int) nlopt_get_force_stop(const nlopt_opt opt);
 256
 257 /* more algorithm-specific parameters */
 258
 259 NLOPT_EXTERN(nlopt_result) nlopt_set_local_optimizer(nlopt_opt opt, const nlopt_opt local_opt);
 260
 261 NLOPT_EXTERN(nlopt_result) nlopt_set_population(nlopt_opt opt, unsigned pop);
 262 NLOPT_EXTERN(unsigned) nlopt_get_population(const nlopt_opt opt);
 263
 264 NLOPT_EXTERN(nlopt_result) nlopt_set_vector_storage(nlopt_opt opt, unsigned dim);
 265 NLOPT_EXTERN(unsigned) nlopt_get_vector_storage(const nlopt_opt opt);
 266
 267 NLOPT_EXTERN(nlopt_result) nlopt_set_default_initial_step(nlopt_opt opt, const double *x);
 268 NLOPT_EXTERN(nlopt_result) nlopt_set_initial_step(nlopt_opt opt, const double *dx);
 269 NLOPT_EXTERN(nlopt_result) nlopt_set_initial_step1(nlopt_opt opt, double dx);
 270 NLOPT_EXTERN(nlopt_result) nlopt_get_initial_step(const nlopt_opt opt, const double *x, double *dx);
 271
 272 /* the following are functions mainly designed to be used internally
 273    by the Fortran and SWIG wrappers, allow us to tel nlopt_destroy and
 274    nlopt_copy to do something to the f_data pointers (e.g. free or
 275    duplicate them, respectively) */
 276 typedef void *(*nlopt_munge) (void *p);
 277 NLOPT_EXTERN(void) nlopt_set_munge(nlopt_opt opt, nlopt_munge munge_on_destroy, nlopt_munge munge_on_copy);
 278 typedef void *(*nlopt_munge2) (void *p, void *data);
 279 NLOPT_EXTERN(void) nlopt_munge_data(nlopt_opt opt, nlopt_munge2 munge, void *data);
 280
 281 /*************************** DEPRECATED API **************************/
 282 /* The new "object-oriented" API is preferred, since it allows us to
 283    gracefully add new features and algorithm-specific options in a
 284    re-entrant way, and we can automatically assume reasonable defaults
 285    for unspecified parameters. */
 286
 287 /* Where possible (e.g. for gcc >= 3.1), enable a compiler warning
 288    for code that uses a deprecated function */
 289 #if defined(__GNUC__) && (__GNUC__ > 3 || (__GNUC__==3 && __GNUC_MINOR__ > 0))
 290 #  define NLOPT_DEPRECATED __attribute__((deprecated))
 291 #else
 292 #  define NLOPT_DEPRECATED
 293 #endif
 294
 295 typedef double (*nlopt_func_old) (int n, const double *x, double *gradient,     /* NULL if not needed */
 296                                   void *func_data);
 297
 298 NLOPT_EXTERN(nlopt_result) nlopt_minimize(nlopt_algorithm algorithm, int n, nlopt_func_old f, void *f_data,
 299                                           const double *lb, const double *ub, /* bounds */
 300                                           double *x,    /* in: initial guess, out: minimizer */
 301                                           double *minf, /* out: minimum */
 302                                           double minf_max, double ftol_rel, double ftol_abs, double xtol_rel, const double *xtol_abs, int maxeval, double maxtime) NLOPT_DEPRECATED;
 303
 304 NLOPT_EXTERN(nlopt_result) nlopt_minimize_constrained(nlopt_algorithm algorithm, int n, nlopt_func_old f, void *f_data, int m, nlopt_func_old fc, void *fc_data, ptrdiff_t fc_datum_size,
 305                                                       const double *lb, const double *ub,   /* bounds */
 306                                                       double *x,        /* in: initial guess, out: minimizer */
 307                                                       double *minf,     /* out: minimum */
 308                                                       double minf_max, double ftol_rel, double ftol_abs, double xtol_rel, const double *xtol_abs, int maxeval, double maxtime) NLOPT_DEPRECATED;
 309
 310 NLOPT_EXTERN(nlopt_result) nlopt_minimize_econstrained(nlopt_algorithm algorithm, int n, nlopt_func_old f, void *f_data, int m, nlopt_func_old fc, void *fc_data, ptrdiff_t fc_datum_size, int p, nlopt_func_old h, void *h_data, ptrdiff_t h_datum_size,
 311                                                        const double *lb, const double *ub,   /* bounds */
 312                                                        double *x,       /* in: initial guess, out: minimizer */
 313                                                        double *minf,    /* out: minimum */
 314                                                        double minf_max, double ftol_rel, double ftol_abs,
 315                                                        double xtol_rel, const double *xtol_abs, double htol_rel, double htol_abs, int maxeval, double maxtime) NLOPT_DEPRECATED;
 316
 317 NLOPT_EXTERN(void) nlopt_get_local_search_algorithm(nlopt_algorithm * deriv, nlopt_algorithm * nonderiv, int *maxeval) NLOPT_DEPRECATED;
 318 NLOPT_EXTERN(void) nlopt_set_local_search_algorithm(nlopt_algorithm deriv, nlopt_algorithm nonderiv, int maxeval) NLOPT_DEPRECATED;
 319
 320 NLOPT_EXTERN(int) nlopt_get_stochastic_population(void) NLOPT_DEPRECATED;
 321 NLOPT_EXTERN(void) nlopt_set_stochastic_population(int pop) NLOPT_DEPRECATED;
 322
 323 /*********************************************************************/
 324
 325 #ifdef __cplusplus
 326 }  /* extern "C" */
 327 #endif /* __cplusplus */
 328 #endif