refactor: minor refactor changes to proposed async extensions

R/AcqFunction.R

@@ -73,6 +73,14 @@ AcqFunction = R6Class("AcqFunction",
       # FIXME: at some point we may want to make this an AB to a private$.update
     },
 
+    #' @description
+    #' Reset the acquisition function.
+    #'
+    #' Can be implemented by subclasses.
+    reset = function() {
+      # FIXME: at some point we may want to make this an AB to a private$.reset
+    },
+
     #' @description
     #' Evaluates multiple input values on the objective function.
     #'

R/AcqFunctionMulti.R

@@ -16,7 +16,7 @@
 #' If acquisition functions have not been initialized with a surrogate, the surrogate passed during construction or lazy initialization
 #' will be used for all acquisition functions.
 #'
-#' For optimization, [AcqOptimizer] can be used as for any other [AcqFunction], however, the [bbotk::Optimizer] wrapped within the [AcqOptimizer]
+#' For optimization, [AcqOptimizer] can be used as for any other [AcqFunction], however, the [bbotk::OptimizerBatch] wrapped within the [AcqOptimizer]
 #' must support multi-objective optimization as indicated via the `multi-crit` property.
 #'
 #' @family Acquisition Function

R/AcqFunctionSmsEgo.R

@@ -18,6 +18,11 @@
 #'   In the case of being `NULL`, an epsilon vector is maintained dynamically as
 #'   described in Horn et al. (2015).
 #'
+#' @section Note:
+#' * This acquisition function always also returns its current epsilon values in a list column (`acq_epsilon`).
+#'   This value will be logged into the [bbotk::ArchiveBatch] of the [bbotk::OptimInstanceBatch] of the [AcqOptimizer] and
+#'   therefore also in the [bbotk::Archive] of the actual [bbotk::OptimInstance] that is to be optimized.
+#'
 #' @references
 #' * `r format_bib("ponweiser_2008")`
 #' * `r format_bib("horn_2015")`
@@ -78,7 +83,7 @@ AcqFunctionSmsEgo = R6Class("AcqFunctionSmsEgo",
 
     #' @field progress (`numeric(1)`)\cr
     #'   Optimization progress (typically, the number of function evaluations left).
-    #'   Note that this requires the [bbotk::OptimInstance] to be terminated via a [bbotk::TerminatorEvals].
+    #'   Note that this requires the [bbotk::OptimInstanceBatch] to be terminated via a [bbotk::TerminatorEvals].
     progress = NULL,
 
     #' @description
@@ -94,7 +99,7 @@ AcqFunctionSmsEgo = R6Class("AcqFunctionSmsEgo",
 
       constants = ps(
         lambda = p_dbl(lower = 0, default = 1),
-        epsilon = p_dbl(lower = 0, default = NULL, special_vals = list(NULL))  # for NULL, it will be calculated dynamically
+        epsilon = p_dbl(lower = 0, default = NULL, special_vals = list(NULL))  # if NULL, it will be calculated dynamically
       )
       constants$values$lambda = lambda
       constants$values$epsilon = epsilon
@@ -140,6 +145,13 @@ AcqFunctionSmsEgo = R6Class("AcqFunctionSmsEgo",
       } else {
         self$epsilon = self$constants$values$epsilon
       }
+    },
+
+    #' @description
+    #' Reset the acquisition function.
+    #' Resets `epsilon`.
+    reset = function() {
+      self$epsilon = NULL
     }
   ),
 
@@ -163,7 +175,7 @@ AcqFunctionSmsEgo = R6Class("AcqFunctionSmsEgo",
       # allocate memory for adding points to front for HV calculation in C
       front2 = t(rbind(self$ys_front, 0))
       sms = .Call("c_sms_indicator", PACKAGE = "mlr3mbo", cbs, self$ys_front, front2, self$epsilon, self$ref_point)  # note that the negative indicator is returned from C
-      data.table(acq_smsego = sms)
+      data.table(acq_smsego = sms, acq_epsilon = list(self$epsilon))
     }
   )
 )

