Example: using the network optimizer with the Callable Library netex1.c

Demonstrates an example of the network optimizer in the C API.

In the standard distribution of CPLEX, the file netex1.c contains code that creates, solves, and displays the solution of the network-flow problem illustrated in Figure 1.

Briefly, the main function initializes the CPLEX environment and creates the problem object; it also calls the optimizer to solve the problem and retrieves the solution.

In detail, main first calls the Callable Library routine CPXopenCPLEX. As explained in Initialize the CPLEX environment, CPXopenCPLEX must always be the first CPLEX routine called in a Callable Library application. Those routines create the CPLEX environment and return a pointer (called env) to it. This pointer will be passed to every Callable Library routine. If this initialization routine fails, env will be NULL and the error code indicating the reason for the failure will be written to status. That error code can be transformed into a string by the Callable Library routine CPXgeterrorstring.

After main initializes the CPLEX environment, it uses the Callable Library routine CPXsetintparam to turn on the CPLEX messages to screen switch parameter CPX_PARAM_SCRIND so that CPLEX output appears on screen. If this parameter is turned off, CPLEX does not produce viewable output, neither on screen, nor in a log file. It is a good idea to turn this parameter on when you are debugging your application.

The Callable Library routine CPXNETcreateprob creates an empty problem object, that is, a minimum-cost network-flow problem with no arcs and no nodes.

The function buildNetwork populates the problem object; that is, it loads the problem data into the problem object. Pointer variables in the example are initialized as NULL so that you can check whether they point to valid data (a good programming practice). The most important calls in this function are to the Callable Library routines, CPXNETaddnodes, which adds nodes with the specified supply values to the network problem, and CPXNETaddarcs, which adds the arcs connecting the nodes with the specified objective values and bounds. In this example, both routines are called with their last argument NULL indicating that no names are assigned to the network nodes and arcs. If you want to name arcs and nodes in your problem, pass an array of strings instead.

The function buildNetwork also includes a few routines that are not strictly necessary to this example, but illustrate concepts you may find useful in other applications. To delete a node and all arcs dependent on that node, it uses the Callable Library routine CPXNETdelnodes. To change the objective sense to minimization, it uses the Callable Library routine CPXNETchgobjsen.

Look again at main , where it actually calls the network optimizer with the Callable Library routine, CPXNETprimopt. If CPXNETprimopt returns a nonzero value, then an error has occurred; otherwise, the optimization was successful. Before retrieving that solution, it is necessary to allocate arrays to hold it. Then use CPXNETsolution to copy the solution into those arrays. After displaying the solution on screen, write the network problem into a file, netex1.net in the NET file format.

The TERMINATE: label is used as a place for the program to exit if any type of error occurs. Therefore, code following this label cleans up: it frees the memory that has been allocated for the solution data; it frees the network object by calling CPXNETfreeprob; and it frees the CPLEX environment by calling CPXcloseCPLEX. All freeing should be done only if the data is actually available. The Callable Library routine CPXcloseCPLEX should always be the last CPLEX routine called in a Callable Library application. In other words, all CPLEX objects that have been allocated should be freed before the call to CPXcloseCPLEX .

The complete program netex1.c appears online in the standard distribution at yourCPLEXinstallation /examples/src.