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
} ororacle
,L
,x0
, andsolver
.- 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 toNone
.- 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 toNone
.- 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) invokingCompModel(in_oracle)
creates a CompModel object with the oracle property set to the input oracle; and (iii) invokingCompModel(f_s, f_n, grad_f_s, prox_f_n)
creates an Oracle object with the propertiesf_s
,f_n
,grad_f_s
, andprox_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
, andK_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