14.2.21 Class Model

mosek.fusion.Model

The object containing all data related to a single optimization model.

Implements:

BaseModel

Members:

Model.acceptedSolutionStatus – Set the accepted solution status.

Model.breakSolver – Request that the solver terminates as soon as possible.

Model.clone – Return a copy of the model.

Model.constraint – Create a new constraint in the model.

Model.dataReport – Print out a report about problem data.

Model.disjunction – Create a new disjunctive constraint in the model.

Model.dispose – Destroy the Model object

Model.dualObjValue – Get the dual objective value in the current solution.

Model.flushParameters – Flush all parameters to the underlying task.

Model.flushSolutions – If any solution values have been provided, flush those values to the underlying task.

Model.getAcceptedSolutionStatus – Get the accepted solution status.

Model.getConstraint – Get the constraint matching the given name or linear index.

Model.getDualSolutionStatus – Return the status of the dual solution.

Model.getName – Return the model name, or an empty string if it has not been set.

Model.getParameter – Get the parameter matching the given name.

Model.getPrimalSolutionStatus – Return the status of the primal solution.

Model.getProblemStatus – Return the status of the problem.

Model.getSolverDoubleInfo – Fetch a solution information item from the solver

Model.getSolverIntInfo – Fetch a solution information item from the solver

Model.getSolverLIntInfo – Fetch a solution information item from the solver

Model.getTask – Return the underlying MOSEK task object.

Model.getVariable – Get the variable matching the given name or linear index.

Model.hasConstraint – Check whether the model contains a constraint with a given name.

Model.hasParameter – Check whether the model contains a parameter with a given name.

Model.hasVariable – Check whether the model contains a variable with a given name.

Model.objective – Replace the objective expression.

Model.optserverHost – Specify an OptServer for remote calls.

Model.parameter – Create a new parameter in the model.

Model.primalObjValue – Get the primal objective value in the current solution.

Model.selectedSolution – Chooses a solution.

Model.setCallbackHandler – Attach a progress callback handler.

Model.setDataCallbackHandler – Attach a data callback handler.

Model.setLogHandler – Attach a log handler.

Model.setSolverParam – Set a solver parameter

Model.solve – Attempt to optimize the model.

Model.updateObjective – Update part of the objective.

Model.variable – Create a new variable in the model.

Model.writeTask – Dump the current solver task to a file.

Model.writeTaskStream – Write the current solver task to a stream.

Static members:

Model.getVersion – Return MOSEK version.

Model.putlicensecode – Set the license code in the global environment.

Model.putlicensepath – Set the license path in the global environment.

Model.putlicensewait – Set the license wait flag in the global environment.

Model.solveBatch – Attempt to optimize a collection of models in parallel.

Model.acceptedSolutionStatus

acceptedSolutionStatus(AccSolutionStatus what)

Set the accepted solution status. This defines which solution status values are considered as acceptable when fetching a solution. Requesting a solution value for a variable or constraint when the status does not match at least the accepted value will cause an error.

By default the accepted solution status is AccSolutionStatus.Optimal. It is necessary to change the accepted status to access sub-optimal solutions and infeasibility certificates.

The methods Model.getPrimalSolutionStatus and Model.getDualSolutionStatus can be used to get the actual status of the solutions.

Parameters:

what (AccSolutionStatus) – The new accepted solution status.

Model.breakSolver

breakSolver()

Request that the solver terminates as soon as possible. This must be called from another thread than the one in which solve() was called, or from a callback function.

The method does not stop the solver directly, rather it sets a flag that the solver checks occasionally, indicating it should terminate.

Model.clone

clone() -> Model

Return a copy of the model.

Return:

(Model)

Model.constraint

constraint(str name, Expression expr, PSDDomain psddom) -> Constraint
constraint(Expression expr, PSDDomain psddom) -> Constraint
constraint(str name, Expression expr, LinearDomain ldom) -> Constraint
constraint(Expression expr, LinearDomain ldom) -> Constraint
constraint(str name, Expression expr, RangeDomain rdom) -> RangedConstraint
constraint(Expression expr, RangeDomain rdom) -> RangedConstraint
constraint(str name, Expression expr, ConeDomain qdom) -> Constraint
constraint(Expression expr, ConeDomain qdom) -> Constraint

