1
 #' @include RcppExports.R raptr-internal.R misc.R
2
NULL
3

4
#' GurobiOpts: An S4 class to represent Gurobi parameters
5
#'
6
#' This class is used to store Gurobi input parameters.
7
#'
8
#' @slot Threads `integer` number of cores to use for processing. Defaults
9
#'   to 1L.
10
#'
11
#' @slot MIPGap `numeric` MIP gap specifying minimum solution quality.
12
#'   Defaults to 0.1.
13
#'
14
#' @slot Method `integer` Algorithm to use for solving model. Defaults to
15
#'   0L.
16
#'
17
#' @slot Presolve `integer` code for level of computation in presolve.
18
#'  Defaults to 2.
19
#'
20
#' @slot TimeLimit `integer` number of seconds to allow for solving.
21
#'   Defaults to NA_integer_, and so a time limit is not imposed.
22
#'
23
#' @slot NumberSolutions `integer` number of solutions to generate.
24
#'   Defaults to 1L.
25
#'
26
#' @slot MultipleSolutionsMethod `integer` name of method to obtain
27
#'   multiple solutions (used when `NumberSolutions` is greater than one).
28
#'   Available options are `"benders.cuts"`, `"solution.pool.0"`,
29
#'   `"solution.pool.1"`, and `"solution.pool.2"`. The
30
#'   `"benders.cuts"` method produces a set of distinct solutions that
31
#'   are all within the optimality gap. The `"solution.pool.0"`
32
#'   method returns all solutions identified whilst trying to find
33
#'   a solution that is within the specified optimality gap. The
34
#'   `"solution.pool.1"` method finds one solution within the optimality
35
#'   gap and a number of additional solutions that are of any level of quality
36
#'   (such that the total number of solutions is equal to
37
#'   `number_solutions`). The `"solution.pool.2"` finds a
38
#'   specified number of solutions that are nearest to optimality. The
39
#'   search pool methods correspond to the parameters used by the Gurobi
40
#'   software suite (see <http://www.gurobi.com/documentation/8.0/refman/poolsearchmode.html#parameter:PoolSearchMode>).
41
#'   Defaults to `"benders.cuts"`.
42
#'
43
#' @seealso [GurobiOpts()].
44
#'
45
#' @name GurobiOpts-class
46
#'
47
#' @rdname GurobiOpts-class
48
#'
49
#' @exportClass GurobiOpts
50
methods::setClass("GurobiOpts",
51
  methods::representation(Threads = "integer", MIPGap = "numeric",
52
                          Method = "integer", Presolve = "integer",
53
                          TimeLimit = "integer", NumberSolutions = "integer",
54
                          MultipleSolutionsMethod = "character"),
55
  prototype = list(Threads = 1L, MIPGap = 0.1, Method = 0L, Presolve = 2L,
56
                   TimeLimit = NA_integer_, NumberSolutions = 1L,
57
                   MultipleSolutionsMethod = "benders.cuts"),
58
  contains = "SolverOpts",
59
  validity = function(object) {
60
    # NumberSolutions
61
    assertthat::assert_that(assertthat::is.count(object@NumberSolutions),
62
                            is.finite(object@NumberSolutions))
63
    # TimeLimit
64
    assertthat::assert_that(is.integer(object@NumberSolutions))
65
    # Threads
66
    assertthat::assert_that(assertthat::is.count(object@Threads),
67
                            is.finite(object@Threads),
68
                            object@Threads <= parallel::detectCores(logical =
69
                                                                      TRUE))
70
    # MultipleSolutionsMethod
71
    assertthat::assert_that(
72
      assertthat::is.string(object@MultipleSolutionsMethod),
73
      object@MultipleSolutionsMethod %in%
74
      c("benders.cuts", "solution.pool.0", "solution.pool.1",
75
        "solution.pool.2"))
76
    # Presolve
77
    assertthat::assert_that(assertthat::is.scalar(object@Presolve),
78
                            is.finite(object@Presolve),
79
                            is.integer(object@Presolve),
80
                            object@Presolve <= 2, object@Presolve >= -1)
81
    # Method
82
    assertthat::assert_that(assertthat::is.scalar(object@Method),
83
                            is.finite(object@Method),
84
                            is.integer(object@Method),
85
                            object@Method <= 4, object@Method >= -1)
86
    # MIPGap
87
    assertthat::assert_that(assertthat::is.scalar(object@MIPGap),
88
                            is.finite(object@MIPGap), object@MIPGap >= 0)
89
    return(TRUE)
90
  }
91
)
92

