# BOAR : Bayesian Optimization for Automated Research
## Authors
[Vincent M. Le Corre](https://github.com/VMLC-PV)
[Larry Lüer](https://github.com/larryluer)
## Institution
Institute Materials for Electronics and Energy Technology (i-MEET)
University of Erlangen-Nuremberg (FAU)
Erlangen, Germany
## Description
This repository contains the code to run the BOAR. BOAR is a Bayesian optimization procedure that can be use for two objectives:
1. to optimize the parameters of a simulation to fit experimental data.
2. to optimize the processing conditions in a self-driving experimental set-up.
BOAR has two main optimizer, one based on [scikit-learn](https://scikit-learn.org/stable/) which uses the [skopt.optimizer](https://scikit-optimize.github.io/stable/modules/generated/skopt.Optimizer.html) and one based on the [BoTorch](https://botorch.org/) and [Ax](https://ax.dev/) packages.
## Repository Folder Structure
.
├── Main # Main directory, place Notebooks here to run them
├── boar # Main directory for the BOAR codes
├── core # Directory with the multi-objective optimization codes
├── agents # Directory with the different experimental agents
├── dynamic_utils # Directory with the different utility functions to solve rate equations
├── SIMsalabim_utils # Directory with the different utility functions to run SIMsalabim, the drift-diffusion simulator
├── Notebooks # Contains clean versions of the Notebooks, Notebooks need to be moved to the main directory to be used
├── Example_Data # Contains some example data for the notebooks
├── SIMsalabim # Contains the codes to run the drift-diffusion simulations using SIMsalabim
├── test # Contains the codes for testing BOAR
└── README.md
## Installation
### With pip
To install BOAR with pip you have two options:
1. Install BOAR using the [PyPI repository](https://pypi.org/project/boar-pv/)
```
pip install boar-pv
```
2. Install BOAR using the GitHub repository
First, you need to clone the repository and install the requirements. The requirements can be installed with the following command:
```
pip install -r requirements.txt
```
Similarly to the conda installation, if you plan on using the BoTorch/Ax optimizer you need to use the requirements_torch_CPU.txt file or install pytorch with the correct version for your system with the requirements.txt file.
### With conda
To install the BOAR, you need to clone the repository and install the requirements. The requirements can be installed with the following command:
```
conda create -n boar
conda activate boar
conda install --file requirements.txt
```
if you want you can also clone your base environment by replacing the first line with:
```
conda create -n boar --clone base
```
If you plan on using only the scikit-learn optimizer, you can remove use the ''requirements.txt'' file, however if you plan on using the BoTorch/Ax optimizer, you have two options:
1. If you only want to use the CPU just install the requirements_torch_CPU.txt file:
2. If you also want to use the GPU and use CUDA you need to refer to the pytorch website to install the correct version of pytorch for your system. First start by intalling the''requirements.txt'' file as described previously then go to the 'Get Started' section [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/) and select the correct option for your system. You should have to run a command similar to the following one:
```
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117
```
## Additional necessary for BOAR with BoTorch/Ax
If you plan on using only the scikit-learn optimizer, you can remove use the ''requirements.txt'' file, however if you plan on using the [Ax & BoTorch](https://ax.dev/tutorials/multiobjective_optimization.html) optimizer, you have two options:
1. If you only want to use the CPU just install the requirements_torch_CPU.txt file as described previously.
2. If you also want to use the GPU and use CUDA you need to refer to the pytorch website to install the correct version of pytorch for your system. First start by intalling the''requirements.txt'' file as described previously then go to the 'Get Started' section [https://pytorch.org/get-started/locally/](https://ax.dev/tutorials/multiobjective_optimization.html) and select the correct option for your system. You should have to run a command similar to the following one:
```
pip install ax-platform
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117
```
## Additional necessary installs for the agents
### Drift-diffusion agent
The drift-diffusion agent uses the [SIMsalabim](https://github.com/kostergroup/SIMsalabim) package to run the drift-diffusion simulations.
If you plan on using the drift-diffusion agent, you need to install SIMsalabim. Note that the drift-diffusion agent can only be used on Linux to run the simulations in parallel and it has not been tested on Windows. However, all the other agents and functionalities of the BOAR can be used on Windows.
#### SIMsalabim
All the details to install SIMsalabim are detailed in the [GitHub repository](https://github.com/kostergroup/SIMsalabim). To make sure that you are running the latest version of SIMsalabim, check regularly the repository.
Note that we include SIMsalabim in this repository as a submodule, however, you are free to use a different verion.
If you use SIMsalabim, please follow the instruction on the [GitHub repository](https://github.com/kostergroup/SIMsalabim) to cite the package.
#### Parallel simulations
On Linux, you have the option to run the simulations in parrallel. Sadly, not on windows (yet).
To be able to run simulations in parrallel efficiently and with any threading or multiprocessing from python we use the `parallel` from the [GNU prallel](https://www.gnu.org/software/parallel/) project.
To install on linux run:
```
sudo apt update
sudo apt install parallel
```
You can also use [Anaconda](https://anaconda.org/):
```
conda install -c conda-forge parallel
```
To test is the installation worked by using by running the following command in the terminal:
```
parallel --help
```
It is also possible to use the `parmap` package to run the simualtions in parallel. To switch, use the `run_multiprocess_simu` instead of `run_parallel_simu` in the `RunSimulation` function in `/VLC_units/Simulation/RunSim.py` folder. However, this does not work on Ubuntu version 22.04 but seems to work on older versions.
## Disclaimer
This repository is still under development. If you find any bugs or have any questions, please contact us.
Raw data
{
"_id": null,
"home_page": "https://github.com/i-MEET/boar",
"name": "boar-pv",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9, <3.12",
"maintainer_email": "",
"keywords": "Bayesian optimization,parameter extraction,experimental design,high throughput,solar cells",
"author": "Vincent Le Corre, Larry Lueer",
"author_email": "vincent.le.corre@fau.de",
"download_url": "https://files.pythonhosted.org/packages/6e/7b/14667825c25741dfde58ffde91cf0ea46922b350cfe1d9526f982ad43d63/boar_pv-1.0.10.tar.gz",
"platform": null,
"description": "# BOAR : Bayesian Optimization for Automated Research\n\n## Authors\n[Vincent M. Le Corre](https://github.com/VMLC-PV) \n[Larry L\u00fcer](https://github.com/larryluer)\n\n\n## Institution\nInstitute Materials for Electronics and Energy Technology (i-MEET) \nUniversity of Erlangen-Nuremberg (FAU) \nErlangen, Germany \n\n## Description\nThis repository contains the code to run the BOAR. BOAR is a Bayesian optimization procedure that can be use for two objectives:\n1. to optimize the parameters of a simulation to fit experimental data.\n2. to optimize the processing conditions in a self-driving experimental set-up. \n\nBOAR has two main optimizer, one based on [scikit-learn](https://scikit-learn.org/stable/) which uses the [skopt.optimizer](https://scikit-optimize.github.io/stable/modules/generated/skopt.Optimizer.html) and one based on the [BoTorch](https://botorch.org/) and [Ax](https://ax.dev/) packages. \n\n## Repository Folder Structure\n .\n \u251c\u2500\u2500 Main # Main directory, place Notebooks here to run them\n \u251c\u2500\u2500 boar # Main directory for the BOAR codes\n \u251c\u2500\u2500 core # Directory with the multi-objective optimization codes\n \u251c\u2500\u2500 agents # Directory with the different experimental agents\n \u251c\u2500\u2500 dynamic_utils # Directory with the different utility functions to solve rate equations\n \u251c\u2500\u2500 SIMsalabim_utils # Directory with the different utility functions to run SIMsalabim, the drift-diffusion simulator\n \u251c\u2500\u2500 Notebooks # Contains clean versions of the Notebooks, Notebooks need to be moved to the main directory to be used \n \u251c\u2500\u2500 Example_Data # Contains some example data for the notebooks\n \u251c\u2500\u2500 SIMsalabim # Contains the codes to run the drift-diffusion simulations using SIMsalabim\n \u251c\u2500\u2500 test # Contains the codes for testing BOAR\n \u2514\u2500\u2500 README.md\n\n\n## Installation\n### With pip\nTo install BOAR with pip you have two options:\n1. Install BOAR using the [PyPI repository](https://pypi.org/project/boar-pv/)\n```\n pip install boar-pv\n```\n\n2. Install BOAR using the GitHub repository\nFirst, you need to clone the repository and install the requirements. The requirements can be installed with the following command:\n```\n pip install -r requirements.txt\n```\nSimilarly to the conda installation, if you plan on using the BoTorch/Ax optimizer you need to use the requirements_torch_CPU.txt file or install pytorch with the correct version for your system with the requirements.txt file.\n\n### With conda\nTo install the BOAR, you need to clone the repository and install the requirements. The requirements can be installed with the following command:\n\n```\nconda create -n boar \nconda activate boar\nconda install --file requirements.txt\n```\nif you want you can also clone your base environment by replacing the first line with:\n```\nconda create -n boar --clone base\n```\n\nIf you plan on using only the scikit-learn optimizer, you can remove use the ''requirements.txt'' file, however if you plan on using the BoTorch/Ax optimizer, you have two options:\n\n1. If you only want to use the CPU just install the requirements_torch_CPU.txt file:\n2. If you also want to use the GPU and use CUDA you need to refer to the pytorch website to install the correct version of pytorch for your system. First start by intalling the''requirements.txt'' file as described previously then go to the 'Get Started' section [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/) and select the correct option for your system. You should have to run a command similar to the following one:\n```\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117\n```\n\n## Additional necessary for BOAR with BoTorch/Ax\nIf you plan on using only the scikit-learn optimizer, you can remove use the ''requirements.txt'' file, however if you plan on using the [Ax & BoTorch](https://ax.dev/tutorials/multiobjective_optimization.html) optimizer, you have two options:\n\n1. If you only want to use the CPU just install the requirements_torch_CPU.txt file as described previously.\n2. If you also want to use the GPU and use CUDA you need to refer to the pytorch website to install the correct version of pytorch for your system. First start by intalling the''requirements.txt'' file as described previously then go to the 'Get Started' section [https://pytorch.org/get-started/locally/](https://ax.dev/tutorials/multiobjective_optimization.html) and select the correct option for your system. You should have to run a command similar to the following one:\n\n```\n pip install ax-platform\n pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117\n```\n\n## Additional necessary installs for the agents\n### Drift-diffusion agent\nThe drift-diffusion agent uses the [SIMsalabim](https://github.com/kostergroup/SIMsalabim) package to run the drift-diffusion simulations.\nIf you plan on using the drift-diffusion agent, you need to install SIMsalabim. Note that the drift-diffusion agent can only be used on Linux to run the simulations in parallel and it has not been tested on Windows. However, all the other agents and functionalities of the BOAR can be used on Windows.\n\n#### SIMsalabim\nAll the details to install SIMsalabim are detailed in the [GitHub repository](https://github.com/kostergroup/SIMsalabim). To make sure that you are running the latest version of SIMsalabim, check regularly the repository. \nNote that we include SIMsalabim in this repository as a submodule, however, you are free to use a different verion. \nIf you use SIMsalabim, please follow the instruction on the [GitHub repository](https://github.com/kostergroup/SIMsalabim) to cite the package.\n\n#### Parallel simulations\nOn Linux, you have the option to run the simulations in parrallel. Sadly, not on windows (yet).\nTo be able to run simulations in parrallel efficiently and with any threading or multiprocessing from python we use the `parallel` from the [GNU prallel](https://www.gnu.org/software/parallel/) project.\nTo install on linux run:\n```\nsudo apt update\nsudo apt install parallel\n```\nYou can also use [Anaconda](https://anaconda.org/):\n```\nconda install -c conda-forge parallel\n```\nTo test is the installation worked by using by running the following command in the terminal:\n```\nparallel --help\n```\nIt is also possible to use the `parmap` package to run the simualtions in parallel. To switch, use the `run_multiprocess_simu` instead of `run_parallel_simu` in the `RunSimulation` function in `/VLC_units/Simulation/RunSim.py` folder. However, this does not work on Ubuntu version 22.04 but seems to work on older versions.\n\n\n## Disclaimer\nThis repository is still under development. If you find any bugs or have any questions, please contact us.\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "High throughput parameter extraction and experimental design with Bayesian optimization",
"version": "1.0.10",
"project_urls": {
"Download": "https://github.com/i-MEET/boar/archive/refs/tags/v1.0.7.tar.gz",
"Homepage": "https://github.com/i-MEET/boar"
},
"split_keywords": [
"bayesian optimization",
"parameter extraction",
"experimental design",
"high throughput",
"solar cells"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9cd15b61f7428caf5b722c9546d2b66f905a46d5f954db407bae472df27edf8a",
"md5": "e21e6f11a6c743864fc3062f468b23cb",
"sha256": "4c83dd2b8e235675fb5ad30a7c9b5522a1833db0abde2054ef04edb1aaec92e2"
},
"downloads": -1,
"filename": "boar_pv-1.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e21e6f11a6c743864fc3062f468b23cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9, <3.12",
"size": 145968,
"upload_time": "2024-02-23T13:30:17",
"upload_time_iso_8601": "2024-02-23T13:30:17.945525Z",
"url": "https://files.pythonhosted.org/packages/9c/d1/5b61f7428caf5b722c9546d2b66f905a46d5f954db407bae472df27edf8a/boar_pv-1.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6e7b14667825c25741dfde58ffde91cf0ea46922b350cfe1d9526f982ad43d63",
"md5": "2299357eb68035a6f9a501702045fe37",
"sha256": "e9bc80504fd56fad683aa198be7a312962b0b799afd32a79d4c93cb3ed4dde20"
},
"downloads": -1,
"filename": "boar_pv-1.0.10.tar.gz",
"has_sig": false,
"md5_digest": "2299357eb68035a6f9a501702045fe37",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9, <3.12",
"size": 129374,
"upload_time": "2024-02-23T13:30:20",
"upload_time_iso_8601": "2024-02-23T13:30:20.189626Z",
"url": "https://files.pythonhosted.org/packages/6e/7b/14667825c25741dfde58ffde91cf0ea46922b350cfe1d9526f982ad43d63/boar_pv-1.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-23 13:30:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "i-MEET",
"github_project": "boar",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "notebook",
"specs": []
},
{
"name": "jupyterlab",
"specs": []
},
{
"name": "ipympl",
"specs": []
},
{
"name": "seaborn",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "scikit-optimize",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "parmap",
"specs": []
},
{
"name": "gitpython",
"specs": []
},
{
"name": "pyodbc",
"specs": []
},
{
"name": "openpyxl",
"specs": []
}
],
"lcname": "boar-pv"
}
JSON