Adds a new constraint to the model. A constraint is always a statement that an expression or variable belongs to a domain. Constraints can have optional names.

Typical domains used for defining constraints include:

• Domain.lessThan, Domain.greaterThan, Domain.inRange, Domain.equalsTo — puts linear bounds \(E\leq u\), \(l\leq E\), \(l\leq E\leq u\) or \(E=c\) on an expresion \(E\).

• Domain.inQCone, Domain.inRotatedQCone — constrains a vector or matrix expression \(E\) to a second-order cone.

• Domain.inPExpCone, Domain.inPPowerCone — constrains a vector or matrix expression \(E\) to an exponential or power cone.

• Domain.inPSDCone — constrains a square matrix expression \(E\) to be positive semidefinite.

See Domain for a full list of domains.

Parameters:

• name (str) – Name of the constraint. This must be unique among all constraints in the model. The value None is allowed instead of a unique name.

• expr (Expression) – An expression.

• psddom (PSDDomain) – A positive semidefinte domain.

• ldom (LinearDomain) – A linear domain.

• rdom (RangeDomain) – A ranged domain.

• qdom (ConeDomain) – A domain in a cone.

Return:

• (Constraint)

• (RangedConstraint)

Model.dataReport

dataReport(int detail)
dataReport()

Prints out a text report about the dimensions and numerical properties of the problem data. The report is printed to the currently attached log stream. The report is generated for the internal low-level optimizer task as a rough guidance for the user; some care may be needed to relate it correctly to the Fusion model.

Parameters:

detail (int) – The amount of detail to include, where 0 means nothing and 10 is full. If not provided then a full report is printed.

Model.disjunction

disjunction(str name, Term t1) -> Disjunction
disjunction(str name, Term t1, Term t2) -> Disjunction
disjunction(str name, Term t1, Term t2, Term t3) -> Disjunction
disjunction(Term t1) -> Disjunction
disjunction(Term t1, Term t2) -> Disjunction
disjunction(Term t1, Term t2, Term t3) -> Disjunction
disjunction(Term[] terms) -> Disjunction
disjunction(str name, Term[] terms) -> Disjunction

Adds a new disjunctive constraint to the model. A disjunctive constraint with terms \(T_1,\ldots,T_n\) is:

\[T_1 \ \mathrm{OR}\ \cdots\ \mathrm{OR}\ T_n.\]

Each term \(T_i\) of a disjunctive constraint is a Term, which can be created with DJC.term or with DJC.AND.

Parameters:

• name (str) – The name of this disjunctive constraint.

• t1 (Term) – A term in the disjunction.

• t2 (Term) – A term in the disjunction.

• t3 (Term) – A term in the disjunction.

• terms (Term[]) – A list of terms forming the disjunctive constraint.

Return:

(Disjunction)

Model.dispose

dispose()

Destroy the Model object. This removes all references to other objects from the Model.

This helps garbage collection by removing cyclic references, and in some cases it is necessary to ensure that the garbage collector can collect the Model object and assosiated objects.

Model.dualObjValue

dualObjValue() -> float

Get the dual objective value in the current solution.

Return:

(float)

Model.flushParameters

flushParameters()

Flush all parameters to the underlying task.

Model.flushSolutions

flushSolutions()

If any solution values have been provided, flush those values to the underlying task.

Model.getAcceptedSolutionStatus

getAcceptedSolutionStatus() -> AccSolutionStatus

Get the accepted solution status.

Return:

(AccSolutionStatus)

Model.getConstraint

getConstraint(str name) -> Constraint
getConstraint(int index) -> Constraint

Get the constraint matching the given name or linear index. Constraints are assigned indices in the order they are added to the model.

Parameters:

• name (str) – The constraint’s name.

