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 theGRB_COMPUTESERVER
environment variable. IfGRB_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 overGRB_CSMANAGER
. IfGRB_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
andGRB_CLOUDSECRETKEY
will run the replay on the cloud.GRB_COMPUTESERVER
has priority overGRB_CLOUDACCESSID
(andGRB_CLOUDSECRETKEY
). IfGRB_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 theGRB_TOKENSERVER
environment variable. IfGRB_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.