Skip to content

Commit

Permalink
Add more writeups for v1.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@zhe-slac
zhe-slac committed Nov 16, 2023
1 parent 955cd31 commit c494440
Show file tree
Hide file tree
Showing 27 changed files with 574 additions and 50 deletions.
34 changes: 3 additions & 31 deletions docs/getting-started/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ Badger is essentially a python package. It's recommended to install and test it

## Requirements

- Python version >= 3.6. Python 3.7+ is recommended
- Python version >= 3.9. Python 3.11+ is recommended

## Install core package
## Install the Badger package

Badger has a core package (`badger-opt`) that can be extended by a set of plugins. Badger core package is available on both [pip](https://pypi.org/project/badger-opt/) and [conda](https://anaconda.org/conda-forge/badger-opt). So you could install Badger with:

Expand All @@ -24,32 +24,4 @@ Or
conda install -c conda-forge badger-opt
```

:::caution

If you go with the conda option and you are using macOS, the Badger GUI would need a specific version of Qt to work properly. Please run the following command in the conda env in which you installed `badger-opt`:

```shell
conda install qt=5.12.5
```

The potential GUI-not-launching issue should be gone now.

:::

## Install sample plugins

Clone the [badger plugins repo](https://github.com/SLAC-ML/Badger-Plugins) to some directory on your computer:

```shell
git clone https://github.com/SLAC-ML/Badger-Plugins.git
```

## Set up Badger

Once `badger-opt` is installed and you have the badger plugins ready, run the following command:

```shell
badger
```

Follow the instructions and configure several paths that are needed by Badger.
That's it!
196 changes: 196 additions & 0 deletions docs/getting-started/tutorial_0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@
---
sidebar_position: 2
---

# Tutorial (GUI mode)

:::note Heads-up

Make sure you have Badger [installed and setup](./installation).

:::

In this short tutorial, we are going to launch Badger in GUI mode, create a routine using the default `sphere_2d` environment shipped with Badger that optimize the following toy problem:

$$
\begin{aligned}
& \underset{x_0,\ x_1}{\text{maximize}}
& & x_0^2 + x_1^2 \\
& \text{subject to}
& & x_i \in [-1, 1], \; i = 0, 1.
\end{aligned}
$$

Then we'll customize the `sphere_2d` environment a bit to add one more variable and shape a `sphere_3d` environment, configure Badger so that it saves data to the directories we specify, create our second routine based on the new `sphere_3d` environment and finally run a new optimization on the problem below:

$$
\begin{aligned}
& \underset{x_0,\ x_1,\ x_2}{\text{minimize}}
& & x_0^2 + x_1^2 + x_2^2 \\
& \text{subject to}
& & x_0 \in [0, 1],\ x_1 \in [-1, -0.5],\ x_2 \in [0.5, 1] \;
\end{aligned}
$$

Let's get started.

## Launch the Badger GUI

Run the following command in your terminal to launch the Badger GUI (assume you are in the python environment in which Badger was installed):

```shell
badger -g
```

You should be able to see the main GUI like below:

![Badger main GUI](/img/gui/main.png)

## Run your first optimization

Before you can run the optimization, you need to create the routine. Click the plus button to the right of the search bar, you'll be navigated to the routine editor:

![Badger routine editor](/img/getting-started/create_1st_routine.png)

Where you can change the routine name and description in the **Metadata** section, as shown above. For your first routine, let's select `upper_confidence_bound` generator[^generator] in the **Algorithm** section. In the **Environment + VOCS** section, select the sphere_2d environment that shipped with Badger.

Now we can shape our optimization problem by configuring the VOCS:

![Configure the VOCS](/img/getting-started/configure_vocs.png)

To archive the above configuration, simply click the blank cell on top of the checkboxes in the variable table to include all the two variables in the routine, then click the *Add Current* button in the **Initial Points** section to add the current values of the variables as the initial points where the optimization starts from. You of course can add more initial points as you wish but for now let's keep it simple -- we only start the run from the current values. Finally check the `f` observable shown in the objectives table and change the rule (direction of the optimization) to `MAXIMIZE`, this means we'll maximize `f` instead of minimize it (which is the default setting).

Now click the *Save* button and we'll be landing back on the main GUI where you can see the monitors, while you'll notice the routine we just created is up there in the routine list, selected and ready to run!

![Ready to run](/img/getting-started/ready_to_go.png)

Now go ahead and click the green *Run* button, feel free to pause/resume the run anytime by clicking the button to the left of the run button, and click the run button (should be turned red now) again to terminate the run.

Congrats! You just run your very first routine in Badger!

![First run](/img/getting-started/first_run.png)

## Customize the environment

Now it's time to do some more serious stuff -- such as performing optimization on your own optimization problem. In order to do that, we need to create our own custom environment (and optionally, the corresponding interface).

First let's point Badger to a new folder where we would like to store our custom plugins. In terminal, do:

```shell
badger config BADGER_PLUGIN_ROOT
```

Follow the CLI guide and set your root for the plugins.

Once that done, put a folder named `sphere_3d` into the environments dir under your plugins root.

Then create the following files inside that `sphere_3d` folder:

- The main python script:

```python title="__init__.py"
from badger import environment


class Environment(environment.Environment):

name = 'sphere_3d' # name of the environment
variables = { # variables and their hard-limited ranges
'x0': [-1, 1],
'x1': [-1, 1],
'x2': [-1, 1],
}
observables = ['f'] # measurements

# Internal variables to store the current values of
# the variables and observables
_variables = {
'x0': 0.0,
'x1': 0.0,
'x2': 0.0,
}
_observations = {
'f': None,
}

# Variable getter -- tells Badger how to get current values of the variables
def get_variables(self, variable_names):
variable_outputs = {v: self._variables[v] for v in variable_names}

return variable_outputs

# Variable setter -- how to set variables to the given values
def set_variables(self, variable_inputs: dict[str, float]):
for var, x in variable_inputs.items():
self._variables[var] = x

# Filling up the observations
f = self._variables['x0'] ** 2 + self._variables['x1'] ** 2 + \
self._variables['x2'] ** 2

self._observations['f'] = [f]

# Observable getter -- how to get current values of the observables
def get_observables(self, observable_names):
return {k: self._observations[k] for k in observable_names}
```

- The config file:

```yaml title="configs.yaml"
---
name: sphere_3d
description: "3D sphere test environment"
version: "0.1"
dependencies:
- torch
- badger-opt
```
- And an optional readme:
```markdown title="README.md"
# 3D Sphere Test Environment for Badger

## Prerequisites

## Usage
```

Now relaunch Badger GUI, you should be able the see the new custom environment we just created in the dropdown menu in the environment selector:



## Configure important Badger settings

You can run the following command to see which settings are configurable in Badger:

```shell
badger config
```

For example you'd like to change the dir where all the databases are stored, you can do:

```shell
badger config BADGER_DB_ROOT
```

Badger would guide you through the setting.

## Run your second optimization

Now it's time to create our new routine with the newly created `sphere_3d` environment. This time we don't have to start from the scratch, instead, we'll base on our first routine, modify the parts as needed, and save the changes as a new routine.

We start by selecting the first routine, then click the *routine editor* tab. Edit the name, description, and the VOCS:

![Edit the first routine](/img/getting-started/configure_vocs_3d.png)

Note that we need to select the `sphere_3d` environment from the env selector and change the variable ranges in the new routine according to our target problem. We'll also change the initial point so that the optimization won't start with the best solution. Since our second problem is a minimization one, remember to change the direction of `f` to *MINIMIZE*. Once configuration is done, click *Save* to save it as a new routine, `my second routine`.

Now we can just run it as we do for `my first routine`, stop whenever you feel right, you should see some optimization curves like this:

![The 2nd run](/img/getting-started/second_run.png)

Congrats! You have accomplished the Badger GUI tutorial! Hope that by this point you already have some feelings about what Badger is and how Badger works. Now you can continue and do the [CLI tutorial](tutorial_1) to get to know the other side of Badger, or you can jump directly to the [guides](../guides/create-a-plugin#create-an-environment-plugin) to adapt Badger to your own optimization problem, good luck!

[^generator]: Term in Xopt, means algorithm
4 changes: 1 addition & 3 deletions docs/getting-started/tutorial.md → docs/getting-started/tutorial_1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
sidebar_position: 2
---

# Tutorial
# Tutorial (CLI mode)

:::note Heads-up

Expand All @@ -12,8 +12,6 @@ Make sure you have Badger [installed and setup](./installation).

Let's discover **Badger in less than 5 minutes**. All of the following commands are assumed to be run in a terminal (Mac, Windows, and Linux are supported).

## Get basic information about Badger

First let's verify that Badger has been installed and configured correctly:

```shell
Expand Down
110 changes: 109 additions & 1 deletion docs/guides/gui-usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,112 @@ sidebar_position: 3

# GUI Usage

**WIP**
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/slaclab/Badger/issues/new) or [shooting us an email](mailto:[email protected]), many thanks :)

