Annotating a model for CPLEX

Annotation of a model specifies to CPLEX how to decompose your model.

If you want to specify a decomposition of your model to CPLEX, you use annotations. In fact, CPLEX offers an application programming interface (API) for the purpose of annotating the objects of a model. An annotation specifies a key and value pair, where keys are strings, and values can be either long or double. You can associate an annotation with each element (such as the objective, variables, constraints, rows, columns, and other modeling objects) of your model. CPLEX can take advantage of these annotations as it solves your model. For example, you can annotate variables to specify to CPLEX the blocks of a partition of the variables to apply Benders algorithm.

To annotate your model for Benders algorithm, you first create a new annotation with a name (that is, a string) and with a default partition value of type long. By default, the name cpxBendersPartition and the value 0 (zero) together designate elements in the master of a Benders decomposition, while other values designate subproblems of the partition. You can specify a default value annotation yourself.

Next, you use cpxBendersPartition to annotate some or all of the variables in your model. These annotations specify to CPLEX whether certain variables belong to the master or to one of the subproblems assigned to workers (where the subproblems are numbered from 1 (one) to N, the number of subproblems).
  • If you annotate a given variable with the value 0 (zero), CPLEX assigns that variable to the master.
  • If you do not annotate a given variable, CPLEX assumes the default value annotation.
  • If you annotate a given variable with the value i, where i is greater than or equal to 1 (one), CPLEX assigns that variable to subproblem i.
  • If you annotate a given variable with a value strictly less than zero, CPLEX raises an error CPXERR_NO_DECOMPOSITION.

Tip: It is a good idea to verify that the N subproblems plus master actually define a decomposition of the original model into disjoint subproblems. That is, make sure you have a complete partition for your decomposition.

CPLEX also produces an error CPXERR_BAD_DECOMPOSITION if the annotated decomposition does not yield disjoint subproblems. For example, if your annotations specify that two (or more) variables belong in different subproblems, yet your model specifies that these variables participate in the same constraint, then these variables are linked. Consequently, the subproblems where these variables appear according to your annotations are not disjoint with respect to the partition.

If you want CPLEX to apply a Benders strategy as it solves your problem, but you do not specify cpxBendersPartition annotations yourself, see the topic Benders decomposition: CPLEX default for an explanation of default CPLEX decomposition.

Besides the application programming interface (API) to support annotations, CPLEX also offers a file format, ANN or .ann, to support annotations of modeling objects. CPLEX can read annotations from such a formatted file and apply those annotations to your model. CPLEX can also collect annotations from a model and write those annotations to such a formatted file.

In the standard distribution of the product, see the file annotation.xsd for the XML schema supporting annotations.

An annotation file has a header that includes the annotation name and type, the default value and the object type that identifies the element in the annotation. Supported object types appear in the table.

Annotated element Object type identifier
objective 0
column or variable 1
row or constraint 2
special ordered set (SOS) 3
indicator constraint 4
quadratic constraint 5

Here is a sample header from an annotation file. This annotation file is based on the example UFL_25_35_1 provided in the CPLEX distribution.

 
< ? xml version='1.0' encoding='utf-8'? >
< CPLEXAnnotations >
< CPLEXAnnotation name='cpxBendersPartition' type='long' default='0' >
< object type='1' >

For more detail about the API for annotations, see the topic about the API of interest to you in your CPLEX application: