Environment Creation and Destruction#

intGRBloadenv(GRBenv**envP,constchar*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 yourgurobi.licfile. This routine will also check the current working directory for afile namedgurobi.env, and it will attempt to read parameter settingsfrom this file if it exists. The file should be inPRMformat (briefly, each line should contain a parameter name, followed by thedesired value for that parameter).

In general, you should aim to create asingle Gurobi environment in your program, even if you plan to work withmultiple models. Reusing one environment is much more efficient thancreating and destroying multiple environments. The one exception is ifyou are writing a multi-threaded program, since environments are notthread safe. In this case, you will need a separate environment for eachof your threads.

Return value:

A non-zero return value indicates that there was a problemcreating the environment. Refer to theError Codes tablefor a list of possible return values.

Arguments:

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

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

intGRBemptyenv(GRBenv**envP)#

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

You should use this routine if you want to set parameters beforeactually starting the environment. This can be useful if you want toconnect to a Compute Server, a Token Server, the Gurobi Instant Cloud, aCluster Manager or use a WLS license. See theEnvironment Section for more details.

Return value:

A non-zero return value indicates that there was a problemcreating the environment. Refer to theError Codes tablefor a list of possible return values.

Arguments:

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

intGRBstartenv(GRBenv*env)#

Start an empty environment. This routine starts an empty environmentcreated byGRBemptyenv. If the environment has already beenstarted, this routine will do nothing. If the routine fails, theenvironment will have the same state as it had before the call to thisfunction.

This routine will also populate any parameter(ComputeServer,TokenServer,ServerPassword, etc.) specified in yourgurobi.licfile. This routine will also check the current working directory for afile namedgurobi.env, and it will attempt to read parameter settingsfrom this file if it exists. The file should be inPRMformat (briefly, each line should contain a parameter name, followed by thedesired value for that parameter). After that, it will apply all parameterchanges specified by the user prior to this call. Note that this mightoverwrite parameters set in the license file, or in thegurobi.envfile, if present.

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

In general, you should aim to create asingle Gurobi environment in your program, even if you plan to work withmultiple models. Reusing one environment is much more efficient thancreating and destroying multiple environments. The one exception is ifyou are writing a multi-threaded program, since environments are notthread safe. In this case, you will need a separate environment for eachof your threads.

Return value:

A non-zero return value indicates that there was a problemstarting the environment. Refer to theError Codes tablefor a list of possible return values.

Arguments:

• env – The empty environment to start.

voidGRBfreeenv(GRBenv*env)#

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

Arguments:

• env – The environment to be freed.

GRBenv*GRBgetconcurrentenv(GRBmodel*model,intnum)#

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 appropriateparameters on these environments (e.g., theMethodparameter), you can control exactly which strategies the concurrentoptimizer employs. For example, if you create two concurrent environments,and setMethod to primal simplex for one and dual simplexfor the other, subsequent concurrent optimizer runs will use the twosimplex algorithms rather than the default choices.

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

Once you create concurrent environments, they will be used for everysubsequent concurrent optimization on that model. UseGRBdiscardconcurrentenvs to revert back to default concurrentoptimizer behavior.

Return value:

The concurrent environment. ANULL return valueindicates 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,intnum)#

Create/retrieve a multi-objective environment for the optimization passwith the given index. This environment enables fine-grained control overthe multi-objective optimization process. Specifically, by changingparameters on this environment, you modify the behavior of theoptimization that occurs during the corresponding pass of themulti-objective optimization.

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

Please refer to the discussion ofMultiple Objectives for information onhow to specify multiple objective functions and control the trade-offbetween them.

Please refer to the discussion onCombining Blended and Hierarchical Objectivesfor information on the optimization passes to solve multi-objectivemodels.

Return value:

The environment associated with a given optimization passwhen solving the multi-objective model. ANULL return value indicatesthat there was a problem retrieving the environment.

Arguments:

• model – The model from where we want to retrieve the multi-objectiveenvironment.

• 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);

voidGRBdiscardconcurrentenvs(GRBmodel*model)#

Discard concurrent environments for a model.

The concurrent environments created byGRBgetconcurrentenvwill be used by every subsequent call to the concurrent optimizer untilthe concurrent environments are discarded.

Arguments:

• model – The model for the concurrent environment.

Example:

GRBdiscardconcurrentenvs(model);

voidGRBdiscardmultiobjenvs(GRBmodel*model)#

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

Please refer to the discussion ofMultiple Objectives for information onhow to specify multiple objective functions and control the trade-offbetween them.

Arguments:

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

Example:

GRBenv*env0=GRBgetmultiobjenv(model,0);GRBenv*env1=GRBgetmultiobjenv(model,1);GRBsetintparam(env0,"Method",2);GRBsetintparam(env1,"Method",1);GRBoptimize(model);GRBdiscardmultiobjenvs(model);