15.3 Data Structures and Notation¶
We specify the notation and data structures used in the interface.
Problem definition
prob
— describes an optimization problem.accs
— structure of affine conic constraints.names
— names of objects in the optimization problem.
Solutions
solver_solutions
— solutions.solution
— one solution.
Other
primal_repair
— used in feasibility repair.prisen
,prisen_data
,duasen
— used in sensitivity analysis.callback
— used to set up a callback function.optserver
— used to set up remote optimization.
15.3.1 Notation¶
The mathematical formulations of problem types solvable by MOSEK are discussed in full detail in Sec. 12 (Problem Formulation and Solutions). Here we summarize them in the context of the Optimization Toolbox for MATLAB API.
Linear problem
A linear problem has the form:
It has \(n\) variables and \(m\) linear constraints. See Sec. 12.1 (Linear Optimization).
Conic problem
A conic problem with affine conic constraints (ACC) is an extension of a linear problem and has the form:
where \(\D\) is a product of domains from Sec. 15.8 (Supported domains) and \(\PSD\) is a product of PSD cones meaning that \(\barX\) is a sequence of PSD matrix variables. The available conic domain types are listed in Sec. 15.8 (Supported domains).
Quadratic and quadratically constrained problems
A problem with quadratic objective or constraints has the form:
It has \(n\) variables, and \(m\) constraints. The matrix \(Q^o=(q_{ij}^o)_{i=1,\ldots,n,j=1,\ldots,n}\) must be symmetric positive semidefinite. See also Sec. 12.4 (Quadratic and Quadratically Constrained Optimization). Each of the matrices \(Q^i=(q_{jk}^i)_{j=1,\ldots,n,k=1,\ldots,n}\) for \(j=1\ldots,m\) must be
negative semidefinite if \(\infty < l_i^c\), \(u_i^c=+\infty\),
positive semidefinite if \(\infty = l_i^c\), \(u_i^c<+\infty\),
zero otherwise.
Mixedinteger problems
All problems without semidefinite variables or domains may be integerconstrained, i.e., for some set \(\mathcal{J}\subseteq\{1,\ldots,n\}\) we require
Minimization vs. Maximization
The objective of every problem can be maximized rather than minimized without any change. In case of quadratic problems the matrix \(Q^o\) must be negative semidefinite.
Data specification in MATLAB
The linear constraint matrix \(A=(a_{ij})_{i=1\ldots,m,j=1,\ldots,n}\) must be a sparse matrix. The dimensions of \(A\) are used to determine the number of constraints \(m\) and the number of variables \(n\) in the problem.
The affine conic constraint matrix \(F=(f_{ij})_{i=1\ldots,k,j=1,\ldots,n}\) must be a sparse matrix. The dimensions of \(F\) are used to determine the total dimension of all conic domains in \(\D\).
The symmetric matrices \(Q^o\), \(Q^i\), \(\barC_j\), \(\barA_{ij}\), \(\barF_{ij}\) are specified in sparse triplet format discarding zero elements, and since they are symmetric, only the lower triangular parts should be specified. A generic matrix \(M\) specified in sparse triplet format is given by three arrays
subi
,subj
andval
of the same length such that\[M_{\mathtt{subi[t]},\mathtt{subj[t]}} = \mathtt{val[t]},\ \quad t=1,\ldots,\mathtt{len(val)}\]For a specification of the domains \(\D\) see
accs
.For a specification of the semidefinite part see
barf
,bara
andbarc
.
The parameters of the optimization problem are stored using one or more subfields of the prob
structure using the naming convention in Table 15.1. Only a
is obligatory. All other fields are optional depending on what problem type is defined.
Field name 
Type 
Dimension 
Problem parameters 


sparse matrix 
\(m \times n\) 
\(a_{ij}\) 


\(n\) 
\(c_j\) 


\(1\) 
\(c^f\) 


\(m\) 
\(l_i^c\) 


\(m\) 
\(u_i^c\) 


\(n\) 
\(l_j^x\) 


\(n\) 
\(u_j^x\) 


\(\mathcal{J}\) 
\(\mathcal{J}\) 

\(\K\) 


sparse matrix 
\(k\times n\) 
\(F\) 


\(k\) 
\(g\) 


