Specify numerical optimizer as R6 object

A Optimizer R6 object defines a numerical optimizer based on an optimization function implemented in R.

The main advantage of working with an Optimizer object instead of using the optimization function directly lies in the standardized inputs and outputs.

Any R function that fulfills the following four constraints can be defined as an Optimizer object:

It must have an input for a function, the objective function to be optimized.
It must have an input for a numeric vector, the initial values from where the optimizer starts.
It must have a ... argument for additional parameters passed on to the objective function.
The output must be a named list, including the optimal function value and the optimal parameter vector.

Active bindings

label

A character, the label for the optimizer.

algorithm

A function, the optimization algorithm.

arg_objective

A character, the argument name for the objective function in algorithm.

arg_initial

A character, the argument name for the initial values in algorithm.

out_value

A character, the element name for the optimal function value in the output list of algorithm.

out_parameter

A character, the element name for the optimal parameters in the output list of algorithm.

direction

Either "min" (if the optimizer minimizes) or "max" (if the optimizer maximizes).

arguments

A named list of custom arguments for algorithm. Defaults are used for arguments that are not specified.

seconds

A numeric, a time limit in seconds. Optimization is interrupted prematurely if seconds is exceeded.

No time limit if seconds = Inf (the default).

Note the limitations documented in setTimeLimit.

hide_warnings

Either TRUE to hide warnings during optimization, or FALSE (default) else.

output_ignore

A character vector of elements to ignore in the optimization output.

Methods

Method `new()`

Initializes a new Optimizer object.

Usage

Optimizer$new(which, ...)

Arguments

which: A character, either one of optimizer_dictionary$keys or "custom" (in which case $definition() must be used to define the optimizer details).
...: Optionally additional arguments to be passed to the optimizer algorithm. Without specifications, default values are used.

Returns

A new Optimizer object.

Method `definition()`

Defines an optimizer.

Usage

Optimizer$definition(
  algorithm,
  arg_objective,
  arg_initial,
  out_value,
  out_parameter,
  direction
)

Arguments

algorithm: A function, the optimization algorithm.
arg_objective: A character, the argument name for the objective function in algorithm.
arg_initial: A character, the argument name for the initial values in algorithm.
out_value: A character, the element name for the optimal function value in the output list of algorithm.
out_parameter: A character, the element name for the optimal parameters in the output list of algorithm.
direction: Either "min" (if the optimizer minimizes) or "max" (if the optimizer maximizes).

Returns

Invisibly the Optimizer object.

Method `set_arguments()`

Sets optimizer arguments.

Usage

Optimizer$set_arguments(...)

Arguments

...: Optionally additional arguments to be passed to the optimizer algorithm. Without specifications, default values are used.

Returns

The Optimizer object.

Method `validate()`

Validates the Optimizer object. A time limit in seconds for the optimization can be set via the $seconds field.

Usage

Optimizer$validate(
  objective = optimizeR::test_objective,
  initial = round(stats::rnorm(2)),
  ...,
  direction = "min"
)

Arguments

objective

A function to be optimized that

has at least one argument that receives a numeric vector
and returns a single numeric value.

Alternatively, it can also be a Objective object for more flexibility.

initial

A numeric vector with starting parameter values for the optimization.

...

Optionally additional arguments to be passed to the optimizer algorithm. Without specifications, default values are used.

direction

Either "min" for minimization or "max" for maximization.

Returns

The Optimizer object.

Method `minimize()`

Performing minimization.

Usage

Optimizer$minimize(objective, initial, ...)

Arguments

objective

A function to be optimized that

has at least one argument that receives a numeric vector
and returns a single numeric value.

Alternatively, it can also be a Objective object for more flexibility.

initial

A numeric vector with starting parameter values for the optimization.

...

Optionally additional arguments to be passed to the optimizer algorithm. Without specifications, default values are used.

Returns

A named list, containing at least these five elements:

value: A numeric, the minimum function value.
parameter: A numeric vector, the parameter vector where the minimum is obtained.
seconds: A numeric, the optimization time in seconds.
initial: A numeric, the initial parameter values.
error: Either TRUE if an error occurred, or FALSE, else.

