Environment Creation and Destruction

int GRBloadenv(GRBenv **envP, const char *logfilename)

Create an environment. Optimization models live within an environment, so this is typically the first Gurobi routine called in an application.

This routine will also populate any parameter (ComputeServer, TokenServer, ServerPassword, etc.) specified in your gurobi.lic file. This routine 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.

Return value:

A non-zero return value indicates that there was a problem creating the environment. Refer to the Error Codes table for a list of possible return values.

Arguments:

• envP – The location in which the pointer to the newly created environment should be placed.

• logfilename – The name of the log file for this environment. May be NULL (or an empty string), in which case no log file is created.

int GRBemptyenv(GRBenv **envP)

Create an empty environment. Note that you will need to call GRBstartenv before you can use this environment.

You should use this routine 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.

Return value:

A non-zero return value indicates that there was a problem creating the environment. Refer to the Error Codes table for a list of possible return values.

Arguments:

• envP – The location in which the pointer to the newly created environment should be placed.

int GRBstartenv(GRBenv *env)

Start an empty environment. This routine starts an empty environment created by GRBemptyenv. If the environment has already been started, this routine will do nothing. If the routine fails, the environment will have the same state as it had before the call to this function.

This routine will also populate any parameter (ComputeServer, TokenServer, ServerPassword, etc.) specified in your gurobi.lic file. This routine 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.

Return value:

A non-zero return value indicates that there was a problem starting the environment. Refer to the Error Codes table for a list of possible return values.

Arguments:

• env – The empty environment to start.

void GRBfreeenv(GRBenv *env)

Free an environment that was previously allocated by GRBloadenv, and release the associated memory. This routine should be called when an environment is no longer needed. In particular, it should only be called once all models built using the environment have been freed.

Arguments:

• env – The environment to be freed.

GRBenv *GRBgetconcurrentenv(GRBmodel *model, int num)

Create/retrieve a concurrent environment for a model.

This routine provides fine-grained control over the concurrent optimizer. By creating your own concurrent environments and setting appropriate parameters on these environments (e.g., the Method parameter), you can control exactly which strategies the concurrent optimizer employs. For example, if you create two concurrent environments, and set Method to primal simplex for one and dual simplex for the other, subsequent concurrent optimizer runs will use the two simplex algorithms rather than the default choices.

Note that you must create contiguously numbered concurrent environments, starting with num=0. For example, if you want three concurrent environments, they must be numbered 0, 1, and 2.

Once you create concurrent environments, they will be used for every subsequent concurrent optimization on that model. Use GRBdiscardconcurrentenvs to revert back to default concurrent optimizer behavior.

Return value:

The concurrent environment. A NULL return value indicates that there was a problem creating the environment.

Arguments:

• model – The model for the concurrent environment.

• num – The concurrent environment number.

Example:

GRBenv *env0 = GRBgetconcurrentenv(model, 0);
GRBenv *env1 = GRBgetconcurrentenv(model, 1);

GRBenv *GRBgetmultiobjenv(GRBmodel *model, int num)

Create/retrieve a multi-objective environment for the optimization pass with the given index. This environment enables fine-grained control over the multi-objective optimization process. Specifically, by changing parameters on this environment, you modify the behavior of the optimization that occurs during the corresponding pass of the multi-objective optimization.

Each multi-objective environment starts with a copy of the current model environment.

Please refer to the discussion of Multiple Objectives for information on how to specify multiple objective functions and control the trade-off between them.

Please refer to the discussion on Combining Blended and Hierarchical Objectives for information on the optimization passes to solve multi-objective models.

Return value:

The environment associated with a given optimization pass when solving the multiobjective model. A NULL return value indicates that there was a problem retrieving the environment.

Arguments:

• model – The model from where we want to retrieve the multiobjective environment.

• num – The optimization pass number, starting from 0.

Example:

GRBenv *env0 = GRBgetmultiobjenv(model,0);
GRBenv *env1 = GRBgetmultiobjenv(model,1);

GRBsetintparam(env0, "Method", 2);
GRBsetintparam(env1, "Method", 1);

GRBoptimize(model);

GRBdiscardmultiobjenvs(model);

void GRBdiscardconcurrentenvs(GRBmodel *model)

Discard concurrent environments for a model.

The concurrent environments created by GRBgetconcurrentenv will be used by every subsequent call to the concurrent optimizer until the concurrent environments are discarded.

Arguments:

• model – The model for the concurrent environment.

Example:

GRBdiscardconcurrentenvs(model);

void GRBdiscardmultiobjenvs(GRBmodel *model)

Discard all multi-objective environments associated with the model, thus restoring multi objective optimization to its default behavior.

Please refer to the discussion of Multiple Objectives for information on how to specify multiple objective functions and control the trade-off between them.

Arguments:

• model – The model in which all multi objective environments will be discarded.

Example:

GRBenv *env0 = GRBgetmultiobjenv(model,0);
GRBenv *env1 = GRBgetmultiobjenv(model,1);

GRBsetintparam(env0, "Method", 2);
GRBsetintparam(env1, "Method", 1);

GRBoptimize(model);

GRBdiscardmultiobjenvs(model);