API Documentation¶

The Server Classes¶

class bayesopt_server.BayesOptServer(config_file: str, server_name: str = 'BayesOpt', log_file: Optional[str] = None, anonymous: bool = True, log_level: int = 2, silent: bool = False, node_rate: float = 5.0)[source]¶

The Bayesian optimization server node.

Acts as a layer between the actual Bayesian optimization and ROS.

__init__(config_file: str, server_name: str = 'BayesOpt', log_file: Optional[str] = None, anonymous: bool = True, log_level: int = 2, silent: bool = False, node_rate: float = 5.0) → None[source]¶

The BayesOptServer class initializer.

Parameters

config_file (str) – File that describes all settings for Bayesian optimization.
server_name (str) – Name of the server that is used for ROS.
log_file (str) – All input/output pairs are logged to this file.
anonymous (bool) – Flag if the node should be anonymous or not (see ROS documentation).
log_level (int) – Controls the log_level of the node’s output.
silent (bool) – Controls the verbosity of the node’s output.
node_rate (float) – Rate at which the server gives feedback.

next_parameter_callback(goal: bayesopt4ros.msg._BayesOptAction.BayesOptAction) → None[source]¶

Method that gets called when a new parameter vector is requested.

The action message (goal/result/feedback) is defined here: action/BayesOpt.action

# Goal: corresponds to the "output value" for BayesOpt
float64 y_new
---
# Result: corresponds to the new parameters
float64[] x_new
---
# Feedback: as of now we do not use this
bool feedback

Parameters: goal (BayesOptAction) – The action (goal) coming from a client.

static run() → None[source]¶: Simply starts the server.

state_callback(goal) → None[source]¶

Method that gets called when the BayesOpt state is requested.

Note

We are calling this state instead of result to avoid confusion with the result variable in the action message.

The action message (goal/result/feedback) is defined here: action/BayesOptState.action

# Goal: as of now we do not use this
bool goal
---
# Result: this contains the BayesOpt state
# 'best' corresponds to observed parameters/outcomes
float64[] x_best
float64 y_best
# 'opt' corresponds to optimum of the posterior mean
float64[] x_opt
float64 f_opt
---
# Feedback: as of now we do not use this
bool feedback

Parameters: goal (BayesOptStateAction) – The action (goal) coming from a client.

class contextual_bayesopt_server.ContextualBayesOptServer(config_file: str, server_name: str = 'ContextualBayesOpt', log_file: Optional[str] = None, anonymous: bool = True, log_level: int = 2, silent: bool = False, node_rate: float = 5.0)[source]¶

The contextual Bayesian optimization server node.

Acts as a layer between the actual contextual Bayesian optimization and ROS.

__init__(config_file: str, server_name: str = 'ContextualBayesOpt', log_file: Optional[str] = None, anonymous: bool = True, log_level: int = 2, silent: bool = False, node_rate: float = 5.0) → None[source]¶

The ContextualBayesOptServer class initializer.

For paramters see bayesopt_server.BayesOptServer.

next_parameter_callback(goal: bayesopt4ros.msg._ContextualBayesOptAction.ContextualBayesOptAction) → None[source]¶

Method that gets called when a new parameter vector is requested.

The action message (goal/result/feedback) is defined here: action/BayesOpt.action

# Goal: corresponds to the "output value" for BayesOpt
float64 y_new
---
# Result: corresponds to the new parameters
float64[] x_new
---
# Feedback: as of now we do not use this
bool feedback

Parameters: goal (BayesOptAction) – The action (goal) coming from a client.

static run() → None¶: Simply starts the server.

state_callback(goal: bayesopt4ros.msg._ContextualBayesOptStateAction.ContextualBayesOptStateAction) → None[source]¶

Method that gets called when the BayesOpt state is requested.

Note

We are calling this state instead of result to avoid confusion with the result variable in the action message.

The action message (goal/result/feedback) is defined here: action/BayesOptState.action

# Goal: as of now we do not use this
bool goal
---
# Result: this contains the BayesOpt state
# 'best' corresponds to observed parameters/outcomes
float64[] x_best
float64 y_best
# 'opt' corresponds to optimum of the posterior mean
float64[] x_opt
float64 f_opt
---
# Feedback: as of now we do not use this
bool feedback

Parameters: goal (BayesOptStateAction) – The action (goal) coming from a client.

