Skip to content

Commit 0af04d8

Browse files
committed
updated the readme file
1 parent 262ff1a commit 0af04d8

File tree

1 file changed

+72
-16
lines changed

1 file changed

+72
-16
lines changed

README.md

Lines changed: 72 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,36 @@
1-
## 📌 Overview
1+
# 🚀 Scalable Neural Network-based Blackbox Optimization
22

3-
This repository implements Scalable Neural Network-based Blackbox Optimization (SNBO) — a novel
4-
method for efficient blackbox optimization using neural networks. This repository also includes code
5-
for various benchmark methods used for evaluating the SNBO.
3+
This repository provides implementation for SNBO (Scalable Neural Network-based Blackbox Optimization) — a novel method for efficient blackbox optimization using neural networks. It also includes code for benchmark algorithms and a suite of test problems used in the paper.
64

7-
This work is currently under review and will be available soon.
5+
📝 **Note**: This work is currently under review. Citation details will be available soon.
6+
7+
## 📌 Features
8+
9+
This repository includes implementations for the following optimization algorithms:
10+
11+
- `SNBO`: Scalable neural network-based blackbox optimization (proposed method)
12+
- `BO+LogEI`: [Bayesian optimization with LogEI acquisition](https://arxiv.org/abs/2310.20708)
13+
- `IBNN`: [Bayesian optimization with IBNN kernel and LogEI acquisition](https://botorch.org/docs/tutorials/ibnn_bo/#i-bnns-for-bayesian-optimization)
14+
- `TuRBO`: [Trust region Bayesian optimization](https://arxiv.org/abs/1910.01739)
15+
- `DYCORS`: [Dynamic coordinate search with repsonse surface model](https://www.tandfonline.com/doi/abs/10.1080/0305215X.2012.687731)
16+
17+
This repository also contains following test problems:
18+
19+
- [Ackley function](https://www.sfu.ca/~ssurjano/ackley.html)
20+
- [Rastrigin function](https://www.sfu.ca/~ssurjano/rastr.html)
21+
- [Levy function](https://www.sfu.ca/~ssurjano/levy.html)
22+
- [Rover trajectory optimization](https://github.com/zi-w/Ensemble-Bayesian-Optimization/blob/master/test_functions/rover_function.py)
23+
- [Half-Cheetah problem](https://gymnasium.farama.org/environments/mujoco/half_cheetah/)
824

925
## 🛠 Installation
1026

11-
Before running SNBO or any of the benchmark methods, you need to set up the environment and install the dependencies.
27+
Before running any example, you need to set up the environment and install the dependencies.
1228

1329
### 🐍 1. Create a conda environment
1430

1531
```
1632
conda create -n "snbo" python=3.12
33+
conda activate snbo
1734
```
1835

1936
### 📦 2. Install dependecies
@@ -25,36 +42,75 @@ pip install numpy==2.3.1 scipy==1.16.0 matplotlib==3.10.3 torch==2.7.1
2542
gpytorch==1.14 botorch==0.14.0 gymnasium["mujoco"]==1.2.0
2643
```
2744

28-
If you want to use DYCORS for running a test case, then please install it by downloading the
29-
[DYCORS repository](https://github.com/aquirosr/DyCors) and running following command in terminal:
45+
If you want to use DYCORS, then please install it using following commands:
3046

3147
```
48+
git clone https://github.com/aquirosr/DyCors
49+
cd DyCors
3250
pip install .
3351
```
3452

35-
## ▶️ Running Examples
53+
## ▶️ Running examples
54+
55+
The main file for running experiments is `optimize.py`, found in algorithms folder. This file provides following arguments:
3656

37-
Before running any of the runscripts, you need to append the path of the
38-
root folder to `PYTHONPATH`. The command for this is already available at the top of all the script files in the runscript folder.
57+
| Argument | Type | Description |
58+
| ----------- | ---- | ----------------------------------------------------------------------------- |
59+
| `method` | str | Optimization method: `"bo"`, `"ibnn"`, `"turbo"`, `"dycors"`, `"snbo"` |
60+
| `problem` | str | Test problem: `"ackley"`, `"rastrigin"`, `"levy"`, `"rover"`, `"halfcheetah"` |
61+
| `dim` | int | Dimensionality of the problem |
62+
| `n_init` | int | Number of initial samples |
63+
| `max_evals` | int | Maximum number of function evaluations |
64+
| `neurons` | list | Neurons per layer (only for `snbo`) |
65+
| `act_funcs` | list | Activation functions per layer (only for `snbo`) |
66+
| `seed` | int | Random seed (optional) |
3967

40-
Open the script file and ensure that the correct path is mentioned.
68+
There are two ways to run this file:
69+
70+
✅ Option 1: You can directly run the file from the terminal. For example, to solve the rover problem using SNBO method, you can use following command:
71+
72+
```
73+
python algorithms/optimize.py --method "snbo" --problem "rover" --dim 100 --n_init 200 --max_evals 2000 --neurons 256 256 --act_funcs "GELU" "GELU"
74+
```
75+
76+
> ⚠️ ***NOTE***: Before running the file, you need to append the path of the root folder to `PYTHONPATH` variable. This can be done by running following command in the terminal before running the python file:
77+
78+
```
79+
export PYTHONPATH=PATH_TO_SNBO_FOLDER:$PYTHONPATH
80+
```
81+
82+
Or, you can add this line to your shell configuration file (`.bashrc` or`.zshrc`) and reload the terminal.
83+
84+
✅ Option 2 (**Recommended**): Instead of directly running the `optimize.py` file, you can use one of the ready-to-use scripts available in runscript folder. These scripts already include the `export` statement requried for appending the `PYTHONPATH` variable at the start of the script, you just need to ensure that correct path is defined.
4185

4286
To solve a test problem using SNBO or any of the benchmark methods, you can use ``single_run.sh`` file under runscripts folder. To execute the file, run:
4387

4488
```
45-
sh runscripts/single_run.sh
89+
bash runscripts/single_run.sh
4690
```
4791

4892
If you want to run a batch of optimization, you can use ``batch_run.sh`` file under runscripts folder. To execute the file, run:
4993

5094
```
51-
sh runscripts/batch_run.sh
95+
bash runscripts/batch_run.sh
5296
```
5397

5498
When you execute any of the above commands, it will create a folder name ``results`` and will save the entire optimization history in a mat file.
5599

56-
> 💡 **_NOTE:_** It is recommended to run the bash file or `optimize.py` file from the root folder and NOT from within the subfolder.
100+
> ⚠️ **_NOTE:_** It is recommended to run the python or the bash file from the root folder and NOT from within the subfolder.
101+
102+
## 📊 Results from paper
103+
104+
To reproduce the data reported in the paper, you can use ``paper_results.sh`` script. Use the following command to run this script:
105+
106+
```
107+
bash runscripts/paper_results.sh
108+
```
109+
110+
For each seed value, this script loops through each problem and solves it using all the methods.
111+
112+
> **Warning**: This script will take a long time to run, depending on the resources used
57113
58114
## 🧾 Citation
59115

60-
If you use this code or SNBO method in your research, please cite the original work (citation coming soon, paper under review).
116+
If you use SNBO method in your research, please cite the original work (citation coming soon, paper under review).

0 commit comments

Comments
 (0)