diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index d461c2dab..c39a83c20 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -22,21 +22,15 @@ jobs: python-version: '3.10' - name: Install pandoc run: sudo apt-get install -y pandoc - - name: Install dependencies + - name: Install Poetry + uses: snok/install-poetry@v1 + - name: Install package and test dependencies run: | - python -m pip install --upgrade pip - pip install sphinx - pip install nbsphinx - pip install sphinx_rtd_theme - pip install jupyter - pip install myst-parser - - name: Install package - run: | - pip install -e . + poetry install --with dev,nbtools - name: build sphinx docs run: | cd docsrc - make github + poetry run make github - name: Deploy uses: peaceiris/actions-gh-pages@v3 if: ${{ github.ref == 'refs/heads/master' }} diff --git a/README.md b/README.md index 300bd09ff..fcbf21238 100644 --- a/README.md +++ b/README.md @@ -51,11 +51,11 @@ for ideas on how to implement bayesian optimization in a distributed fashion usi 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](./static/bo_example.png) +![BayesianOptimization in action](docsrc/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](./static/bayesian_optimization.gif) +![BayesianOptimization in action](docsrc/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. @@ -183,7 +183,7 @@ Sometimes the initial boundaries specified for a problem are too wide, and addin 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](./static/sdr.png) +![sequential domain reduction](docsrc/static/sdr.png) 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). diff --git a/docsrc/Makefile b/docsrc/Makefile index c3886de30..0e926ff11 100644 --- a/docsrc/Makefile +++ b/docsrc/Makefile @@ -15,10 +15,10 @@ BUILDDIR = ../docs .PHONY: help Makefile github: - @cp ../README.md . - @cp -r ../static . +# @cp ../README.md . @make html @cp -a ../docs/html/. ../docs + @cp -r ../docsrc/ ../docs # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/docsrc/quickstart.rst b/docsrc/quickstart.rst index 9f12a4c65..c17c94002 100644 --- a/docsrc/quickstart.rst +++ b/docsrc/quickstart.rst @@ -1,2 +1,2 @@ -.. include:: README.md +.. include:: ../README.md :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/static/bayesian_optimization.gif b/docsrc/static/bayesian_optimization.gif similarity index 100% rename from static/bayesian_optimization.gif rename to docsrc/static/bayesian_optimization.gif diff --git a/static/bo_example.png b/docsrc/static/bo_example.png similarity index 100% rename from static/bo_example.png rename to docsrc/static/bo_example.png diff --git a/static/func.png b/docsrc/static/func.png similarity index 100% rename from static/func.png rename to docsrc/static/func.png diff --git a/static/sdr.png b/docsrc/static/sdr.png similarity index 100% rename from static/sdr.png rename to docsrc/static/sdr.png diff --git a/examples/advanced-tour.ipynb b/examples/advanced-tour.ipynb index fc6bc001c..f19137d58 100644 --- a/examples/advanced-tour.ipynb +++ b/examples/advanced-tour.ipynb @@ -353,7 +353,7 @@ "source": [ "### 3.3 Changing kernels\n", "\n", - "By default this package uses the Matern 2.5 kernel. Depending on your use case you may find that tunning the GP kernel could be beneficial. You're on your own here since these are very specific solutions to very specific problems." + "By default this package uses the Matern 2.5 kernel. Depending on your use case you may find that tunning the GP kernel could be beneficial. You're on your own here since these are very specific solutions to very specific problems. You should start with the [scikit learn docs](https://scikit-learn.org/stable/modules/gaussian_process.html#kernels-for-gaussian-processes)" ] }, { @@ -504,9 +504,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.9.5" + "version": "3.10.12" } }, "nbformat": 4, - "nbformat_minor": 2 + "nbformat_minor": 4 } diff --git a/examples/domain_reduction.ipynb b/examples/domain_reduction.ipynb index 81ec8f164..6dd73bf94 100644 --- a/examples/domain_reduction.ipynb +++ b/examples/domain_reduction.ipynb @@ -18,7 +18,7 @@ "\n", "**Zoom**: contract the region of interest.\n", "\n", - "![](../static/sdr.png)\n", + "![](../docsrc/static/sdr.png)\n", "\n", "\n", "## Parameters\n", @@ -298,9 +298,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.9.6" + "version": "3.10.12" } }, "nbformat": 4, - "nbformat_minor": 2 + "nbformat_minor": 4 } diff --git a/pyproject.toml b/pyproject.toml index 537a6ea5e..a0568c5d2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,6 +31,10 @@ nbformat = "^5.9.2" nbconvert = "^7.14.2" jupyter = "^1.0.0" matplotlib = "^3.0" +sphinx = "^7.3.7" +nbsphinx = "^0.9.4" +sphinx-rtd-theme = "^2.0.0" +myst-parser = "^3.0.1" [build-system]