Key Performance Indicators (KPIs)

Key Performance Indicators

A Key Performance Indicator (KPI) is any measurable value that you are interested in for monitoring your business performance. In fact, it can be anything that you can quantify and write a formula for. For example, in a scheduling problem you might minimize the makespan (the date at which all tasks are completed), but other values might also be of interest, like the number of jobs not completed by their deadline, or the total amount of idle time in the schedule. You can identify such expressions in the model by marking them as KPIs.

Defining KPIs in a model

You can now define your own KPIs in your model and their values will be displayed in the CPO solution.

KPI values are automatically displayed in the log. They can also be queried after the solve or for each solution. In addition, they are exported to a CPO file when the model is exported.

To define a KPI, you can use the following syntax: cp.addKPI(<formula>, "<name of your KPI>"); See the appropriate page in these release notes for your programming language.


The plantlocation example now includes two KPI definitions (mean occupancy and minimal occupancy) to illustrate this new KPI feature. The first KPI is the mean occupancy defined as the total demand divided by the total capacity of the used plants. The second indicator is the minimum plant occupancy defined as the ratio of demand to capacity of the plant where this ratio is the smallest. See plant_location.cpp (C++), (Java) or PlantLocation.cs (C#) for more information.

The following shows an extract of the log file for this plant location example. As it is running the values of the two KPIs are printed in the log with an 'I' representing 'indicator'.
  *         70490     106k  9.18s        2      (gap is 45.44%)
       I Mean occupancy: 0.9869259; Min occupancy: 0.9270833
                 70490     120k         31    3   F    29  = _int72
                 70490     120k         31    5   F    29  = _int72
                 70490     110k         11    2   F    19  = _int132
       ! Time = 9.52s, Average fail depth = 49, Memory usage = 16.5 MB
       ! Current bound is 38456 (gap is 45.44%)
       !          Best Branches  Non-fixed    W       Branch decision
                 70490     120k         39    8         5 != _int148
                 70490     110k         22    4        16 != _int80
                 70490     110k          8    7        12 != _int94
       *         70488     113k  9.94s        2      (gap is 45.44%)
       I Mean occupancy: 0.9869259; Min occupancy: 0.9166666
                 70488     130k         30    6         8 != _int86
       ! ----------------------------------------------------------------------------
       ! Search terminated by limit, 48 solutions found.
       ! Best objective         : 70488 (gap is 45.44%)
       ! Best bound             : 38456
       ! Mean occupancy         : 0.9869259
       ! Min occupancy          : 0.9166666
       ! ----------------------------------------------------------------------------
       ! Number of branches     : 925154
       ! Number of fails        : 417150
       ! Total memory usage     : 16.6 MB (16.3 MB CP Optimizer + 0.3 MB Concert)
       ! Time spent in solve    : 10.00s (10.00s engine + 0.00s extraction)
       ! Search speed (br. / s) : 92515.4
       ! ----------------------------------------------------------------------------

KPIDisplay Parameter

You can use the new KPIDisplay parameter to control how your defined KPIs are displayed in the log file. This parameter can take two symbolic values: SingleLine and MultipleLines, so that you can display your KPIs either on one line or on several lines. See KPIDisplay in Parameters of CP Optimizer for more information.

Querying KPIs

For the APIs which manipulate and query KPIs, see the appropriate section of these release notes according to the programming language you use.

KPIs in exported models

When a model with KPIs is exported as a CPO file, a specific section is added to the CPO file. For example, if you export the model from the plant location example, you will see the following section:
 KPIs {
        "Mean occupancy" = 2944 / (137*IntVar_0 + 122*IntVar_5 + 87*IntVar_9 + 125*IntVar_13 + 120*IntVar_17 ...
        "Min occupancy" = min([1 + IntVar_1 * 0.0072992700729927005 - IntVar_0, 1 + IntVar_6 * 0.00819672131 ...

KPIs in imported files

When you read in a file with KPIs (for example,in the CP Optimizer Interactive optimizer),you will see the evolution of the KPIs in the log as in the original model.

CPO File format

More information on how KPIs are expressed in the CPO File format are given in the CP Optimizer File Format Reference Manual.