CPLEX cplex

This page is part of the CPLEX Manual. See CPLEX.

Purpose

CPLEX solves mixed-integer linear and quadratic programming (MILP, MIQP) and linear and quadratic program- ming (LP, QP) interface. For users with a full license for the optimizer, the solver also handles problems with quadratic constraints (MIQQ). CPLEX solves problems of the form

${\begin{array}{ccccccl}\min \limits _{x}&f(x)={\frac {1}{2}}x^{T}Fx+c^{T}x\\s/t&x_{L}&\leq &x&\leq &x_{U}\\&b_{L}&\leq &Ax&\leq &b_{U}\\&&&x^{T}Q^{(i)}x+a^{(i)T}x&\leq &r_{U}^{(i)},&i=1,\ldots ,n_{qc}\\&&&x_{i}\mathrm {\ \ integer} &&i\in I\\\end{array}}$

where $c,x,x_{L},x_{U},a^{(i)}\in \mathbb {R} ^{n}$, $F,Q^{(i)}\in \mathbb {R} ^{n\times n}$, $A\in \mathbb {R} ^{m\times n}$ and $b_{L},b_{U}\in \mathbb {R} ^{m}$. $r_{U}^{(i)}$ is a scalar. The variables $x\in I$, the index subset of $1,...,n$, are restricted to be integers.

If F is empty and no quadratic constraints are given, an LP or MILP problem is solved.

An additional set of logical constraints can also be defined. See the help for input parameter logcon.

Calling Syntax

[x, slack, v, rc, f k, ninf, sinf, Inform, basis, lpiter, glnodes, confstat, iconfstat, sa] = 
cplex(c, A, x L, x U, b L, b U, cpxControl, callback, PriLev, Prob, IntVars, PI, SC, SI, sos1, 
      sos2, F, logfile, savefile, savemode, qc, confgrps, conflictFile, saRequest, basis, xIP, logcon);

Description of Inputs

Please note that CPLEX only handles single-sided bounds on quadratic constraints. An arbitrary number of qc's is set using the Prob.QP.qc structure array: qc(1).Q = sparse( <quadratic coefficient nxn matrix> ); qc(1).a = full ( <linear coefficient nx1 vector > ); qc(1).r U = <scalar upper bound>; And similarly for qc(2), ... , qc(n qc). The standard interpretation is xl * Q * x + cl * x <= rU , but it is possible to define an alternative sense xl * Q * x + cl * x >= rL by setting qc(i).sense to a nonzero value and specifying a lower bound in qc(i).rL . Observe that the Q matrix must be sparse, non-empty and positive semi-definite for all qc's. The linear coefficient vector qc(i).a may be omitted or set empty, in which case all zeros are assumed. Likewise, if a bound r U or r L is empty or not present, it is assumed to be 0.0. Note that this is contrary to the usual TOMLAB standard, where an empty or omitted bound is assumed to be +/- Inf. The reason is that a single-sided constraint with an infinite bound would have no meaning.

