Solvers

buildOptProblemFromModel(model, verify, param)[source]

Builds an COBRA Toolbox LP,QP,RLP,or RQP problem structure from a COBRA Toolbox model structure.

LP - linear optimisation

\[ \begin{align}\begin{aligned}\begin{split} max/min ~& c^T x + 0.5 x^T F x \\ s.t. ~& [S, E; C, D] x <=> b ~~~~~~~~~~~:y \\ ~& lb \leq x \leq ub~~~~:w\end{split}\\QRLP - quadratically regularised LP\end{aligned}\end{align} \]
\[ \begin{align}\begin{aligned}\begin{split} max/min ~& c^T x + 0.5 x^T F x \\ s.t. ~& [S, E; C, D] x + r <=> b ~~~~~~~~~~~:y \\ ~& lb \leq x + u \leq ub~~~~:w\end{split}\\QP - quadratic optimisation\end{aligned}\end{align} \]
\[ \begin{align}\begin{aligned}\begin{split} max/min ~& c^T x + 0.5 x^T F x \\ s.t. ~& [S, E; C, D] x <=> b ~~~~~~~~~~~:y \\ ~& lb \leq x \leq ub~~~~:w\end{split}\\QRLP - quadratically regularised QP\end{aligned}\end{align} \]
\[ \begin{align}\begin{aligned}\begin{split} max/min ~& c^T x + 0.5 x^T F x \\ s.t. ~& [S, E; C, D] x + r <=> b ~~~~~~~~~~~:y \\ ~& lb \leq x + u \leq ub~~~~:w\end{split}\\USAGE:\\ optProblem = buildoptProblemFromModel(model,verify)\\INPUT: model: A COBRA model structure with at least the following fields\\ * `.S` - The stoichiometric matrix * `.c` - Objective coeff vector * `.lb` - Lower bound vector * `.ub` - Upper bound vector\\OPTIONAL INPUTS: model: The model structure can also have these additional fields:\\ * `.b`: accumulation/depletion vector (default 0 for each metabolite). * `.osense`: Objective sense (-1 means maximise (default), 1 means minimise) * `.csense`: a string with the constraint sense for each row in A ('E', equality(default), 'G' greater than, 'L' less than). * `.C`: the Constraint matrix; * `.d`: the right hand side vector for C; * `.dsense`: the constraint sense vector; * `.E`: the additional Variable Matrix * `.evarub`: the upper bounds of the variables from E; * `.evarlb`: the lower bounds of the variables from E; * `.evarc`: the objective coefficients of the variables from E; * `.D`: The matrix coupling additional Constraints (form C), with additional Variables (from E); A QPproblem structure will also have the following field: * `.F`: Quadratic part of objective (F*osense must be positive semidefinite, for all solvers except Gurobi)\\ verify: Check the input (default: true);\\OUTPUT: optProblem: A COBRA optProblem structure with the following fields:\\ * `.A`: LHS matrix * `.b`: RHS vector * `.c`: Objective coeff vector * `.lb`: Lower bound vector * `.ub`: Upper bound vector * `.osense`: Objective sense (`-1`: maximise (default); `1`: minimise) * `.csense`: string with the constraint sense for each row in A ('E', equality, 'G' greater than, 'L' less than). * `.F`: Positive semidefinite matrix for quadratic part of objective OPTIONAL OUTPUT:\end{aligned}\end{align} \]
isCompatible(solverName, printLevel, specificSolverVersion)[source]

determine the compatibility status of a solver based on the file compatMatrix.rst stored here cobratoolbox/docs/source/installation/compatMatrix.rst

clear isCompatible when the compatMatrix has been changed as the data from compatMatrix is stored in a persistent variable

USAGE

compatibleStatus = isCompatible (solverName, printLevel, specificSolverVersion)

INPUT

  • solverName – Name of the solver

  • printLevel – verbose level (default: 0)

  • specificSolverVersion – string with specific solver version (example: ‘12.7.1’ or ‘6.5.1’)

OUTPUT

compatibleStatus – compatibility status

  • 0: not compatible with the COBRA Toolbox (tested)

  • 1: compatible with the COBRA Toolbox (tested)

  • 2: unverified compatibility with the COBRA Toolbox (not tested)

optimizeTwoCbModels(model1, model2, osenseStr, minFluxFlag, verbFlag)[source]

Simultaneously solve two flux balance problems and minimize the difference between the two solutions

USAGE

[solution1, solution2, totalFluxDiff] = optimizeTwoCbModels (model1, model2, osenseStr, minFluxFlag, verbFlag)

INPUTS

  • model1 – The first COBRA model

  • model2 – The second COBRA model, where both models have mandatory fields:

    • S - Stoichiometric matrix

    • b - Right hand side = 0

    • c - Objective coefficients

    • lb - Lower bounds

    • ub - Upper bounds