R/AcqFunctionStochasticCB.R

@@ -8,36 +8,76 @@
 #'
 #' @description
 #' Lower / Upper Confidence Bound with lambda sampling and decay.
-#' The initial lambda value is drawn from an uniform distribution between `min_lambda` and `max_lambda` or from an exponential distribution with rate `1 / lambda`.
-#' The lambda value is updated after each evaluation by the formula `lambda * exp(-rate * (t %% period))`.
+#' The initial \eqn{\lambda} is drawn from an uniform distribution between `min_lambda` and `max_lambda` or from an exponential distribution with rate `1 / lambda`.
+#' \eqn{\lambda} is updated after each update by the formula `lambda * exp(-rate * (t %% period))`, where `t` is the number of times the acquisition function has been updated.
+#'
+#' While this acquisition function usually would be used within an asynchronous optimizer, e.g., [OptimizerAsyncMbo],
+#' it can in principle also be used in synchronous optimizers, e.g., [OptimizerMbo].
 #'
 #' @section Parameters:
 #' * `"lambda"` (`numeric(1)`)\cr
-#'   Lambda value for sampling from the exponential distribution.
+#'   \eqn{\lambda} value for sampling from the exponential distribution.
 #'   Defaults to `1.96`.
 #' * `"min_lambda"` (`numeric(1)`)\cr
-#'   Minimum value of lambda for sampling from the uniform distribution.
+#'   Minimum value of \eqn{\lambda}for sampling from the uniform distribution.
 #'   Defaults to `0.01`.
 #' * `"max_lambda"` (`numeric(1)`)\cr
-#'   Maximum value of lambda for sampling from the uniform distribution.
+#'   Maximum value of \eqn{\lambda} for sampling from the uniform distribution.
 #'   Defaults to `10`.
 #' * `"distribution"` (`character(1)`)\cr
-#'   Distribution to sample lambda from.
+#'   Distribution to sample \eqn{\lambda} from.
 #'   One of `c("uniform", "exponential")`.
 #'   Defaults to `uniform`.
 #' * `"rate"` (`numeric(1)`)\cr
 #'   Rate of the exponential decay.
 #'   Defaults to `0` i.e. no decay.
 #' * `"period"` (`integer(1)`)\cr
 #'   Period of the exponential decay.
-#'   Defaults to `NULL` i.e. the decay has no period.
+#'   Defaults to `NULL`, i.e., the decay has no period.
+#'
+#' @section Note:
+#' * This acquisition function always also returns its current (`acq_lambda`) and original (`acq_lambda_0`) \eqn{\lambda}.
+#'   These values will be logged into the [bbotk::ArchiveBatch] of the [bbotk::OptimInstanceBatch] of the [AcqOptimizer] and
+#'   therefore also in the [bbotk::Archive] of the actual [bbotk::OptimInstance] that is to be optimized.
 #'
 #' @references
 #' * `r format_bib("snoek_2012")`
 #' * `r format_bib("egele_2023")`
 #'
 #' @family Acquisition Function
 #' @export
