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

grad_f_s¶

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¶

Bases: src.models.CompModel

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

grad_constr_fn¶

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