Gurobi recording files enable a user to replay the exact model-building and solution process from one machine on another machine, independent of the underlying hardware. This can be helpful in identifying inconsistent solver behavior on a specific machine. Additionally, recording files show model alterations such as variable additions or coefficient modifications as they are performed before, after, or even during an optimization run.
Create a recording file
Although the following description is limited to the Python API, it applies to the other Gurobi APIs.
In order to activate the recording mechanism, the Record parameter must be set to 1 before the Gurobi environment is started. This can be done in two ways:
- Create a gurobi.env file containing the line Record 1 in the working directory of your Gurobi application. By default, Gurobi searches for this file in the current working directory and initializes an environment according to the parameter settings in the file.
- Directly set the Record parameter through the API. This is done by defining an empty environment, setting the Record parameter, starting the environment, then associating the newly created environment with a model:
import gurobipy as gp
from gurobipy import GRB
e = gp.Env(empty=True) # create an empty environment
e.setParam("Record", 1) # set Record parameter to 1
e.start() # start the environment
m = gp.Model("mip1", env=e) # new model uses this environment
Using the mip1 model as an example:
x = m.addVar(vtype=GRB.BINARY, name="x")
y = m.addVar(vtype=GRB.BINARY, name="y")
z = m.addVar(vtype=GRB.BINARY, name="z")
m.setObjective(x + y + 2 * z, GRB.MAXIMIZE)
m.addConstr(x + 2 * y + 3 * z <= 4, "c0")
m.addConstr(x + y >= 1, "c1")
# dispose of model and environment post-optimization
the output confirms that Gurobi has successfully completed a recording file:
*** Start recording in file recording000.grbr
*** Recording complete - close file recording000.grbr
Gurobi will not overwrite an existing recording file in the current directory. For example, if a file named recording000.grbr already exists, Gurobi will create a new recording file named recording001.grbr.
Replay a recording file
To replay a Gurobi recording file, use the Gurobi command-line tool:
This replays the model-building and optimization, including all API calls, exactly as it was performed on the original machine where the recording file was created.
Replaying the recording from the above mip1 example produces output similar to the following:
*Replay* Replay of file 'recording000.grbr'
*Replay* Recording captured Tue Aug 18 16:42:40 2020
*Replay* Recording captured with Gurobi version 9.5.1 (mac64[x86])
*Replay* Recording captured with Gurobi Python version 9.5.1
*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
*Replay* Add 2 new constraints
*Replay* Change 3 objective coefficients
*Replay* Change objective constant to 0
*Replay* Discard Q matrix
*Replay* Update Gurobi model
Gurobi Optimizer version 9.5.1 build v9.5.1rc2 (mac64[x86])
Optimize a model with 2 rows, 3 columns and 5 nonzeros
Model fingerprint: 0xf43f5bdf
Variable types: 0 continuous, 3 integer (3 binary)
Matrix range [1e+00, 3e+00]
Objective range [1e+00, 2e+00]
Bounds range [1e+00, 1e+00]
RHS range [1e+00, 4e+00]
Found heuristic solution: objective 2.0000000
Presolve removed 2 rows and 3 columns
Presolve time: 0.00s
Presolve: All rows and columns removed
Explored 0 nodes (0 simplex iterations) in 0.00 seconds
Thread count was 1 (of 4 available processors)
Solution count 2: 3
Optimal solution found (tolerance 1.00e-04)
Best objective 3.000000000000e+00, best bound 3.000000000000e+00, gap 0.0000%
*Replay* Free Gurobi model
*Replay* Free Gurobi environment
*Replay* Replay complete
*Replay* Gurobi API routine runtime: 0.00s
*Replay* Gurobi solve routine runtime: 0.00s
Note: The order of API calls in the recording is not exact. For example, in the original Python code, the three variables were created before the objective sense was set. However, in the recording, the objective sense is set before the variables are created. This difference is due to the fact that all model changes are processed by a Model.update() call, which does not necessarily preserve the original order of function calls. In this case, the model update is implicitly performed in the Model.optimize() call.
Note: The recording output explicitly shows that the Gurobi model and environment were freed. If the environments were not properly disposed at the end of the mip1 example script, the recording output would include the following:
*Replay* Environments leaked: 1
The time spent in API routines and the actual solve time are displayed at the end of the recording.
Record multiple optimization runs
It is possible to record multiple optimization runs.
- If the existing model is modified and re-solved, these API calls will be included in the recording file. The model and environment should be disposed only after all optimization runs are complete.
- If a new model is created and solved, simply re-use the same Gurobi environment to create the new model. E.g.:
m2 = gp.Model(env=e)
Recording files are currently not compatible with callbacks. Moreover, recording files may provide false results when working with concurrent and/or distributed optimization. In addition, recording won't capture calls to the Gurobi tuning tool.