OPTIONAL INPUTS

  • osenseStr – Maximize (‘max’)/minimize (‘min’) (Default = ‘max’)

  • minFluxFlag – Minimize the absolute value of fluxes in the optimal MOMA solution (Default = false)

  • verbFlag – Verbose output (Default = false)

OUTPUTS

  • solution1 – Solution for the 1st model

  • solution2 – Solution for the 2nd model

  • totalFluxDiff – 1-norm of the difference between the flux vectors sum|v1-v2|

Example

solution

f Objective value x Primal (flux vector)

First solves two separate FBA problems:

f1 = max/min c1’v1 subject to S1*v1 = b1

lb1 <= v1 <= ub1

f2 = max/min c2’v2 subject to S2*v2 = b2

lb2 <= v2 <= ub2

Then solves the following LP to obtain the two flux vectors with the smallest possible 1-norm difference between them

min |v1-v2|
s.t. S1*v1 = b1

c1’v1 = f1 lb1 <= v1 <= ub1 S2*v2 = b2 c2’v2 = f2 lb2 <= v2 <= ub2

Finally optionally minimizes the 1-norm of the flux vectors

solveCobraLP(LPproblem, varargin)[source]

Solves constraint-based LP problems

USAGE

solveCobraLP (LPproblem, varargin)

INPUT

LPproblem – Structure containing the following fields describing the LP problem to be solved

  • .A - m x n linear constraint matrix

  • .b - m x 1 right hand sider vector for constraint A*x = b

  • .c - n x 1 linear objective coefficient vector

  • .lb - n x 1 lower bound vector for lb <= x

  • .ub - n x 1 upper bound vector for x <= ub

  • .osense - scalar objective sense (-1 means maximise (default), 1 means minimise)

  • .csense - m x 1 character array of constraint senses, one for each row in A

    must be either (‘E’, equality, ‘G’ greater than, ‘L’ less than).

OPTIONAL INPUTS

  • varargin – Additional parameters either as parameter struct, or as parameter/value pairs. A combination is possible, if the parameter struct is either at the beginning or the end of the optional input. All fields of the struct which are not COBRA parameters (see getCobraSolverParamsOptionsForType) for this problem type will be passed on to the solver in a solver specific manner. Some optional parameters which can be passed to the function as parameter value pairs, or as part of the options struct are listed below:

  • printLevel – Printing level

    • 0 - Silent (Default)

    • 1 - Warnings and Errors

    • 2 - Summary information

    • 3 - More detailed information

    • > 10 - Pause statements, and maximal printing (debug mode)

  • saveInput – Saves LPproblem to filename specified in field. i.e. parameters.saveInput = ‘LPproblem.mat’;

  • minNorm – {(0), scalar , n x 1 vector}, where [m, n] = size(S); If not zero then, minimise the Euclidean length of the solution to the LP problem. minNorm ~1e-6 should be high enough for regularisation yet maintain the same value for the linear part of the objective. However, this should be checked on a case by case basis, by optimization with and without regularisation.

  • primalOnly – {(0), 1}; 1 = only return the primal vector (lindo solvers)

  • solverParams – solver-specific parameter structure with field names that match exactly those in that solvers matlab interface.

OUTPUT

solution – Structure containing the following fields describing a LP solution: * .full: Full LP solution vector * .obj: Objective value * .rcost: Reduced costs, dual solution to \(lb <= v <= ub\) * .dual: dual solution to A*v (‘E’ | ‘G’ | ‘L’) b * .solver: Solver used to solve LP problem * .lpmethod: Algorithm used by solver to solve LP problem * .stat: Solver status in standardized form

  • 0 - Infeasible problem

  • 1 - Optimal solution

  • 2 - Unbounded solution

  • 3 - Almost optimal solution

  • -1 - Some other problem (timelimit, numerical problem etc)

  • .origStat: Original status returned by the specific solver

  • .origStatText: Original status text returned by the specific solver

  • .time: Solve time in seconds

  • .basis: (optional) LP basis corresponding to solution

Note

Optional parameters can also be set through the solver can be set through changeCobraSolver(‘LP’, value); changeCobraSolverParams(‘LP’, ‘parameter’, value) function. This includes the minNorm and the printLevel flags.

Example

%Optional parameters can be entered in three different ways {A,B,C}

%A) as a problem specific parameter followed by parameter value: [solution] = solveCobraLP(LP, ‘printLevel’, 1); [solution] = solveCobraLP(LP, ‘printLevel’, 1, ‘feasTol’, 1e-8);

%B) as a parameters structure with field names specific to a specific solver [solution] = solveCobraLP(LPCoupled, parameters);

