GRBEnv#

GRBEnv#

Gurobi environment object. Gurobi models are always associated with an environment. You must create an environment before you can create and populate a model. You will generally only need a single environment object in your program.

Objects of this class have unmanaged resources associated with them. The class implements the IDisposable interface.

The methods on environment objects are mainly used to manage Gurobi parameters (e.g., Get, GetParamInfo, Set).

While the .NET garbage collector will eventually collect an unused GRBEnv object, an environment will hold onto resources (Gurobi licenses, file descriptors, etc.) until that collection occurs. If your program creates multiple GRBEnv objects, we recommend that you call GRBEnv.Dispose when you are done using one (or use the .NET using statement).

GRBEnv GRBEnv()#

Constructor for GRBEnv object that creates a Gurobi environment (with logging disabled). 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.

Returns:

An environment object (with no associated log file).

Example:
// Create environment
GRBEnv env = new GRBEnv();
GRBEnv GRBEnv(string logFileName)#

Constructor for GRBEnv object that creates a Gurobi environment (with logging enabled). 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 – The desired log file name.

Returns:

An environment object.

Example:
// Create environment with associated log file
GRBEnv env = new GRBEnv("gurobi.log");
GRBEnv GRBEnv(bool empty)#

Constructor for GRBEnv object. If empty=true, creates an empty Gurobi environment. Use Start to start the environment. If empty=false, the result is the same as providing no arguments to the constructor.

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:

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.

Returns:

An environment object.

Example:
// Create empty environment
GRBEnv env = new GRBEnv(true);
// Populate Compute Server parameters
env.Set("ComputeServer", "server1:61000");
env.Set("ServerPassword", "passwd");
// Start the environment
env.Start()
void Dispose()#

Release the resources associated with a GRBEnv object. While the .NET garbage collector will eventually reclaim these resources, we recommend that you call the Dispose method when you are done using an environment if your program creates more than one.

The Dispose method on a GRBEnv should be called only after you have called Dispose on all of the models that were created within that environment. You should not attempt to use a GRBEnv object after calling Dispose.

Example:
// Create environment
GRBEnv env = new GRBEnv();
// ...
// Clean up environment
env.Dispose()
string ErrorMsg#

(Property) The error message for the most recent exception associated with this environment.

double Get(GRB.DoubleParam param)#

Query the value of a double-valued parameter.

Parameters:

param – The parameter being queried. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

Returns:

The current value of the requested parameter.

Example:
// Query value of TimeLimit parameter
double value = env.Get(GRB.DoubleParam.TimeLimit);
int Get(GRB.IntParam param)#

Query the value of an int-valued parameter.

Parameters:

param – The parameter being queried. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

Returns:

The current value of the requested parameter.

Example:
// Query value of PumpPasses parameter
int value = env.Get(GRB.IntParam.PumpPasses);
string Get(GRB.StringParam param)#

Query the value of a string-valued parameter.

Parameters:

param – The parameter being queried. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

Returns:

The current value of the requested parameter.

Example:
// Query value of LogFile parameter
string value = env.Get(GRB.StringParam.LogFile);
void GetParamInfo(GRB.DoubleParam param, double[] info)#

Obtain detailed information about a double parameter.

Parameters:

  • param – The parameter of interest. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

  • info – The returned information. The result will contain four entries: the current value of the parameter, the minimum allowed value, the maximum allowed value, and the default value. Memory allocation for the info array has to be performed by the caller.

Example:
// Query information about TimeLimit parameter
double[] doubleInfo = new double[4];
env.GetParamInfo(GRB.DoubleParam.TimeLimit, doubleInfo);
void GetParamInfo(GRB.IntParam param, int[] info)#

Obtain detailed information about an integer parameter.

Parameters:

  • param – The parameter of interest. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

  • info – The returned information. The result will contain four entries: the current value of the parameter, the minimum allowed value, the maximum allowed value, and the default value. Memory allocation for the info array has to be performed by the caller.

Example:
// Query information about PumpPasses parameter
int[] IntInfo = new int[4];
env.GetParamInfo(GRB.IntParam.PumpPasses, IntInfo);
void GetParamInfo(GRB.StringParam param, string[] info)#

Obtain detailed information about a string parameter.

Parameters:

  • param – The parameter of interest. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

  • info – The returned information. The result will contain two entries: the current value of the parameter and the default value. Memory allocation for the info array has to be performed by the caller.

Example:
// Query information about LogFile parameter
string[] StringInfo = new string[2];
env.GetParamInfo(GRB.StringParam.LogFile, StringInfo);
void Message(string message)#

Write a message to the console and the log file.

Parameters:

message – The message to be written.

Note

This call has no effect unless the OutputFlag parameter is set. In addition, it is ignored from within a MESSAGE callback (see WHERE values) and logging callback. The console logging can be controled with LogToConsole.

Example:
// Write message
env.Message("Hello Gurobi!");
void ReadParams(string paramfile)#

Read new parameter settings from a file.

Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

Parameters should be listed one per line, with the parameter name first and the desired value second. For example:

# Gurobi parameter file
Threads 1
MIPGap 0

Blank lines and lines that begin with the hash symbol are ignored.

Parameters:

paramfile – Name of the file containing parameter settings.

Example:
// Read params.prm file
env.ReadParams("params.prm");
void Release()#

Release the license associated with this environment. You will no longer be able to call Optimize on models created with this environment after the license has been released.

Example:
// Release license from environment
env.Release();
void ResetParams()#

Reset all parameters to their default values.

Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

Example:
// Reset all parameters to their default values
env.ResetParams();
void Set(GRB.DoubleParam param, double newvalue)#

Set the value of a double-valued parameter.

Parameters:

  • param – The parameter being modified. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

  • newvalue – The desired new value of the parameter.

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 the appropriate version of the overloaded method GRBModel.Set to change a parameter on an existing model.

Example:
// Set TimeLimit parameter
env.Set(GRB.DoubleParam.TimeLimit, 2.0);
void Set(GRB.IntParam param, int newvalue)#

Set the value of an int-valued parameter.

Parameters:

  • param – The parameter being modified. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

  • newvalue – The desired new value of the parameter.

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 the appropriate version of the overloaded method GRBModel.Set to change a parameter on an existing model.

Example:
// Set PumpPasses parameter
env.Set(GRB.IntParam.PumpPasses, 10);
void Set(GRB.StringParam param, string newvalue)#

Set the value of a string-valued parameter.

Parameters:

  • param – The parameter being modified. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

  • newvalue – The desired new value of the parameter.

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 the appropriate version of the overloaded method GRBModel.Set to change a parameter on an existing model.

Example:
// Set LogFile parameter
env.Set(GRB.StringParam.LogFile, "myLog.log");
void Set(string param, string newvalue)#

Set the value of any parameter using strings alone.

Parameters:

  • param – The name of the parameter being modified. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

  • newvalue – The desired new value of the parameter.

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 the appropriate version of the overloaded method GRBModel.Set to change a parameter on an existing model.

Example:
// Set TimeLimit parameter via strings
env.Set("TimeLimit", "2.0");
void 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.

Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

Example:
// Create empty environment
GRBEnv env = new GRBEnv(true);
// Populate Compute Server parameters
env.Set("ComputeServer", "server1:61000");
env.Set("ServerPassword", "passwd");
// Start the environment
env.Start();
void WriteParams(string paramfile)#

Write all non-default parameter settings to a file.

Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

Parameters:

paramfile – Name of the file to which non-default parameter settings should be written. The previous contents are overwritten.

Example:
// Write all non-default parameters to file
env.WriteParams("myParams.prm");