MATLAB API Reference

Warning

The alpaqa MATLAB API is experimental. Options are subject to change, and there may be some problems or bugs that need to be ironed out.

Please share your experience on https://github.com/kul-optec/alpaqa/issues

alpaqa.minimize(problem, x0, y0, method="panoc", params=struct)

Solves the given minimization problem using one of alpaqa’s solvers.

Parameters:

• problem (alpaqa.Problem) – A description of the minimization problem to solve.

• x0 (double(1,:)) – Optional initial guess.

• y0 (double(1,:)) – Optional initial guess for the Lagrange multipliers.

• method (string) –

  Name of the solver to use. (Keyword-only)

  Possible values are: panoc, panoc.lbfgs, panoc.struclbfgs, panoc.anderson, zerofpr, zerofpr.lbfgs, zerofpr.struclbfgs, zerofpr.anderson, pantr

• params (struct) –

  Options to pass to the solver. (Keyword-only)

  The struct can contain four top-level fields, specifying options for the different components of the solver:

  • alm: Parameters for the outer ALM solver alpaqa::ALMParams

  • solver: Parameters for the inner solver alpaqa::PANOCParams, alpaqa::ZeroFPRParams, alpaqa::PANTRParams

  • dir: Parameters for the inner solver’s direction provider alpaqa::LBFGSDirectionParams, alpaqa::StructuredLBFGSDirectionParams, alpaqa::NewtonTRDirectionParams

  • accel: Parameters for the direction’s accelerator alpaqa::LBFGSParams, alpaqa::SteihaugCGParams

Returns:

The solution, corresponding Lagrange multipliers, and a struct containing solver statistics.

Return type:

[double(1,:), double(1,:), struct]

class alpaqa.Problem

Describes a minimization problem. For more details, please see Problem formulations (Doxygen).

f

Objective function.

Type:

casadi.SX | casadi.MX

x

Optimization variables.

Type:

casadi.SX | casadi.MX

g

General constraints.

Type:

casadi.SX | casadi.MX

param

Optional problem parameter variable.

Type:

casadi.SX | casadi.MX

C_lowerbound

Lower bound on the optimization variables.

Type:

double(1,:)

C_upperbound

Upper bound on the optimization variables.

Type:

double(1,:)

D_lowerbound

Lower bound on the general constraints.

Type:

double(1,:)

D_upperbound

Upper bound on the general constraints.

Type:

double(1,:)

l1_regularization

Weight factor(s) of the optional 1-norm regularization of the optimization variables.

Type:

double(1,1) | double(1,:)

param_value

Numerical value of the problem parameters.

Type:

double(1,:)

Example

The following is a transcription of the Python example from the Getting started page.

[version, build_time] = alpaqa.version

%% Build the problem (CasADi code, independent of alpaqa)
import casadi.*

% Make symbolic decision variables
x1 = SX.sym('x1'); x2 = SX.sym('x2');
x = [x1, x2];  % Collect decision variables into one vector
% Make a parameter symbol
p = SX.sym('p');

% Objective function f and the constraints function g
problem = alpaqa.Problem;
problem.x = x;
problem.param = p;
problem.f = (1 - x1)^2 + p * (x2 - x1^2)^2;
problem.g = [(x1 - 0.5)^3 - x2 + 1, x1 + x2 - 1.5];

% Define the bounds
problem.C_lowerbound = [-0.25, -0.5];  % -0.25 <= x1 <= 1.5, -0.5 <= x2 <= 2.5
problem.C_upperbound = [1.5, 2.5];
problem.D_lowerbound = [-inf, -inf];  %     g1 <= 0,           g2 <= 0
problem.D_upperbound = [0, 0];
problem.param_value = 10.0;

%% Choose a solver and configure its parameters
solver = "panoc.lbfgs";

params = struct;
params.accel.memory = 10;
params.solver.stop_crit = "FPRNorm";
params.solver.print_interval = 1;
params.alm.tolerance = 1e-10;
params.alm.dual_tolerance = 1e-10;
params.alm.initial_penalty = 50;
params.alm.penalty_update_factor = 20;
params.alm.print_interval = 1;
params.alm.max_iter = 20;

%% Compute a solution

[x_sol, y_sol, stats] = alpaqa.minimize( ...
    problem, method=solver, params=params);

%% Compute a solution starting with an initial guess

% Set initial guesses at arbitrary values
x0 = [0.1, 1.8];  % decision variables
y0 = [0.0, 0.0];  % Lagrange multipliers for g(x)

% Solve the problem
[x_sol, y_sol, stats] = alpaqa.minimize( ...
    problem, x0, y0, method=solver, params=params);

%% Print the results
disp('Stats:');
disp(stats);
disp(stats.inner);
disp('Solution:');
disp(x_sol);
disp('Multipliers:');
disp(y_sol);
disp(stats.status)

Limitations and known issues

• Only problems formulated using CasADi expressions are currently supported.

• Pre-compilation of CasADi functions is not implemented, which means that the MATLAB version of alpaqa may be significantly slower than its Python and C++ counterparts.

• User-defined callbacks, per-iteration statistics, and function counters are not available.

• Parallelization and cancellation are not possible.

• Options with a non-ASCII name must be specified using their ASCII aliases.

• Duration options must be encoded as a string (e.g. '1min 30s 456µs').

• Statistics that are NaN or infinite are converted to a string.

• Error checking and reporting need to be improved.

• Console output contains ANSI escape sequences.