MATLAB

In this page we briefly discuss the MATLAB wrapper, which provides most of Optunity’s functionality. For a general overview, we recommend reading the User Guide.

For installation instructions, please refer to Installing Optunity.

Whenever the Python API requires a dictionary, we use a MATLAB struct. As MATLAB has no keyword arguments, we use varargs with the convention of <name>, <value>. Please refer to each function’s help for details on how to use it.

Warning

Since MATLAB does not have keyword arguments, every objective function you define should accept a single struct argument, whose fields represent hyperparameters.

Example, to model a function \(f(x, y) = x + y\):

f = @(pars) pars.x + pars.y;

For MATLAB, the following main features are provided:

• Manual
• Optimizing hyperparameters
• Cross-validation

The file <optunity>/wrappers/matlab/optunity_example.m contains code for all the functionality that is available in MATLAB.

Note

If you experience any issues with the MATLAB wrapper, create a global variable DEBUG_OPTUNITY and set its value to true. This will show all debugging output:

global DEBUG_OPTUNITY
DEBUG_OPTUNITY=true;

Please submit this output as an issue at https://github.com/claesenm/optunity/issues/new to obtain help.

If MATLAB hangs while using Optunity there is a communication issue. This should not occur, if you encounter this please file an issue at https://github.com/claesenm/optunity/issues/new. Currently the only way out of this is to kill MATLAB.

Manual

To obtain the manual of all solvers and a list of available solver names, use optunity.manual(). If you specify a solver name, its manual will be printed out.

You can verify whether or not a certain solver, for instance cma-es, is available like this:

solvers = optunity.manual();
available = any(arrayfun(@(x) strcmp(x, 'cma-es'), solvers));

Optimizing hyperparameters

The MATLAB wrapper offers optunity.maximize(), optunity.minimize() and optunity.optimize(). These provide the same functionality as their Python equivalents.

The following code fragment shows how to optimize a simple function f with Random Search within the box \(-4 < x < 4\) and \(-5 < y < 5\) and 200 evaluations:

offx = rand();
offy = rand();
f = @(pars) - (offx+pars.x)^2 - (offy+pars.y)^2;

[max_solution, max_details, max_solver] = optunity.maximize(f, 200, ...
        'solver_name', 'random search', 'x', [-4, 4], 'y', [-5, 5]);

If you want to use optunity.optimize(), you must create the solver in advance using optunity.make_solver(). This will return an optunity.Solver object or return an error message:

f = @(pars) pars.x + pars.y
rnd_solver = optunity.make_solver('random search', 'x', [-5, 5], ...
        'y', [-5, 5], 'num_evals', 400);
[rnd_solution, rnd_details] = optunity.optimize(rnd_solver, f);

Differences between Python and MATLAB version of optimize

The MATLAB version has an extra argument constraints where you can specify domain constraints (the MATLAB wrapper has no equivalent of optunity.wrap_constraints()). Constraints are communicated as a struct with the correct field names and corresponding values (more info at Domain constraints).

As an example, to add constraints \(x < 3\) and \(y \geq 0\), we use the following code:

constraints = struct('ub_o', struct('x', 3), 'lb_c', struct('y', 0));

Information about the solvers can be obtained at Solver overview. To learn about the specific parameter names for each solver, check out the optunity.solvers.

Cross-validation

Two functions are provided for cross-validation:

• optunity.generate_folds(): generates a set of cross-validation folds
• optunity.cross_validate(): function decorator, to perform cross-validation with specified function

Both functions can deal with strata and clusters. You can specify these as a cell array of vectors of indices:

strata = {[1,2,3], [6,7,8,9]};
folds = optunity.generate_folds(20, 'num_folds', 10, 'num_iter', 2, 'strata', strata);

Cross-validation folds are returned as a matrix of num_instances * num_iter with entries ranging from 1 to num_folds to indicate the fold each instance belongs to per iteration.

optunity.cross_validate() requires a function handle as its first argument. This is the function that will be decorated, which must have the following first arguments: x_train and x_test (if unsupervised) or x_train, y_train, x_test, y_test.

As an example, assume we have a function optunity_cv_fun(x_train, x_test, pars):

function [ result ] = cv_fun( x_train, x_test, pars )
disp('training set:');
disp(x_train');
disp('test set:');
disp(x_test');

result = -pars.x^2 - pars.y^2;
end

This must be decorated with cross-validation, for instance:

x = (1:10)';
cvf = optunity.cross_validate(@optunity_cv_fun, x);

% evaluate the function: this will return a cross-validation result
performance = cvf(struct('x',1,'y',2));

Warning

After decorating with cross-validation, the objective function should have a single argument, namely a struct of hyperparameters.