%C) as parameter followed by parameter value, with a parameter structure %with field names specific to a particular solvers internal parameter, %fields as the LAST argument [solution] = solveCobraLP(LPCoupled, ‘printLevel’, 1, ‘feasTol’, 1e-6, parameters);

solveCobraMILP(MILPproblem, varargin)[source]

Solves constraint-based MILP problems The solver is defined in the CBT_MILP_SOLVER global variable (set using changeCobraSolver). Solvers currently available are ‘tomlab_cplex’ and ‘glpk’

USAGE

solution = solveCobraMILP (MILPproblem, parameters)

INPUT

MILPproblem – Structure containing the following fields describing the LP problem to be solved

  • .A - LHS matrix

  • .b - RHS vector

  • .c - Objective coeff vector

  • .lb - Lower bound vector

  • .ub - Upper bound vector

  • .osense - Objective sense (-1 max, +1 min)

  • .csense - Constraint senses, a string containting the constraint sense for each row in A (‘E’, equality, ‘G’ greater than, ‘L’ less than).

  • .vartype - Variable types (‘C’ continuous, ‘I’ integer, ‘B’ binary)

  • .x0 - Initial solution

Optional parameters can be entered using parameters structure or as parameter followed by parameter value: i.e. ,’printLevel’, 3) Setting parameters = ‘default’ uses default setting set in getCobraSolverParameters.

OPTIONAL INPUTS

  • varargin – Additional parameters either as parameter struct, or as parameter/value pairs. A combination is possible, if the parameter struct is either at the beginning or the end of the optional input. All fields of the struct which are not COBRA parameters (see getCobraSolverParamsOptionsForType) for this problem type will be passed on to the solver in a solver specific manner. Some optional parameters which can be passed to the function as parameter value pairs, or as part of the options struct are listed below:

  • timeLimit – Global solver time limit

  • intTol – Integrality tolerance

  • relMipGapTol – Relative MIP gap tolerance

  • logFile – Log file (for CPLEX)

  • printLevel – Printing level

    • 0 - Silent (Default)

    • 1 - Warnings and Errors

    • 2 - Summary information

    • 3 - More detailed information

    • > 10 - Pause statements, and maximal printing (debug mode)

  • saveInput – Saves LPproblem to filename specified in field. i.e. parameters.saveInput = ‘LPproblem.mat’;

OUTPUT

solution – Structure containing the following fields describing a MILP solution

  • .cont: Continuous solution

  • .int: Integer solution

  • .full: Full MILP solution vector

  • .obj: Objective value

  • .solver: Solver used to solve MILP problem

  • .stat: Solver status in standardized form (see below)

    • 1 - Optimal solution found

    • 2 - Unbounded solution

    • 0 - Infeasible MILP

    • -1 - No integer solution exists

    • 3 - Other problem (time limit etc, but integer solution exists)

  • .origStat: Original status returned by the specific solver

  • .time: Solve time in seconds

solveCobraMIQP(MIQPproblem, varargin)[source]

Solves constraint-based QP problems The solver defined in the CBT_MIQP_SOLVER global variable (set using changeCobraSolver). Solvers currently available are ‘tomlab_cplex’

USAGE

solution = solveCobraMIQP (MIQPproblem, varargin)

Solves problems of the type \(min osense * 0.5 x' * F * x + osense * c' * x\) s/t. \(lb <= x <= ub\) \(A * x <=/=/>= b\) xi = integer

INPUT

MIQPproblem – Structure containing the following fields describing the MIQP problem to be solved

  • .A - LHS matrix

  • .b - RHS vector

  • .F - F matrix for quadratic objective (see above)

  • .c - Objective coeff vector

  • .lb - Lower bound vector

  • .ub - Upper bound vector

  • .osense - Objective sense (-1 max, +1 min)

  • .csense - Constraint senses, a string containting the constraint sense for each row in A (‘E’, equality, ‘G’ greater than, ‘L’ less than).

Optional parameters can be entered using parameters structure or as parameter followed by parameter value: i.e. ,’printLevel’, 3) Setting parameters = ‘default’ uses default setting set in getCobraSolverParameters.

OPTIONAL INPUTS

  • varargin – Additional parameters either as parameter struct, or as parameter/value pairs. A combination is possible, if the parameter struct is either at the beginning or the end of the optional input. All fields of the struct which are not COBRA parameters (see getCobraSolverParamsOptionsForType) for this problem type will be passed on to the solver in a solver specific manner. Some optional parameters which can be passed to the function as parameter value pairs, or as part of the options struct are listed below:

  • printLevel – Print level for solver

  • saveInput – Saves LPproblem to filename specified in field.

OUTPUT