\(s\) 
\(r_j\) 

\(\barC_j\) 


\(\barA_{ij}\) 


\(\barF_{ij}\) 




\(q_{ij}^o\), sparse rep. 



\(q_{ij}^o\), sparse rep. 



\(q_{ij}^o\), sparse rep. 



\(q_{ij}^k\), sparse rep. 



\(q_{ij}^k\), sparse rep. 



\(q_{ij}^k\), sparse rep. 



\(q_{ij}^k\), sparse rep. 
The int
type indicates that the field must contain an integer value, double
indicates any real number. This distinction is only a convenience for the reader — all actual data structures in MATLAB are ordinary matrices/arrays of floatingpoint numbers.
The sparse representation of quadratic terms is:
Since \(Q^o\), \(Q^i\) are by assumption symmetric, all elements are assumed to belong to the lower triangular part. If an element is specified multiple times, the different elements are added together.
15.3.2 Data Types and Structures¶
 prob¶
The
prob
data structure is used to communicate an optimization problem to MOSEK or for MOSEK to return an optimization problem to the user. It defines an optimization problem using a number of subfields. Most of the fields are optional, depending on what problem type is being solved. Fields:
names
(names
) – A structure which contains the names of the problem, variables, constraints and so on.a
(double[][]) – The linear constraint matrix. It is obligatory, and its dimensions define the number of variables and constraints. It must be a sparse matrix. This field should always be defined, even if the problem does not have any constraints. In that case a sparse matrix having zero rows and the correct number of columns is the appropriate definition of the field.c
(double[]) – Linear term in the objective.cfix
(double) – Fixed term in the objective.blc
(double[]) – Lower bounds of the constraints. \(\infty\) denotes an infinite lower bound. If the field is not defined orblc==[]
, then all the lower bounds are assumed to be equal to \(\infty\).buc
(double[]) – Upper bounds of the constraints. \(\infty\) denotes an infinite upper bound. If the field is not defined orbuc==[]
, then all the upper bounds are assumed to be equal to \(\infty\).blx
(double[]) – Lower bounds on the variables. \(\infty\) denotes an infinite lower bound. If the field is not defined orblx==[]
, then all the lower bounds are assumed to be equal to \(\infty\).bux
(double[]) – Upper bounds on the variables. \(\infty\) denotes an infinite upper bound. If the field is not defined orbux==[]
, then all the upper bounds are assumed to be equal to \(\infty\).bardim
(int[]) – A list with the dimensions of the semidefinite variables.barc
(barc
) – A structure for specifying \(\barC_j\).bara
(bara
) – A structure for specifying \(\barA_{ij}\).qosubi
(int[]) – \(i\) subscripts in the sparse specification of \(q_{ij}^o\) in \(Q^o\). See (15.5).qosubj
(int[]) – \(j\) subscripts in the sparse specification of \(q_{ij}^o\) in \(Q^o\). See (15.5).qoval
(double[]) – Numerical values in the sparse specification of \(q_{ij}^o\) in \(Q^o\). See (15.5).qcsubk
(int[]) – \(k\) subscripts in the sparse specification of \(q_{ij}^k\) in \(Q^k\). See (15.5)qcsubi
(int[]) – \(i\) subscripts in the sparse specification of \(q_{ij}^k\) in \(Q^k\). See (15.5)qcsubj
(double[]) – \(j\) subscripts in the sparse specification of \(q_{ij}^k\) in \(Q^k\). See (15.5)qcval
(double[]) – Numerical values in the sparse specification of \(q_{ij}^k\) in \(Q^k\). See (15.5)accs
(accs
) – A structure defining the structural data (list of domains) for affine conic constraints (ACC), see (15.2).f
(double[][]) – The matrix of affine conic constraints. It must be a sparse matrix.g
(double[]) – The constant term of affine conic constraints. If not present org==[]
it is assumed \(g=0\).barf
(barf
) – A structure for specifying \(\barF_{ij}\).cones
(cones
) – Deprecated.ints.sub
(int[]) – A list of indexes of integerconstrained variables.ints.sub
is identical to the set \(\mathcal{j}\) in (15.4).sol
(solver_solutions
) – A structure containing a guess on the optimal solution which some of the optimizers in MOSEK may exploit.primlarepair
(primal_repair
) – Specification of primal feasibility repair. See Sec. 14.2.1.1 (Using the automatic repair tool).prisen
(prisen
) – Request sensitivity analysis. See Sec. 14.3 (Sensitivity Analysis).duasen
(duasen
) – Request sensitivity analysis. See Sec. 14.3 (Sensitivity Analysis).
 res¶