93
#' Create GurobiOpts object
94
#'
95
#' This function creates a new GurobiOpts object.
96
#'
97
#' @param Threads `integer` number of cores to use for processing.
98
#'   Defaults to 1L.
99
#'
100
#' @param MIPGap `numeric` MIP gap specifying minimum solution quality.
101
#'   Defaults to 0.1.
102
#'
103
#' @param Method `integer` Algorithm to use for solving model. Defaults to
104
#'   0L.
105
#'
106
#' @param Presolve `integer` code for level of computation in presolve
107
#'   (lp_solve parameter). Defaults to 2.
108
#'
109
#' @param TimeLimit `integer` number of seconds to allow for solving.
110
#'   Defaults to `NA_integer_`, and so a time limit is not imposed.
111
#'
112
#' @param NumberSolutions `integer` number of solutions to generate.
113
#'   Defaults to 1L.
114
#'
115
#' @param MultipleSolutionsMethod `integer` name of method to obtain
116
#'   multiple solutions (used when `NumberSolutions` is greater than one).
117
#'   Available options are `"benders.cuts"`, `"solution.pool.0"`,
118
#'   `"solution.pool.1"`, and `"solution.pool.2"`. The
119
#'   `"benders.cuts"` method produces a set of distinct solutions that
120
#'   are all within the optimality gap. The `"solution.pool.0"`
121
#'   method returns all solutions identified whilst trying to find
122
#'   a solution that is within the specified optimality gap. The
123
#'   `"solution.pool.1"` method finds one solution within the optimality
124
#'   gap and a number of additional solutions that are of any level of quality
125
#'   (such that the total number of solutions is equal to
126
#'   `number_solutions`). The `"solution.pool.2"` finds a
127
#'   specified number of solutions that are nearest to optimality. The
128
#'   search pool methods correspond to the parameters used by the Gurobi
129
#'   software suite (see <http://www.gurobi.com/documentation/8.0/refman/poolsearchmode.html#parameter:PoolSearchMode>).
130
#'   Defaults to `"benders.cuts"`.
131
#'
132
#' @return `GurobiOpts` object
133
#'
134
#' @seealso [GurobiOpts-class].
135
#'
136
#' @examples
137
#' # create GurobiOpts object using default parameters
138
#' GurobiOpts(Threads = 1L, MIPGap = 0.1, Method = 0L, Presolve=2L,
139
#'            TimeLimit = NA_integer_, NumberSolutions = 1L)
140
#'
141
#' @export
142
GurobiOpts <- function(Threads = 1L, MIPGap = 0.1, Method = 0L, Presolve = 2L,
143
                       TimeLimit = NA_integer_, NumberSolutions = 1L,
144
                       MultipleSolutionsMethod = c("benders.cuts",
145
                                                   "solution.pool.0",
146
                                                   "solution.pool.1",
147
                                                   "solution.pool.2")[1]) {
148 4
  go <- methods::new("GurobiOpts", Threads = Threads, MIPGap = MIPGap,
149 4
                     Method = Method, Presolve = Presolve,
150 4
                     TimeLimit = TimeLimit, NumberSolutions = NumberSolutions,
151 4
                     MultipleSolutionsMethod = MultipleSolutionsMethod)
152 4
  methods::validObject(go, test = FALSE)
153 4
  return(go)
154
}
155

156
#' @method print GurobiOpts
157
#'
158
#' @rdname print
159
#'
160
#' @export
161
print.GurobiOpts <- function(x, ..., header=TRUE) {
162 0
  assertthat::assert_that(assertthat::is.flag(header))
163 0
  if (header) {
164 0
    message("GurobiOpts object.")
165
  } else {
166 0
    message("  Method: Gurobi")
167
  }
168 0
  message("  Threads: ", x@Threads)
169 0
  message("  MIPGap: ", x@MIPGap)
170 0
  message("  Method: ", x@Method)
171 0
  message("  Presolve: ", x@Presolve)
172 0
  message("  TimeLimit: ", x@TimeLimit)
173 0
  message("  NumberSolutions: ", x@NumberSolutions)
174 0
  message("  MultipleSolutionsMethod: ", x@MultipleSolutionsMethod)
175
}
176

177
#' @rdname show
178
#'
179
#' @usage \S4method{show}{GurobiOpts}(object)
180
#'
181
#' @name show
182
#'
183
#' @aliases show,GurobiOpts-method
184
methods::setMethod("show", "GurobiOpts",
185 0
                   function(object) print.GurobiOpts(object))
186

187
#' @method as.list GurobiOpts
188
#'
189
#' @rdname as.list
190
#'
191
#' @export
192
as.list.GurobiOpts <- function(x, ...) {
193 4
  y <- list(Threads = x@Threads, MIPGap = x@MIPGap, Presolve = x@Presolve,
194 4
            Method = x@Method)
195 4
  if (is.finite(x@TimeLimit))
196 0
    y$TimeLimit <- x@TimeLimit
197 4
  return(y)
198
}
199

200
#' @rdname update
201
#'
202
#' @method update GurobiOpts
203
#'
204
#' @export
205
update.GurobiOpts <- function(object, Threads = NULL, MIPGap = NULL,
206
                              Method = NULL, Presolve = NULL, TimeLimit = NULL,
207
                              NumberSolutions = NULL,
208
                              MultipleSolutionsMethod = NULL, ...) {
209
  # update arguments
210 4
  if (!is.null(Threads))
211 0
    object@Threads <- Threads
212 4
  if (!is.null(MIPGap))
213 4
    object@MIPGap <- MIPGap
214 4
  if (!is.null(Method))
215 4
    object@Method <- Method
216 4
  if (!is.null(Presolve))
217 4
    object@Presolve <- Presolve
218 4
  if (!is.null(TimeLimit))
219 4
    object@TimeLimit <- TimeLimit
220 4
  if (!is.null(NumberSolutions))
221 4
    object@NumberSolutions <- NumberSolutions
222 4
  if (!is.null(MultipleSolutionsMethod))
223 0
    object@MultipleSolutionsMethod <- MultipleSolutionsMethod
224
  # check object for validity
225 4
  methods::validObject(object, test = FALSE)
226
  # return object
227 4
  return(object)
228
}

Read our documentation on viewing source code .

Loading