Skip to content

Commit

Permalink
minor changes to 5_AcquisitionFunction.md (in progress)
Browse files Browse the repository at this point in the history
  • Loading branch information
xuyuting committed Aug 17, 2024
1 parent 3f21b92 commit 5272736
Showing 1 changed file with 37 additions and 36 deletions.
73 changes: 37 additions & 36 deletions docs/wiki/5_AcquisitionFunction.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,68 +4,69 @@

The [`obsidian.acquisition`](https://github.com/MSDLLCpapers/obsidian/tree/main/obsidian/acquisition) submodule is a crucial component of the Obsidian APO library. It provides acquisition functions that guide the optimization process by determining which points in the parameter space should be evaluated next. These acquisition functions balance exploration of uncertain areas and exploitation of promising regions, which is key to efficient optimization.

## 2. Basic Syntax
## 2. Usage

Typically, users don't need to interact with acquisition functions directly.
The `BayesianOptimizer` class handles the selection and use of acquisition functions.
The acquisition functions, as well as their hyperparameters, could be specified as an input argument when calling the `suggest` method.

The format of `acquisition` should be a list of strings (if using default hyperparameters) and/or dictionaries, where the key is an acquisition function name and the value is a nested dictionary storing its hyperparameter:

```python
# DO NOT RUN
from obsidian.optimizer import BayesianOptimizer

optimizer = BayesianOptimizer(X_space=param_space)

# Use one acquisition function EI per iteration
X_suggest, eval_suggest = optimizer.suggest(acquisition=['EI'])
### 2.1 Available Acquisition Functions

# Use two acquisition functions EI and UCB per iteration
X_suggest, eval_suggest = optimizer.suggest(acquisition=['EI','UCB'])

# Use two acquisition functions EI and UCB per iteration, while specifying hyperparameters for UCB
X_suggest, eval_suggest = optimizer.suggest(acquisition=['EI',{'UCB':{'beta':0.1}}])
```

## 3. Customization Options

### 3.1 Available Acquisition Function Names

The acquisition submodule includes multiple acquisition functions, both standard `BoTorch` acquisition functions and custom implementations.
Below are several categories of options for the `acquisition` argument, each followed by a short description.
The acquisition submodule offers a range of acquisition functions, including standard `BoTorch` acquisition functions and custom implementations.
Below, you will find various options for the acquisition argument, along with a brief description for each.

#### Standard Acquisition Functions from BoTorch

_Single-Objective Optimization:_

- EI: Expected Improvement
- NEI: Noisy Expected Improvement
- PI: Probability of Improvement
- UCB: Upper Confidence Bound
- SR: Simple Regret
- NIPV: Integrated Negative Posterior Variance

_Multi-Objective Optimization:_

- EHVI: Expected Hypervolume Improvement
- NEHVI: Noisy Expected Hypervolume Improvement
- NParEGO: Random augmented chebyshev scalarization with Noisy Expected Improvement
- NIPV: Integrated Negative Posterior Variance

#### Custom Acquisition Functions

- Mean: qMean: Optimizes for the maximum value of the posterior mean
- SF: qSpaceFill: Optimizes for the maximum value of minimum distance between a point and the training data
- Mean: Seeks to optimize the maximum value of the posterior mean
- SF: Space filling, aims to optimize the maximum value of the minimum distance between a point and the training data

#### Baseline: No Acquisition Function

- RS: Random sampling from the parameter space

### 2.2 Basic Syntax

Typically, users don't need to interact with acquisition functions directly.
The `BayesianOptimizer` class handles the selection and use of acquisition functions.
The acquisition functions, as well as their hyperparameters, could be specified as an input argument when calling the `suggest` method:

```python
# DO NOT RUN
from obsidian.optimizer import BayesianOptimizer

optimizer = BayesianOptimizer(X_space=param_space)

# Use one acquisition function EI per iteration
X_suggest, eval_suggest = optimizer.suggest(acquisition=['EI'])

### 3.2 Shared Hyperparameters
# Use two acquisition functions EI and UCB per iteration
X_suggest, eval_suggest = optimizer.suggest(acquisition=['EI','UCB'])

# Use two acquisition functions EI and UCB per iteration, while specifying hyperparameters for UCB
X_suggest, eval_suggest = optimizer.suggest(acquisition=['EI',{'UCB':{'beta':0.1}}])
```

There are some commonly used hyperparameters that could apply to multiple acquisition functions.
The `acquisition` parameter should be always a list, containing either string or dictionary elements. When multiple elements are present in the list, the `suggest` function will propose new candidates sequentially using each acquisition function.

* If using the default hyperparameters for an acquisition function, specify a string element using the name of the acquisition function (e.g., 'EI' for Expected Improvement).
* If specifying custom hyperparameters for an acquisition function, use a dictionary element where the key is the acquisition function name and the value is a nested dictionary storing its hyperparameters (e.g., {'UCB': {'beta': 0.1}} for Upper Confidence Bound with a specified beta parameter).


---------------
## 3. Understanding Acquisition Functions and Hyperparameters

## 4. Understanding Acquisition Functions and Hyperparameters

### 3.1 Expected Improvement (EI)

Expand Down Expand Up @@ -111,7 +112,7 @@ X_suggest, eval_suggest = optimizer.suggest(acquisition=['NEI'])

## 4. Advanced Usage

### 4.1 Multi-Objective Optimization
### 4.1 Additional Options for Multi-Objective Optimization

For multi-objective optimization problems, you can use specialized acquisition functions:

Expand Down

0 comments on commit 5272736

Please sign in to comment.