Standalone implementation

This module is for developer use only. It is used to start a communication session.

Warning

Importing this module should only be done when launching Optunity as a subprocess to access functionality from non-Python environments. Do not import this module as a Python user.

This module implements several use cases to provide the main Optunity API in other environments. It communicates with the external environment using JSON messages.

We will discuss the use cases as if they are ordinary function calls. Parameter names are keys in the JSON root message.

This standalone subprocess can communicate through stdin/stdout or sockets. To use sockets:

• standalone as client: specify the port as first commandline argument and host as second (omitting host will imply localhost).
• standalone as server: launch with ‘server’ as first command line argument. The port number that is being listened on will be printed on stdout.

Requesting manuals

Emulates optunity.manual().

Request:

Key	Value	Optional
manual	name of the solver whose manual we want or empty string	no

Examples:

{"manual": ""}
{"manual": "grid search"}

Reply:

Key	Value	Type
manual	the manual that was requested	list of strings
solver_names	the name of the solver whose manual was requested or a list of all registered solvers	list of strings

Manuals are returned as a list of strings, each string is a line of the manual.

Generate cross-validation folds

Use the Python library to generate k-fold cross-validation folds. This requires one message back and forth.

Emulates optunity.generate_folds().

Request:

Key	Value	Optional
generate_folds	dictionary: num_instances number of instances to consider num_folds number of folds num_iter number of iterations strata to account for in fold generation clusters to account for in fold generation	no no yes (10) yes (1) yes yes

Strata and clusters are sent as list (strata/clusters) of lists (instance indices).

Note

strata and cluster indices must be 0-based

Example:

{"generate_folds": {"num_instances": 10, "num_folds": 2, "num_iter": 5, "strata": [[1, 2], [3, 4]], "clusters": [[5, 6], [7, 8]]}}

Reply:

Key	Value	Type
folds	the resulting folds	list (iterations) of lists (folds) of lists (instances)

The inner lists contain the instance indices per fold (0-based indexing).

Example:

{"folds": [[[2, 3, 0, 5, 8], [1, 4, 7, 6, 9]], [[2, 4, 7, 8, 0], [1, 3, 6, 9, 5]], [[2, 4, 9, 7, 8], [1, 3, 0, 5, 6]], [[1, 3, 7, 6, 5], [2, 4, 9, 8, 0]], [[2, 3, 5, 8, 0], [1, 4, 6, 9, 7]]]}

Maximize

Emulates optunity.maximize().

Using the simple maximize functionality involves sending an initial message with the arguments to optunity.maximize() as shown below.

Subsequently, the solver will send objective function evaluation requests sequentially. These requests can be for scalar or vector evaluations (details below).

When the solution is found, or the maximum number of evaluations is reached a final message is sent with all details.

Setup request:

Key	Value	Optional
maximize	dictionary: num_evals number of permitted function evaluations box constraints dictionary	no no no
call_log	a call log of previous function evaluations	yes
constraints	domain constraints on the objective function ub_{oc} upper bound (open/closed) lb_{oc} lower bound (open/closed) range_{oc}{oc} interval bounds	yes yes yes yes
default	number, default function value if constraints are violated	yes

After the initial setup message, Optunity will send objective function evaluation requests. These request may be for a scalar or a vector evaluation, and look like this:

Scalar evaluation request: the message is a dictionary containing the hyperparameter names as keys and their associated values as values.

An example request to evaluate f(x, y) in (x=1, y=2):

{"x": 1, "y": 2}

Vector evaluation request: the message is a list of dictionaries with the same form as the dictionary of a scalar evaluation request.

An example request to evaluate f(x, y) in (x=1, y=2) and (x=2, y=3):

[{"x": 1, "y": 2}, {"x": 2, "y": 3}]

The replies to evaluation requests are simple:

• scalar request: dictionary with key value and value the objective function value
• vector request: dictionary with key values and value a list of function values

Note

Results of vector evaluations must be returned in the same order as the request.

When a solution is found, Optunity will send a final message with all necessary information and then exit. This final message contains the following:

Key	Value	Type
solution	the optimal hyperparameters	dictionary
details	various details about the solving process optimum: f(solution) stats: number of evaluations and wall clock time call_log: record of all function evaluations report: optional solver report	dictionary number dictionary dictionary optional
solver	information about the solver that was used	dictionary

Minimize

Identical to maximize (above) except that the initial message has the key minimize instead of maximize.

Emulates optunity.minimize().

Make solver

Attempt to instantiate a solver from given configuration. This serves as a sanity-check.

Emulates optunity.make_solver().

Key	Value	Optional
make_solver	dictionary solver_name name of the solver to be instantiated everything necessary for the solver constructor see Solvers for details.	no no no

Example:

{"make_solver": {"x": [1, 2], "y": [2, 3], "solver_name": "grid search"}}

Optunity replies with one of two things:

• {"success": true}: the solver was correctly instantiated
• {"error_msg": "..."}: instantiating the solver failed

Optimize

Using the optimize functionality involves sending an initial message with the arguments to optunity.optimize() as shown below.

Subsequently, the solver will send objective function evaluation requests sequentially. These requests can be for scalar or vector evaluations (details below).

When the solution is found, or the maximum number of evaluations is reached a final message is sent with all details.

Emulates optunity.optimize().

Key	Value	Optional
optimize	dictionary max_evals: maximum number of evaluations, or 0 maximize: boolean, indicates maximization (default: true)	no yes yes
solver	dictionary solver_name: name of the solver everything necessary for the solver constructor see Solvers for details.	no no no
call_log	a call log of previous function evaluations	yes
constraints	domain constraints on the objective function ub_{oc} upper bound (open/closed) lb_{oc} lower bound (open/closed) range_{oc}{oc} interval bounds	yes yes yes yes
default	number, default function value if constraints are violated	yes

After the initial setup message, Optunity will send objective function evaluation requests. These request may be for a scalar or a vector evaluation, and look like this:

Scalar evaluation request: the message is a dictionary containing the hyperparameter names as keys and their associated values as values.

An example request to evaluate f(x, y) in (x=1, y=2):

{"x": 1, "y": 2}

Vector evaluation request: the message is a list of dictionaries with the same form as the dictionary of a scalar evaluation request.

An example request to evaluate f(x, y) in (x=1, y=2) and (x=2, y=3):

[{"x": 1, "y": 2}, {"x": 2, "y": 3}]

The replies to evaluation requests are simple:

• scalar request: dictionary with key value and value the objective function value
• vector request: dictionary with key values and value a list of function values

Note

Results of vector evaluations must be returned in the same order as the request.

When a solution is found, Optunity will send a final message with all necessary information and then exit. This final message contains the following:

Key	Value	Type
solution	the optimal hyperparameters	dictionary
details	various details about the solving process optimum: f(solution) stats: number of evaluations and wall clock time call_log: record of all function evaluations report: optional solver report	dictionary number dictionary dictionary optional

Module author: Marc Claesen

optunity.standalone.fold_request(cv_opts)

Computes k-fold cross-validation folds. Emulates optunity.cross_validated().

optunity.standalone.main()

optunity.standalone.make_solver(solver_config)

optunity.standalone.manual_request(solver_name)

Emulates optunity.manual().

optunity.standalone.max_or_min(solve_fun, kwargs, constraints, default, call_log)

Emulates optunity.maximize() and optunity.minimize().

optunity.standalone.optimize(solver_config, constraints, default, call_log, maximize, max_evals)

Emulates optunity.optimize().

optunity.standalone.prepare_fun(mgr, constraints, default, call_log)

Creates the objective function and wraps it with domain constraints and an existing call log, if applicable.