diff --git a/blog/2021-11-24-welcome/index.md b/blog/2021-11-24-welcome/index.md index 4220294..d4d8263 100644 --- a/blog/2021-11-24-welcome/index.md +++ b/blog/2021-11-24-welcome/index.md @@ -8,3 +8,5 @@ tags: [SLAC, hello, badger] ![Badger Banner](./badger-banner.png) Hello world from Badger! + + \ No newline at end of file diff --git a/docs/extensions/bo-extension.md b/docs/extensions/bo-extension.md index abc54c3..68fde88 100644 --- a/docs/extensions/bo-extension.md +++ b/docs/extensions/bo-extension.md @@ -2,31 +2,31 @@ sidebar_position: 1 --- -# BO Visualization +# Bayesian optimization visualizer ## Overview -The BO Visualization extension allows for an interactive graphical interpretation of the model of the objective and constraining functions generated during BO an optimization. +The Bayesian optimization visualizer extension allows for an interactive graphical interpretation of the model of the objective and constraining functions generated during BO an optimization. ## Usage -The extension can be used both statically and dynamically during or after a Badger optimization run. When used during an Badger optimization, the plots will update at a set interval in real time according to the variables and plot options set. Any plot options, reference points, and variables are saved throughout the use of that instance of the BO Visualization extension and are lost when the window is closed. +The extension can be used both statically and dynamically during or after a Badger optimization run. When used during a Badger optimization, the plots will update at a set interval in real time according to the variables and plot options set. Any plot options, reference points, and variables are saved throughout the use of that instance of the Bayesian optimization visualizer extension and are lost when the window is closed. ## Constraints -The BO Visualization extension is only available when conducting a Badger optimization that uses a Bayesian Generator such as the `expected_improvement` and `mobo` algorithms. +The Bayesian optimization visualizer extension is only available when conducting a Badger optimization that uses a Bayesian Generator such as the `expected_improvement` and `mobo` algorithms. ## Tutorial ### Step 1: Start Badger optimization -First step to use the BO Visualization is to use the Badger UI to run through an optimization using a compatible Bayesian algorithm. +First step to use the Bayesian optimization visualizer is to use the Badger UI to run through an optimization using a compatible Bayesian algorithm. -Once you have a converged on a solution or have stopped the optimization after a certain number of iterations, you can visualize the model of the objective and constraint functions by opening the BO Visualization extension. +Once you have a converged on a solution or have stopped the optimization after a certain number of iterations, you can visualize the model of the objective and constraint functions by opening the Bayesian optimization visualizer extension. ### Step 2: How to access the extension -![extension window](/img/extensions/bo/extension-window.png) +![extension palette](/img/extensions/extension-palette.png) Description: @@ -35,9 +35,9 @@ Description: **2** - The Badger extensions palette contains all extensions included by default with Badger Note: not all extensions are applicable to every optimization configuration -**3** - Access the BO Visualization extension by clicking the corresponding option within the Badger extensions palette +**3** - Access the Bayesian optimization visualizer extension by clicking the corresponding option within the Badger extensions palette -### Step 3: BO Visualization controls +### Step 3: Bayesian optimization visualizer controls ![bo extension window](/img/extensions/bo/bo-window.png) @@ -51,7 +51,9 @@ Description: - **Note:** In >2D spaces the reference point will display the input space value for axes that are not visualized on the plot -**4** - If you wish to change what is information being displayed you can do so by modifying the various plot options +**4** - The set best reference point button will set the reference point within the extension to the current best observed point in the optimization run according to Badger. + +**5** - If you wish to change what is information being displayed you can do so by modifying the various plot options - **Acquisition function** - value is maximized to select the next point to observe during Bayesian optimization. - **Note:** acquisition function is often exponentiated for visualization purposes. @@ -61,11 +63,22 @@ Description: - **Prior Mean (Optional)** - -- **Feasibility (Optional)** - the probability that all of the constraints are satisfied at a given location +- **Feasibility (Optional)** - the probability that all the constraints are satisfied at a given location - **No. of grid points** - the number of mesh points used to visualize the model value, higher number of points produces a higher resolution visualization, but at the cost of increased computation time -**5** - The BO Visualization extension will automatically update the charts reactively upon any changes however, if at any point you believe the plots are out of sync then you can forcefully update the plots using the update button +**6** - The charts within the extension are interactive through mouse inputs and can display additional information. + +The possible actions are as follows: + + +- `Right Click` - Will allow you to set the reference point based on the current mouse position. +- `Middle Click` - Will reset the view and reference points to their default states. +- `Scroll` - Zoom in and out of the chart. + +**7** - For additional interaction options, you can also use the Matplotlib navigation toolbar to modify the current view or export the current plot. + +**8** - The Bayesian optimization visualizer extension will automatically update the charts reactively upon any changes however, if at any point you believe the plots are out of sync then you can forcefully update the plots using the update button ### Charts explanation diff --git a/docs/extensions/pf-extension.md b/docs/extensions/pf-extension.md new file mode 100644 index 0000000..0ac7604 --- /dev/null +++ b/docs/extensions/pf-extension.md @@ -0,0 +1,68 @@ +--- +sidebar_position: 2 +--- + +# Pareto front viewer + +## Overview + +The Pareto front viewer extension allows for an interactive graphical interface for visualizing the Pareto front of a multi-objective optimization problem in both objective and variable spaces. + +## Usage + +The extension can be used both statically and dynamically during or after a Badger optimization run. When used during a Badger optimization, the plots will update at a set interval in real time according to the variables and plot options set. Any plot options, reference points, and variables are saved throughout the use of that instance of the Pareto front viewer extension and are lost when the window is closed. + +## Constraints + +The Pareto front viewer extension requires a Badger optimization run that uses an algorithm that utilizes the Xopt `MOBOGenerator` and that has 2 or more objectives defined in the optimization problem. The extension will not be available for single-objective optimizations and is only compatible with the `mobo` algorithm currently. + +## Tutorial + +### Step 1: Start Badger optimization + +First step to use the Pareto front viewer is to use the Badger UI to run through an optimization using a compatible algorithm. + +Once you have a converged on a solution or have stopped the optimization after a certain number of iterations, you can visualize the model by opening the Pareto front viewer extension. + +### Step 2: How to access the extension + +![extension palette](/img/extensions/extension-palette.png) + +Description: + +**1** - Access the Badger extensions palette by clicking the icon in the bottom right + +**2** - The Badger extensions palette contains all extensions included by default with Badger + Note: not all extensions are applicable to every optimization configuration + +**3** - Access the Pareto front viewer extension by clicking the corresponding option within the Badger extensions palette + +### Step 3: Pareto front viewer controls + +![pareto front viewer window](/img/extensions/pf/pf-window.png) + +Description: + +**1** - Change the variables or objectives that are being plotted by the X and Y axes within the extension depending on the selected type of plot. + +**2** - To only show the data points that are included in the Pareto front, you can enable the "Show only Pareto Front" option and the charts will update to show those data points. + +**3** - There are two separate charts that visualize the Pareto front data in different ways: one in an objective space and one in the variable space. When selecting either of these charts through the tabs at the top of the extension, the corresponding data will be displayed. The X and Y axes plotted within the chart will update automatically according to the selected chart type. + +**4** - The charts within the extension are interactive through mouse inputs and can display additional information. + +The possible actions are as follows: + +- `Left Click` - Select a data point to view both the coordinate values in the selected space and the index of the iteration that the data point corresponds to within the optimization run. +- `Right Click` or `Middle Click` - Will reset the view to the default state. +- `Scroll` - Zoom in and out of the chart. + +**5** - For additional interaction options, you can also use the Matplotlib navigation toolbar to modify the current view or export the current plot. + +**6** - The Pareto front viewer extension will automatically update the charts reactively upon any changes however, if at any point you believe the plots are out of sync then you can forcefully update the plots using the update button + +### Charts explanation + +The leftmost chart is able to visualize the optimization run data in either the objective space or the variable space, depending on the selected tab. When the objective space tab is selected, the chart will display the values of the objectives selected for each axes as the optimization progressed. When the variable space tab is selected, the chart will display the same information for the input variables. For both of the charts, each of the data points are color-coded based on the index of the corresponding iteration within the optimization run. When the "Show only Pareto Front" option is enabled, the chart will only display the data points that are directly a part of the Pareto front in the selected space. + +The rightmost chart is a plot of the hypervolume as it evolves over the course of the optimization run. The hypervolume is a measure of the volume of the space covered by the Pareto front. diff --git a/docs/guides/gui-usage.md b/docs/guides/gui-usage.md index b379a09..7fbb22f 100644 --- a/docs/guides/gui-usage.md +++ b/docs/guides/gui-usage.md @@ -6,7 +6,7 @@ sidebar_position: 1 Once you launch Badger in GUI mode, you'll have various Badger features to explore. You can search through this page to get to the guide on any specify GUI feature, or if you believe a guide is missing for the topic you are interested in, please consider [raising an issue here](https://github.com/xopt-org/Badger/issues/new) or [shooting us an email](mailto:zhezhang@slac.stanford.edu), many thanks :) -## GUI Layout +## GUI Layout The Badger GUI is an interface made for optimizing accelerator performance. Behind the scenes, Badger uses Xopt, a python package designed to support a wide variety of control system optimization problems and algorithms. There are four important sections to defining an optimization problem using the Badger GUI: **Environment**, **VOCS**, **Algorithm**, and **Metadata**. The Badger GUI organizes these into three tabs, with Environment + VOCS being combined into a single main tab. @@ -74,7 +74,7 @@ The **Algorithm** section lets you select an algorithm to use for optimization ( 3. **If the “Automatic” checkbox is checked, selecting a variable will automatically add a set of initial points.** By default, these will be the current value followed by three random points within a fraction of the variable bounds centered around the current value. If **Automatic** is not checked, or to adjust the initial points, you can use the **Add Current** and **Add Random** buttons to configure your own initial points. -![Badger GUI new optimization, lower page](/img/gui/highlight_new_optimization_2.png) + ![Badger GUI new optimization, lower page](/img/gui/highlight_new_optimization_2.png) 4. **Select an objective from the “Objectives” table.** Make sure to select whether the objective should be maximized or minimized! Currently only single objective optimization is available, but multi-objective optimization will be supported in the future. @@ -83,7 +83,8 @@ The **Algorithm** section lets you select an algorithm to use for optimization ( Beneath the **Objectives** table is a collapsable **More** section, which allows you to add Constraints and Observables. The constraints and observables available for selection are based on the selected environment. 6. **Choose an optimization algorithm.** - There are several different optimization algorithms available within the Badger GUI. Generally, **expected improvement** and **Nelder-Mead** are good choices for online accelerator optimization. To select an algorithm navigate to the "Algorithm" tab. To read more about different algorithms, see the "[Overview of Different Optimization Algorithms](#overview-of-different-optimization-algorithms)” section below. + There are several different optimization algorithms available within the Badger GUI. Generally, **expected improvement** and **Nelder-Mead** are good choices for online accelerator optimization. To select an algorithm navigate to the "Algorithm" tab. + 7. **Metadata:** Provide a name and description for your optimization routine. diff --git a/static/img/extensions/bo/bo-window.png b/static/img/extensions/bo/bo-window.png index 100743c..b0886c0 100644 Binary files a/static/img/extensions/bo/bo-window.png and b/static/img/extensions/bo/bo-window.png differ diff --git a/static/img/extensions/bo/extension-window.png b/static/img/extensions/bo/extension-window.png deleted file mode 100644 index 8377bdb..0000000 Binary files a/static/img/extensions/bo/extension-window.png and /dev/null differ diff --git a/static/img/extensions/extension-palette.png b/static/img/extensions/extension-palette.png new file mode 100644 index 0000000..4375902 Binary files /dev/null and b/static/img/extensions/extension-palette.png differ diff --git a/static/img/extensions/pf/pf-window.png b/static/img/extensions/pf/pf-window.png new file mode 100644 index 0000000..135b97e Binary files /dev/null and b/static/img/extensions/pf/pf-window.png differ diff --git a/versioned_docs/version-1.4/extensions/bo-extension.md b/versioned_docs/version-1.4/extensions/bo-extension.md index abc54c3..68fde88 100644 --- a/versioned_docs/version-1.4/extensions/bo-extension.md +++ b/versioned_docs/version-1.4/extensions/bo-extension.md @@ -2,31 +2,31 @@ sidebar_position: 1 --- -# BO Visualization +# Bayesian optimization visualizer ## Overview -The BO Visualization extension allows for an interactive graphical interpretation of the model of the objective and constraining functions generated during BO an optimization. +The Bayesian optimization visualizer extension allows for an interactive graphical interpretation of the model of the objective and constraining functions generated during BO an optimization. ## Usage -The extension can be used both statically and dynamically during or after a Badger optimization run. When used during an Badger optimization, the plots will update at a set interval in real time according to the variables and plot options set. Any plot options, reference points, and variables are saved throughout the use of that instance of the BO Visualization extension and are lost when the window is closed. +The extension can be used both statically and dynamically during or after a Badger optimization run. When used during a Badger optimization, the plots will update at a set interval in real time according to the variables and plot options set. Any plot options, reference points, and variables are saved throughout the use of that instance of the Bayesian optimization visualizer extension and are lost when the window is closed. ## Constraints -The BO Visualization extension is only available when conducting a Badger optimization that uses a Bayesian Generator such as the `expected_improvement` and `mobo` algorithms. +The Bayesian optimization visualizer extension is only available when conducting a Badger optimization that uses a Bayesian Generator such as the `expected_improvement` and `mobo` algorithms. ## Tutorial ### Step 1: Start Badger optimization -First step to use the BO Visualization is to use the Badger UI to run through an optimization using a compatible Bayesian algorithm. +First step to use the Bayesian optimization visualizer is to use the Badger UI to run through an optimization using a compatible Bayesian algorithm. -Once you have a converged on a solution or have stopped the optimization after a certain number of iterations, you can visualize the model of the objective and constraint functions by opening the BO Visualization extension. +Once you have a converged on a solution or have stopped the optimization after a certain number of iterations, you can visualize the model of the objective and constraint functions by opening the Bayesian optimization visualizer extension. ### Step 2: How to access the extension -![extension window](/img/extensions/bo/extension-window.png) +![extension palette](/img/extensions/extension-palette.png) Description: @@ -35,9 +35,9 @@ Description: **2** - The Badger extensions palette contains all extensions included by default with Badger Note: not all extensions are applicable to every optimization configuration -**3** - Access the BO Visualization extension by clicking the corresponding option within the Badger extensions palette +**3** - Access the Bayesian optimization visualizer extension by clicking the corresponding option within the Badger extensions palette -### Step 3: BO Visualization controls +### Step 3: Bayesian optimization visualizer controls ![bo extension window](/img/extensions/bo/bo-window.png) @@ -51,7 +51,9 @@ Description: - **Note:** In >2D spaces the reference point will display the input space value for axes that are not visualized on the plot -**4** - If you wish to change what is information being displayed you can do so by modifying the various plot options +**4** - The set best reference point button will set the reference point within the extension to the current best observed point in the optimization run according to Badger. + +**5** - If you wish to change what is information being displayed you can do so by modifying the various plot options - **Acquisition function** - value is maximized to select the next point to observe during Bayesian optimization. - **Note:** acquisition function is often exponentiated for visualization purposes. @@ -61,11 +63,22 @@ Description: - **Prior Mean (Optional)** - -- **Feasibility (Optional)** - the probability that all of the constraints are satisfied at a given location +- **Feasibility (Optional)** - the probability that all the constraints are satisfied at a given location - **No. of grid points** - the number of mesh points used to visualize the model value, higher number of points produces a higher resolution visualization, but at the cost of increased computation time -**5** - The BO Visualization extension will automatically update the charts reactively upon any changes however, if at any point you believe the plots are out of sync then you can forcefully update the plots using the update button +**6** - The charts within the extension are interactive through mouse inputs and can display additional information. + +The possible actions are as follows: + + +- `Right Click` - Will allow you to set the reference point based on the current mouse position. +- `Middle Click` - Will reset the view and reference points to their default states. +- `Scroll` - Zoom in and out of the chart. + +**7** - For additional interaction options, you can also use the Matplotlib navigation toolbar to modify the current view or export the current plot. + +**8** - The Bayesian optimization visualizer extension will automatically update the charts reactively upon any changes however, if at any point you believe the plots are out of sync then you can forcefully update the plots using the update button ### Charts explanation diff --git a/versioned_docs/version-1.4/extensions/pf-extension.md b/versioned_docs/version-1.4/extensions/pf-extension.md new file mode 100644 index 0000000..0ac7604 --- /dev/null +++ b/versioned_docs/version-1.4/extensions/pf-extension.md @@ -0,0 +1,68 @@ +--- +sidebar_position: 2 +--- + +# Pareto front viewer + +## Overview + +The Pareto front viewer extension allows for an interactive graphical interface for visualizing the Pareto front of a multi-objective optimization problem in both objective and variable spaces. + +## Usage + +The extension can be used both statically and dynamically during or after a Badger optimization run. When used during a Badger optimization, the plots will update at a set interval in real time according to the variables and plot options set. Any plot options, reference points, and variables are saved throughout the use of that instance of the Pareto front viewer extension and are lost when the window is closed. + +## Constraints + +The Pareto front viewer extension requires a Badger optimization run that uses an algorithm that utilizes the Xopt `MOBOGenerator` and that has 2 or more objectives defined in the optimization problem. The extension will not be available for single-objective optimizations and is only compatible with the `mobo` algorithm currently. + +## Tutorial + +### Step 1: Start Badger optimization + +First step to use the Pareto front viewer is to use the Badger UI to run through an optimization using a compatible algorithm. + +Once you have a converged on a solution or have stopped the optimization after a certain number of iterations, you can visualize the model by opening the Pareto front viewer extension. + +### Step 2: How to access the extension + +![extension palette](/img/extensions/extension-palette.png) + +Description: + +**1** - Access the Badger extensions palette by clicking the icon in the bottom right + +**2** - The Badger extensions palette contains all extensions included by default with Badger + Note: not all extensions are applicable to every optimization configuration + +**3** - Access the Pareto front viewer extension by clicking the corresponding option within the Badger extensions palette + +### Step 3: Pareto front viewer controls + +![pareto front viewer window](/img/extensions/pf/pf-window.png) + +Description: + +**1** - Change the variables or objectives that are being plotted by the X and Y axes within the extension depending on the selected type of plot. + +**2** - To only show the data points that are included in the Pareto front, you can enable the "Show only Pareto Front" option and the charts will update to show those data points. + +**3** - There are two separate charts that visualize the Pareto front data in different ways: one in an objective space and one in the variable space. When selecting either of these charts through the tabs at the top of the extension, the corresponding data will be displayed. The X and Y axes plotted within the chart will update automatically according to the selected chart type. + +**4** - The charts within the extension are interactive through mouse inputs and can display additional information. + +The possible actions are as follows: + +- `Left Click` - Select a data point to view both the coordinate values in the selected space and the index of the iteration that the data point corresponds to within the optimization run. +- `Right Click` or `Middle Click` - Will reset the view to the default state. +- `Scroll` - Zoom in and out of the chart. + +**5** - For additional interaction options, you can also use the Matplotlib navigation toolbar to modify the current view or export the current plot. + +**6** - The Pareto front viewer extension will automatically update the charts reactively upon any changes however, if at any point you believe the plots are out of sync then you can forcefully update the plots using the update button + +### Charts explanation + +The leftmost chart is able to visualize the optimization run data in either the objective space or the variable space, depending on the selected tab. When the objective space tab is selected, the chart will display the values of the objectives selected for each axes as the optimization progressed. When the variable space tab is selected, the chart will display the same information for the input variables. For both of the charts, each of the data points are color-coded based on the index of the corresponding iteration within the optimization run. When the "Show only Pareto Front" option is enabled, the chart will only display the data points that are directly a part of the Pareto front in the selected space. + +The rightmost chart is a plot of the hypervolume as it evolves over the course of the optimization run. The hypervolume is a measure of the volume of the space covered by the Pareto front. diff --git a/versioned_docs/version-1.4/guides/gui-usage.md b/versioned_docs/version-1.4/guides/gui-usage.md index b379a09..7fbb22f 100644 --- a/versioned_docs/version-1.4/guides/gui-usage.md +++ b/versioned_docs/version-1.4/guides/gui-usage.md @@ -6,7 +6,7 @@ sidebar_position: 1 Once you launch Badger in GUI mode, you'll have various Badger features to explore. You can search through this page to get to the guide on any specify GUI feature, or if you believe a guide is missing for the topic you are interested in, please consider [raising an issue here](https://github.com/xopt-org/Badger/issues/new) or [shooting us an email](mailto:zhezhang@slac.stanford.edu), many thanks :) -## GUI Layout +## GUI Layout The Badger GUI is an interface made for optimizing accelerator performance. Behind the scenes, Badger uses Xopt, a python package designed to support a wide variety of control system optimization problems and algorithms. There are four important sections to defining an optimization problem using the Badger GUI: **Environment**, **VOCS**, **Algorithm**, and **Metadata**. The Badger GUI organizes these into three tabs, with Environment + VOCS being combined into a single main tab. @@ -74,7 +74,7 @@ The **Algorithm** section lets you select an algorithm to use for optimization ( 3. **If the “Automatic” checkbox is checked, selecting a variable will automatically add a set of initial points.** By default, these will be the current value followed by three random points within a fraction of the variable bounds centered around the current value. If **Automatic** is not checked, or to adjust the initial points, you can use the **Add Current** and **Add Random** buttons to configure your own initial points. -![Badger GUI new optimization, lower page](/img/gui/highlight_new_optimization_2.png) + ![Badger GUI new optimization, lower page](/img/gui/highlight_new_optimization_2.png) 4. **Select an objective from the “Objectives” table.** Make sure to select whether the objective should be maximized or minimized! Currently only single objective optimization is available, but multi-objective optimization will be supported in the future. @@ -83,7 +83,8 @@ The **Algorithm** section lets you select an algorithm to use for optimization ( Beneath the **Objectives** table is a collapsable **More** section, which allows you to add Constraints and Observables. The constraints and observables available for selection are based on the selected environment. 6. **Choose an optimization algorithm.** - There are several different optimization algorithms available within the Badger GUI. Generally, **expected improvement** and **Nelder-Mead** are good choices for online accelerator optimization. To select an algorithm navigate to the "Algorithm" tab. To read more about different algorithms, see the "[Overview of Different Optimization Algorithms](#overview-of-different-optimization-algorithms)” section below. + There are several different optimization algorithms available within the Badger GUI. Generally, **expected improvement** and **Nelder-Mead** are good choices for online accelerator optimization. To select an algorithm navigate to the "Algorithm" tab. + 7. **Metadata:** Provide a name and description for your optimization routine.