Docstring overhaul (#457)

* Replace custom colour implementation, add docs for `logger.py`, `util.py` (#435)

* Replace custom colour implementation, add docs for `logger.py`, `util.py`

* minor typo/syntax fixes

* User `or` to separate different possible types

* Update docs & linting for `constraints.py`, `target_space.py` (#440)

* Run tests on any PR

* Update docs, linting

* Update bayes_opt/constraint.py

Co-authored-by: Leandro Braga <[email protected]>

* Rename mislabelled parameters

---------

Co-authored-by: Leandro Braga <[email protected]>

* Update various docstrings, add workflow to check docstrings (#445)

* Fixes issue-436: Constrained optimization does not allow duplicate points (#437)

* Update docs of `bayesian_optimization.py` and `observer.py`.

* Fix minor style issue in module docstring

* Update docs of `__init__.py` and `events.py`.

* Fix minor style issue in class docstring

* Add workflow to check docstrings

* Update bayes_opt/bayesian_optimization.py

Co-authored-by: Leandro Braga <[email protected]>

---------

Co-authored-by: YoungJae Bae <[email protected]>
Co-authored-by: Leandro Braga <[email protected]>

* Pydocstyle (#453)

* Improve acq_max seeding of L-BFGS-B optimization (#297)

---------

Co-authored-by: ptapping <[email protected]>

* Domain reduction, Sphinx docs (#455)

* Fixes issue-436: Constrained optimization does not allow duplicate points (#437)

* Update docs of `bayesian_optimization.py` and `observer.py`.

* Fix minor style issue in module docstring

* Update docs of `__init__.py` and `events.py`.

* Fix minor style issue in class docstring

* Add workflow to check docstrings

* Update bayes_opt/bayesian_optimization.py

Co-authored-by: Leandro Braga <[email protected]>

* Improve acq_max seeding of L-BFGS-B optimization (#297)

* bounds_transformer could bypass global_bounds due to the test logic within _trim function in domain_reduction.py (#441)

* Update trim bounds in domain_reduction.py

Previously, when the new upper limit was less than the original lower limit, the new_bounds could bypass the global_bounds.

* Update test_seq_domain_red.py

Added test cases to catch an error when both bounds of new_bounds exceeded the global_bounds

* Update domain_reduction.py

_trim function now avoids an error when both bounds for a given parameter in new_bounds exceed the global_bounds

* Update domain_reduction.py comments

* fixed English in domain_reduction.py

* use numpy to sort bounds,  boundary exceeded warn.

* simple sort test added

* domain_red windows target_space to global_bounds

Added windowing function to improve the convergence of optimizers that use domain_reduction. Improved comments and documentation.

* target_space.max respects bounds; SDRT warnings

* Remove unused function.

This function was used to prototype a solution. It should not have been pushed and can be removed.

* Updated target_space.py docstrings

* Update tests/test_target_space.py

Co-authored-by: till-m <[email protected]>

* Added pbound warnings, updated various tests.

* updated line spacing for consistency and style

* added pbound test condition

---------

Co-authored-by: till-m <[email protected]>

* DomainReduction docs, docstyle

* Add missing doc dependency

---------

Co-authored-by: YoungJae Bae <[email protected]>
Co-authored-by: Leandro Braga <[email protected]>
Co-authored-by: ptapping <[email protected]>
Co-authored-by: Edgar <[email protected]>

* Small fixes, minor cosmetic changes

* Add some more docs to target space and constraint, cosmetic changes

* Remove duplicate code snippet

* Remove numpydoc + adjust "*" formatting accordingly

* Explicitly add D417, adjust code accordingly

* Adjust `TargetSpace.probe()` behaviour to be in line with docstring.

* Update bayes_opt/target_space.py

Co-authored-by: Edgar <[email protected]>

* Update README.md

---------

Co-authored-by: Leandro Braga <[email protected]>
Co-authored-by: YoungJae Bae <[email protected]>
Co-authored-by: ptapping <[email protected]>
Co-authored-by: Edgar <[email protected]>

.github/workflows/build_docs.yml

@@ -29,6 +29,7 @@ jobs:
           pip install nbsphinx
           pip install sphinx_rtd_theme
           pip install jupyter
+          pip install myst-parser
       - name: Install package
         run: |
           pip install -e .

.github/workflows/check_docstrings.yml

@@ -0,0 +1,30 @@
+# This workflow will install Python dependencies and check docstrings with a single version of Python
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Check docstrings
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pydocstyle
+    - name: Check docstyle
+      run : pydocstyle --convention=numpy --add-select D417 bayes_opt/*
+    #- name: Run linting
+    #  run : pylint bayes_opt/* --disable=C0103 # ignore no snake_case conformity of arguments

.github/workflows/run_tests.yml

@@ -7,7 +7,6 @@ on:
   push:
     branches: [ "master" ]
   pull_request:
-    branches: [ "master" ]
 
 permissions:
   contents: read

.gitignore

@@ -32,4 +32,6 @@ venv.bak/
 
 docs/*
 docsrc/.ipynb_checkpoints/*
-docsrc/*.ipynb
+docsrc/*.ipynb
+docsrc/static/*
+docsrc/README.md

README.md

@@ -1,16 +1,18 @@
 <div align="center">
-  <img src="https://github.com/fmfn/BayesianOptimization/blob/master/examples/func.png"><br><br>
+  <img src="https://raw.githubusercontent.com/bayesian-optimization/BayesianOptimization/master/static/func.png"><br><br>
 </div>
 
 # Bayesian Optimization
 
-![tests](https://github.com/fmfn/BayesianOptimization/actions/workflows/run_tests.yml/badge.svg)
-[![Codecov](https://codecov.io/github/fmfn/BayesianOptimization/badge.svg?branch=master&service=github)](https://codecov.io/github/fmfn/BayesianOptimization?branch=master)
+![tests](https://github.com/bayesian-optimization/BayesianOptimization/actions/workflows/run_tests.yml/badge.svg)
+[![Codecov](https://codecov.io/github/bayesian-optimization/BayesianOptimization/badge.svg?branch=master&service=github)](https://codecov.io/github/bayesian-optimization/BayesianOptimization?branch=master)
 [![Pypi](https://img.shields.io/pypi/v/bayesian-optimization.svg)](https://pypi.python.org/pypi/bayesian-optimization)
 
 Pure Python implementation of bayesian global optimization with gaussian
 processes.
 
+## Installation
+
 * PyPI (pip):
 
 ```console
@@ -30,48 +32,40 @@ suited for optimization of high cost functions, situations where the balance
 between exploration and exploitation is important.
 
 ## Quick Start
-See below for a quick tour over the basics of the Bayesian Optimization package. More detailed information, other advanced features, and tips on usage/implementation can be found in the [examples](https://github.com/fmfn/BayesianOptimization/tree/master/examples) folder. I suggest that you:
-- Follow the
-[basic tour notebook](https://github.com/fmfn/BayesianOptimization/blob/master/examples/basic-tour.ipynb)
-to learn how to use the package's most important features.
-- Take a look at the
-[advanced tour notebook](https://github.com/fmfn/BayesianOptimization/blob/master/examples/advanced-tour.ipynb)
-to learn how to make the package more flexible, how to deal with categorical parameters, how to use observers, and more.
-- Check out this
-[notebook](https://github.com/fmfn/BayesianOptimization/blob/master/examples/visualization.ipynb)
-with a step by step visualization of how this method works.
-- To understand how to use bayesian optimization when additional constraints are present, see the
-[constrained optimization notebook](https://github.com/fmfn/BayesianOptimization/blob/master/examples/constraints.ipynb).
-- Explore this [notebook](https://github.com/fmfn/BayesianOptimization/blob/master/examples/exploitation_vs_exploration.ipynb)
+See below for a quick tour over the basics of the Bayesian Optimization package. More detailed information, other advanced features, and tips on usage/implementation can be found in the [examples](http://bayesian-optimization.github.io/BayesianOptimization/examples.html) folder. I suggest that you:
+- Follow the [basic tour notebook](http://bayesian-optimization.github.io/BayesianOptimization/basic-tour.html) to learn how to use the package's most important features.
+- Take a look at the [advanced tour notebook](http://bayesian-optimization.github.io/BayesianOptimization/advanced-tour.html) to learn how to make the package more flexible, how to deal with categorical parameters, how to use observers, and more.
+- Check out this [notebook](http://bayesian-optimization.github.io/BayesianOptimization/visualization.html) with a step by step visualization of how this method works.
+- To understand how to use bayesian optimization when additional constraints are present, see the [constrained optimization notebook](http://bayesian-optimization.github.io/BayesianOptimization/constraints.html).
+- Explore this [notebook](http://bayesian-optimization.github.io/BayesianOptimization/exploitation_vs_exploration.html)
 exemplifying the balance between exploration and exploitation and how to
 control it.
-- Go over this [script](https://github.com/fmfn/BayesianOptimization/blob/master/examples/sklearn_example.py)
+- Go over this [script](https://github.com/bayesian-optimization/BayesianOptimization/blob/master/examples/sklearn_example.py)
 for examples of how to tune parameters of Machine Learning models using cross validation and bayesian optimization.
-- Explore the [domain reduction notebook](https://github.com/fmfn/BayesianOptimization/blob/master/examples/domain_reduction.ipynb) to learn more about how search can be sped up by dynamically changing parameters' bounds.
-- Finally, take a look at this [script](https://github.com/fmfn/BayesianOptimization/blob/master/examples/async_optimization.py)
+- Explore the [domain reduction notebook](http://bayesian-optimization.github.io/BayesianOptimization/domain_reduction.html) to learn more about how search can be sped up by dynamically changing parameters' bounds.
+- Finally, take a look at this [script](https://github.com/bayesian-optimization/BayesianOptimization/blob/master/examples/async_optimization.py)
 for ideas on how to implement bayesian optimization in a distributed fashion using this package.
 
 
 ## How does it work?
 
 Bayesian optimization works by constructing a posterior distribution of functions (gaussian process) that best describes the function you want to optimize. As the number of observations grows, the posterior distribution improves, and the algorithm becomes more certain of which regions in parameter space are worth exploring and which are not, as seen in the picture below.
 
-![BayesianOptimization in action](./examples/bo_example.png)
+![BayesianOptimization in action](./static/bo_example.png)
 
 As you iterate over and over, the algorithm balances its needs of exploration and exploitation taking into account what it knows about the target function. At each step a Gaussian Process is fitted to the known samples (points previously explored), and the posterior distribution, combined with a exploration strategy (such as UCB (Upper Confidence Bound), or EI (Expected Improvement)), are used to determine the next point that should be explored (see the gif below).
 
-![BayesianOptimization in action](./examples/bayesian_optimization.gif)
+![BayesianOptimization in action](./static/bayesian_optimization.gif)
 
 This process is designed to minimize the number of steps required to find a combination of parameters that are close to the optimal combination. To do so, this method uses a proxy optimization problem (finding the maximum of the acquisition function) that, albeit still a hard problem, is cheaper (in the computational sense) and common tools can be employed. Therefore Bayesian Optimization is most adequate for situations where sampling the function to be optimized is a very expensive endeavor. See the references for a proper discussion of this method.
 
 This project is under active development, if you find a bug, or anything that
 needs correction, please let me know.
 
 
-Basic tour of the Bayesian Optimization package
-===============================================
+## Basic tour of the Bayesian Optimization package
 
-## 1. Specifying the function to be optimized
+### 1. Specifying the function to be optimized
 
 This is a function optimization package, therefore the first and most important ingredient is, of course, the function to be optimized.
 
@@ -89,7 +83,7 @@ def black_box_function(x, y):
     return -x ** 2 - (y - 1) ** 2 + 1
 ```
 
-## 2. Getting Started
+### 2. Getting Started
 
 All we need to get started is to instantiate a `BayesianOptimization` object specifying a function to be optimized `f`, and its parameters with their corresponding bounds, `pbounds`. This is a constrained optimization technique, so you must specify the minimum and maximum values that can be probed for each parameter in order for it to work
 
@@ -160,7 +154,7 @@ for i, res in enumerate(optimizer.res):
 ```
 
 
-### 2.1 Changing bounds
+#### 2.1 Changing bounds
 
 During the optimization process you may realize the bounds chosen for some parameters are not adequate. For these situations you can invoke the method `set_bounds` to alter them. You can pass any combination of **existing** parameters and their associated new bounds.
 
@@ -183,17 +177,17 @@ optimizer.maximize(
     |  10       | -1.762    |  1.442    |  0.1735   |
     =================================================
 
-### 2.2 Sequential Domain Reduction
+#### 2.2 Sequential Domain Reduction
 
 Sometimes the initial boundaries specified for a problem are too wide, and adding points to improve the response surface in regions of the solution domain is extraneous. Other times the cost function is very expensive to compute, and minimizing the number of calls is extremely beneficial.
 
 When it's worthwhile to converge on an optimal point quickly rather than try to find the optimal point, contracting the domain around the current optimal value as the search progresses can speed up the search progress considerably. Using the `SequentialDomainReductionTransformer` the bounds of the problem can be panned and zoomed dynamically in an attempt to improve convergence.
 
-![sequential domain reduction](./examples/sdr.png)
+![sequential domain reduction](./static/sdr.png)
 
-An example of using the `SequentialDomainReductionTransformer` is shown in the [domain reduction notebook](https://github.com/fmfn/BayesianOptimization/blob/master/examples/domain_reduction.ipynb). More information about this method can be found in the paper ["On the robustness of a simple domain reduction scheme for simulation‐based optimization"](http://www.truegrid.com/srsm_revised.pdf).
+An example of using the `SequentialDomainReductionTransformer` is shown in the [domain reduction notebook](http://bayesian-optimization.github.io/BayesianOptimization/domain_reduction.html). More information about this method can be found in the paper ["On the robustness of a simple domain reduction scheme for simulation‐based optimization"](http://www.truegrid.com/srsm_revised.pdf).
 
-## 3. Guiding the optimization
+### 3. Guiding the optimization
 
 It is often the case that we have an idea of regions of the parameter space where the maximum of our function might lie. For these situations the `BayesianOptimization` object allows the user to specify points to be probed. By default these will be explored lazily (`lazy=True`), meaning these points will be evaluated only the next time you call `maximize`. This probing process happens before the gaussian process takes over.
 
@@ -221,11 +215,11 @@ optimizer.maximize(init_points=0, n_iter=0)
     =================================================
 
 
-## 4. Saving, loading and restarting
+### 4. Saving, loading and restarting
 
 By default you can follow the progress of your optimization by setting `verbose>0` when instantiating the `BayesianOptimization` object. If you need more control over logging/alerting you will need to use an observer. For more information about observers checkout the advanced tour notebook. Here we will only see how to use the native `JSONLogger` object to save to and load progress from files.
 
-### 4.1 Saving progress
+#### 4.1 Saving progress
 
 
 ```python
@@ -255,7 +249,7 @@ optimizer.maximize(
 
 By default the previous data in the json file is removed. If you want to keep working with the same logger, the `reset` parameter in `JSONLogger` should be set to False.
 
-### 4.2 Loading progress
+#### 4.2 Loading progress
 
 Naturally, if you stored progress you will be able to load that onto a new instance of `BayesianOptimization`. The easiest way to do it is by invoking the `load_logs` function, from the `util` submodule.
 
@@ -277,54 +271,51 @@ load_logs(new_optimizer, logs=["./logs.log"]);
 
 ## Next Steps
 
-This introduction covered the most basic functionality of the package. Checkout the [basic-tour](https://github.com/fmfn/BayesianOptimization/blob/master/examples/basic-tour.ipynb) and [advanced-tour](https://github.com/fmfn/BayesianOptimization/blob/master/examples/advanced-tour.ipynb) notebooks in the example folder, where you will find detailed explanations and other more advanced functionality. Also, browse the examples folder for implementation tips and ideas.
-
-Installation
-============
-
-### Installation
-
-The latest release can be obtained by two ways:
-
-* With PyPI (pip):
-
-      pip install bayesian-optimization
-
-* With conda (from conda-forge channel):
-
-      conda install -c conda-forge bayesian-optimization
-
-The bleeding edge version can be installed with:
-
-    pip install git+https://github.com/fmfn/BayesianOptimization.git
+This introduction covered the most basic functionality of the package. Checkout the [basic-tour](http://bayesian-optimization.github.io/BayesianOptimization/basic-tour.html) and [advanced-tour](http://bayesian-optimization.github.io/BayesianOptimization/advanced-tour.html), where you will find detailed explanations and other more advanced functionality. Also, browse the [examples](http://bayesian-optimization.github.io/BayesianOptimization/examples.html) for implementation tips and ideas.
 
-If you prefer, you can clone it and run the setup.py file. Use the following
-commands to get a copy from Github and install all dependencies:
+## Minutiae
 
-    git clone https://github.com/fmfn/BayesianOptimization.git
-    cd BayesianOptimization
-    python setup.py install
+### Citation
 
-Citation
-============
-
-If you used this package in your research and is interested in citing it here's how you do it:
+If you used this package in your research, please cite it:
 
 ```
 @Misc{,
     author = {Fernando Nogueira},
     title = {{Bayesian Optimization}: Open source constrained global optimization tool for {Python}},
     year = {2014--},
-    url = " https://github.com/fmfn/BayesianOptimization"
+    url = " https://github.com/bayesian-optimization/BayesianOptimization"
+}
+```
+If you used any of the advanced functionalities, please additionally cite the corresponding publication:
+
+For the `SequentialDomainTransformer`:
+```
+@article{
+    author = {Stander, Nielen and Craig, Kenneth},
+    year = {2002},
+    month = {06},
+    pages = {},
+    title = {On the robustness of a simple domain reduction scheme for simulation-based optimization},
+    volume = {19},
+    journal = {International Journal for Computer-Aided Engineering and Software (Eng. Comput.)},
+    doi = {10.1108/02644400210430190}
+}
+```
+
+For constrained optimization:
+```
+@inproceedings{gardner2014bayesian,
+    title={Bayesian optimization with inequality constraints.},
+    author={Gardner, Jacob R and Kusner, Matt J and Xu, Zhixiang Eddie and Weinberger, Kilian Q and Cunningham, John P},
+    booktitle={ICML},
+    volume={2014},
+    pages={937--945},
+    year={2014}
 }
 ```
 
-# Dependencies
-* Numpy
-* Scipy
-* Scikit-learn
-
-# References:
+### References:
 * http://papers.nips.cc/paper/4522-practical-bayesian-optimization-of-machine-learning-algorithms.pdf
 * http://arxiv.org/pdf/1012.2599v1.pdf
 * http://www.gaussianprocess.org/gpml/

bayes_opt/__init__.py

@@ -1,8 +1,10 @@
+"""Pure Python implementation of bayesian global optimization with gaussian processes."""
 from .bayesian_optimization import BayesianOptimization, Events
 from .domain_reduction import SequentialDomainReductionTransformer
 from .util import UtilityFunction
 from .logger import ScreenLogger, JSONLogger
 from .constraint import ConstraintModel
+from .util import UtilityFunction
 
 __all__ = [
     "BayesianOptimization",