+#' @examples
+#' if (requireNamespace("mlr3learners") &
+#'     requireNamespace("DiceKriging") &
+#'     requireNamespace("rgenoud")) {
+#'   library(bbotk)
+#'   library(paradox)
+#'   library(mlr3learners)
+#'   library(data.table)
+#'
+#'   fun = function(xs) {
+#'     list(y = xs$x ^ 2)
+#'   }
+#'   domain = ps(x = p_dbl(lower = -10, upper = 10))
+#'   codomain = ps(y = p_dbl(tags = "minimize"))
+#'   objective = ObjectiveRFun$new(fun = fun, domain = domain, codomain = codomain)
+#'
+#'   instance = OptimInstanceBatchSingleCrit$new(
+#'     objective = objective,
+#'     terminator = trm("evals", n_evals = 5))
+#'
+#'   instance$eval_batch(data.table(x = c(-6, -5, 3, 9)))
+#'
+#'   learner = default_gp()
+#'
+#'   surrogate = srlrn(learner, archive = instance$archive)
+#'
+#'   acq_function = acqf("stochastic_cb", surrogate = surrogate, lambda = 3)
+#'
+#'   acq_function$surrogate$update()
+#'   acq_function$update()
+#'   acq_function$eval_dt(data.table(x = c(-1, 0, 1)))
+#' }
 AcqFunctionStochasticCB = R6Class("AcqFunctionStochasticCB",
   inherit = AcqFunction,
 
@@ -52,7 +92,7 @@ AcqFunctionStochasticCB = R6Class("AcqFunctionStochasticCB",
     #' @param max_lambda (`numeric(1)`).
     #' @param distribution (`character(1)`).
     #' @param rate (`numeric(1)`).
-    #' @param period (`integer(1)`).
+    #' @param period (`NULL` | `integer(1)`).
     initialize = function(
       surrogate = NULL,
       lambda = 1.96,
@@ -69,19 +109,17 @@ AcqFunctionStochasticCB = R6Class("AcqFunctionStochasticCB",
       private$.distribution = assert_choice(distribution, choices = c("uniform", "exponential"))
 
       if (private$.distribution == "uniform" && (is.null(private$.min_lambda) || is.null(private$.max_lambda))) {
-        stop("If `distribution` is 'uniform', `min_lambda` and `max_lambda` must be set.")
+        stop('If `distribution` is "uniform", `min_lambda` and `max_lambda` must be set.')
       }
 
       if (private$.distribution == "exponential" && is.null(private$.lambda)) {
-        stop("If `distribution` is 'exponential', `lambda` must be set.")
+        stop('If `distribution` is "exponential", `lambda` must be set.')
       }
 
       private$.rate = assert_number(rate, lower = 0)
       private$.period = assert_int(period, lower = 1, null.ok = TRUE)
 
-      constants = ps(
-        lambda = p_dbl(lower = 0)
-      )
+      constants = ps(lambda = p_dbl(lower = 0))
 
       super$initialize("acq_cb",
         constants = constants,
@@ -117,8 +155,15 @@ AcqFunctionStochasticCB = R6Class("AcqFunctionStochasticCB",
         rate = private$.rate
 
         self$constants$values$lambda = lambda_0 * exp(-rate * t)
-        private$.t = t + 1
+        private$.t = t + 1L
       }
+    },
+
+    #' @description
+    #' Reset the acquisition function.
+    #' Resets the private update counter `.t` used within the epsilon decay.
+    reset = function() {
+      private$.t = 0L
     }
   ),
 
@@ -129,9 +174,8 @@ AcqFunctionStochasticCB = R6Class("AcqFunctionStochasticCB",
     .distribution = NULL,
     .rate = NULL,
     .period = NULL,
-    .t = 0,
     .lambda_0 = NULL,
-
+    .t = 0L,
     .fun = function(xdt, lambda) {
       p = self$surrogate$predict(xdt)
       cb = p$mean - self$surrogate_max_to_min * lambda * p$se

R/AcqFunctionStochasticEI.R

@@ -8,6 +8,10 @@
 #'
 #' @description
 #' Expected Improvement with epsilon decay.
+#' \eqn{\epsilon} is updated after each update by the formula `epsilon * exp(-rate * (t %% period))` where `t` is the number of times the acquisition function has been updated.
+#'
+#' While this acquisition function usually would be used within an asynchronous optimizer, e.g., [OptimizerAsyncMbo],
+#' it can in principle also be used in synchronous optimizers, e.g., [OptimizerMbo].
 #'
 #' @section Parameters:
 #' * `"epsilon"` (`numeric(1)`)\cr
@@ -20,13 +24,50 @@
 #'   Defaults to `0.05`.
 #' * `"period"` (`integer(1)`)\cr
 #'   Period of the exponential decay.
-#'   Defaults to `NULL` i.e. the decay has no period.
+#'   Defaults to `NULL`, i.e., the decay has no period.
+#'
+#' @section Note:
+#' * This acquisition function always also returns its current (`acq_epsilon`) and original (`acq_epsilon_0`) \eqn{\epsilon}.
+#'   These values will be logged into the [bbotk::ArchiveBatch] of the [bbotk::OptimInstanceBatch] of the [AcqOptimizer] and
+#'   therefore also in the [bbotk::Archive] of the actual [bbotk::OptimInstance] that is to be optimized.
 #'
 #' @references
 #' * `r format_bib("jones_1998")`
 #'
 #' @family Acquisition Function
 #' @export
+#' @examples
+#' if (requireNamespace("mlr3learners") &
+#'     requireNamespace("DiceKriging") &
+#'     requireNamespace("rgenoud")) {
+#'   library(bbotk)
+#'   library(paradox)
+#'   library(mlr3learners)
+#'   library(data.table)
+#'
+#'   fun = function(xs) {
+#'     list(y = xs$x ^ 2)
+#'   }
+#'   domain = ps(x = p_dbl(lower = -10, upper = 10))
+#'   codomain = ps(y = p_dbl(tags = "minimize"))
+#'   objective = ObjectiveRFun$new(fun = fun, domain = domain, codomain = codomain)
+#'
+#'   instance = OptimInstanceBatchSingleCrit$new(
+#'     objective = objective,
+#'     terminator = trm("evals", n_evals = 5))
+#'
+#'   instance$eval_batch(data.table(x = c(-6, -5, 3, 9)))
+#'
+#'   learner = default_gp()
+#'
+#'   surrogate = srlrn(learner, archive = instance$archive)
+#'
+#'   acq_function = acqf("stochastic_ei", surrogate = surrogate)
+#'
+#'   acq_function$surrogate$update()
+#'   acq_function$update()
+#'   acq_function$eval_dt(data.table(x = c(-1, 0, 1)))
+#' }
 AcqFunctionStochasticEI = R6Class("AcqFunctionStochasticEI",
   inherit = AcqFunction,
 
@@ -43,7 +84,7 @@ AcqFunctionStochasticEI = R6Class("AcqFunctionStochasticEI",
     #' @param surrogate (`NULL` | [SurrogateLearner]).
     #' @param epsilon (`numeric(1)`).
     #' @param rate (`numeric(1)`).
-    #' @param period (`integer(1)`).
+    #' @param period (`NULL` | `integer(1)`).
     initialize = function(
       surrogate = NULL,
       epsilon = 0.1,
@@ -55,9 +96,7 @@ AcqFunctionStochasticEI = R6Class("AcqFunctionStochasticEI",
       private$.rate = assert_number(rate, lower = 0, finite = TRUE)
       private$.period = assert_int(period, lower = 1, null.ok = TRUE)
 
-      constants = ps(
-        epsilon = p_dbl(lower = 0)
-      )
+      constants = ps(epsilon = p_dbl(lower = 0, default = 0.1))
 
       super$initialize("acq_ei",
         constants = constants,
@@ -82,16 +121,22 @@ AcqFunctionStochasticEI = R6Class("AcqFunctionStochasticEI",
       rate = private$.rate
 
       self$constants$values$epsilon = epsilon_0 * exp(-rate * t)
-      private$.t = t + 1
+      private$.t = t + 1L
+    },
+
+    #' @description
+    #' Reset the acquisition function.
+    #' Resets the private update counter `.t` used within the epsilon decay.
+    reset = function() {
+      private$.t = 0L
     }
   ),
 
   private = list(
     .rate = NULL,
     .period = NULL,
     .epsilon_0 = NULL,
-    .t = 0,
-
+    .t = 0L,
     .fun = function(xdt, epsilon) {
       if (is.null(self$y_best)) {
         stop("$y_best is not set. Missed to call $update()?")