Contains a response from
mosekopt
. Fields:
sol
(solver_solutions
) – A structure containing solutions (if any).rcode
(int) – The numerical response code from the solver. See Sec. 7.2 (Errors and exceptions).rcodestr
(string) – The response code from the solver as a symbolic string. See Sec. 7.2 (Errors and exceptions).rmsg
(string) – A message explaining the error (if any). See Sec. 7.2 (Errors and exceptions).info
(struct) – A structure containing information items (if requested by the commandinfo
inmosekopt
). See Sec. 7.5 (Retrieving information items).prob
(prob
) – Contains the problem data, if the commandread
was used to read a problem from a file. See Sec. 7.3.4 (Reading a problem from a file).param
(struct) – A structure which contains the complete MOSEK parameter database (if requested by the commandparam
inmosekopt
). See Sec. 7.4 (Setting solver parameters).symbcon
(struct) – A structure which contains symbolic constants and their numerical values (if requested by the commandsymbcon
inmosekopt
). See Sec. 15.7 (Enumerations) and Sec. 15.6 (Response codes).version
(struct) – A structure which contains the MOSEK version numbers (if requested by the commandversion
inmosekopt
).prisen
(prisen
) – A structure with results of sensitivity analysis (if requested by passingprisen
data inprob
). See Sec. 14.3 (Sensitivity Analysis).duasen
(duasen
) – A structure with results of sensitivity analysis (if requested by passingduasen
data inprob
). See Sec. 14.3 (Sensitivity Analysis).
 solver_solutions¶
It contains informations about initial/final solutions. Availability of solutions depends on the problem/algorithm type, see Sec. 7.1.2 (Available solutions).
 solution¶
Stores information about one solution. See Sec. 7.1.2 (Available solutions).
 Fields:
prosta
(string) – Problem status (prosta
).solsta
(string) – Solution status (solsta
).skc
(string[]) – Linear constraint status keys (stakey
).skx
(string[]) – Variable status keys (stakey
).skn
(string[]) – Conic constraint status keys (stakey
, not in basic solution).xc
(double[]) – Constraint activities, i.e., \(x_c = Ax\) where \(x\) is the optimal solution.xx
(double[]) – The optimal \(x\) solution.barx
(list) – Semidefinite variable solution (not in basic solution).y
(double[]) – Identical tosol.slcsol.suc
(not in integer solution).slc
(double[]) – Dual variable for constraint lower bounds (not in integer solution).suc
(double[]) – Dual variable for constraint upper bounds (not in integer solution).slx
(double[]) – Dual variable for variable lower bounds (not in integer solution).sux
(double[]) – Dual variable for variable upper bounds (not in integer solution).snx
(double[]) – Dual variable of conic constraints (not in basic or integer solution).doty
(double[]) – Dual variables of affine conic constraints (not in basic or integer solution).bars
(list) – Dual variable of semidefinite domains (not in basic or integer solution).pobjval
(double) – The primal objective value.dobjval
(double) – The dual objective value (not in integer solution).
 names¶
This structure is used to store all the names of individual items in the optimization problem such as the constraints and the variables.
 Fields:
name
(string) – contains the problem name.obj
(string) – contains the name of the objective.con
(cell) – a cell array wherenames.con{i}
contains the name of the \(i\)th constraint.var
(cell) – a cell array wherenames.var{j}
contains the name of the \(j\)th variable.acc
(cell) – a cell array wherenames.acc{j}
contains the name of the \(j\)th affine conic constraint.cone
(cell) – Deprecated.barvar
(cell) – a cell array wherenames.barvar{j}
contains the name of the \(j\)th semidefinite variable.
 cones¶
Deprecated. Represents structural information for old style cones. Use
accs
instead. If necessary consult the manual for version 9.
 accs¶
