# 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], ...} 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 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], ...} 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 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
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)