• index (int) – The constraint’s linear index.

Return:

(Constraint)

Model.getDualSolutionStatus

getDualSolutionStatus(SolutionType which) -> SolutionStatus
getDualSolutionStatus() -> SolutionStatus

Return the status of the dual solution. If no solution type is given the solution set with Model.selectedSolution is checked. It is recommended to check the problem and solution status before accessing the solution values.

Parameters:

which (SolutionType) – The type of the solution for which status is requested.

Return:

(SolutionStatus)

Model.getName

getName() -> str

Return the model name, or an empty string if it has not been set.

Return:

(str)

Model.getParameter

getParameter(str name) -> Parameter

Get the parameter matching the given name.

Parameters:

name (str) – The parameter’s name.

Return:

(Parameter)

Model.getPrimalSolutionStatus

getPrimalSolutionStatus(SolutionType which) -> SolutionStatus
getPrimalSolutionStatus() -> SolutionStatus

Return the status of the primal solution. If no solution type is given the solution set with Model.selectedSolution is checked. It is recommended to check the problem and solution status before accessing the solution values.

Parameters:

which (SolutionType) – The type of the solution for which status is requested.

Return:

(SolutionStatus)

Model.getProblemStatus

getProblemStatus(SolutionType which) -> ProblemStatus
getProblemStatus() -> ProblemStatus

Return the status of the problem. If no solution type is given the solution set with Model.selectedSolution is checked. It is recommended to check the problem and solution status before accessing the solution values.

Parameters:

which (SolutionType) – The type of the solution.

Return:

(ProblemStatus)

Model.getSolverDoubleInfo

getSolverDoubleInfo(str name) -> float

This method returns the value for the specified double solver information item. The information items become available during and after the solver execution. A runtime exception is thrown if a non-existing information item is requested. The double information items are listed in Section Double information items.

Parameters:

name (str) – A string name of the information item.

Return:

(float)

Model.getSolverIntInfo

getSolverIntInfo(str name) -> int

This method returns the value for the specified integer solver information item. The information items become available during and after the solver execution. A runtime exception is thrown if a non-existing information item is requested. The integer information items are listed in Section Integer information items..

Parameters:

name (str) – A string name of the information item.

Return:

(int)

Model.getSolverLIntInfo

getSolverLIntInfo(str name) -> int

This method returns the value for the specified long solver information item. The information items become available during and after the solver execution. A runtime exception is thrown if a non-existing information item is requested. The long integer information items are listed in Section Long integer information items..

Parameters:

name (str) – A string name of the information item.

Return:

(int)

Model.getTask

getTask() -> mosek.Task

Returns the underlying MOSEK Task object. Note that the returned object is the actual underlying object, not a copy. This means if the returned object is modified by the user, the Model object may become invalid. Accessing the task object should never be necessary, except maybe for advanced debugging. For details on the Task object see the Optimizer API documentation.

Return:

(Task)

Model.getVariable

getVariable(str name) -> Variable
getVariable(int index) -> Variable

Get the variable matching the given name or linear index. Variables are assigned indices in the order they are added to the model.

Parameters:

• name (str) – The variable’s name.

• index (int) – The variable’s linear index.

Return:

(Variable)

Model.getVersion

Model.getVersion() -> str

Returns the MOSEK version as a string, for example “10.1.28”.

Return:

(str)

Model.hasConstraint

hasConstraint(str name) -> bool

Check whether the model contains a constraint with a given name.

Parameters:

name (str) – The constraint name.

Return:

(bool)

Model.hasParameter

hasParameter(str name) -> bool

Check whether the model contains a parameter with a given name.

Parameters:

name (str) – The parameter’s name.

Return:

(bool)

Model.hasVariable

hasVariable(str name) -> bool

Check whether the model contains a variable with a given name.

Parameters:

name (str) – The variable name.

Return:

(bool)

Model.objective