Represents structural information about affine conic constraints (ACC). The numerical data is contained in
prob.f
,prob.g
andbarf
.For a problem with \(s\) affine conic constraints \(Fx+\langle\barF,\barX\rangle +g\in \D\), where \(\D=\D_1\times\cdots\times\D_s\),
accs
is a list consisting of \(s\) concatenated conic domain descriptions. For a list of domains see Sec. 15.8 (Supported domains).If a domain definition requires no additional parameters (quadratic, rotated quadratic, exponential, geometric mean, linear) then its description is
\[[\mathrm{type}, \mathrm{len}]\]where \(\mathrm{type}\) is the type (
domaintype
) and \(\mathrm{len}\) is the length (dimension). The length must be present.Any additional parameters defining the domain should follow. Currently this is only the case for the power cones, whose description has the form
\[[\mathrm{type}, \mathrm{len}, n_l, \alpha_1, \ldots, \alpha_{n_l}]\]where \(n_l\) is integer and \(\alpha_1,\ldots,\alpha_{n_l}\in \real\) are the additional parameters.
Example. Suppose we have two affine conic constraints: one with a quadratic cone of dimension 5 and one with a power cone \(\POW_4^{(40,60)}\). Then \(\D = \Q^5\times \POW_4^{(40,60)}\). We specify this data as
prob.accs = [res.symbcon.MSK_DOMAIN_QUADRATIC_CONE 5 res.symbcon.MSK_DOMAIN_PRIMAL_POWER_CONE, 4, 2, 40.0, 60.0 ];
 barc¶
Together with field
bardim
this structure specifies the symmetric matrices \(\barC_j\) in the objective for semidefinite problems.The symmetric matrices are specified in blocktriplet format as
\[[\barC_{\mathtt{barc.subj(t)}}]_{\mathtt{barc.subk(t)},\mathtt{barc.subl(t)}} = \mathtt{barc.val(t)},\quad t=1,2,\ldots ,\mathtt{length(barc.subj)}.\]Only the lower triangular parts of \(\barC_j\) are specified, i.e., it is required that
\[\mathtt{barc.subk(t)} \geq \mathtt{barc.subl(t)},\quad t=1,2,\ldots ,\mathtt{length(barc.subk)},\]and that
\[1 \leq \mathtt{barc.subk(t)} \leq \mathtt{bardim(barc.subj(t))}, \quad t=1,2,\ldots ,\mathtt{length(barc.subj)}.,\]All the structure fields must be arrays of the same length.
 Fields:
subj
(int[]) – Semidefinite variable indices \(j\).subk
(int[]) – \(k\) subscripts of nonzeros elements.subl
(int[]) – \(l\) subscripts of nonzeros elements.val
(double) – Numerical values.
 bara¶
Together with the field
bardim
this structure specifies the symmetric matrices \(\barA_{ij}\) in the constraints of semidefinite problems.The symmetric matrices are specified in blocktriplet format as
\[[\barA_{\mathtt{bara.subi(t)},\mathtt{bara.subj(t)}}]_{\mathtt{bara.subk(t)},\mathtt{bara.subl(t)}} = \mathtt{bara.val(t)},\quad t=1,2,\ldots ,\mathtt{length(bara.subi)}.\]Only the lower triangular parts of \(\barA_{ij}\) are specified, i.e., it is required that
\[\mathtt{bara.subk(t)} \geq \mathtt{bara.subl(t)},\quad t=1,2,\ldots ,\mathtt{length(bara.subk)},\]and that
\[1 \leq \mathtt{bara.subk(t)} \leq \mathtt{bardim(bara.subj(t))}, \quad t=1,2,\ldots ,\mathtt{length(bara.subj)},\]All the structure fields must be arrays of the same length.
 Fields:
subi
(int[]) – Constraint indices \(i\).subj
(int[]) – Semidefinite variable indices \(j\).subk
(int[]) – \(k\) subscripts of nonzeros elements.subl
(int[]) – \(l\) subscripts of nonzeros elements.val
(double[]) – Numerical values.
 barf¶
