| 298 | // ---------------------------------------------------------------------------------------- |
| 299 | |
| 300 | void bind_global_optimization(py::module& m) |
| 301 | { |
| 302 | |
| 303 | |
| 304 | const char* docstring = |
| 305 | "requires \n\ |
| 306 | - len(bound1) == len(bound2) == len(is_integer_variable) \n\ |
| 307 | - for all valid i: bound1[i] != bound2[i] \n\ |
| 308 | - solver_epsilon >= 0 \n\ |
| 309 | - f() is a real valued multi-variate function. It must take scalar real \n\ |
| 310 | numbers as its arguments and the number of arguments must be len(bound1). \n\ |
| 311 | ensures \n\ |
| 312 | - This function performs global optimization on the given f() function. \n\ |
| 313 | The goal is to maximize the following objective function: \n\ |
| 314 | f(x) \n\ |
| 315 | subject to the constraints: \n\ |
| 316 | min(bound1[i],bound2[i]) <= x[i] <= max(bound1[i],bound2[i]) \n\ |
| 317 | if (is_integer_variable[i]) then x[i] is an integer value (but still \n\ |
| 318 | represented with float type). \n\ |
| 319 | - find_max_global() runs until it has called f() num_function_calls times. \n\ |
| 320 | Then it returns the best x it has found along with the corresponding output \n\ |
| 321 | of f(). That is, it returns (best_x_seen,f(best_x_seen)). Here best_x_seen \n\ |
| 322 | is a list containing the best arguments to f() this function has found. \n\ |
| 323 | - find_max_global() uses a global optimization method based on a combination of \n\ |
| 324 | non-parametric global function modeling and quadratic trust region modeling \n\ |
| 325 | to efficiently find a global maximizer. It usually does a good job with a \n\ |
| 326 | relatively small number of calls to f(). For more information on how it \n\ |
| 327 | works read the documentation for dlib's global_function_search object. \n\ |
| 328 | However, one notable element is the solver epsilon, which you can adjust. \n\ |
| 329 | \n\ |
| 330 | The search procedure will only attempt to find a global maximizer to at most \n\ |
| 331 | solver_epsilon accuracy. Once a local maximizer is found to that accuracy \n\ |
| 332 | the search will focus entirely on finding other maxima elsewhere rather than \n\ |
| 333 | on further improving the current local optima found so far. That is, once a \n\ |
| 334 | local maxima is identified to about solver_epsilon accuracy, the algorithm \n\ |
| 335 | will spend all its time exploring the function to find other local maxima to \n\ |
| 336 | investigate. An epsilon of 0 means it will keep solving until it reaches \n\ |
| 337 | full floating point precision. Larger values will cause it to switch to pure \n\ |
| 338 | global exploration sooner and therefore might be more effective if your \n\ |
| 339 | objective function has many local maxima and you don't care about a super \n\ |
| 340 | high precision solution. \n\ |
| 341 | - Any variables that satisfy the following conditions are optimized on a log-scale: \n\ |
| 342 | - The lower bound on the variable is > 0 \n\ |
| 343 | - The ratio of the upper bound to lower bound is > 1000 \n\ |
| 344 | - The variable is not an integer variable \n\ |
| 345 | We do this because it's common to optimize machine learning models that have \n\ |
| 346 | parameters with bounds in a range such as [1e-5 to 1e10] (e.g. the SVM C \n\ |
| 347 | parameter) and it's much more appropriate to optimize these kinds of \n\ |
| 348 | variables on a log scale. So we transform them by applying log() to \n\ |
| 349 | them and then undo the transform via exp() before invoking the function \n\ |
| 350 | being optimized. Therefore, this transformation is invisible to the user \n\ |
| 351 | supplied functions. In most cases, it improves the efficiency of the \n\ |
| 352 | optimizer."; |
| 353 | /*! |
| 354 | requires |
| 355 | - len(bound1) == len(bound2) == len(is_integer_variable) |
| 356 | - for all valid i: bound1[i] != bound2[i] |
| 357 | - solver_epsilon >= 0 |
no test coverage detected