Appended are additional output elements of the optimizer.

If an error occurred, then the error message is also appended as element error_message.

If the time limit was exceeded, this also counts as an error. In addition, the flag time_out = TRUE is appended.

Examples

Optimizer$new("stats::nlm")$
  minimize(objective = function(x) x^4 + 3*x - 5, initial = 2)

Method `maximize()`

Performing maximization.

Usage

Optimizer$maximize(objective, initial, ...)

Arguments

objective

A function to be optimized that

has at least one argument that receives a numeric vector
and returns a single numeric value.

Alternatively, it can also be a Objective object for more flexibility.

initial

A numeric vector with starting parameter values for the optimization.

...

Optionally additional arguments to be passed to the optimizer algorithm. Without specifications, default values are used.

Returns

A named list, containing at least these five elements:

value: A numeric, the maximum function value.
parameter: A numeric vector, the parameter vector where the maximum is obtained.
seconds: A numeric, the optimization time in seconds.
initial: A numeric, the initial parameter values.
error: Either TRUE if an error occurred, or FALSE, else.

Appended are additional output elements of the optimizer.

If an error occurred, then the error message is also appended as element error_message.

If the time limit was exceeded, this also counts as an error. In addition, the flag time_out = TRUE is appended.

Examples

Optimizer$new("stats::nlm")$
  maximize(objective = function(x) -x^4 + 3*x - 5, initial = 2)

Method `optimize()`

Performing minimization or maximization.

Usage

Optimizer$optimize(objective, initial, direction = "min", ...)

Arguments

objective

A function to be optimized that

has at least one argument that receives a numeric vector
and returns a single numeric value.

Alternatively, it can also be a Objective object for more flexibility.

initial

A numeric vector with starting parameter values for the optimization.

direction

Either "min" for minimization or "max" for maximization.

...

Optionally additional arguments to be passed to the optimizer algorithm. Without specifications, default values are used.

Returns

A named list, containing at least these five elements:

value: A numeric, the maximum function value.
parameter: A numeric vector, the parameter vector where the maximum is obtained.
seconds: A numeric, the optimization time in seconds.
initial: A numeric, the initial parameter values.
error: Either TRUE if an error occurred, or FALSE, else.

Appended are additional output elements of the optimizer.

If an error occurred, then the error message is also appended as element error_message.

If the time limit was exceeded, this also counts as an error. In addition, the flag time_out = TRUE is appended.

Examples

objective <- function(x) -x^4 + 3*x - 5
optimizer <- Optimizer$new("stats::nlm")
optimizer$optimize(objective = objective, initial = 2, direction = "min")
optimizer$optimize(objective = objective, initial = 2, direction = "max")

Method `print()`

Prints the optimizer label.

Usage

Optimizer$print(...)

Arguments

...: Optionally additional arguments to be passed to the optimizer algorithm. Without specifications, default values are used.

Returns

Invisibly the Optimizer object.

Method `clone()`

The objects of this class are cloneable with this method.

Usage

Optimizer$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

### Task: compare minimization with 'stats::nlm' and 'pracma::nelder_mead'

# 1. define objective function and initial values
objective <- TestFunctions::TF_ackley
initial <- c(3, 3)

# 2. get overview of optimizers in dictionary
optimizer_dictionary$keys
#> [1] "lbfgsb3c::lbfgsb3c" "stats::nlm"         "stats::nlminb"     
#> [4] "stats::optim"       "ucminf::ucminf"    

# 3. define 'nlm' optimizer
nlm <- Optimizer$new(which = "stats::nlm")

# 4. define the 'pracma::nelder_mead' optimizer (not contained in the dictionary)
nelder_mead <- Optimizer$new(which = "custom")
#> Please use method `$definition()` next to define a custom optimizer.
nelder_mead$definition(
  algorithm = pracma::nelder_mead, # the optimization function
  arg_objective = "fn",            # the argument name for the objective function
  arg_initial = "x0",              # the argument name for the initial values
  out_value = "fmin",              # the element for the optimal function value in the output
  out_parameter = "xmin",          # the element for the optimal parameters in the output
  direction = "min"                # the optimizer minimizes
)