objective(str name, ObjectiveSense sense, Expression expr)
objective(str name, ObjectiveSense sense, float c)
objective(str name, float c)
objective(ObjectiveSense sense, Expression expr)
objective(ObjectiveSense sense, float c)
objective(float c)

Replace the objective expression. This method must be called at least once before the first Model.solve.

Parameters:

• name (str) – Name of the objective. This may be any string, and it has no function except when writing the problem to an external file format.

• sense (ObjectiveSense) – The objective sense. Defines whether the objective must be minimized or maximized.

• expr (Expression) – The objective expression. This must be an affine expression that evaluates to a scalar.

• c (float) – A constant scalar.

Model.optserverHost

optserverHost(str addr)

Specify an OptServer URL for remote calls. The URL should contain protocol, host and port in the form http://server:port or https://server:port. If the URL is set using this function, all subsequent calls to Model.solve will be sent to the specified OptServer instead of being executed locally. Passing NULL deactivates this redirection.

Parameters:

addr (str) – Address of the OptServer. It should be a valid URL, for example http://server:port or https://server:port.

Model.parameter

parameter(int[] shape, int[][] sparsity) -> Parameter
parameter(int[] shape, int[] sp) -> Parameter
parameter(int[] shape) -> Parameter
parameter(int d1) -> Parameter
parameter(int d1, int d2) -> Parameter
parameter(int d1, int d2, int d3) -> Parameter
parameter() -> Parameter
parameter(str name, int[] shape, int[][] sparsity) -> Parameter
parameter(str name, int[] shape, int[] sp) -> Parameter
parameter(str name, int[] shape) -> Parameter
parameter(str name, int d1) -> Parameter
parameter(str name, int d1, int d2) -> Parameter
parameter(str name, int d1, int d2, int d3) -> Parameter
parameter(str name) -> Parameter

Create a new parameter in the model. A parameter is a placeholder for a constant (scalar or array) value that can be assigned and reset after the model is built and between optimizations.

If the shape is not provided, the parameter is a scalar parameter. The default value of a newly created parameter is 0. To set the value use Parameter.setValue.

Parameters:

• shape (int[]) – Shape of the parameter.

• sparsity (int[][]) – Non-zero sparsity pattern, if the parameter is sparse.

• sp (int[]) – Non-zero sparsity pattern as a list of linear indexes, if the parameter is sparse.

• d1 (int) – First dimension of a parameter.

• d2 (int) – Second dimension of a parameter.

• d3 (int) – Third dimension of a parameter.

• name (str) – Name of the parameter.

Return:

(Parameter)

Model.primalObjValue

primalObjValue() -> float

Get the primal objective value in the current solution.

Return:

(float)

Model.putlicensecode

Model.putlicensecode(int[] code)

Set the license code in the global environment. This function has an effect only before the first optimization in the current process.

Parameters:

code (int[])

Model.putlicensepath

Model.putlicensepath(str licfile)

Set the license path in the global environment. This function has an effect only before the first optimization in the current process.

Parameters:

licfile (str)

Model.putlicensewait

Model.putlicensewait(bool wait)

Set the license wait flag in the global environment. If set, MOSEK will wait until a license becomes available.

Parameters:

wait (bool)

Model.selectedSolution

selectedSolution(SolutionType soltype)

Chooses a solution. The values of variables and constraints will be read from the chosen solution. The default is to consider all solution types in the order of SolutionType.Default.

Parameters:

soltype (SolutionType) – The solution type to select as default.

Model.setCallbackHandler

setCallbackHandler(System.CallbackHandler h)

Attach a progress callback handler. During optimization this handler will be called, providing a code with the current state of the solver. Passing None detaches the current handler. See Section Progress and data callback for details and examples and the Optimizer API for information about callback codes.

The progress callback handler is a function of type (mosek.callback) -> int.

Parameters:

h (CallbackHandler) – The callback handler or None.

Model.setDataCallbackHandler

setDataCallbackHandler(System.DataCallbackHandler h)

Attach a data callback handler. During optimization this handler will be called, providing various information about the current state of the solution and solver. Passing None detaches the current handler. See Section Progress and data callback for details and examples and the Optimizer API for information about callback codes.

