initGurobiNumericalOptimizationExperimentalDesignObject: Begin Gurobi Optimized Search

In GreedyExperimentalDesign: Greedy Experimental Design Construction

Begin Gurobi Optimized Search

Description

This method creates an object of type optimal_experimental_design and will immediately initiate a search through allocation space for forced balance designs. Make sure you setup Gurobi properly first. This means applying for a license, downloading, installing, registering it on your computer using the grbgetkey command with the license file in the default directory. Then, in R, install the package from the file in your gurobi directory.

Usage

initGurobiNumericalOptimizationExperimentalDesignObject(
  X = NULL,
  objective = "mahal_dist",
  Kgram = NULL,
  num_cores = 2,
  w_0 = NULL,
  initial_time_limit_sec = 5 * 60,
  restart_time_limit_sec = 60,
  max_number_of_restarts = 0,
  max_no_good_cuts = 0,
  verbose = TRUE,
  gurobi_params = list(),
  use_safe_inverse = FALSE,
  r,
  pool_solutions = NULL,
  pool_gap = 0.2,
  pool_gap_abs = NULL,
  pool_search_mode = 2,
  mip_gap = 1e-04,
  mip_gap_abs = 1e-10,
  mip_focus = 1,
  heuristics = 0.2,
  cuts = 2,
  presolve = 2
)

Arguments

X	The design matrix with $n$ rows (one for each subject) and $p$ columns (one for each measurement on the subject). This is the design matrix you wish to search for a more optimal design.
objective	The objective function to use when searching design space. This is a string with valid values "mahal_dist" (the default) or "kernel".
Kgram	If the objective = kernel, this argument is required to be an n x n matrix whose entries are the evaluation of the kernel function between subject i and subject j. Default is NULL.
num_cores	Number of cores to use during search. Default is 2.
w_0	The initial starting location (optional).
initial_time_limit_sec	The maximum amount of time the optimizer can run for in seconds. The default is 5 * 60.
restart_time_limit_sec	The maximum amount of time each restart can run for in seconds. The default is 60.
max_number_of_restarts	The maximum number of restarts to attempt if too few unique solutions are returned. Default is 0.
max_no_good_cuts	The maximum number of no-good cuts to attempt. Default is 0 (disabled).
verbose	Should Gurobi log to console? Default is TRUE.
gurobi_params	A list of optional parameters to be passed to Gurobi (see their documentation online).
use_safe_inverse	Should a regularized inverse be used for the Mahalanobis objective? Default is FALSE.
r	Number of solution vectors to request from the Gurobi pool.
pool_solutions	Number of solutions to request from the Gurobi pool. Defaults to 10 * r.
pool_gap	Relative optimality gap for the pool. Default is 0.2. Use NULL to skip.
pool_gap_abs	Absolute optimality gap for the pool. Default is NULL to skip.
pool_search_mode	Solution pool search mode. Default is 2 for diverse solutions.
mip_gap	Relative MIP gap target (stops when |best-bound - best-incumbent| / |best-incumbent| <= mip_gap). Lower values force deeper search. Default is 1e-4.
mip_gap_abs	Absolute MIP gap target (stops when |best-bound - best-incumbent| <= mip_gap_abs). Lower values force deeper search. Default is 1e-10.
mip_focus	Search focus: 0 (balance), 1 (find feasible solutions), 2 (prove optimality), 3 (bound improvement). Default is 1.
heuristics	Heuristics effort in [0,1] where higher values spend more time on heuristics. Default is 0.2.
cuts	Cut aggressiveness: -1 (automatic), 0 (off), 1 (conservative), 2 (aggressive), 3 (very aggressive). Default is 2.
presolve	Presolve aggressiveness: -1 (automatic), 0 (off), 1 (conservative), 2 (aggressive). Default is 2.

Details

Currently, this method does not return multiple vectors. This will be improved in a later version. If you want this functionality now, use the hacked-up method gurobi_multiple_designs.

Value

A list object which houses the results from Gurobi. Depending on the gurobi_parms, the data within will be different. The most relevant tags are x for the best found solution and objval for the object

Author(s)

Adam Kapelner

Examples

## Not run: 
if ("gurobi" %in% loadedNamespaces()) {
  set.seed(1)
  X = matrix(rnorm(12), nrow = 6)
  gobj = initGurobiNumericalOptimizationExperimentalDesignObject(
    X,
    r = 2,
    num_cores = 1,
    initial_time_limit_sec = 5,
    verbose = FALSE
  )
  gobj$n
}

## End(Not run)

GreedyExperimentalDesign documentation built on Jan. 9, 2026, 5:07 p.m.