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.


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:

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


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:


Please submit this output as an issue at 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 Currently the only way out of this is to kill MATLAB.


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.


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('test set:');

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

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));


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