The data callback handler is a function of type (mosek.callback, double[], int[], long[]) -> int.

Parameters:

h (DataCallbackHandler) – The callback handler or None.

Model.setLogHandler

setLogHandler(System.StreamWriter h)

Attach a log handler. The solver log information will be sent to the stream handler. Passing None detaches the current handler.

The log handler is an object providing methods write(str) and flush(), for example

M.setLogHandler(sys.stdout)

Parameters:

h (StreamWriter) – The log handler object or None.

Model.setSolverParam

setSolverParam(str name, str strval)
setSolverParam(str name, int intval)
setSolverParam(str name, float floatval)

Set a solver parameter. Solver parameter values can be either symbolic values, integers or doubles, depending on the parameter. The value is automatically converted to a suitable type whenever possible. If this fails, an exception will be thrown. For example, if the parameter accepts a double value and is given a string, the string will be parsed to produce a double.

See Section Parameters (alphabetical list sorted by type) for a listing of all parameter settings.

Parameters:

• name (str) – Name of the parameter to set

• strval (str) – A string value to assign to the parameter.

• intval (int) – An integer value to assign to the parameter.

• floatval (float) – A floating point value to assign to the parameter.

Model.solve

solve()
solve(str addr, str accesstoken)

This calls the MOSEK solver to solve the problem defined in the model.

If no error occurs, on exit a solution status will be defined for the primal and the dual solutions. These can be obtained with Model.getPrimalSolutionStatus and Model.getDualSolutionStatus. Depending on the solution status, various values may be defined:

• If the model is primal-dual feasible, or nearly so, and the solver found a solution, the solution values can be accessed through the Variable and Constraint objects in the model. For integer problems only the primal solution is defined, while for continuous problems both primal and dual solutions are available.

• If the model is primal or dual infeasible, only the primal or the dual solution is defined, depending on the solution status. The available solution contains a certificate of infeasibility.

• If the status is unknown the solver ran into problems and did not find anything useful. In this case the solution values may be garbage.

The solution can be obtained with Model.primalObjValue and Variable.level and their dual analogues.

By default, trying to fetch a non-optimal solution using Variable.level or Variable.dual will cause an exception. To fetch infeasibility certificates or other less optimal solutions it is necessary to change the accepted solution flag with Model.acceptedSolutionStatus.

Parameters:

• addr (str) – Address of the OptServer if optimizing remotely. It should be a valid URL, for example http://server:port or https://server:port.

• accesstoken (str) – Access token if optimizing remotely with authentication.

Model.solveBatch

Model.solveBatch(bool israce, float maxtime, int numthreads, Model[] models) -> SolverStatus[]

Calls the MOSEK solver to solve all the provided models in parallel. All callbacks and log output streams are disabled.

Assuming that each model takes about same time and there many more models than threads then a linear speedup can be achieved, also known as strong scaling. A typical application of this method is to solve many small models of similar type; in this case it is recommended that each of them is allocated a single thread by setting numThreads to \(1\).

If the parameters israce or maxtime are used, then the result may not be deterministic, in the sense that the models which complete first may vary between runs.

The remaining behavior is the same as if each model was solved separately with Model.solve. The return array describes if each model solved, failed or wasn’t attempted because another one finished first (if israce is used). Debugging a failed model can be done by solving it individually.

This method parallelizes the call to the numerical solver; additional operations such as postprocessing the optimizer solution into the solution of the Fusion model are still performed sequentially.

Parameters:

• israce (bool) – If true, then the function is terminated after the first model completed.

• maxtime (float) – Time limit: if nonnegative, then the function is terminated after this time (seconds).

• numthreads (int) – The number of threads for the whole pool available to all models. If set to 0 the number of threads used will be equal to the number of cores detected on the machine.

• models (Model[]) – An array of models to be solved.

Return:

(SolverStatus[])

Model.updateObjective

updateObjective(Expression expr, Variable x)

