Modeling assistance callback

The modeling assistance callback allows the user to intercept information coming from modeling assistance.

The most common reason to do this is to prevent certain types of messages from being displayed or to redirect the messages (for example, rather than displaying them on the screen, put them in a log file). Another possible usage of this callback would be to abort the solve if some warning is triggered.

For the modeling assistance callback, whenever a modeling assistance warning is detected inside CPLEX, CPLEX calls the user function with the issueid and message parameters. Then, the code that the user wrote handles those parameters. After the user function returns, CPLEX continues on with its internal logic.

The modeling assistance callback interacts closely with two parameters:

• The data consistency checking and modeling assistance parameter, CPXPARAM_Read_DataCheck, controls whether modeling assistance is turned on. When the value of this parameter is set to level 2, CPX_DATACHECK_ASSIST, CPLEX turns on both data consistency checking and modeling assistance. Otherwise, CPLEX will not turn on modeling assistance.
• The warning limit parameter, CPXPARAM_Read_WarningLimit, controls the number of warnings displayed. By default, when modeling assistance is turned on via the data consistency checking parameter, CPLEX will display 10 warnings for a given modeling issue and then omit the rest. This parameter controls this limit and allows the user to display all of the warnings if desired.

For a list of the routines and type definitions that enable you to implement the modeling assistance callback in the C API, see Modeling assistance callback in the CPLEX Callable Library (C API) Reference Manual. The modeling assistance callback is also implemented in the C++, Java, .NET, and Python APIs of CPLEX. See the reference manuals of those APIs for more detailed information.

The following example shows how to implement the modeling assistance callback using the Java API. In this example, the code uses the modeling assistance callback to "block" specified modeling assistance messages. The user can "block" more than one message at a time by adding additional if statements.

/* -------------------------------------------------------------- -*- Java -*-
 * File: ModelAsstCB.java
 * Version 12.9.0  
 * --------------------------------------------------------------------------
 * Licensed Materials - Property of IBM
 * 5725-A06 5725-A29 5724-Y48 5724-Y49 5724-Y54 5724-Y55 5655-Y21
 * Copyright IBM Corporation 2017, 2018, 2019. All Rights Reserved.
 *
 * US Government Users Restricted Rights - Use, duplication or
 * disclosure restricted by GSA ADP Schedule Contract with
 * IBM Corp.
 * --------------------------------------------------------------------------
 */

import ilog.concert.*;
import ilog.cplex.*;


/**
 * Demonstrate how to use the modeling assistance callback.
 *
 * See the usage message for required command line arguments.
 */
public class ModelAsstCB {

   /**
    * This is the class implementing the callback for modeling assistance.
    */
   private static class Callback implements IloModelingAssistance.Callback {
      private int numCalls;

      public Callback() {
         this.numCalls = 0;
      }

      /**
       * Get the number of times the callback was invoked.
       */
      public int getNumCalls() {
         return numCalls;
      }

      /**
       * This is the function that we have to implement and that CPLEX will call
       * during modeling assistance (e.g., before and after optimization).
       */
      @Override
      public void invoke (int issueid, String message) throws IloException {
         // Increment the number of calls.
         numCalls++;

         // IloModelingAssistance.BIGM_TO_IND corresponds to CPXMI_BIGM_TO_IND
         // in the callable Library. This applies to all of the CPXMI macros.
         if (issueid == IloModelingAssistance.BIGM_TO_IND) {
            // Purely as an example, for no reason in particular, ignore
            // this type of modeling issue.
         }
         else {
            // Otherwise, display the warning message.
            System.out.println(message);
         }
      }
   }

   private static void usage() {
      System.out.println("Usage: java ModelAsstCB <filename>");
      System.out.println("  filename  Name of a file, with .mps, .lp, or .sav");
      System.out.println("            extension, and a possible, additional .gz");
      System.out.println("            extension");
      System.exit(2);
   }

   public static void main(String[] args) throws Exception {
      if (args.length != 1) {
         usage();
         return;
      }

      // Create the modeler/solver object
      IloCplex cplex = new IloCplex();

      // Read model from file with name args[0] into cplex optimizer object
      cplex.importModel(args[0]);

      // Turn on modeling assistance. Otherwise, the modeling assistance
      // callback would not be invoked.
      cplex.setParam(IloCplex.Param.Read.DataCheck, IloCplex.DataCheck.Assist);
      // Increase the warning limit, so that we print "all" possible modeling
      // assistance warnings. This also applies to the number of warnings
      // that will be captured by the modeling assistance callback.
      cplex.setParam(IloCplex.Param.Read.WarningLimit,
                     cplex.getMax(IloCplex.Param.Read.WarningLimit));

      // Instantiate a Callback object and register it with the IloCplex
      // instance. When a modeling assistance callback is registered,
      // modeling assistance messages will _not_ be printed in the engine
      // log.
      Callback callback = new Callback();
      cplex.use(callback);

      try {
         // Solve the model and display the solution if one was found.
         if (cplex.solve()) {
            System.out.println("Solution status    = " + cplex.getStatus());
            System.out.println("Solution value     = " + cplex.getObjValue());
         }
         // Display the number of times the modeling assistance callback was
         // invoked.
         System.out.println("Number of warnings = " + callback.getNumCalls());
      }
      finally {
         cplex.end();
      }
   }
}