The Optimizer Classes¶

class bayesopt4ros.bayesopt.BayesianOptimization(input_dim: int, max_iter: int, bounds: torch.Tensor, acq_func: str = 'UCB', n_init: int = 5, log_dir: Optional[str] = None, load_dir: Optional[str] = None, config: Optional[dict] = None, maximize: bool = True, debug_visualization: bool = False)[source]¶

The Bayesian optimization class.

Implements the actual heavy lifting that is done under the hood of bayesopt_server.BayesOptServer.

__init__(input_dim: int, max_iter: int, bounds: torch.Tensor, acq_func: str = 'UCB', n_init: int = 5, log_dir: Optional[str] = None, load_dir: Optional[str] = None, config: Optional[dict] = None, maximize: bool = True, debug_visualization: bool = False) → None[source]¶

The BayesianOptimization class initializer.

Note

If a log_dir is specified, three different files will be created: 1) evaluations file, 2) model file, 3) config file. As the names suggest, these store the evaluated points, the final GP model as well as the configuration, respectively.

Parameters

input_dim (int) – Number of input dimensions for the parameters.
max_iter (int) – Maximum number of iterations.
bounds (torch.Tensor) – A [2, input_dim] shaped tensor specifying the optimization domain.
acq_func (str) – The acquisition function specifier.
n_init (int) – Number of point for initial design, i.e. Sobol.
log_dir (str) – Directory to which the log files are stored.
load_dir (str or list of str) – Directory/directories from which initial data points are loaded.
config (dict) – The configuration dictionary for the experiment.
maximize (bool) – If True, consider the problem a maximization problem.
debug_visualization (bool) – If True, the optimization of the acquisition function is visualized.

property constant_config_parameters: List[str]¶: These parameters need to be the same when loading previous runs. For all other settings, the user might have a reasonable explanation to change it inbetween experiments/runs. E.g., maximum number of iterations or bounds.

See also

_check_config

classmethod from_file(config_file: str) → bayesopt4ros.bayesopt.BayesianOptimization[source]¶

Initialize a BayesianOptimization instance from a config file.

Parameters: config_file (str) – The config file (full path, relative or absolute).
Returns: An instance of the BayesianOptimization class.
Return type: BayesianOptimization

get_best_observation() → Tuple[torch.Tensor, float][source]¶

Get the best parameters and corresponding observed value.

Note

‘Best’ refers to the highest/lowest observed datum.

Returns

torch.Tensor – Location of the highest/lowest observed datum.
float – Function value of the highest/lowest observed datum.

See also

get_optimal_parameters

get_optimal_parameters() → Tuple[torch.Tensor, float][source]¶

Get the optimal parameters with corresponding expected value.

Note

‘Optimal’ referes to the optimum of the GP model.

Returns

torch.Tensor – Location of the GP posterior mean’s optimum.
float – Function value of the GP posterior mean’s optium.

See also

get_best_observation

next(goal: bayesopt4ros.msg._BayesOptAction.BayesOptAction) → torch.Tensor[source]¶

Compute new parameters to perform an experiment with.

The functionality of this method can generally be split into three steps:

Update the model with the new data.
Retrieve a new point as response of the server.
Save current state to file.

Parameters: goal (BayesOptAction) – The goal sent from the client for the most recent experiment.
Returns: The new parameters as an array.
Return type: torch.Tensor

update_last_goal(goal: bayesopt4ros.msg._BayesOptAction.BayesOptAction) → None[source]¶

Updates the GP model with the last function value obtained.

Note

This function is only called once from the server, right before shutting down the node. However, we still want to update the GP model with the latest data.

Parameters: goal (BayesOptAction) – The goal sent from the client for the last recent experiment.

class bayesopt4ros.contextual_bayesopt.ContextualBayesianOptimization(input_dim: int, context_dim: int, max_iter: int, bounds: torch.Tensor, acq_func: str = 'UCB', n_init: int = 5, log_dir: Optional[str] = None, load_dir: Optional[str] = None, config: Optional[dict] = None, maximize: bool = True)[source]¶

The contextual Bayesian optimization class.

Implements the actual heavy lifting that is done under the hood of contextual_bayesopt_server.ContextualBayesOptServer.

See also

bayesopt.BayesianOptimization

