4. Overview of the API¶
This section presents a high level overview of the NC-OPT MATLAB interface. All sections following this one present a comprehensive description of the key classes, solvers, and frameworks.
4.1. Creating a Model¶
NC-OPT allows you to model problems of the following form:
Models are generated by using constructors for the CompModel
or ConstrCompModel
classes, each containing properties that specify its various components such as solvers, oracles, and tolerances. By default, the empty constructor sets
While not enforced, it is assumed that the user will configure the model so that the set \(S\) and the functions \(f_s\), \(f_n\), and \(g\) satisfy the following minimal assumptions:
The set \(S\) is either empty or nonempty and convex.
The function \(f_s\) is continuously differentiable and its gradient is \(L\)-Lipschitz continuous.
The function \(f_n\) is proper, closed, and convex.
The function \(g\) is either linear or (cone) convex.
Either \(\inf_u [f_s(u) + f_n(u)] > -\infty\) or the domain of \(f_n\) is compact.
After constructing the model, one or more of the following components will then need to be specified, depending on the type of model created.
CompModel
or ConstrCompModel
objects, the user needs to provide: (a) an initial point \(x_0\) in the domain of f_n
; and (b) the Lipschitz constant \(L\) of the gradient of \(f_s\). These can be specified by setting the x0
and L
properties of the models.CompModel
or ConstrCompModel
objects, the user needs to provide a subset of the functions above or a first-order oracle, represented by an Oracle
object, to the model. The first-order oracle has a method eval()
which, when evaluated at point, returns information about the objective function at that point.CompModel
or ConstrCompModel
objects, the user needs to provide a composite optimization solver to the model. This solver takes an Oracle
object and a struct
object of hyperparameters as input, and outputs a solution associated the problem underlying the oracle.ConstrCompModel
objects, the user needs to provide a constrained optimization framework to the model. This framework takes a solver function, Oracle
object, and a struct
of hyperparameters as input, and outputs a solution associated the problem underlying the oracle and hyperparameters.4.2. Solving a Model¶
When a model has been fully constructed, it can solved by invoking the optimize()
method. This method, in particular, applies either the underlying solver
or framework
to produce an approximate stationary point of the associated optimization problem. For unconstrained problems, this point is a pair \((x, v)\) satisfying
for a given tolerance \(\rho \in {\mathbb R}_{++}\). For constrained problems, this point is a triple \((x, v, w)\) satisfying
for a given tolerance pair \((\rho, \eta) \in {\mathbb R}_{++}^2\). By default, the tolerances are set to \(\rho=10^{-6}\) and \(\eta=10^{-6}\). Messages about the model’s configuration and final status will be output to the MATLAB command line.
4.3. A Simple Example¶
Below is a simple example for solving the unconstrained convex optimization problem
1% Create the Model object and specify the solver.
2cvx_qp = CompModel;
3cvx_qp.solver = @AIPP;
4
5% Define the function and its gradient.
6cvx_qp.f_s = @(x) (1 / 2) * (x - 1) ^ 2;
7cvx_qp.grad_f_s = @(x) x - 1;
8
9% Set the Lipschitz constant of the gradient and the starting point x0.
10cvx_qp.L = 10;
11cvx_qp.x0 = 10;
12
13% Solve the problem.
14cvx_qp.optimize;
The complete code for this example can be found in ./nc_opt/examples/unconstrained/basic_convex_qp.m
.