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).
python -m optunity.standalone <PORT> <HOST>
standalone as server: launch with ‘server’ as first command line argument. The port number that is being listened on will be printed on stdout.
python -m optunity.standalone server
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:
|
no
|
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:
|
no
|
| call_log | a call log of previous function evaluations | yes |
| constraints | domain constraints on the objective function
|
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
|
dictionary
|
| 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
see Solvers for details. |
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
|
no
|
| solver | dictionary
see Solvers for details. |
no
|
| call_log | a call log of previous function evaluations | yes |
| constraints | domain constraints on the objective function
|
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
|
dictionary
|
Module author: Marc Claesen
-
optunity.standalone.fold_request(cv_opts)[source]¶ Computes k-fold cross-validation folds. Emulates
optunity.cross_validated().
-
optunity.standalone.manual_request(solver_name)[source]¶ Emulates
optunity.manual().
-
optunity.standalone.max_or_min(solve_fun, kwargs, constraints, default, call_log)[source]¶ Emulates
optunity.maximize()andoptunity.minimize().
-
optunity.standalone.optimize(solver_config, constraints, default, call_log, maximize, max_evals)[source]¶ Emulates
optunity.optimize().