The following inputs are used:
c	Linear objective function cost coefficients, vector n × 1.
A	Linear constraint matrix for linear constraints, dense or sparse matrix m × n.
x_L	Lower bounds on design parameters x. If empty assumed to be zero.
x_U	Upper bounds on design parameters x.
b_L	Lower bounds on the linear constraints.
The following parameters are optional:
b_U	Upper bounds on the linear constraints. If empty, then b U=b L is assumed, i.e. equality constraints.
cpxControl	Structure, where the fields are set to the CPLEX control parameters that the user wants to specify values for.
callback	0 - 1 vector defining which callbacks to use in CPLEX. If the ith entry of the logical vector callback is set, the corresponding callback is defined. The callback calls the m-file specified in Table 7 below. The user may edit this file, or make a new copy, which is put in a directory that is searched before the cplex directory in the Matlab path.
PriLev	Printing level in the cplex m-file and the CPLEX C-interface. = 0 Silent = 1 Summary information = 2 More detailed information
Prob	A structure. If cplex.m is called through cplexTL.m, for example when the user has used the TOMLAB driver routine tomRun, then Prob is the standard TOMLAB problem structure. Otherwise the user optionally may set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. If any callback is defined then problem arrays are set as fields in Prob, and the Prob structure is always passed to the callback routines as the last parameter. The defined fields are Prob.c, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U and Prob.QP.F. If the input structure is empty ([ ]), then Prob.P = 1 is set.
IntVars	Defines which variables are integers, of the general type I or binary B. Variable indices should be in the range [1,...,n]. If I ntV ars is a logical vector then all variables xi where I ntV ars(i) > 0 are defined to be integers. If I ntV ars is determined to be a vector of indices then x(I ntV ars) are defined as integers. If the input is empty ([ ]), then no integers of type I or B are defined. The interface routine cplex checks which of the integer variables have lower bound xL = 0 and upper bound xU = 1, i.e. are binary 0/1 variables.
PI	Integer variables of type Partially Integer (PI), i.e. takes an integer value up to a specified limit, and any real value above that limit. PI must be a structure array where:
PI.var	is a vector of variable indices in the range [1, ..., n].
PI.lim	is a vector of limit values for each of the variables specified in PI.var, i.e. for variable i, that is the PI variable with index j in P I .var, then x(i) takes integer values in [xL (i), P I .lim(j)] and values in [P I .lim(j), xU (i)].
SC	A vector with indices for the integer variables of type Semi-continuous (SC), i.e. that takes either the value 0 or a real value in the range [xL (i), xU (i)], assuming for some j, that i = SC (j), where i is an variable number in the range [1, ..., n].
SI	A vector with indices for the integer variables of type Semi-integer (SI), i.e. that takes either the value 0 or an integer value in the range [xL (i), xU (i)], assuming for some j, that i = SI e(j), where i is an variable number in the range [1, ..., n].
sos1	A structure defining the Special Ordered Sets of Type One (sos1). Assume there are k sets of type sos1, then sos1(k).var is a vector of indices for variables of type sos1 in set k. sos1(k).row is the row number for the reference row identifying the ordering information for the sos1 set, i.e. A(sos1(k).row,sos1(k).var) identifies this information. As ordering information, also the objective function coefficients c could be used. Then as row number, 0 is instead given in sos1(k).row.
sos2	A structure defining the Special Ordered Sets of Type Two (sos2). Specified in the same way as sos1 sets; see sos1 input variable description.
F	Quadratic coefficient matrix. Dense or sparse Matlab matrix, size n × n. The matrix is always converted to Matlab sparse format before ILOG CPLEX is invoked on the problem.
logfile	Name of file to write the CPLEX log information to. If empty, no log is written.
savefile	Name of a file to save the CPLEX problem object. This is useful for sending problems to ILOG for analysis. The format of the file is controlled by the following parameters, savemode. If empty, no file is written.
savemode	The format of the file given in savefile is possible to choose by setting savemode to one of the following values: 1 SAV Binary SAV format 2 MPS MPS format (ASCII) 3 LP CPLEX LP format (ASCII) 4 RMP MPS file with generic names 5 REW MPS file with generic names 6 RLP LP file with generic names Modes 4-6 are of limited interest, since the TOMLAB interface does not provide a way to change the default row names in the first place.
qc	Structure array defining quadratic constraints ("qc").
confgrps	Conflict groups descriptor (cpxBuildConflict can be used to generate the input). Set this if conflict refinement is desired in the case that infeasibility is detected by CPLEX. A conflict group consists of lists of indices describing which of the following entities are part of a group: confgrps(i).lowercol Column (variable) lower bounds confgrps(i).uppercol Column (variable) upper bounds confgrps(i).linear Linear rows confgrps(i).quad Quadratic constraints confgrps(i).sos Special ordered sets confgrps(i).indicator Indicator constraints Additionally, the group's priority value may be assigned in confgrps(i).priority Please refer to the TOMLAB /CPLEX User's Guide for an example of Conflict Refinement.
conflictFile	Name of a file to write the conflict refinement to. No file is written if this input parameter is empty or if no conflict refinement is done.
saRequest	Structure telling whether and how you want CPLEX to perform a sensitivity analysis (SA). You can complete an SA on the objective function, right hand side vector, lower and upper bounds. The saRequest structure contains four sub structures: .obj, .rhs, .xl, .xu Each one of these contain the field: .index .index contain indices to variables or constraints of which to return possible value ranges. The .index array has to be sorted, ascending. To get an SA of objective function on the four variables 120 to 123 (included) and variable 19, the saRequest structure would look like this: saRequest.obj.index = [19 120 121 122 123]; The result is returned through the output parameter 'sa'.
basis	Vector with CPLEX starting basis. If re-solving a similar problem several times, this can be set to the 'basis' output argument of an earlier call to cplex.m. The length of this vector must be equal to the sum of the number of rows (m) and columns (n). The first m elements contain row basis information, with the following possible values for non-ranged rows: 0 associated slack/surplus/artificial variable nonbasic at value 0.0 1 associated slack/surplus/artificial variable basic and for ranged rows (both upper and lower bounded) 0 associated slack/surplus/artificial variable nonbasic at its lower bound 1 associated slack/surplus/artificial variable basic 2 associated slack/surplus/artificial variable nonbasic at its upper bound The last n elements, i.e. basis(m+1:m+n) contain column basis information: 0 variable at lower bound 1 variable is basic 2 variable at upper bound 3 variable free and nonbasic
xIP	Vector with MIP starting solution, if known. Missing values may be set to NaN. Length should be equal to number of columns in problem.
logcon	Structure defining logical (or "indicator") constraints. This is a special type of linear con- straint which is included in a mixed integer problem only if an associated binary variable is equal to 1. Note that when associating a variable with a logical constraint, the variable in question will be forced to become a binary variable; even if it was a continuous or integer variable with bounds other than 0-1. Each element logcon(i) describes one logical constraint: y- > rowl * x <= rhs (also == and >= possible) The following three fields (row,var,rhs) are mandatory: The following fields are optional: logcon(i).row: A dense or sparse row vector with the same length as the number of variables in the problem. logcon(i).var: The index of the variable y which should control whether the constraint is "active" or not. Must be less than or equal to the number of variables in the problem. logcon(i).rhs: The scalar value of the right hand side of the i:th logical constraint. The following fields are optional in the description of a logical constraint: logcon(i).sense Defines the sense of the i:th logical constraint: 0 or 'lt' : implies row*x <= rhs 1 or 'eq' : implies row*x == rhs 2 or 'gt' : implies row*x >= rhs logcon(i).comp: Complement flag. The default value 0 (empty field or left out entirely) implies that the logical constraint is active when the associated variable is equal to 1. If setting the comp field to a nonzero value, the binary variable is complemented and the constraint will become active when the variable is zero. logcon(i).name: A string containing a name for the i:th logical constraint. This is only used if a save file is written.
branchprio	A nonnegative vector of length n. A priority order assigns a branching priority to some or all of the integer variables in a model. CPLEX performs branches on variables with a higher assigned priority number before variables with a lower priority; variables not assigned an explicit priority value by the user are treated as having a priority value of 0.
branchdir	A vector with -1, 0, 1 entries of length n. -1 forces branching towards the lower end of the integer, while 1 forces branching to the higher.
cpxSettings	Structure with flags controlling various CPLEX features. Currently the following fields are defined:
tune	Flag to control the CPLEX Parameter Tuning feature. The following values are recognized: 0 - Disable parameter tuning (default). 1 - Enable parameter tuning and solve problem using the parameter set found by CPLEX. 2 - Enable parameter tuning and return without solving the problem. The only meaningful output data will be the cpxControl output. During parameter tuning, the settings in cpxControl are frozen and are not changed by CPLEX. After parameter tuning has run, the complete set of modified CPLEX parameters are returned in the cpxControl output argument.
presolve	Flag controlling the CPLEX Presolve feature. The following values are recognized: 0 - No special treatment of presolve (default). 1 - Invoke CPLEX Presolve on problem before optimization begins and create information about the changes made. 2 - As 1, but also returns the presolved problem, including linear constraints, objective and bounds.

