CPLEX cplexTL

From TomWiki
Jump to navigationJump to search

Notice.png

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

Purpose

The TOMLAB /CPLEX MILP, MIQP, LP and QP solver. It solves linear programming (LP), quadratic pro- gramming (QP) , mixed integer linear programming (MILP) and mixed integer quadratic programming problems (MIQP). The solver also handles problems with quadratic constraints (MIQQ). cplexTL solves problems of the form


where , , and . is a scalar. The variables , the index subset of , are restricted to be integers.

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

Calling Syntax

Prob = ProbCheck(Prob, 'cplex'); 
Result = cplexTL(Prob); or
Result = tomRun('cplex', Prob, 1);

Description of Inputs

Problem description structure. The following fields are used:
QP.c Linear objective function cost coefficients, vector n × 1.
QP.F Square n × n dense or sparse matrix. Empty if non-quadratic problem.
A Linear constraint matrix for linear constraints, dense or sparse m × n matrix.
b_L Lower bounds on the linear constraints.
b_U Upper bounds on the linear constraints.
x_L Lower bounds on design parameters x. If empty assumed to be -Inf .
x_U Upper bounds on design parameters x. If empty assumed to be I nf .
QP.qc Structure array defining quadratic constraints ("qc").

Please note that CPLEX only handles single-sided bounds on qc's. 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.

PriLevOpt Printing level in cplex.m file and the CPLEX C-interface.

= 0 Silent

= 1 Warnings and Errors

= 2 Summary information

= 3 More detailed information

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

optParam Structure with optimization parameters. The following fields are used:
MaxIter Limit of iterations. If a value is given here, it is set as cpxControl.ITLIM. Note that a value given directly in Prob.MIP.cpxControl.ITLIM takes precedence.
MIP Structure holding information about mixed integer optimization. Also found here is the
cpxControl structure in which CPLEX parameter settings can be made. The fields used are:
cpxControl Structure, where fields are set to the CPLEX control parameters that the user wants to specify values for. Please refer to Section G for more information on how to set the fields.
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 i 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.m 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 continuous 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 (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 exactly as sos1 sets, see M I P.sos1 input variable description.
basis Basis for warm start of solution process. See Section A.1 and F.4 for more information.
xIP Vector with MIP starting solution, if known. NaN can be used to indicate missing values.

Length should be equal to number of columns in problem. Values of continuous variables are ignored.

callback Logical 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 10 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.
CPLEX Structure with solver specific parameters for logging and saving problems. The following fields are used:
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 Prob.CPLEX.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.

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.
sa 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.

Problem description structure. The following fields are used:, continued

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'.

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.
Tune Flag controlling the CPLEX Parameter Tuning feature. The following values are recognized:

0 - Disable Parameter Tuning (default).

1 - Enable Parameter Tuning and solve problem after tuning.

2 - Enable Parameter Tuning and return after tuning. No solution will be generated.

The non-default CPLEX parameters found during Parameter Tuning is returned in Re- sult.MIP.cpxControl together with any settings given in Prob.MIP.cpxControl. The settings given as input are considered as constants during the tuning process.

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.

The results of the presolve phase (when Presolve¿0) are returned in Result.CPLEX.Presolve.

Description of Outputs

Result structure. The following fields are used:
Iter Number of iterations, or nodes visited.
ExitFlag 0: OK.

1: Maximal number of iterations reached.

2: Unbounded feasible region.

4: No feasible point found.

5: Error of some kind.

ExitText Number of iterations, or nodes visited.
Inform Result of CPLEX run. See CPLEX cplexStatus for details on the ExitText and possible Inform values.
x_0 Initial starting point not known, set as empty.
QP.B Optimal active set, basis vector, in TOMLAB QP standard.

B(i) = 1: Include variable x(i) is in basic set.

B(i) = 0: Variable x(i) is set on its lower bound.

B(i) = -1: Variable x(i) is set on its upper bound.

f_k Function value at optimum, f (xk ).
g_k Gradient value at optimum, c or c + F * x.
x_k Optimal solution vector xk .
v_k Lagrangian multipliers (for bounds and dual solution vector). Set as vk = [rc; v], where rc is the n-vector of reduced costs and v holds the m dual variables.
xState State of variables. Free == 0; On lower == 1; On upper == 2; Fixed == 3;
bState State of linear constraints. Free == 0; Lower == 1; Upper == 2; Equality == 3; Solver Solver used - CPLEX .
SolverAlgorithm Solver algorithm used.
FuncEv Number of function evaluations. Set to Iter. GradEv Number of gradient evaluations. Set to Iter. ConstrEv Number of constraint evaluations. Set to Iter. Prob Problem structure used.
MIP.ninf Number of infeasibilities.
MIP.sinf Sum of infeasibilities.
MIP.slack Slack variables (m × 1 vector).
MIP.lpiter Number of LP iterations.
MIP.glnodes Number of nodes visited.
MIP.basis Basis status of constraints and variables ( (m + n) × 1 vector) in the CPLEX format, fields xState and bState has the same information in the TOMLAB format. See CPLEX cplex and CPLEX Warm Start for more information.
MIP.cpxControl Structure with non-default CPLEX parameters generated during CPLEX Parameter Tuning.
CPLEX.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.
CPLEX.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).
CPLEX.iconfstat Conflict status information. For an infeasible problem where at least one conflict group have been supplied in the Prob.CPLEX.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.

CPLEX.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 Prob.CPLEX.Presolve flag.

For Prob.CPLEX.Presolve=0, this output is empty.

For Prob.CPLEX.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 Result.CPLEX.Presolve will contain useful information only if sta- tus==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

Global Parameters Used

cpxCBInfo

cpxRetVec

Description

The TOMLAB CPLEX MILP, MIQP, QP and LP interface calls the interface routine cplex.m. Values > 1010 and Inf values are set to 1010 , and the opposite for negative numbers. An empty objective coefficient c-vector is set to the zero-vector.

Examples

See mip_prob

M-files Used

cplex.m

See Also

mipSolve

Table: 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