h1. The Java Interface to CPLEX
The use of CPLEX in Java is based around the class IloCplex (documented [here|http://pic.dhe.ibm.com/infocenter/cosinfoc/v12r5/index.jsp?topic=%2Filog.odms.cplex.help%2Frefjavacplex%2Fhtml%2Filog%2Fcplex%2FIloCplex.html]). The basic idea is that you create an IloCplex object for your optimization problem, then add variables, the objective, and constraints using methods in the class IloCplex. The IloCplex object can produce [IloNumVar|http://pic.dhe.ibm.com/infocenter/cosinfoc/v12r5/index.jsp?topic=%2Filog.odms.cplex.help%2Frefjavacplex%2Fhtml%2Filog%2Fconcert%2FIloNumVar.html] objects and their subclass [IloIntVar|http://pic.dhe.ibm.com/infocenter/cosinfoc/v12r5/index.jsp?topic=%2Filog.odms.cplex.help%2Frefjavacplex%2Fhtml%2Filog%2Fconcert%2FIloIntVar.html] objects, when are then used as arguments to further methods from IloCplex to make the objective and constraints. The IloCplex interface is pretty confusing. It is very large, has lots of redundant methods, and has lots of methods that appear to be the same but produce very different results. We now summarize the methods of IloCplex which will be of use to us:
||Name||Return Type||Arguments||Description||
|boolVar|IloIntVar| |Creates and returns a new Boolean variable (domain 0,1).|
|boolVarArray|IloIntVar[]|int n |Creates and returns an array of n new Boolean variables (domain 0,1)|
|linearIntExpr|IloLinearIntExpr| |Creates and returns an integer linear expression initialized as 0 (zero).|
|addGe|IloRange|IloNumExpr e, double v|Creates and returns a range representing the constraint {mathinline} e \geq v{mathinline}|
|addEq|IloRange|IloNumExpr e, double v|Creates and returns a range representing the constraint {mathinline} e = v{mathinline}|
|addMinimize|IloObjective|IloNumExpr e|Creates and returns an objective to minimize the expression and adds it to the invoking model.|
|sovle|boolean| |Solves the active model. Returns true if a feasible solution was found|
|getValue|double|IloNumVar var|Returns the solution value for var.|
|getValues|double|IloNumVar[] vars|Returns the solution values for each of vars.|
|getObjVal|double| |Returns the objective value of the current solution.|
{warning:title=Warning}
For an IloCplex cplex, an IloNumExpr e and a double v, calling cplex.addGe(e,v) and cplex.addGe(v,e) are both allowed but do not produce the same result! The first gives the constraint {mathinline} e \geq v{mathinline} while the second gives the constraint {mathinline}v \geq e{mathinline}.
{warning}
{warning:title=Warning}
For an IloCplex cplex, an IloNumExpr e and a double v, calling cplex.ge(e,v) and cplex.addGe(e,v) are both allowed but do not produce the same result! While both return an object for the constraint {mathinline} e \geq v{mathinline}, only the latter adds the constraint to the model! We will actually have use cplex.ge(e,v) later when we add constraints through callbacks instead of adding them directly to the model.
{warning}
Notice that the various numeric expressions are arguments for these functions. The inheritance relationship between the different classes of numeric expressions is a little complicated, but well designed. They are summarized in the chart below, with an arrow from interface A to interface B if A implements B (is a subinterface, like a subclass).
{gliffy:name=cplexNumericExpressionInheritance|align=left|size=M|version=1}
We will use a few method from IloLinearIntExpr to build up sums.
||Name||Return Type||Arguments||Description||
|addTerm|void|IloIntVar v, int c|Adds the new term {mathinline}c\cdot v{mathinline} to a scalar product. This method can create duplicate terms {mathinline} \cdots + a_i \cdot x + \cdots + a_k
\cdot x + \cdots{mathinline} that could be joined to a single term {mathinline}\cdots + (a_i + a_k) \cdot x + \cdots{mathinline}. Duplicates do not generate errors but require more memory and more running time.|
The interface for IloLinearNumExpr is similar.
h1. A Short Example
Suppose we want to solve the following IP in CPLEX:
{mathdisplay}
\begin{aligned}
&\min & x + 2y + 3z\\
&\text{subject to}& x + y + z &\geq 2\\
&& x,y,z &\in\{0,1\}
\end{aligned}
{mathdisplay}
How can we implement this using the above methods? We demonstrate this in the code snippet below:
{code}
IloCplex cplex = new IloCplex();
IloIntVar x = cplex.boolVar();
IloIntVar y = cplex.boolVar();
IloIntVar z = cplex.boolVar();
IloLinearIntExpr constraintSum = cplex.linearIntExpr();
constraintSum.addTerm(x,1);
constraintSum.addTerm(y,1);
constraintSum.addTerm(z,1);
cplex.addGe(constraintSum,2);
IloLinearIntExpr objectiveSum = cplex.linearIntExpr();
objectiveSum.addTerm(x,1);
objectiveSum.addTerm(y,2);
objectiveSum.addTerm(z,3);
cplex.addMinimize(objectiveSum);
{code}
|