Python API - Env#

class Env#

Gurobi environment object. Note that environments play a much smaller role in the Python interface than they do in other Gurobi language APIs, mainly because the Python interface has a default environment. Unless you explicitly pass your own environment to routines that require an environment, the default environment will be used.

The primary situations where you will want to use your own environment are:

  • When you are using a Gurobi Compute Server and want to choose the server from within your program.

  • When you need control over garbage collection of your environment. The Gurobi Python interface maintains a reference to the default environment, so by default it will never be garbage collected. By creating your own environment, you can control exactly when your program releases any licensing tokens or Compute Servers it is using.

  • When you are using concurrent environments in one of the concurrent optimizers.

It is good practice to use the with keyword when dealing with environment (and model) objects. That way the resources tied to these objects are properly released even if an exception is raised at some point. The following example illustrates two typical use patterns.

Example:
import gurobipy as gp
with gp.Env("gurobi.log") as env, gp.Model(env=env) as model:
    # Populate model object here...
    model.optimize()

with gp.Env(empty=True) as env:
    env.setParam("ComputeServer", "myserver1:32123")
    env.setParam("ServerPassword", "pass")
    env.start()
    with gp.Model(env=env) as model:
        # Populate model object here...
        model.optimize()

Note that you can manually remove the reference to the default environment by calling disposeDefaultEnv. After calling this, and after all models built within the default environment are garbage collected, the default environment will be garbage collected as well. A new default environment will be created automatically if you call a routine that needs one.

Env(logfilename='', empty=False, params=None)#

Env constructor. You will generally want to use the default environment in Gurobi Python programs. The exception is when you want explicit control over environment garbage collection. By creating your own environment object and always passing it to methods that take an environment as input (read or the Model constructor), you will avoid creating the default environment. Once every model created using an Env object is garbage collected, and once the Env object itself is no longer referenced, the garbage collector will reclaim the environment and release all associated resources.

If the environment is not empty, This method will also populate any parameter (ComputeServer, TokenServer, ServerPassword, etc.) specified in your gurobi.lic file. This method will also check the current working directory for a file named gurobi.env, and it will attempt to read parameter settings from this file if it exists. The file should be in PRM format (briefly, each line should contain a parameter name, followed by the desired value for that parameter).

In general, you should aim to create a single Gurobi environment in your program, even if you plan to work with multiple models. Reusing one environment is much more efficient than creating and destroying multiple environments. The one exception is if you are writing a multi-threaded program, since environments are not thread safe. In this case, you will need a separate environment for each of your threads.

Parameters:

  • logfilename – Name of the log file for this environment. Pass an empty string if you don’t want a log file.

  • empty – Indicates whether the environment should be empty. You should use empty=True if you want to set parameters before actually starting the environment. This can be useful if you want to connect to a Compute Server, a Token Server, the Gurobi Instant Cloud, a Cluster Manager or use a WLS license. See the Environment Section for more details.

  • params – A dict containing Gurobi parameter/value pairs that should be set already upon environment creation. Any server related parameters can be set through this dict, too.

Returns:

New environment object.

Example:
env = gp.Env("gurobi.log")
model = gp.read("misc07.mps", env)
model.optimize()
Example:
p = {"ComputeServer": "localhost:33322",
     "ServerPassword": "pass",
     "TimeLimit": 120.0}
with gp.Env(params=p) as env, gp.read('misc07.mps', env=env) as model:
    model.optimize()
close()#

Free all resources associated with this Env object. This method is a synonym for dispose.

Users should close all models created in this environment before closing this Env object.

After this method is called, this Env object must no longer be used.

Example:
env = gp.Env()
model = gp.read("misc07.mps", env)
model.optimize()
model.close()
env.close()
dispose()#

Free all resources associated with this Env object. This method is a synonym for close.

Users should dispose of all models created in this environment before disposing of this Env object.

After this method is called, this Env object must no longer be used.

Example:
env = gp.Env()
model = gp.read("misc07.mps", env)
model.optimize()
model.dispose()
env.dispose()
getParam(paramname)#

Get the current value of a given parameter.

Parameters:

paramname – String containing the name of parameter that you would like to query. Note that case is ignored.

Returns:

Current value of the parameter in this environment

resetParams()#

Reset the values of all parameters to their default values.

Example:
env.resetParams()
setParam(paramname, newvalue)#

Set the value of a parameter to a new value.

Parameters:

  • paramname – String containing the name of parameter that you would like to modify. The name can include ‘*’ and ‘?’ wildcards. If more than one parameter matches, a GurobiError is raised with the matching names listed, and no parameters are modified. Note that case is ignored.

  • newvalue – Desired new value for parameter. Can be ‘default’, which indicates that the parameter should be reset to its default value.

Note

Note that a model gets its own copy of the environment when it is created. Changes to the original environment have no effect on the copy, and vice versa. Use Model.setParam to change a parameter on an existing model.

Example:
env.setParam("Cuts", 2)
env.setParam("Heu*", 0.5)
env.setParam("*Interval", 10)
start()#

Start an empty environment. If the environment has already been started, this method will do nothing. If the call fails, the environment will have the same state as it had before the call to this method.

This method will also populate any parameter (ComputeServer, TokenServer, ServerPassword, etc.) specified in your gurobi.lic file. This method will also check the current working directory for a file named gurobi.env, and it will attempt to read parameter settings from this file if it exists. The file should be in PRM format (briefly, each line should contain a parameter name, followed by the desired value for that parameter). After that, it will apply all parameter changes specified by the user prior to this call. Note that this might overwrite parameters set in the license file, or in the gurobi.env file, if present.

After all these changes are performed, the code will actually activate the environment, and make it ready to work with models.

In general, you should aim to create a single Gurobi environment in your program, even if you plan to work with multiple models. Reusing one environment is much more efficient than creating and destroying multiple environments. The one exception is if you are writing a multi-threaded program, since environments are not thread safe. In this case, you will need a separate environment for each of your threads.

Example:
env = gp.Env(empty=True)
env.setParam('ComputeServer', 'server.mydomain.com:61000')
env.setParam('ServerPassword', 'mypassword')
env.start()
writeParams(filename)#

Write all modified parameters to a file. The file is written in PRM format.

Example:
env.setParam("Heu*", 0.5)
env.writeParams("params.prm")  # file will contain changed parameter
system("cat params.prm")