docs: improve documention of AcqFunctionMulti and AcqOptimizer

R/AcqFunctionMulti.R

@@ -10,6 +10,15 @@
 #' Wrapping multiple [AcqFunction]s resulting in a multi-objective acquisition function composed of the individual ones.
 #' Note that the optimization direction of each wrapped acquisition function is corrected for maximization.
 #'
+#' For each acquisition function, the same [Surrogate] must be used.
+#' If acquisition functions passed during construction already have been initialized with a surrogate, it is checked whether
+#' the surrogate is the same for all acquisition functions.
+#' 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]
+#' must support multi-objective optimization as indicated via the `multi-crit` property.
+#'
 #' @family Acquisition Function
 #' @export
 #' @examples
@@ -159,7 +168,7 @@ AcqFunctionMulti = R6Class("AcqFunctionMulti",
     },
 
     #' @field acq_functions (list of [AcqFunction])\cr
-    #'   Points to the list of the individual acqusition functions.
+    #'   Points to the list of the individual acquisition functions.
     acq_functions = function(rhs) {
       if (!missing(rhs) && !identical(rhs, private$.acq_functions)) {
         stop("$acq_functions is read-only.")
@@ -168,7 +177,7 @@ AcqFunctionMulti = R6Class("AcqFunctionMulti",
     },
 
     #' @field acq_function_ids (character())\cr
-    #'   Points to the ids of the individual acqusition functions.
+    #'   Points to the ids of the individual acquisition functions.
     acq_function_ids = function(rhs) {
       if (!missing(rhs) && !identical(rhs, private$.acq_function_ids)) {
         stop("$acq_function_ids is read-only.")
@@ -202,6 +211,13 @@ AcqFunctionMulti = R6Class("AcqFunctionMulti",
         set(values, j = j, value = - values[[j]])
       }
       values
+    },
+
+    deep_clone = function(name, value) {
+      switch(name,
+        .acq_functions = value$clone(deep = TRUE),
+        value
+      )
     }
   )
 )

R/AcqOptimizer.R

@@ -9,35 +9,40 @@
 #' \item{`n_candidates`}{`integer(1)`\cr
 #'   Number of candidate points to propose.
 #'   Note that this does not affect how the acquisition function itself is calculated (e.g., setting `n_candidates > 1` will not
-#'   result in computing the q- or multi-Expected Improvement) but rather the top `n-candidates` are selected from the
+#'   result in computing the q- or multi-Expected Improvement) but rather the top `n_candidates` are selected from the
 #'   [bbotk::Archive] of the acquisition function [bbotk::OptimInstance].
 #'   Note that setting `n_candidates > 1` is usually not a sensible idea but it is still supported for experimental reasons.
-#'   Default is `1`.}
+#'   Note that in the case of the acquisition function [bbotk::OptimInstance] being multi-criteria, due to using an [AcqFunctionMulti],
+#'   selection of the best candidates is performed via non-dominated-sorting.
+#'   Default is `1`.
+#' }
 #' \item{`logging_level`}{`character(1)`\cr
 #'   Logging level during the acquisition function optimization.
 #'   Can be `"fatal"`, `"error"`, `"warn"`, `"info"`, `"debug"` or `"trace"`.
 #'   Default is `"warn"`, i.e., only warnings are logged.
 #' }
 #' \item{`warmstart`}{`logical(1)`\cr
 #'   Should the acquisition function optimization be warm-started by evaluating the best point(s) present in the [bbotk::Archive] of
-#'   the actual [bbotk::OptimInstance]?
+#'   the actual [bbotk::OptimInstance] (which is contained in the archive of the [AcqFunction])?
 #'   This is sensible when using a population based acquisition function optimizer, e.g., local search or mutation.
 #'   Default is `FALSE`.
+#'   Note that in the case of the [bbotk::OptimInstance] being multi-criteria, selection of the best point(s) is performed via non-dominated-sorting.
 #' }
 #' \item{`warmstart_size`}{`integer(1) | "all"`\cr
-#'   Number of best points selected from the [bbotk::Archive] that are to be used for warm starting.
-#'   Can also be "all" to use all available points.
+#'   Number of best points selected from the [bbotk::Archive] of the actual [bbotk::OptimInstance] that are to be used for warm starting.
+#'   Can either be an integer or "all" to use all available points.
 #'   Only relevant if `warmstart = TRUE`.
 #'   Default is `1`.
 #' }
 #' \item{`skip_already_evaluated`}{`logical(1)`\cr
-#'   It can happen that the candidate resulting of the acquisition function optimization was already evaluated in a previous
-#'   iteration. Should this candidate proposal be ignored and the next best point be selected as a candidate?
+#'   It can happen that the candidate(s) resulting of the acquisition function optimization were already evaluated on the actual [bbotk::OptimInstance].
+#'   Should such candidate proposals be ignored and only candidates that were yet not evaluated be considered?
 #'   Default is `TRUE`.
 #' }
 #' \item{`catch_errors`}{`logical(1)`\cr
 #'   Should errors during the acquisition function optimization be caught and propagated to the `loop_function` which can then handle
 #'   the failed acquisition function optimization appropriately by, e.g., proposing a randomly sampled point for evaluation?
+#'   Setting this to `FALSE` can be helpful for debugging.
 #'   Default is `TRUE`.
 #' }
 #' }
@@ -123,6 +128,8 @@ AcqOptimizer = R6Class("AcqOptimizer",
 
     #' @description
     #' Helper for print outputs.
+    #'
+    #' @return (`character(1)`).
     format = function() {
       sprintf("<%s>", class(self)[1L])
     },
@@ -139,7 +146,7 @@ AcqOptimizer = R6Class("AcqOptimizer",
     #' @description
     #' Optimize the acquisition function.
     #'
-    #' @return [data.table::data.table()] with 1 row per optimum and x as columns.
+    #' @return [data.table::data.table()] with 1 row per candidate.
     optimize = function() {
       is_multi_acq_function = self$acq_function$codomain$length > 1L
 

R/ResultAssigner.R

@@ -36,6 +36,8 @@ ResultAssigner = R6Class("ResultAssigner",
 
     #' @description
     #' Helper for print outputs.
+    #'
+    #' @return (`character(1)`).
     format = function() {
       sprintf("<%s>", class(self)[1L])
     },

R/Surrogate.R

@@ -69,6 +69,8 @@ Surrogate = R6Class("Surrogate",
 
     #' @description
     #' Helper for print outputs.
+    #'
+    #' @return (`character(1)`).
     format = function() {
       sprintf("<%s>", class(self)[1L])
     },