optunity.api module

A collection of top-level API functions for Optunity.

Main functions in this module:

We recommend using these functions rather than equivalents found in other places, e.g. optunity.solvers.

Module author: Marc Claesen

optunity.api.available_solvers()[source]

Returns a list of all available solvers.

These can be used in optunity.make_solver().

optunity.api.make_solver(solver_name, *args, **kwargs)[source]

Creates a Solver from given parameters.

Parameters:
  • solver_name (string) – the solver to instantiate
  • args – positional arguments to solver constructor.
  • kwargs – keyword arguments to solver constructor.

Use optunity.manual() to get a list of registered solvers. For constructor arguments per solver, please refer to Solver overview.

Raises KeyError if

  • solver_name is not registered
  • *args and **kwargs are invalid to instantiate the solver.
optunity.api.manual(solver_name=None)[source]

Prints the manual of requested solver.

Parameters:solver_name – (optional) name of the solver to request a manual from. If none is specified, a general manual is printed.

Raises KeyError if solver_name is not registered.

optunity.api.maximize(f, num_evals=50, solver_name=None, pmap=<built-in function map>, **kwargs)[source]

Basic function maximization routine. Maximizes f within the given box constraints.

Parameters:
  • f – the function to be maximized
  • num_evals – number of permitted function evaluations
  • solver_name (string) – name of the solver to use (optional)
  • pmap (callable) – the map function to use
  • kwargs – box constraints, a dict of the following form {'parameter_name': [lower_bound, upper_bound], ...}
Returns:

retrieved maximum, extra information and solver info

This function will implicitly choose an appropriate solver and its initialization based on num_evals and the box constraints.

optunity.api.maximize_structured(f, search_space, num_evals=50, pmap=<built-in function map>)[source]

Basic function maximization routine. Maximizes f within the given box constraints.

Parameters:
  • f – the function to be maximized
  • search_space – the search space (see Structured search spaces for details)
  • num_evals – number of permitted function evaluations
  • pmap (callable) – the map function to use
Returns:

retrieved maximum, extra information and solver info

This function will implicitly choose an appropriate solver and its initialization based on num_evals and the box constraints.

optunity.api.minimize(f, num_evals=50, solver_name=None, pmap=<built-in function map>, **kwargs)[source]

Basic function minimization routine. Minimizes f within the given box constraints.

Parameters:
  • f – the function to be minimized
  • num_evals – number of permitted function evaluations
  • solver_name (string) – name of the solver to use (optional)
  • pmap (callable) – the map function to use
  • kwargs – box constraints, a dict of the following form {'parameter_name': [lower_bound, upper_bound], ...}
Returns:

retrieved minimum, extra information and solver info

This function will implicitly choose an appropriate solver and its initialization based on num_evals and the box constraints.

optunity.api.minimize_structured(f, search_space, num_evals=50, pmap=<built-in function map>)[source]

Basic function minimization routine. Minimizes f within the given box constraints.

Parameters:
  • f – the function to be maximized
  • search_space – the search space (see Structured search spaces for details)
  • num_evals – number of permitted function evaluations
  • pmap (callable) – the map function to use
Returns:

retrieved maximum, extra information and solver info

This function will implicitly choose an appropriate solver and its initialization based on num_evals and the box constraints.

optunity.api.optimize(solver, func, maximize=True, max_evals=0, pmap=<built-in function map>, decoder=None)[source]

Optimizes func with given solver.

Parameters:
  • solver – the solver to be used, for instance a result from optunity.make_solver()
  • func (callable) – the objective function
  • maximize (bool) – maximize or minimize?
  • max_evals (int) – maximum number of permitted function evaluations
  • pmap (function) – the map() function to use, to vectorize use optunity.pmap()

Returns the solution and a namedtuple with further details.

Result details includes the following:

optimum
optimal function value f(solution)
stats
statistics about the solving process
call_log
the call log
report
solver report, can be None

Statistics gathered while solving a problem:

num_evals
number of function evaluations
time
wall clock time needed to solve
optunity.api.suggest_solver(num_evals=50, solver_name=None, **kwargs)[source]
optunity.api.wrap_call_log(f, call_dict)[source]

Wraps an existing call log (as dictionary) around f.

This allows you to communicate known function values to solvers. (currently available solvers do not use this info)