__init__(input_dim: int, context_dim: int, max_iter: int, bounds: torch.Tensor, acq_func: str = 'UCB', n_init: int = 5, log_dir: Optional[str] = None, load_dir: Optional[str] = None, config: Optional[dict] = None, maximize: bool = True) → None[source]¶

The ContextualBayesianOptimization class initializer.

Note

For a definition of the other arguments, see bayesopt.BayesianOptimization.

Parameters: context_dim (int) – Number of context dimensions for the parameters.

property constant_config_parameters: List[str]¶: These parameters need to be the same when loading previous runs. For all other settings, the user might have a reasonable explanation to change it inbetween experiments/runs. E.g., maximum number of iterations or bounds.

See also

_check_config

classmethod from_file(config_file: str) → bayesopt4ros.contextual_bayesopt.ContextualBayesianOptimization[source]¶

Initialize a ContextualBayesianOptimization instance from a config file.

Parameters: config_file (str) – The config file (full path, relative or absolute).
Returns: An instance of the ContextualBayesianOptimization class.
Return type: ContextualBayesianOptimization

get_best_observation() → Tuple[torch.Tensor, torch.Tensor, float][source]¶

Get the best parameters, context and corresponding observed value.

Note

‘Best’ refers to the highest/lowest observed datum.

Returns

torch.Tensor – Location of the highest/lowest observed datum.
torch.Tensor – Context of the highest/lowest observed datum.
float – Function value of the highest/lowest observed datum.

See also

get_optimal_parameters

get_optimal_parameters(context=None) → Tuple[torch.Tensor, float][source]¶

Get the optimal parameters for given context with corresponding value.

Note

‘Optimal’ referes to the optimum of the GP model.

Parameters

context (torch.Tensor, optional) – The context for which to get the optimal parameters. If none is none is provided, use the last observed context.

Returns

torch.Tensor – Location of the GP posterior mean’s optimum for the given context.
float – Function value of the GP posterior mean’s optium for the given context.

See also

get_best_observation

next(goal: bayesopt4ros.msg._BayesOptAction.BayesOptAction) → torch.Tensor¶

Compute new parameters to perform an experiment with.

The functionality of this method can generally be split into three steps:

Update the model with the new data.
Retrieve a new point as response of the server.
Save current state to file.

Parameters: goal (BayesOptAction) – The goal sent from the client for the most recent experiment.
Returns: The new parameters as an array.
Return type: torch.Tensor

update_last_goal(goal: bayesopt4ros.msg._BayesOptAction.BayesOptAction) → None¶

Updates the GP model with the last function value obtained.

Note

This function is only called once from the server, right before shutting down the node. However, we still want to update the GP model with the latest data.

Parameters: goal (BayesOptAction) – The goal sent from the client for the last recent experiment.

Utilities¶

class bayesopt4ros.data_handler.DataHandler(x: Optional[torch.Tensor] = None, y: Optional[torch.Tensor] = None, maximize: bool = True)[source]¶

Helper class that handles all data for BayesOpt.

Note

This is mostly a convenience class to clean up the BO classes.

__init__(x: Optional[torch.Tensor] = None, y: Optional[torch.Tensor] = None, maximize: bool = True) → None[source]¶

The DataHandler class initializer.

Parameters

x (torch.Tensor) – The training inputs.
y (torch.Tensor) – The training targets.
maximize (bool) – Specifies if ‘best’ refers to min or max.

add_xy(x: Optional[torch.Tensor] = None, y: Optional[Union[float, torch.Tensor]] = None)[source]¶: Adds new data to the existing data.

classmethod from_file(file: Union[str, List[str]]) → bayesopt4ros.data_handler.DataHandler[source]¶

Creates a DataHandler instance with input/target values from the specified file.

Parameters: file (str or List[str]) – One or many evaluation files to load data from.
Returns: An instance of the DataHandler class. Returns an empty object if not file could be found.
Return type: DataHandler

get_xy(as_dict: dict = False) → Union[Dict, Tuple[torch.Tensor, torch.Tensor]][source]¶: Returns the data as a tuple (default) or as a dictionary.

property n_data¶: Number of data points.

set_xy(x: Optional[torch.Tensor] = None, y: Optional[Union[float, torch.Tensor]] = None)[source]¶: Overwrites the existing data.

property x_best¶: Location of the best observed datum.