solution – Structure containing the following fields describing a MIQP solution

  • .full: Full MIQP solution vector

  • .obj: Objective value

  • .solver: Solver used to solve MIQP problem

  • .stat: Solver status in standardized form (see below)

    • 1 - Optimal solution found

    • 2 - Unbounded solution

    • 0 - Infeasible MIQP

    • -1 - No optimal solution found (time limit etc)

    • 3 - Solution exists but with problems

  • .origStat: Original status returned by the specific solver

  • .time: Solve time in seconds

solveCobraQP(QPproblem, varargin)[source]

Solves constraint-based QP problems

The solver is defined in the CBT_MILP_SOLVER global variable (set using changeCobraSolver). Solvers currently available are ‘tomlab_cplex’, ‘mosek’ and ‘qpng’ (limited support for small problems)

Solves problems of the type \(min/max osense * c' * x + 0.5 x' * F * x\) s/t \(lb <= x <= ub\) \(A * x <=/=/>= b\)

If minimising, then F must be positive semi-definite i.e. chol(F) does not return an error. If maximising, then chol(-F) must not return an error.

USAGE

solution = solveCobraQP (QPproblem, varargin)

INPUT

QPproblem – Structure containing the following fields describing the QP

  • .A - LHS matrix

  • .b - RHS vector

  • .F - positive semidefinite matrix for quadratic part of objective (see above)

  • .c - Objective coeff vector

  • .lb - Lower bound vector

  • .ub - Upper bound vector

  • .osense - linear objective sense (-1 max, +1 min),

    it is assumed that the quadratic part is minimised and the F matrix is positive semi-definite

  • .csense - Constraint senses, a string containing the constraint sense for each row in A (‘E’, equality, ‘G’ greater than, ‘L’ less than).

Optional parameters can be entered using parameters structure or as parameter followed by parameter value: i.e. ,’printLevel’, 3) Setting parameters = ‘default’ uses default setting set in getCobraSolverParameters.

OPTIONAL INPUTS

  • varargin – Additional parameters either as parameter struct, or as parameter/value pairs. A combination is possible, if the parameter struct is either at the beginning or the end of the optional input. All fields of the struct which are not COBRA parameters (see getCobraSolverParamsOptionsForType) for this problem type will be passed on to the solver in a solver specific manner. Some optional parameters which can be passed to the function as parameter value pairs, or as part of the options struct are listed below:

  • printLevel – Print level for solver

  • saveInput – Saves LPproblem to filename specified in field.

OUTPUT

solution – Structure containing the following fields describing a QP solution

  • .full: Full QP solution vector

  • .rcost: Reduced costs, dual solution to \(lb <= x <= ub\)

  • .dual: dual solution to \(A*x <=/=/>= b\)

  • .slack: slack variable such that \(A*x + s = b\)

  • .obj: Objective value

  • .solver: Solver used to solve QP problem

  • .qpmethod: Solver qpmethod used to solve QP problem

  • .origStat: Original status returned by the specific solver

  • .time: Solve time in seconds

  • .stat: Solver status in standardized form (see below)

  • 0 - Infeasible problem

  • 1 - Optimal solution

  • 2 - Unbounded solution

  • 3 - Almost optimal solution

  • -1 - Some other problem (timelimit, numerical problem etc)

verifyCobraProblem(XPproblem, x, tol, verbose)[source]

Verifies dimensions of fields in XPproblem and determines if they are valid LP, QP, MILP, MIQP problems. Also checks inputs for NaN. If x is provided, it will see if x is a valid solution to tolerance (tol).

USAGE

[statusOK, invalidConstraints, invalidVars, objective] = verifyCobraProblem (XPproblem, x, tol, verbose)

INPUT

XPproblem – struct containing:

  • .A - Constraints matrix

  • .b - rhs

  • .csense - vector of ‘E’, ‘L’, ‘G’ for equality, Less than and Greater than constraint

  • .lb, .ub - lower and upper bound on variables

  • .c - objective coefficients

  • .F - quadratic objective (optional, only used for QP, MIQP problems)

  • .vartype - vector of ‘C’, ‘I’, ‘B’ for ‘continuous’, ‘integer’, ‘binary’ variables (optional, only used for MILP, MIQP problems).

OPTIONAL INPUT

  • x – Vector. Function will determine if x satisfies XPproblem

  • tol – numerical tolerance to which all constraints should be verified to. (default = 1e-8)

  • verbose – Controls whether results are printed to screen.(Default = true)

OUTPUT

  • statusOK – Returns -1 if any field in XPproblem has an error, returns 0 if the x vector is not valid for XPproblem and returns 1 if at least one problem type is satisfied

  • invalidConstraints – Vector which lists a 1 for any constaint that is invalid

  • invalidVars – Vector which lists a 1 for any variable that is invalid

  • objective – Objective of XPproblem