13.1 Conic Toolbox API

Reference for mosekmodel, the API for defining and solving conic problems. This is the main component of the API for MATLAB.

For tutorials with explanations and full code examples see Sec. 7 (Optimization Tutorials), and especially Sec. 7.1 (The conic interface tutorial).

13.1.1 Construction

model = mosekmodel(name, numvar, objsense, objective, objfixterm, intvars, F, g, domain, solution_x, solution_y, conindexes)

Creates a model, which represents a conic problem. Most of the problem’s data can be set directly in this constructor; problem data can also be input and altered using dedicated methods later. The model object is the user’s access point to the problem and solution.

Return:

model (mosekmodel) – The created model object.

Parameters:

  • name (string) – (optional) Name of the model.

  • numvar (uint32) – (optional) Number of scalar variables initially in the model.

  • objsense (string) – (optional) Objective sense: "min", "minimize", "max", "maximize".

  • objective (double(:,1)) – (optional) Objective vector of length matching numvar, if provided.

  • objfixterm (double) – (optional) Fixed term in the objective.

  • intvars (uint64(:,1)) – (optional) List of indexes of integer variables.

  • F (double(:,:)) – (optional) The constraint matrix of affine conic constraints.

  • g (double(:,1)) – (optional) The constant vector of affine conic constraints. Defaults to 0 if not provided.

  • domain (mosekdomain(:,1)) – (optional) List of constraint domains, objects created with mosekdomain.

  • solution_x (double(:,1)) – (optional) Initial x solution.

  • solution_y (double(:,1)) – (optional) Initial y solution.

  • conindexes (uint64(:,1)) – (optional) List of row indexes of F that define the actual constraints. This allows is to reuse the same F row in multiple constraints without repeating the row. Defaults to [1:size(F,1))]' if not provided.

Example:

model = mosekmodel(objsense = "minimize", ...
                   numvar = 4, ...
                   objective = [ 1 2 5 0 ]', ...
                   F = [ 1 0 1 0; ...
                         0 1 2 -1; ...
                         3 -1 1 0], ...
                   domain = [ mosekdomain("greater than", rhs = 2), ... 
                              mosekdomain("less than", rhs = [3 5]', dim = 2) ])

13.1.2 Adding data to the model

conindexes = mosekmodel.appendcons(F, g, domain, indexes, name)

Append a constraint block. A constraint block is a block of the form

\[Fx+g \in D_1\times\cdots\times D_n\]

Where each \(D_i\) is a domain created with mosekdomain. The affine expression is in most cases specified by passing F and/or g.

Return:

conindexes – Indices of constraint rows.

Parameters:

  • F (double(:,:)) – (optional) Matrix block of the appended constraints.

  • g (double(:,1)) – (optional) Constant term of the appended constraints. If both F and g are present then size(g,1)==size(F,1) must hold.

  • domain (mosekdomain(:,1)) – (required) Domain or list of domains.

  • indexes (uint64(:,1)) – (optional) Indexes of rows already existing in the model. Only allowed if neither F nor g are specified.

  • name (string) – (optional) Name of the constraint block.

Example:

model.appendcons(name = "sum", ...
                 F = [1 1 1 1], ...
                 domain = mosekdomain("==", rhs = 1.0))
model.appendcons(F = eye(4), g = [0 2 3 1], ...
                 domain = [ mosekdomain("rqcone", dim = 4) ])
mosekmodel.objective(objsense, objective, objfixterm)

Adds or replaces the objective in the model.

Parameters:

  • objsense (string) – (required) Objective sense: "min", "minimize", "max", "maximize".

  • objective (double(:,1)) – (required) The objective vector. It’s length must match the number of variables in the model.

  • objfixterm (double(:,1)) – (optional) Fixed term in the objective;

Example:

model.objective("minimize", [4 2 0 1]')
%model.objective("maximize", sparse([1], [2], [1.5], 1, 4), objfixterm = 10.0)
mosekmodel.setsolution(part, values)

Set an initial solution.

Parameters:

  • part (string) – (required) Indicates which part of the solution is requested. Must be either "x", indicating the primal variable values, or "y" indicating the dual constraint values.

  • values (double(:,1)) – (required) The vector of the initial solution.

Example:

model.setsolution("x", [1.0 1.0 2.0 3.0]')
varindexes = mosekmodel.appendvars(num, intvars)

Adds a number of new variables to the model.

Return:

varindexes (uint32(:,1)) – Indexes of the newly added variables.

Parameters:

  • num (uint32) – (required) Number of scalar variables to add.

  • intvars (uint32(:,1)) – (optional) List of indexes of integer variables. Index 1 refers to the first new variable.

Example:

model.appendvars(2)
model.appendvars(5, intvars = 1:5)
rowindexes = mosekmodel.appendrows(F, g)

This method is rarely needed. Appends a new block of rows to the problem’s affine expression storage. The new rows are initially not used in any constraints. They can later be used to create a conic or disjunctive constraint.

Return:

Indexes of newly added rows.

Parameters:

  • F (double(:,:)) – (optional) Matrix block of the appended rows.

  • g (double(:,1)) – (optional) Constant term of the appended rows. If both F and g are present then size(g,1)==size(F,1) must hold.

13.1.3 Domains

dom = mosekdomain(which, rhs, dim, n, alpha)

Defines a conic domain (including linear domains). The domain is a product \(D_1\times\cdots\times D_n\) of n identical domains, each of dimension dim and type which. By default \(n=1\).

Depending on the domain type which, some of the arguments alpha, dim must or must not appear, see the full specification below.

The argument rhs is an offset of the domain, ie. a vector \(b\) such that instead of \(D\) the domain is taken to be \(D+b\). For linear domains this corresponds to the right-hand side of the (in-)equality (for instance \(a^Tx=b\) instead of \(a^Tx=0\) for the domain rzero).

The possible values of which are (for corresponding domain definitions see Sec. 13.8 (Supported domains)):

  • "rminus", "less than", "lt", "nonpositive", "r-", "<=": Nonpositive values. Default dim=1 if not provided.

  • "rplus", "greater than", "gt", "nonnegative", "r+", ">=": Nonnegative values. Default dim=1 if not provided.

  • "r", "unbounded": Unbounded domain. Default dim=1 if not provided.

  • "zero", "equal", "eq", "fixed", "equals", "==": Equal to zero. Default dim=1 if not provided.

  • "qcone", "quadratic cone": Second order cone. dim is required and dim >= 2.

  • "rqcone", "rotated quadratic cone": Rotated second order cone. dim is required and dim >= 3.

  • "exp", "exponential cone", "dual exp": Exponential cone. Dimension is always exactly 3.

  • "dexp", "dual exponential cone": Dual exponential cone. Dimension is always exactly 3.

  • "pow", "power cone": The power cone. dim and alpha are required.

  • "dpow", "dual power cone", "dual pow": The dual power cone. dim and alpha are required.

  • "geomean", "geometric mean cone": Geometric mean cone. dim is required.

  • "dgeomean", "dual geometric mean cone", "dual geomean": Dual geometric mean cone. dim is required.

Parameters:

  • which (string) – (required) Defines the domain type.

  • rhs (double(:,1)) – (optional) Domain offset. Shifts the domain by this vector. The leght must equal the total dimension of the domain. See above.

  • dim (uint64) – (optional) Dimension of the domain. Defaults to 1 for linear domains, to 3 for exponential cones, and required for other domains. See above.

  • n (uint64) – (optional) Number of times the domain is repeated. Defaults to 1.

  • alpha (double(:,1)) – (only power cones) The additional vector generating the power cone exponents by normalizing. Its length is the number of variables on the left-hand side of the power cone definiton. If the length is 1, it will be interpreted as [alpha, 1.0-alpha].

Return:

dom (mosekdomain) – An object representing the defined domain.

Example:

dom = mosekdomain("greater than", rhs = 5)                    % >= 5                                                 (1 row in F)
dom = mosekdomain("equals", rhs = ones(10,1), dim = 10)       % >= 1, of dimension 10                                (10 rows in F)
dom = mosekdomain("qcone", dim = 5, n = 10)                   % 10 copies of a 5-dimensional quadratic cone          (50 rows in F)
dom = mosekdomain("exp", n = 10)                              % 10 copies of exponential cone                        (30 rows in F)
dom = mosekdomain("pow", alpha = [3 5 2]', dim = 5)           % x1^(3/10)*x2^(5/10)*x3^(2/10) >= sqrt(x4^2 + x5^2)   (5 rows in F)

13.1.4 Disjunctions

clause = mosekmodel.clause(F, g, domain, indexes)

A disjunctive constraint consists of a list of clauses. This method creates such a clause, being a conjunction of simple terms of the form \(F_ix+g_i\in D_i\), represented as a single affine block and a list of domains created with mosekdomain. The affine expressions, if given via F, g, are appended to the affine expression storage. The clauses created with this method can be used in mosekmodel.appenddisjunction.

The total dimension of all the domains must equal the number of rows in either F, g or indexes.

Parameters:

  • F (double(:,:)) – (optional) Matrix block of the clause.

  • g (double(:,1)) – (optional) Constant term of the clause. If both F and g are present then size(g,1)==size(F,1) must hold.

  • domain (mosekdomain(:,1)) – (required) A domain or an array of domains, each domain defines one simple term in the conjunction.

  • indexes (uint64(:,1)) – (optional) Indexes of rows already existing in the model. Only allowed if neither F nor g are specified.

Return:

c – Return a clause object representing a constraint block

mosekmodel.appenddisjunction(clauses)

Appends a disjunctive constraint which is a disjunction of the given clauses.

Parameters:

clauses (mosekterm(:,1)) – (required) List of clauses.

Example:

model.appenddisjunction( [ model.clause(F = [1 -2 0 0 ;
                                             0  0 1 0 ; 
                                             0  0 0 1], ...
                                        domain =[ mosekdomain("less than", rhs = [-1]), ...
                                                  mosekdomain("equal",     dim = 2, rhs = [0 0]') ]), ...

                           model.clause(F = [0 0 1 -3 ; 
                                             1 0 0  0 ; 
                                             0 1 0  0], ...
                                        domain = [ mosekdomain("less than", rhs = -2), ...
                                                   mosekdomain("equal", dim = 2, rhs = [0 0]') ]) ], ...
                        name = "disj")

13.1.5 Solving and obtaining the solution

mosekmodel.solve(write_to_file, logfile, nosolve, quiet, optserver, analyze, licfile, liccode, param)

Invokes the optimizer to solve the problem.

Parameters:

  • write_to_file (string) – (optional) Write the problem to this file before solving. The extension specifies the file format.

  • logfile (string) – (optional) Write log to this file.

  • nosolve (logical) – (optional) Format and load problem, but do not solve.

  • quiet (logical) – (optional) Do not print log.

  • optserver (string) – (optional) Host name for remote optimization.

  • licfile (string) – (optional) License file path. The same value must be used in all calls in the current process, otherwise the outcome is undefined.

  • liccode (char(1,:)) – (optional) License key as string. The same value must be used in all calls in the current process, otherwise the outcome is undefined.

  • analyze (logical) – (optional) Whether to run the problem analyzer after optimization.

  • param (string(1,:)) – (optional) Array of parameters in the form [name, value, name, value,...].

Example:

model.solve()
model.solve(quiet = true)
model.solve(quiet = true, param = ["MSK_DPAR_OPTIMIZER_MAX_TIME", "10.0"])
exists, prosta, solsta = mosekmodel.hassolution(which)

Check if the specified solution exists and return its statuses.

Return:

  • exists (logical) – Indicates if the solution is available.

  • prosta (string) – (optional) A string indicating the problem status for the requested solution, one of prosta. Only returned if exists is true.

  • solsta (string) – (optional) A string indicating the solution status for the requested solution, one of solsta. Only returned if exists is true.

Parameters:

which (string) – (required) Indicates which solution is requested. Must be one of the values "interior", "basic" or "integer".

Example:

[exists, prosta, solsta] = model.hassolution("interior")
exists = model.hassolution("integer")
value, prosta, solsta = mosekmodel.getsolution(which, part)

Return the requested solution values. Throws an error if the requested solution is not available; use mosekmodel.hassolution to check solution availability.

Return:

  • value (double(:,1)) – The solution values requested.

  • prosta (string) – A string indicating the problem status for the requested solution, one of prosta.

  • solsta (string) – A string indicating the solution status for the requested solution, one of solsta.

Parameters:

  • which (string) – (required) Indicates which solution is requested. Must be one of the values "interior", "basic" or "integer" to indicate a specific solution, or "any" to indicate any solution available. The latter will choose integer, basic and interior solutions in that order, whichever is first available.

  • part (string) – (required) Indicates which part of the solution is requested. Must be either "x", indicating the primal variable values, or "y" indicating the dual constraint values.

Example:

x = model.getsolution("any", "x")
[x, prosta, solsta] = model.getsolution("integer", "x")

13.1.6 Auxiliary functions

mosekmodel.write(filename, param)

Writes the current problem to a file.

Parameters:

  • filename (string) – (required) File name to write the problem to. The format is determined by the extension.

  • param (string(1,:)) – (optional) Array of parameters in the form [name, value, name, value,...].

Example:

model.write("dump.task.gz")
model.write("save.ptf", param = ["MSK_IPAR_PTF_WRITE_SOLUTIONS", "MSK_ON"])

13.1.7 Names

mosekmodel.varname(indexes, names)

Adds variable names to the model.

Parameters:

  • indexes (uint64(:,1)) – (required) Indexes of the variables to name.

  • names (string(:,1)) – (required) Names to assign.

Example:

model.varname(1:3, ["b", "tmp1", "tmp2"])