property x_best_accumulate¶: Locations of the best observed datum accumulated along first axis.

property y_best¶: Function value of the best observed datum.

property y_best_accumulate¶: Function value of the best ovbserved datum accumulated along first axis.

bayesopt4ros.util.count_requests(func: Callable) → Callable[source]¶

Decorator that keeps track of number of requests.

Parameters: func (Callable) – The function to be decorated.
Returns: The decorated function.
Return type: Callable

bayesopt4ros.util.create_log_dir(log_dir)[source]¶

Creates a new logging sub-directory with current date and time.

Parameters: log_dir (str) – Path to the root logging directory.
Returns: The final sub-directory path.
Return type: str

bayesopt4ros.util.iter_to_string(it, format_spec, separator=', ')[source]¶

Represents an iterable (list, tuple, etc.) as a formatted string.

Parameters

it (Iterable) – An iterable with numeric elements.
format_spec (str) – Format specifier according to https://docs.python.org/3/library/string.html#format-specification-mini-language
separator (str) – String between items of the iterator.

Returns

The iterable as formatted string.

Return type

str

class bayesopt4ros.util.PosteriorMean(model: botorch.models.model.Model, objective: Optional[botorch.acquisition.objective.ScalarizedObjective] = None, maximize: bool = True)[source]¶

Greedy acquisition function.

Note

Had to overwrite the implementation of BoTorch (version 0.5.0) because it does provide the maximize flag. See the discussion on Github: https://github.com/pytorch/botorch/issues/875

__init__(model: botorch.models.model.Model, objective: Optional[botorch.acquisition.objective.ScalarizedObjective] = None, maximize: bool = True) → None[source]¶

Base constructor for analytic acquisition functions.

Parameters

model – A fitted single-outcome model.
objective – A ScalarizedObjective (optional).

forward(X: torch.Tensor) → torch.Tensor[source]¶: Evaluate the posterior mean on the candidate set X.

Examplary Clients¶

class test_client_python.ExampleClient(server_name: str, objective: Callable, maximize=True)[source]¶

A demonstration on how to use the BayesOpt server from a Python node.

__init__(server_name: str, objective: Callable, maximize=True) → None[source]¶

Initializer of the client that queries the BayesOpt server.

Parameters

server_name (str) – Name of the server (needs to be consistent with server node).
objective (str) – Name of the example objective.
maximize (bool) – If True, consider the problem a maximization problem.

request_bayesopt_state() → bayesopt4ros.msg._BayesOptStateResult.BayesOptStateResult[source]¶: Method that requests the (final) state of BayesOpt server.

Note

As we only call this function once, we can just create the corresponding client locally.

request_parameter(y_new: float) → numpy.ndarray[source]¶

Method that requests new parameters from the BayesOpt server.

Parameters: value (float) – The function value obtained from the objective/experiment.
Returns: An array containing the new parameters suggested by BayesOpt server.
Return type: numpy.ndarray

run() → None[source]¶: Method that emulates client behavior.

class test_client_contextual_python.ExampleContextualClient(server_name: str, objective: Callable, maximize=True)[source]¶

A demonstration on how to use the contexutal BayesOpt server from a Python node.

__init__(server_name: str, objective: Callable, maximize=True) → None[source]¶

Initializer of the client that queries the contextual BayesOpt server.

Parameters

server_name (str) – Name of the server (needs to be consistent with server node).
objective (str) – Name of the example objective.
maximize (bool) – If True, consider the problem a maximization problem.

request_bayesopt_state(context) → bayesopt4ros.msg._ContextualBayesOptStateResult.ContextualBayesOptStateResult[source]¶: Method that requests the (final) state of BayesOpt server.

Note

As we only call this function once, we can just create the corresponding client locally.

request_parameter(y_new: float, c_new: numpy.ndarray) → numpy.ndarray[source]¶

Method that requests new parameters from the ContextualBayesOpt server for a given context.

Parameters

y_new (float) – The function value obtained from the objective/experiment.
c_new (np.ndarray) – The context variable for the next evaluation/experiment.

Returns

An array containing the new parameters suggested by contextual BayesOpt server.

Return type

numpy.ndarray

run() → None[source]¶: Method that emulates client behavior.

sample_context() → numpy.ndarray[source]¶: Samples a random context variable to emulate the client.