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:

\[\begin{split}\text{minimize} \quad & f_s(x) + f_n(x) \\ \text{subject to} \quad & g(x) \in S.\end{split}\]

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

\[f_n \equiv 0, \quad g \equiv 0, \quad S = \{0\}.\]

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.

Initial Point and \(L\)
For 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.
Oracle
For 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.
Solver
For 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.
Framework
For 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

\[\begin{split}\begin{gathered} v \in \nabla f_s(x) + \partial f_n(x), \\ x \in {\rm dom}\, f_n, \quad \|v\| \leq \rho, \end{gathered}\end{split}\]

for a given tolerance \(\rho \in {\mathbb R}_{++}\). For constrained problems, this point is a triple \((x, v, w)\) satisfying

\[\begin{split}\begin{gathered} v \in \nabla f_s(x) + \partial f_n(x) + \nabla g(x) y, \\ \quad x \in {\rm dom}\, f_n, \quad g(x) + w \in S, \quad \|v\| \leq \rho, \quad \|w\| \leq \eta, \end{gathered}\end{split}\]

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

\[\underset{x\in {\mathbb R}}{\text{minimize}} \quad \frac{1}{2}x ^2 - x + \frac{1}{2}.\]
 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.