The Java Interface to CPLEX

The use of CPLEX in Java is based around the class IloCplex (documented here). 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 objects and their subclass IloIntVar 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:

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

We will use a few methods from IloLinearIntExpr to build up sums.

The interface for IloLinearNumExpr is similar.

A Short Example

Suppose we want to solve the following IP in CPLEX:

In the file src/main/WarmUps.java, try to solve the above IP inside the method exerciseOne() and print out the values of the variables and the optimal solution. Then run the code. If you are on Linux or Mac, you will probably need to set a virtual machine argument as you did in the installation assignment. You can also look at the installation assignment if you need to see an example.

Solution

public class WarmUps {

	public static void main(String[] args) {		
		try {
			exerciseOne();
		} catch (IloException e) {
			throw new RuntimeException(e);
		}
	}
	
	public static void exerciseOne() throws IloException{
		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);
		cplex.solve();
		System.out.println("x: " + cplex.getValue(x));
		System.out.println("y: " + cplex.getValue(y));
		System.out.println("z: " + cplex.getValue(z));
		System.out.println("obj: " + cplex.getObjValue());
	}
}

Reading Integer Variable Values from CPLEX

After solving an LP that is integral or an IP, you often want to query a variable and take some action if the variable has value 1.0, and another action if the variable has value 0.0. However, due to the nature of floating point arithmetic, there are often small rounding errors in the values produced by CPLEX. For example, to test if a variable is equal to zero, do not write

IloCplex cplex = new IloCplex();
IloIntVar var = cplex.boolVar();
//...
//solve some problem
//...
double val = cplex.getValue(var);
if(val == 0){
  //take some action
}

Instead, you need to allow for a small error, like so:

IloCplex cplex = new IloCplex();
IloIntVar var = cplex.boolVar();
//...
//solve some problem
//...
double val = cplex.getValue(var);
if(Math.abs(val) < 0.00001){
  //take some action
}

The level of numerical tolerance and a variety of methods to extract integer values up to a tolerance are provided for you with the following static methods from Util.java

Performance Issues Reading Variable Values from CPLEX

Consider the following piece of code you can find in your WarmUps.java:

	public static void testSpeed() throws IloException{
		IloCplex cplex = new IloCplex();
		IloIntVar[] variables = cplex.boolVarArray(2000000);
		cplex.addMaximize(cplex.sum(variables));
		cplex.solve();
		{			
			System.err.println("testing group access");
			long startTime = System.currentTimeMillis();
			double sum = 0;
			double[] vals = cplex.getValues(variables);
			for(int i = 0; i < vals.length; i++){
				sum+= vals[i];
			}
			long endTime = System.currentTimeMillis();
			System.err.println("group: " + (endTime-startTime));
			System.err.println(sum);
		}
		{
			System.err.println("testing individual access");
			long startTime = System.currentTimeMillis();
			double sum = 0;
			for(int i = 0; i < variables.length; i++){
				double val = cplex.getValue(variables[i]);
				sum+=val;
			}
			long endTime = System.currentTimeMillis();
			System.err.println("individual: " + (endTime-startTime));
			System.err.println(sum);
		}		
	}

It solves a very simple IP, then compares the amount of time to query the variables one at a time versus the amount of time needed to query all of the variables at once. Adjust the main method to run testSpeed() instead of exercise1(). The result should be surprising! On my machine, the group access took 23 milliseconds, while the individual access took 282 milliseconds, over ten times as long. If the variables were further wrapped in a BiMap (as suggested in the next section), the running time increases to over 500 milliseconds. If we are going to only read the values of the variables once, we wouldn't really care, as a typical IP with 2,000,000 variables takes much longer than half a second to solve. However, if instead we are querying the values of the variables at every node in the branch and bound tree to test for separation (as we will be soon), then these half seconds add up quickly. Know when to optimize.