# 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.

**Initial Point and**\(L\)

`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**

`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**

`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**

`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`

.