# 5. compare the minimization results
nlm$minimize(objective, initial)
#> $value
#> [1] 6.559645
#> 
#> $parameter
#> [1] 1.974451 1.974451
#> 
#> $seconds
#> [1] 0.01338601
#> 
#> $initial
#> [1] 3 3
#> 
#> $error
#> [1] FALSE
#> 
#> $gradient
#> [1] 5.757896e-08 5.757896e-08
#> 
#> $code
#> [1] 1
#> 
#> $iterations
#> [1] 6
#> 
nelder_mead$minimize(objective, initial)
#> $value
#> [1] 4.440892e-16
#> 
#> $parameter
#> [1] 0 0
#> 
#> $seconds
#> [1] 0.009227514
#> 
#> $initial
#> [1] 3 3
#> 
#> $error
#> [1] FALSE
#> 
#> $count
#> [1] 105
#> 
#> $info
#> $info$solver
#> [1] "Nelder-Mead"
#> 
#> $info$restarts
#> [1] 0
#> 
#> 


## ------------------------------------------------
## Method `Optimizer$minimize`
## ------------------------------------------------

Optimizer$new("stats::nlm")$
  minimize(objective = function(x) x^4 + 3*x - 5, initial = 2)
#> $value
#> [1] -7.044261
#> 
#> $parameter
#> [1] -0.9085614
#> 
#> $seconds
#> [1] 0.001205921
#> 
#> $initial
#> [1] 2
#> 
#> $error
#> [1] FALSE
#> 
#> $gradient
#> [1] -6.068035e-06
#> 
#> $code
#> [1] 1
#> 
#> $iterations
#> [1] 7
#> 

## ------------------------------------------------
## Method `Optimizer$maximize`
## ------------------------------------------------

Optimizer$new("stats::nlm")$
  maximize(objective = function(x) -x^4 + 3*x - 5, initial = 2)
#> $value
#> [1] -2.955739
#> 
#> $parameter
#> [1] 0.9085598
#> 
#> $seconds
#> [1] 0.001421928
#> 
#> $initial
#> [1] 2
#> 
#> $error
#> [1] FALSE
#> 
#> $gradient
#> [1] -3.801404e-07
#> 
#> $code
#> [1] 1
#> 
#> $iterations
#> [1] 8
#> 

## ------------------------------------------------
## Method `Optimizer$optimize`
## ------------------------------------------------

objective <- function(x) -x^4 + 3*x - 5
optimizer <- Optimizer$new("stats::nlm")
optimizer$optimize(objective = objective, initial = 2, direction = "min")
#> $value
#> [1] -1.012458e+16
#> 
#> $parameter
#> [1] 10031
#> 
#> $seconds
#> [1] 0.0009684563
#> 
#> $initial
#> [1] 2
#> 
#> $error
#> [1] FALSE
#> 
#> $gradient
#> [1] -4.037322e+12
#> 
#> $code
#> [1] 5
#> 
#> $iterations
#> [1] 6
#> 
optimizer$optimize(objective = objective, initial = 2, direction = "max")
#> $value
#> [1] -2.955739
#> 
#> $parameter
#> [1] 0.9085598
#> 
#> $seconds
#> [1] 0.001451492
#> 
#> $initial
#> [1] 2
#> 
#> $error
#> [1] FALSE
#> 
#> $gradient
#> [1] -3.801404e-07
#> 
#> $code
#> [1] 1
#> 
#> $iterations
#> [1] 8
#>

Specify numerical optimizer as R6 object

Active bindings

Methods

Public methods

Method new()

Usage

Arguments

Returns

Method definition()

Usage

Arguments

Returns

Method set_arguments()

Usage

Arguments

Returns

Method validate()

Usage

Arguments

Returns

Method minimize()

Usage

Arguments

Returns

Examples

Method maximize()

Usage

Arguments

Returns

Examples

Method optimize()

Usage

Arguments

Returns

Examples

Method print()

Usage

Arguments

Returns

Method clone()

Usage

Arguments

Examples

Method `new()`

Method `definition()`

Method `set_arguments()`

Method `validate()`

Method `minimize()`

Method `maximize()`

Method `optimize()`

Method `print()`

Method `clone()`