Description of Outputs

The following fields are used:
x	Solution vector x with decision variable values (n × 1 vector).
slack	Slack variables (m × 1 vector).
v	Lagrangian multipliers (dual solution vector) (m × 1 vector).
rc	Reduced costs. Lagrangian multipliers for simple bounds on x.
f_k	Objective function value at optimum.
ninf	Number of infeasibilities.
sinf	Sum of infeasibilities.
Inform	See CPLEX cplexStatus.
basis	Basis status of constraints and variables, ((m + n) × 1 vector). See inputs for more information.
lpiter	Number of simplex iterations.
glnodes	Number of nodes visited.
confstat	Structure with extended conflict status information. This output is a replica of the Prob.CPLEX.confgrps input argument with the added fields 'status' and 'istat'. confs- tat(k).status gives a text description of the status of conflict group k; the corresponding istat field is the numeric value also available in iconfstat(k).
iconfstat	Conflict status information. For an infeasible problem where at least one conflict group have been supplied in the confgrps input argument, this output argument contains the status of each conflict group, in the same order as given in the confgrps input. The following values are possible: -1 Excluded 0 Possible member 1 Possible LB 2 Possible UB 3 Member 4 Upper bound 5 Lower bound If confstat is empty even though Conflict Refinement has been requested, there was a problem in the refinement process.
sa	Structure with information about the requested SA, if requested. The fields:
obj	Ranges for the variables in the objective function.
rhs	Ranges for the right hand side values.
xl	Ranges for the lower bound values.
xu	Ranges for the upper bound values.
These fields are structures themselves. All four structures have identical field names:
status	Status of the SA operation. Possible values: 1 = Successful. 0 = SA not requested. -1 = Error: begin is greater than end. -2 = Error: The selected range (begin...end) stretches out of available variables or con- straints. -3 = Error: No SA available.
lower	The lower range.
upper	The upper range.
cpxControl	Structure with non-default CPLEX parameters generated during CPLEX Parameter Tuning.
presolve	Structure with information about the changes CPLEX Presolve made to the problem before solving. The amount of information depends on the value of the cpxSettings.presolve flag. For cpxSettings.presolve=0, this output is empty. For cpxSettings.presolve=1, the presolve output contains six arrays, pcstat, prstat, ocstat, orstat, status and objoffset.
status	Flag telling status of presolve results: 0: Problem was not presolved or no reductions were made 1: A presolved problem exists 2: The original problem was reduced to an empty problem The remaining fields of presolve will contain useful information only if status==1.
pcstat	Contains information about variables in the original problem. For each element pcstat(i): >= 1: variable i corresponds to variable pcstat(i) in the presolved problem -1: variable i is fixed to its lower bound -2: variable i is fixed to its upper bound -3: variable i is fixed to some other value -4: variable i is aggregated out -5: variable i is deleted or merged for some other reason
prstat	Contains information about constraints (rows) in the original problem. For each element prstat(i): >= 1: row i corresponds to row prstat(i) in the presolved problem -1: row i is redundant -2: row i is used for aggregation -3: row i is deleted for some other reason
ocstat	Contains information about variables in the presolved problem: For each element ocstat(i): >= 1: variable i in the presolved problem corresponds to variable ocstat(i) in the original problem. -1: variable i corresponds to a linear combination of some variables in the original problem
orstat	Contains information about constraints (rows) in the presolved problem. For each element orstat(i): >= 1: row i in the presolved problem corresponds to row orstat(i) in the original problem -1: row i is created by, for example, merging two rows in the original problem

Description

The interface routine cplex calls CPLEX to solve LP, QP, MILP, MIQP and MIQQ problems. The matrices A and F are transformed in cplex.m to the CPLEX sparse matrix format.

Error checking is made on the lengths of the vectors and matrices.

Callback functions.

Index	m-file	Description
(1)	cpxcb_PRIM	From primal simplex
(2)	cpxcb_DUAL	From dual simplex
(3)	cpxcb_PRIMCROSS	From primal crossover
(4)	cpxcb_DUALCROSS	From dual crossover
(5)	cpxcb_BARRIER	From barrier
(6)	cpxcb_PRESOLVE	From presolve
(7)	cpxcb_MIP	From mipopt
(8)	cpxcb_MIPPROBE	From probing or clique merging
(9)	cpxcb_FRACCUT	From gomory fractional cuts
(10)	cpxcb_DISJCUT	From disjunctive cuts
(11)	cpxcb_FLOWMIR	From mixed Integer Rounding cuts
(12)	cpxcb_QPBARRIER	From quadratic Barrier
(13)	cpxcb_QPSIMPLEX	From quadratic Simplex
(14)	cpxcb_INCUMBENT	From MIP incumbent