Begin Gurobi Optimized Search

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.

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

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.

Author

Adam Kapelner

Examples

if (FALSE) { # \dontrun{
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
}
} # }