Update the columns in the objective expression defined by x.

Parameters:

• expr (Expression) – The expression to update with. This must have size 1.

• x (Variable) – The columns to replace.

Model.variable

variable(str name) -> Variable
variable(str name, int size) -> Variable
variable(str name, int size, LinearDomain ldom) -> Variable
variable(str name, int size, RangeDomain rdom) -> RangedVariable
variable(str name, int size, ConeDomain qdom) -> Variable
variable(str name, int[] shp) -> Variable
variable(str name, int[] shp, LinearDomain ldom) -> Variable
variable(str name, int[] shp, RangeDomain rdom) -> RangedVariable
variable(str name, int[] shp, ConeDomain qdom) -> Variable
variable(str name, LinearDomain ldom) -> Variable
variable(str name, RangeDomain rdom) -> RangedVariable
variable(str name, ConeDomain qdom) -> Variable
variable() -> Variable
variable(int size) -> Variable
variable(int size, LinearDomain ldom) -> Variable
variable(int size, RangeDomain rdom) -> RangedVariable
variable(int size, ConeDomain qdom) -> Variable
variable(int[] shp) -> Variable
variable(int[] shp, LinearDomain ldom) -> Variable
variable(int[] shp, RangeDomain rdom) -> RangedVariable
variable(int[] shp, ConeDomain qdom) -> Variable
variable(LinearDomain ldom) -> Variable
variable(RangeDomain rdom) -> RangedVariable
variable(ConeDomain qdom) -> Variable
variable(str name, int[] shp, PSDDomain psddom) -> Variable
variable(str name, int n, PSDDomain psddom) -> Variable
variable(str name, int n, int m, PSDDomain psddom) -> Variable
variable(str name, PSDDomain psddom) -> Variable
variable(int n, PSDDomain psddom) -> Variable
variable(int n, int m, PSDDomain psddom) -> Variable
variable(PSDDomain psddom) -> Variable

Create a new variable in the model. All variables must be created using this method. The many versions of the method accept a name (optional), the shape of the variable and its domain. The domain must be suitable for the given variable shape. If the domain is not provided, it is assumed that the variable is unbounded. If the dimension is not provided the variable is a single scalar variable.

Typical domains used for creating variables include:

• Domain.lessThan, Domain.greaterThan, Domain.inRange — creates a variable \(x\) with bounds \(x\leq u\), \(l\leq x\) or \(l\leq x\leq u\).

• Domain.inPSDCone — creates a symmetric positive definite variable of dimension \(n\).

Parameters:

• name (str) – Name of the variable. This must be unique among all variables in the model. The value None is allowed instead of a unique name.

• size (int) – Size of the variable. The variable becomes a one-dimensional vector of the given size.

• ldom (LinearDomain) – A linear domain for the variable.

• rdom (RangeDomain) – A ranged domain for the variable.

• qdom (ConeDomain) – A conic domain for the variable.

• shp (int[]) – Defines the shape of the variable.

• psddom (PSDDomain) – A semidefinte domain for the variable.

• n (int) – Dimension of the semidefinite variable.

• m (int) – Number of semidefinite variables.

Return:

• (Variable)

• (RangedVariable)

Model.writeTask

writeTask(str filename)

Dump the current solver task to a file. The file extension determines the file format, see Section Supported File Formats for details. The file can be read with the command line MOSEK or with the Optimizer API for debugging purposes.

Parameters:

filename (str) – Name of the output file.

Model.writeTaskStream

writeTaskStream(str ext, System.DataStream stream)

Write the current solver task to a stream object. The extension determines the file format, see Section Supported File Formats, and it should be a string such as "ptf", "task.gz", etc. that would be used for file extension in Model.writeTask.

stream must have a write method accepting a byte-like object, for example

    M.writeTaskStream("jtask", sys.stdout.buffer);

    with open("dump.ptf", "wb") as f:
        M.writeTaskStream("ptf", f)

Parameters:

• ext (str) – Extension, which determines the file format.

• stream (DataStream) – The output stream.