## Home page

### Create a new routine

On Badger home page, click the *Plus* button (highlighted in the screenshot below):

![Create new routine](/img/guides/create_new_routine.png)

You'll land on the routine editor page:

![Routine editor](/img/guides/routine_editor.png)

where you can select the generator to use, the environment to optimize on, and configure the VOCS.

### Select/deselect a routine

Hover one item in the routine list (highlighted below) and click it will select the specific routine:

![Hover on routine](/img/guides/hover_on_routine.png)

Once selected, the content in the [history browser](#browse-the-historical-runs) (on top of the run monitor) will change to show the runs corresponding to the selected routine only.

Click the selected routine again to deselect it. If no routine is selected, the history browser will show all the runs for all the routines.

### Delete a routine

Hover the *Delete* button (the one with the trash can icon) on the routine you'd like to delete will highlight it in red, click the button and confirm on the confirmation dialog will delete the routine.

![Delete a routine](/img/guides/delete_routine.png)

Note that deleting a routine will **NOT** automatically delete all the runs associate with it. This behavior is intended to give users a chance to recover it if regretted later. Of course, if all the associated runs have already been deleted, then it will not be possible to recover the routine -- nevertheless you can [recreate it](#create-a-new-routine), creating a routine is not that hard after all.

### Filter routines

You can use the search bar to filter the routines. Badger will try to match the routine names with the text you put in the search bar. Currently we don't support RegEx, but we plan to add the support in the future releases, along with the ability to search other metadata, such as descriptions.

![Filter routines](/img/guides/filter_routines.png)

### Browse the historical runs

You can browse the historical runs in Badger by clicking the *Next*/*Previous* buttons in the history browser:

![History browser](/img/guides/history_browser.png)

or simply click on the combobox that shows the current run name, to trigger a dropdown menu that lists all the matched runs (categorized and sorted by run date and time). Clicking on a run in the menu will show the run data in the run monitor below.

![History dropdown](/img/guides/history_dropdown.png)

Note that the routine editor content will also be refreshed according to routine of the selected run.

### Configure Badger settings

Click the *Settings* button (with the little gear icon) on the bottom right of the Badger GUI will bring up the Badger settings dialog, where you can configure Badger as needed:

![Configure Badger](/img/guides/settings.png)

As a side note, the routine name for the current run shown in the run monitor is displayed besides the *Settings* button.

### Export/import routines

Click the *Export*/*Import* button below the routine list will let you export the [**FILTERED** routines](#filter-routines) as a `.db` file or import the routines in a `.db` file.

![Export/import routines](/img/guides/export_import_routines.png)

## Routine monitor

### Control an optimization run

![Control a run](/img/guides/control.png)

### Reset the environment

You can reset the environment to initial states after a run by clicking the *Reset* button. Note that you can only reset the environment that you just run, and you cannot reset the environment in the middle of a run. To achieve the latter, [terminate the run](#control-an-optimization-run) first and then reset.

![Reset the env](/img/guides/control.png)

### Inspect the solutions in a run

![Inspect solutions](/img/guides/inspect_sol.png)

### Jump to the optimal solution

### Dial in the selected solution

### Change the horizontal axis

You can show the run on iteration-based x-axis or time-based x-axis. Simply select the desired x-axis type in the dropdown menu of the *X Axis Plot Type* selector will do. You can switch the x-axis types anytime, in the middle of a run of not.

### Normalize the variables for better visualization

You can show the run on iteration-based x-axis or time-based x-axis. Simply select the desired x-axis type in the dropdown menu of the *X Axis Plot Type* selector will do. You can switch the x-axis types anytime, in the middle of a run of not.

### Delete a run

### Send record to logbook

### Use data analysis/visualization extensions

## Routine editor

### Set the metadata

### Select and configure the generator

### Select and configure the environment

### Configure the VOCS
Loading

0 comments on commit c494440

Please sign in to comment.