Recording API Calls#

The Gurobi Optimizer provides the option to record the set of Gurobi commands issued by your program and store them to a file. The commands can be played back later using the Gurobi Command-Line Tool. If you replay the commands on a machine with the same specs (operating system, core count, and instruction set) as the machine where you created the recording, your Gurobi calls will take the exact same computational paths that they took when you ran your original program.

Recording can be useful in a number of situations.

  • If you want to understand how much time is being spent in Gurobi routines, the replay will show you the total time spent in Gurobi API routines, and the total time spent in Gurobi algorithms.

  • If you want to check for leaks of Gurobi data, the replay will show you how many Gurobi models and environments were never freed by your program.

  • If you run into a question or an issue and you would like to get help from Gurobi, your recording will allow Gurobi technical support to reproduce the exact results that you are seeing without requiring you to send your entire application.

Recording is useful for testing across deployment scenarios. In particular, you can do the following:

  • A recording made on a Compute Server can be replayed on a Compute Server or locally. By default, the recording will use localhost:61000; this can be overridden by setting the GRB_COMPUTESERVER environment variable. If GRB_COMPUTESERVER is set to an empty string, the replay will occur locally.

  • A Cluster Manager recording can be replayed via a Cluster Manager, on a Compute Server, or locally. GRB_COMPUTESERVER has priority over GRB_CSMANAGER. If GRB_CSMANAGER is set to “”, the replay will run locally or on the specified Compute Server.

  • A Gurobi Instant Cloud recording can be replayed on the cloud, on a Compute Server, or locally. Setting GRB_CLOUDACCESSID and GRB_CLOUDSECRETKEY will run the replay on the cloud. GRB_COMPUTESERVER has priority over GRB_CLOUDACCESSID (and GRB_CLOUDSECRETKEY). If GRB_CLOUDACCESSID is set to “”, the replay will run locally or on the specified Compute Server.

  • A token server recording can be replayed. The recording tries to use a token server at localhost (with the default port 41954). This can be overridden by setting the GRB_TOKENSERVER environment variable. If GRB_TOKENSERVER is set to an empty string, the replay will be done using a local license.

  • A recording that includes the WorkerPool parameter (used in the distributed MIP and distributed concurrent algorithms) can only be done by setting the GRB_WORKERPOOL environment variable.

For recordings of optimization with Compute Server or Instant Cloud, the recording will query the number of processors and cores from the remote worker and store this information in the recording file. When replaying a recording file, Gurobi uses these stored values.

Recording#

To enable recording, you simply need to set the Record parameter to 1 as soon as you create your Gurobi environment. The easiest way to do this is with a gurobi.env file. This file should contain the following line:

Record 1

If you put this file in the same directory as your application, Gurobi will pick up the setting when your application makes its first Gurobi call. You can also set this parameter through the standard parameter modification routines in your program.

Once this parameter is set, you should see the following in your log:

*** Start recording in file recording000.grbr

If your application creates more than one Gurobi environment, you may see more than one of these messages. Each will write to a different file:

*** Start recording in file recording001.grbr

As your program runs, Gurobi will write the commands and data that are passed into Gurobi routines to these files. Recording continues until you free your Gurobi environment (or until your program ends). When you free the environment, if Gurobi logging is enabled you will see the following message:

*** Recording complete - close file recording000.grbr

At this point, you have a recording file that is ready for later replay.

Replay#

To replay a Gurobi recording, you issue the following command:

> gurobi_cl recording000.grbr

You should adjust the file name to match the file you wish to replay. If your program generated multiple recording files, you will need to replay each one separately.

When the replay starts, the first output you will see will look like this:

*Replay* Replay of file 'recording000.grbr'
*Replay* Recording captured Tue Sep 13 19:28:48 2023
*Replay* Recording captured with Gurobi version 11.0.0 (linux64)

After this output, the replay will start executing the commands issued by your program…

*Replay* Load new Gurobi environment
*Replay* Create new Gurobi model (0 rows, 0 cols)
*Replay* Update Gurobi model
*Replay* Change objective sense to -1
*Replay* Add 3 new variables

This continues until the recording file ends. At that point, the replay will print out a final runtime accounting…

*Replay* Replay complete

*Replay* Gurobi API routine runtime: 0.05s
*Replay* Gurobi solve routine runtime: 2.31s

If your program leaked any Gurobi models or environments, you may also see that in the output:

*Replay* Models leaked: 2
*Replay* Environments leaked: 1

Limitations#

Recording works with most programs that call Gurobi. There are a few Gurobi features that aren’t supported, though:

  • Recording won’t capture calls to the Gurobi tuning tool.

  • Recording won’t capture data passed into control callbacks. In other words, you can’t record a program that adds lazy constraints, user cuts, or solutions through callbacks.

  • Recording is not yet compatible with Batch Mode.