Together with the field
bardim
this structure specifies the symmetric matrices \(\barF_{ij}\) in the affine expressions appearing in affine conic constraints.The symmetric matrices are specified in blocktriplet format as
\[[\barF_{\mathtt{barf.subi(t)},\mathtt{barf.subj(t)}}]_{\mathtt{barf.subk(t)},\mathtt{barf.subl(t)}} = \mathtt{barf.val(t)},\quad t=1,2,\ldots ,\mathtt{length(barf.subi)}.\]Only the lower triangular parts of \(\barF_{ij}\) are specified, i.e., it is required that
\[\mathtt{barf.subk(t)} \geq \mathtt{barf.subl(t)},\quad t=1,2,\ldots ,\mathtt{length(barf.subk)},\]and that
\[1 \leq \mathtt{barf.subk(t)} \leq \mathtt{bardim(barf.subj(t))}, \quad t=1,2,\ldots ,\mathtt{length(barf.subj)},\]All the structure fields must be arrays of the same length.
 Fields:
subi
(int[]) – Indices \(i\) defining the affine row in the affine conic constraints specification.subj
(int[]) – Semidefinite variable indices \(j\).subk
(int[]) – \(k\) subscripts of nonzeros elements.subl
(int[]) – \(l\) subscripts of nonzeros elements.val
(double[]) – Numerical values.
 primal_repair¶
A structure holding data for primal feasibility repair. If either of the subfields is missing, it assumed to be a vector with value 1 of appropriate dimension. See Sec. 14.2.1.1 (Using the automatic repair tool).
 Fields:
wlc
(double[]) – Weights for lower bounds on constraints.wuc
(double[]) – Weights for upper bounds on constraints.wlx
(double[]) – Weights for lower bounds on variables.wux
(double[]) – Weights for upper bounds on variables.
 prisen¶
A structure holding information about primal sensitivity analysis. See Sec. 14.3 (Sensitivity Analysis).
 Fields:
cons
(prisen_data
) – Constraints shadow prices.vars
(prisen_data
) – Variables shadow prices.
 prisen_data¶
A structure holding information about shadow prices of constraints or variables.
 Fields:
subl
(int[]) – Indices of variables/constraints to be analyzed for lower bounds.subu
(int[]) – Indices of variables/constraints to be analyzed for upper bounds.lr_bl
(double[]) – Left value \(\beta_1\) in the linearity interval for a lower bound.rr_bl
(double[]) – Right value \(\beta_2\) in the linearity interval for a lower bound.ls_bl
(double[]) – Left shadow price \(s_l\) for a lower bound.rs_bl
(double[]) – Right shadow price \(s_r\) for a lower bound.lr_bu
(double[]) – Left value \(\beta_1\) in the linearity interval for an upper bound.rr_bu
(double[]) – Right value \(\beta_2\) in the linearity interval for an upper bound.ls_bu
(double[]) – Left shadow price \(s_l\) for an upper bound.rs_bu
(double[]) – Right shadow price \(s_r\) for an upper bound.
 duasen¶
A structure holding information about dual sensitivity analysis. See Sec. 14.3 (Sensitivity Analysis).
 Fields:
sub
(int[]) – Indices of variables to be analyzed.lr_c
(double) – Left value \(\beta_1\) in linearity interval for an objective coefficientrr_c
(double) – Right value \(\beta_2\) in linearity interval for an objective coefficientls_c
(double) – Left shadow price \(s_l\) for an objective coefficientrs_c
(double) – Right shadow price \(s_r\) for an objective coefficient
 callback¶
A structure containing callback information (all subfields are optional).
 Fields:
loghandle
(struct) – A data structure or just[]
.log
(string) –Log handler. The name of a userdefined function which must accept two input arguments, e.g.,
function myprint(handle,str)
where
handle
will be identical tocallback.handle
whenmyfunc
is called, andstr
is a string of text from the log.iterhandle
(struct) – A data structure or just[]
.iter
(string) –Progress callback handler. The name of a userdefined function which must accept three input arguments,
function [r] = callback_handler(handle,where,info)
where
handle
will be identical tocallback.iterhandle
when the handler is called,where
indicates the current progress of the solver (callback
) andinfo
is the current information items list. See Sec. 7.6 (Progress and data callback) for further details.
 optserver¶
A structure containing information about the OptServer which should be used for remote optimization.
 Fields:
host
(string) – URL of the OptServer in the formhttp://server:port
orhttps://server:port
.