Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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.

  The methods on environment objects are mainly used to manage Gurobi parameters (e.g., `get`, `getParamInfo`, `set`).

  While the Java 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.

  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.

    Return value:

      An environment object (with no associated log file).

    Example:

          // Create environment
          GRBEnv env = new GRBEnv();

  GRBEnv GRBEnv(boolean empty)

    Constructor for `GRBEnv` object. If `empty=true`, creates an empty 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.

    Arguments:

      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.

    Return value:

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

  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.

    Arguments:

      logFileName – The desired log file name.

    Return value:

      An environment object.

    Example:

          // Create environment with associated log file
          GRBEnv env = new GRBEnv("gurobi.log");

  void dispose()

    Release the resources associated with a `GRBEnv` object. While the Java 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()

  double get(GRB.DoubleParam param)
  int get(GRB.IntParam param)
  String get(GRB.StringParam param)

    Query the value of a parameter.

    Arguments:

      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.

    Return value:

      The current value of the requested parameter.

    Example:

          // Query value of TimeLimit parameter
          double timelimit = env.get(GRB.DoubleParam.TimeLimit);
          // Query value of PumpPasses parameter
          int pumppasses = env.get(GRB.IntParam.PumpPasses);
          // Query value of LogFile parameter
          String logfile = env.get(GRB.StringParam.LogFile);

  String getErrorMsg()

    Query the error message for the most recent exception associated with this environment.

    Return value:

      The error string.

    Example:

          // Query the error message of the most recent exception
          String msg = env.getErrorMsg();

  void getParamInfo(GRB.DoubleParam param, double[] info)
  void getParamInfo(GRB.IntParam param, int[] info)
  void getParamInfo(GRB.StringParam param, String[] info)

    Obtain detailed information about a parameter.

    Arguments:

      - 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. For double and integer parameters, the result will contain four entries: the current value of the parameter, the minimum allowed value, the maximum allowed value, and the default value. For string parameters, the result will contain two entries: the current value of the parameter and the default value.

    Example:

          // Query information about TimeLimit parameter
          double[] timelimit = new double[4];
          env.getParamInfo(GRB.DoubleParam.TimeLimit, timelimit);
          // Query information about PumpPasses parameter
          int[] pumppasses = new int[4];
          env.getParamInfo(GRB.IntParam.PumpPasses, pumppasses);
          // Query information about LogFile parameter
          String[] logfile = new String[2];
          env.getParamInfo(GRB.StringParam.LogFile, logfile);

  void message(String message)

    Write a message to the console and the log file.

    Arguments:

      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.

    Arguments:

      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 newval)
  void set(GRB.IntParam param, int newval)
  void set(GRB.StringParam param, String newval)

    Set the value of a parameter.

    Arguments:

      - 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.

      - newval – 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);
          // Set PumpPasses parameter
          env.set(GRB.IntParam.PumpPasses, 10);
          // Set LogFile parameter
          env.set(GRB.StringParam.LogFile, "mylog.log");

  void set(String param, String newval)

    Set the value of any parameter using strings alone.

    Arguments:

      - 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.

      - newval – 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 setLogCallback(java.util.function.Consumer<String> logCallback)

    Sets a logging callback function to query all output posted by the environment object. Can be set after an empty environment was created.

    Arguments:

      logCallback – The logging callback function.

  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.

    Arguments:

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

Help and Feedback

Press `/` or click to search this documentation | Gurobi website | Gurobi community forum
Go to other Gurobi documentation | Gurobi download | Contact support