Example: C++ API

Demonstrates an example of distributed parallel MIP in the C++ API of CPLEX.

Note:

Distributed parallel optimization of mixed integer programming (MIP) models has been deprecated in CPLEX 20.1.0 and will be removed in a future release.

You write a distributed parallel MIP application in C++ in much the same way that you write a conventional (shared memory) application of CPLEX in C++. In that application, you include an additional step: before you invoke the method IloCplex::solve, you must load a Virtual Machine Configuration (a configuration.vmc file, as explained in Distributed parallel MIP in the Interactive Optimizer.) The presence of the configuration file tells IloCplex::solve to run distributed parallel MIP instead of conventional (shared memory) MIP optimization.

Source code

CPLEX offers sample code ilodistmipex1.cpp that shows how to use distributed parallel MIP. The important statements in that code are these statements:



 IloEnv env;

IloModel model(env);

IloCplex cplex(model);

cplex.importModel(model, argv[i]);

cplex.readCopyVMConfig(vmconfig);

cplex.solve();

Those first four statements create an instance of the CPLEX solver and load the model of a problem into it.

The call to IloCplex::readCopyVMConfig loads a Virtual Machine Configuration from a file. This configuration specifies which machines the distributed parallel MIP optimization will use.

Finally, the call to IloCplex::solve checks whether the problem is a MIP and whether a Virtual Machine Configuration has been loaded. If so, CPLEX runs distributed parallel MIP optimization. Otherwise, it uses one of the conventional algorithms to solve the loaded model.

Compiling and linking

The conventions to compile applications that use distributed parallel MIP optimization are precisely the same as the conventions of other CPLEX C++ applications.

On platforms other than Windows, however, the linking is slightly different for an application of distributed parallel MIP optimization. When your application uses distributed parallel MIP, you must link with libcplexdistmip.a, a part of the CPLEX distribution, located in the same place as libcplex.a. You must also link with libdl.so to enable your application to load shared objects. To link with libdl.so, you can add the option -ldl to your linker command.

Running your application

Execution of an application using distributed parallel MIP optimization is slightly more complicated than running a conventional (shared memory) C++ application of CPLEX. Your application acts as master in distributed parallel MIP while the other machines specified in the Virtual Machine Configuration act as workers. In order to run your application, you follow these steps:

  1. Deploy the workers. That is, copy the binaries and shared libraries as explained in Distributed parallel MIP in the Interactive Optimizer.

  2. Set up your environment so that your application can find the CPLEX shared libraries. One way to do so is to set an environment variable to specify the folder or directory where the CPLEX shared library is located.

    • On GNU/Linux, set the environment variable LD_LIBRARY_PATH.
    • On MacOS, set the environment variable DYLD_LIBRARY_PATH.
    • On Windows, set the environment variable PATH.

  3. Run your application.

    • On Windows, CPLEX offers a Visual Studio project, that is, a file with the extension .vcxproj and containing options and values to compile, link, and run the example ilodistmipex1.cpp. Simply load ilodistmipex1.vcxproj and run the project to execute the code.
    • On other platforms, CPLEX offers a Makefile that compiles, links, and runs the example ilodistmipex1.cpp. In the following sample commands, replace these values by appropriate values from your installation.
      • COS_INSTALL_DIR is the folder or directory where you installed IBM ILOG CPLEX Optimization Studio.
      • system is the type of your computer platform.
      • libformat is the library format.

      Then execute the equivalent commands:

      
    cd COS_INSTALL_DIR/cplex/examples/system/libformat
    make -f Makefile.distmip dm_execute_cpp