# 8. Models¶

This section documents the constructors, properties, and methods of the CompModel and ConstrCompModel classes. Hidden and inherited properties are not shown here for simplicity.

class src.models.CompModel(varargin)

Bases: matlab.mixin.Copyable

An abstract model class for composite optimization.

Note

The following properties are necessary before the optimize() method can be called to solve the model: either {f_s, grad_f_s} or oracle, L, x0, and solver.

f_s

A one argument function that, when evaluated at a point $$x$$, outputs $$f_s(x)$$. Defaults to None.

Type

function handle

A one argument function that, when evaluated at a point $$x$$, outputs $$\nabla f_s(x)$$. Defaults to None.

Type

function handle

f_n

A one argument function that, when evaluated at a point $$x$$, outputs $$f_n(x)$$. Defaults to @(x) zeros(size(x)).

Type

function handle

prox_f_n

A two argument function that, when evaluated at $$\{x,\lambda\}$$, outputs

${\rm prox}_{\lambda f_n}(x) := {\rm argmin}_u \left\{\lambda f_n(u) + \frac{1}{2}\|u-x\|^2\right\}.$
Defaults to @(x, lam) x.

Type

function handle

L

A required Lipschitz constant of $$\nabla f_s$$. Defaults to None.

Type

double

M

An optional upper curvature constant of $$\nabla f_s$$, i.e., a constant satisfying

$f_s(z) - f_s(u) - \langle\nabla f_s(u), z - u \rangle \leq \frac{M}{2}\|u-z\|^2 \quad \forall u,z \in {\rm dom}\, f_n.$
Defaults to None.

Type

double

m

An optional lower curvature constant of $$\nabla f_s$$, i.e. a constant satisfying

$f_s(z) - f_s(u) - \langle\nabla f_s(u), z - u \rangle \geq -\frac{m}{2}\|u-z\|^2 \quad \forall u,z \in {\rm dom}\, f_n.$
Defaults to None.

Type

double

x0

A required starting point of the solver. Defaults to None.

Type

double vector

oracle

An optional oracle that may be given to the model, which will be passed to the solver if the flag i_update_oracle is False. Defaults to None.

Type

Oracle

solver

A required function handle to a solver that solves unconstrained composite optimization problems (see src/solvers). Defaults to None.

Type

function handle

model

The model struct output by the solver. Defaults to None.

Type

struct

history

The history struct output by the solver. Defaults to None.

Type

struct

solver_hparams

Contains additional hyperparameters that will be given to the solver when it is called. Defaults to None.

Type

struct

iter_limit

An upper bound on the total number of gradient/function/proximal evaluations done by the solver. Defaults to Inf.

Type

int

time_limit

An upper bound on the total time used by the solver. Defaults is Inf.

Type

double

opt_tol

The tolerance for optimality, i.e. $$\rho=\text{opt_tol}$$. Defaults to 1e-6.

Type

double

opt_type

Is either ‘relative’ or ‘absolute’. If it is ‘absolute’, then the optimality condition is $$\|v\|\leq\text{opt_tol}$$. If it is ‘relative’, then the optimality condition is $$\|v\|/[1+\|\nabla f_s(x_0)\|] \leq \text{opt_tol}$$. Defaults to 'absolute'.

Type

character vector

prod_fn

A two argument function that, when evaluated at $$\{a, b\}$$, outputs the inner product $$\langle a,b \rangle$$. Defaults to the Euclidean inner product, i.e. @(a,b) sum(dot(a, b)).

Type

function handle

norm_fn

A one function that, when evaluated at a point $$a$$, outputs $$\|a\|$$. Defaults to the Frobenius norm, i.e. norm(a, 'fro').

Type

function handle

iter

The number of gradient/function/proximal evaluations done by the solver. Defaults to 0. Cannot be set by the user.

Type

int

runtime

The total runtime used by the solver. Defaults to 0.0. Cannot be set by the user.

Type

double

x

The stationary point returned by the solver. Defaults to None. Cannot be set by the user.

Type

double vector

v

The stationary residual returned by the solver. Defaults to None. Cannot be set by the user.

Type

double vector

CONSTRUCTORS

CompModel(varargin)

The constructor for the CompModel class. It has three ways to initialize: (i) invoking CompModel creates a CompModel object with the default properties; (ii) invoking CompModel(in_oracle) creates a CompModel object with the oracle property set to the input oracle; and (iii) invoking CompModel(f_s, f_n, grad_f_s, prox_f_n) creates an Oracle object with the properties f_s, f_n, grad_f_s, and prox_f_n filled by the corresponding input.

view_flags()

Displays flags that control the behavior of optimize().

view_topology()

Displays functions related to the underlying inner product space.

view_solution()

Displays metrics related to the obtained solution by the solver.

view_curvatures()

Displays the underlying curvatures.

view_history()

Displays the history structure output by the solver.

class src.models.ConstrCompModel

An abstract model class for constrained composite optimization.

Note

The following (non-inherited) properties are necessary before the optimize() method can be called to solve the model: framework, constr_fn, grad_constr_fn, set_projector, and K_constr.

framework

A required function handle to a framework that solves constrained composite optimization problems (see src/frameworks). Defaults to None.

Type

function handle

constr_fn

A required one argument function that, when evaluated at a point $$x$$, returns the constraint function at that point, i.e. $$g(x)$$. Defaults to @(x) 0.

Type

function handle

A required function that represents the gradient of the constraint function. Has two possible prototypes: (i) a one argument function that, when evaluated at a point $$x$$, returns $$\nabla g(x)$$; and (ii) a two argument function that, when evaluated at $$\{x, \delta\}$$, returns $$\nabla g(x) \delta$$. Defaults to @(x) zeros(size(x)).

Type

function handle

set_projector

A one argument function that, when evaluated at a point $$x$$, returns the projection of $$x$$ onto the set $$S$$. Defaults to @(x) zeros(size(x)).

Type

function handle

primal_cone_project

A one argument function that, that, when evaluated at a point $$x$$, returns the projection of $$x$$ onto the cone K. Defaults to @(x) zeros(size(x)).

Type

function handle

dual_cone_projector

A one argument function that, when evaluated at a point $$x$$, returns the projection of $$x$$ onto the dual cone K^{*}. Defaults to @(x) x.

Type

function handle

B_constr

A bound on the norm of the constraint function over the domain of $$f_n$$. Defaults to 0.0.

K_constr

A required Lipschitz constant of the constraint function. Defaults to None.

L_constr

A Lipschitz constant of the gradient of the constraint function. Defaults to 0.0.

feas_tol

The tolerance for feasibility, i.e. $$\eta=\text{feas_tol}$$. Defaults to 1e-6.

Type

double

feas_type

Is either ‘relative’ or ‘absolute’. If it is ‘absolute’, then the optimality condition is $$\|w\|\leq \text{opt_tol}$$. If it is ‘relative’, then the optimality condition is $$\|w\|/(1 + {\cal F}) \leq\text{opt_tol}$$ where $${\cal F} = \|g(x_0) - {\rm Proj}_S(g(x_0))\|$$. Defaults to 'absolute'.

Type

character vector

w

The feasibility residual returned by the solver. Defaults to None. Cannot be set by the user.

Type

double vector