Abstract acquisition function class.
Based on the predictions of a Surrogate, the acquisition function encodes the preference to evaluate a new point.
Most acquisition functions are stateful and depend on quantities that must be recomputed whenever the Surrogate
has been refitted on new data, e.g., the best objective function value observed so far ($y_best of
mlr_acqfunctions_ei) or the current Pareto front and the reference point ($ys_front and $ref_point of
mlr_acqfunctions_ehvi).
These quantities are cached in public fields and are recomputed from the Surrogate and its bbotk::Archive by
calling $update().
Which fields a subclass sets is documented in its $update() method.
Loop functions such as bayesopt_ego call $update() in every iteration, directly after updating the surrogate
and before optimizing the acquisition function:
The order matters, because $update() reads the archive through the surrogate and may rely on the surrogate's
predictions or its OutputTrafo.
Evaluating an acquisition function whose cached fields have not been set results in an error along the lines of
"$y_best is not set. Missed to call $update()?".
$reset() discards state so that the same acquisition function object can be reused for another optimization run
without carrying over information from the previous one.
Fields that $update() recomputes from scratch in every iteration need not be reset,
which is why most acquisition functions do not override $reset().
It matters for state that persists across iterations instead:
mlr_acqfunctions_stochastic_cb, for example, samples lambda once at the first $update() and afterwards only
decays it using an iteration counter,
so both are reset to make the next run start from a freshly sampled lambda.
OptimizerMbo and OptimizerAsyncMbo call $reset() at the beginning of $optimize(), together with resetting
the Surrogate and the AcqOptimizer.
Both methods can be implemented by subclasses. The default implementations do nothing, which is sufficient for stateless acquisition functions such as mlr_acqfunctions_mean or mlr_acqfunctions_sd.
See also
Other Acquisition Function:
mlr_acqfunctions,
mlr_acqfunctions_aei,
mlr_acqfunctions_cb,
mlr_acqfunctions_ehvi,
mlr_acqfunctions_ehvigh,
mlr_acqfunctions_ei,
mlr_acqfunctions_ei_log,
mlr_acqfunctions_eips,
mlr_acqfunctions_mean,
mlr_acqfunctions_multi,
mlr_acqfunctions_pi,
mlr_acqfunctions_sd,
mlr_acqfunctions_smsego,
mlr_acqfunctions_stochastic_cb,
mlr_acqfunctions_stochastic_ei
Super class
bbotk::Objective -> AcqFunction
Active bindings
direction(
"same"|"minimize"|"maximize")
Optimization direction of the acquisition function relative to the direction of the objective function of the bbotk::OptimInstance related to the passed bbotk::Archive. Must be"same","minimize", or"maximize".surrogate_max_to_min(
-1|1)
Multiplicative factor to correct for minimization or maximization of the acquisition function.label(
character(1))
Label for this object.man(
character(1))
String in the format[pkg]::[topic]pointing to a manual page for this object.archive(bbotk::Archive)
Points to the bbotk::Archive of the surrogate.fun(
function)
Points to the private acquisition function to be implemented by subclasses.surrogate(Surrogate)
Surrogate.requires_predict_type_se(
logical(1))
Whether the acquisition function requires the surrogate to have"se"as$predict_type.packages(
character())
Set of required packages.
Methods
AcqFunction$new()
Creates a new instance of this R6 class.
Note that the surrogate can be initialized lazy and can later be set via the active binding $surrogate.
Usage
AcqFunction$new(
id,
constants = ParamSet$new(),
surrogate = NULL,
requires_predict_type_se,
surrogate_class,
direction,
packages = NULL,
label = NA_character_,
man = NA_character_
)Arguments
id(
character(1)).constants(paradox::ParamSet). Changeable constants or parameters.
surrogate(
NULL| Surrogate). Surrogate whose predictions are used in the acquisition function.requires_predict_type_se(
logical(1))
Whether the acquisition function requires the surrogate to have"se"as$predict_type.surrogate_class(
character(1))
Allowed class of the surrogate.direction(
"same"|"minimize"|"maximize"). Optimization direction of the acquisition function relative to the direction of the objective function of the bbotk::OptimInstance. Must be"same","minimize", or"maximize".packages(
character())
Set of required packages. A warning is signaled prior to construction if at least one of the packages is not installed, but loaded (not attached) later on-demand viarequireNamespace().label(
character(1))
Label for this object.man(
character(1))
String in the format[pkg]::[topic]pointing to a manual page for this object.
AcqFunction$update()
Update the acquisition function. Recomputes the cached quantities from the current state of the Surrogate and its bbotk::Archive. Can be implemented by subclasses; see the class description above for details.
AcqFunction$reset()
Reset the acquisition function. Discards state so that the acquisition function can be reused for another optimization run. Can be implemented by subclasses; see the class description above for details.
AcqFunction$eval_many()
Evaluates multiple input values on the acquisition function.
Arguments
xss(
list())
A list of lists that contains multiple x values, e.g.list(list(x1 = 1, x2 = 2), list(x1 = 3, x2 = 4)).
AcqFunction$eval_dt()
Evaluates multiple input values on the objective function
Arguments
xdt(
data.table::data.table())
One point per row, e.g.data.table(x1 = c(1, 3), x2 = c(2, 4)).
AcqFunction$assert_surrogate()
Validate that the surrogate is compatible with this acquisition function.
Asserts the surrogate class and that $predict_type is "se" if required.
Subclasses with additional requirements must override this method.
Arguments
surrogate(Surrogate)
Surrogate to validate.
Returns
The validated Surrogate.