Writes a first version of the docs for some poli baselines

miguelgondu · miguelgondu · commit a42d8e18917b · 2024-01-22T00:51:58.000+01:00
diff --git a/docs/protein-optimization/_autosummary/poli.objective_repository.foldx_sasa.rst b/docs/protein-optimization/_autosummary/poli.objective_repository.foldx_sasa.rst
@@ -1,4 +1,4 @@
-﻿poli.objective\_repository.foldx\_sasa
+poli.objective\_repository.foldx\_sasa
 ======================================
 
 .. automodule:: poli.objective_repository.foldx_sasa
diff --git a/docs/protein-optimization/_autosummary/poli.objective_repository.foldx_stability.rst b/docs/protein-optimization/_autosummary/poli.objective_repository.foldx_stability.rst
@@ -1,4 +1,4 @@
-﻿poli.objective\_repository.foldx\_stability
+poli.objective\_repository.foldx\_stability
 ===========================================
 
 .. automodule:: poli.objective_repository.foldx_stability
diff --git a/docs/protein-optimization/_autosummary/poli.objective_repository.gfp_cbas.rst b/docs/protein-optimization/_autosummary/poli.objective_repository.gfp_cbas.rst
@@ -1,4 +1,4 @@
-﻿poli.objective\_repository.gfp\_cbas
+poli.objective\_repository.gfp\_cbas
 ====================================
 
 .. automodule:: poli.objective_repository.gfp_cbas
diff --git a/docs/protein-optimization/_autosummary/poli.objective_repository.rfp_foldx_stability_and_sasa.register.rst b/docs/protein-optimization/_autosummary/poli.objective_repository.rfp_foldx_stability_and_sasa.register.rst
@@ -0,0 +1,30 @@
+poli.objective\_repository.rfp\_foldx\_stability\_and\_sasa.register
+====================================================================
+
+.. automodule:: poli.objective_repository.rfp_foldx_stability_and_sasa.register
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      RFPFoldXStabilityAndSASABlackBox
+      RFPFoldXStabilityAndSASAProblemFactory
+   
+   
+
+   
+   
+   
+
+
+
diff --git a/docs/protein-optimization/_autosummary/poli.objective_repository.rfp_foldx_stability_and_sasa.rst b/docs/protein-optimization/_autosummary/poli.objective_repository.rfp_foldx_stability_and_sasa.rst
@@ -0,0 +1,31 @@
+poli.objective\_repository.rfp\_foldx\_stability\_and\_sasa
+===========================================================
+
+.. automodule:: poli.objective_repository.rfp_foldx_stability_and_sasa
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   poli.objective_repository.rfp_foldx_stability_and_sasa.register
+
diff --git a/docs/protein-optimization/_autosummary/poli.objective_repository.rst b/docs/protein-optimization/_autosummary/poli.objective_repository.rst
@@ -1,4 +1,4 @@
-poli.objective\_repository
+﻿poli.objective\_repository
 ==========================
 
 .. automodule:: poli.objective_repository
@@ -40,6 +40,7 @@ poli.objective\_repository
    poli.objective_repository.rasp
    poli.objective_repository.rdkit_logp
    poli.objective_repository.rdkit_qed
+   poli.objective_repository.rfp_foldx_stability_and_sasa
    poli.objective_repository.sa_tdc
    poli.objective_repository.super_mario_bros
    poli.objective_repository.toy_continuous_problem
diff --git a/docs/protein-optimization/_autosummary/poli.tests.registry.proteins.test_foldx_rfp_lambo.rst b/docs/protein-optimization/_autosummary/poli.tests.registry.proteins.test_foldx_rfp_lambo.rst
@@ -0,0 +1,29 @@
+﻿poli.tests.registry.proteins.test\_foldx\_rfp\_lambo
+====================================================
+
+.. automodule:: poli.tests.registry.proteins.test_foldx_rfp_lambo
+
+   
+   
+   
+
+   
+   
+   .. rubric:: Functions
+
+   .. autosummary::
+   
+      test_foldx_rfp_lambo_runs
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+
+
diff --git a/docs/protein-optimization/_autosummary/poli.tests.registry.test_passing_array_of_strings.rst b/docs/protein-optimization/_autosummary/poli.tests.registry.test_passing_array_of_strings.rst
@@ -0,0 +1,29 @@
+﻿poli.tests.registry.test\_passing\_array\_of\_strings
+=====================================================
+
+.. automodule:: poli.tests.registry.test_passing_array_of_strings
+
+   
+   
+   
+
+   
+   
+   .. rubric:: Functions
+
+   .. autosummary::
+   
+      test_passing_array_of_strings
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+
+
diff --git a/docs/protein-optimization/_toc.yml b/docs/protein-optimization/_toc.yml
@@ -31,6 +31,13 @@ parts:
       - file: using_poli/objective_repository/foldx_sasa.md
       - file: using_poli/objective_repository/RaSP.md
       - file: using_poli/objective_repository/super_mario_bros.md
+  - caption: "Optimizers"
+    chapters:
+      - file: using_poli_baselines/random_mutations.md
+      - file: using_poli_baselines/cma_es.md
+      - file: using_poli_baselines/nsga_2.md
+      - file: using_poli_baselines/bayesian_optimization.md
+      - file: using_poli_baselines/line_bayesian_optimization.md
   - caption: "Observers"
     chapters:
     - file: observers/registering_an_observer.md
diff --git a/docs/protein-optimization/index.md b/docs/protein-optimization/index.md
@@ -116,28 +116,28 @@ On top of `poli`, we provide `poli-baselines`, a collection of **black-box optim
 Optimizing a discrete sequence by performing random mutations
 :::
 
-:::{grid-item-card} NSGA-2
+:::{grid-item-card} Discrete NSGA-2
 :link: ./using_poli_baselines/nsga_2.html
 :columns: 6
-A Genetic algorithm for optimizing more than one metric [WIP]
+A Genetic algorithm for multi-objective optimization of discrete sequences
 :::
 
 :::{grid-item-card} CMA-ES
 :link: ./using_poli_baselines/cma_es.html
 :columns: 6
-An evolutionary strategy for continuous problems [WIP]
+An evolutionary strategy for continuous problems
 :::
 
-:::{grid-item-card} Latent Space Bayesian Optimization
+:::{grid-item-card} Bayesian Optimization
 :link: ./using_poli_baselines/latent_space_bo.html
 :columns: 6
 Learning continuous representations and optimizing in latent space. [WIP]
 :::
 
-:::{grid-item-card} Graph GA
-:link: ./using_poli_baselines/graph_ga.html
+:::{grid-item-card} Line Bayesian Optimization
+:link: ./using_poli_baselines/latent_space_bo.html
 :columns: 6
-Graph Genetic Algorithms for small molecules. [WIP]
+Learning continuous representations and optimizing in latent space. [WIP]
 :::
 
 ::::
diff --git a/docs/protein-optimization/references.bib b/docs/protein-optimization/references.bib
@@ -86,4 +86,16 @@ @inproceedings{
 booktitle={Thirty-sixth Conference on Neural Information Processing Systems Datasets and Benchmarks Track},
 year={2022},
 url={https://openreview.net/forum?id=yCZRdI0Y7G}
-}
+}
+
+ @article{Deb:NSGA-2:2002, title={A fast and elitist multiobjective genetic algorithm: NSGA-II}, volume={6}, ISSN={1089778X}, DOI={10.1109/4235.996017}, number={2}, journal={IEEE Transactions on Evolutionary Computation}, author={Deb, K. and Pratap, A. and Agarwal, S. and Meyarivan, T.}, year={2002}, month=apr, pages={182–197}, language={en} }
+
+@ARTICLE{pymoo,
+    author={J. {Blank} and K. {Deb}},
+    journal={IEEE Access},
+    title={pymoo: Multi-Objective Optimization in Python},
+    year={2020},
+    volume={8},
+    number={},
+    pages={89497-89509},
+}
diff --git a/docs/protein-optimization/using_poli_baselines/bayesian_optimization.md b/docs/protein-optimization/using_poli_baselines/bayesian_optimization.md
@@ -0,0 +1,41 @@
+# Bayesian Optimization
+
+![Type of optimizer algorithm: continuous inputs](https://img.shields.io/badge/Type-continuous_inputs-cyan)
+
+## About
+
+Bayesian Optimization is a sample-efficient black box optimization algorithm which uses an uncertainty-aware approximation $\tilde{f}(\bm{x})$ of the objective function $f$. This surrogate model $\tilde{f}$ is usually a Gaussian Process, whose predictions and uncertainties are used to build an _acquisition function_ $\alpha(\bm{x})$. Optimizing $\alpha$ renders points that are _likely_ to perform well for $f$. By smartly including uncertainties in $\alpha$, Bayesian Optimization balances exploration and exploitation.
+
+Our implementation uses `gpytorch` and `botorch` as the engines for Bayesian Optimization {cite+p}`Balandat:botorch:2020,gardner:gpytorch:2018`. We use the default `botorch` single-task Gaussian Process, and we optimize the acquisition function using grid-search for 1 and 2 dimensions, and using `botorch`'s utilities from 3 onwards.
+
+## How to run
+
+```python
+import numpy as np
+
+from poli import objective_factory
+
+from poli_baselines.solvers import VanillaBayesianOptimization
+
+problem_info, f_ackley, _, _, _ = objective_factory.create(
+    name="toy_continuous_problem",
+    function_name="ackley_function_01",
+    n_dimensions=2,
+)
+
+x0 = np.random.randn(2).reshape(1, -1).clip(-2.0, 2.0)
+y0 = f_ackley(x0)
+
+bo_solver = VanillaBayesianOptimization(
+    black_box=f_ackley,
+    x0=x0,
+    y0=y0,
+)
+
+bo_solver.solve(max_iter=10)
+```
+
+## See more
+
+- [*Taking the human out of the loop*](https://www.cs.ox.ac.uk/people/nando.defreitas/publications/BayesOptLoop.pdf) is a great tutorial of Bayesian Optimization {cite:p}`Shahriari:BOReview:2016`.
+- Since `poli` works mostly on discrete inputs, this baseline is implemented with the intention of optimizing in the latent spaces of deep generative models like Generative Adversarial Networks (GANs) or Variational Autoencoders (VAEs) {cite:p}`GomezBombarelli:VAEsAndOpt:2018`.
diff --git a/docs/protein-optimization/using_poli_baselines/line_bayesian_optimization.md b/docs/protein-optimization/using_poli_baselines/line_bayesian_optimization.md
@@ -0,0 +1,37 @@
+# Line Bayesian Optimization
+
+![Type of optimizer algorithm: continuous inputs](https://img.shields.io/badge/Type-continuous_inputs-cyan)
+
+## About
+
+Line Bayesian Optimization (LineBO) is a version of [Bayesian Optimization](./bayesian_optimization.md) that restricts the optimization of the acquisition function to a single line in input space {cite:p}`Kirschner:LineBO:2019`. This line can either be selected at random, or can follow one of the coordinate directions.
+
+By default, we use `botorch`'s `SingleTaskGP` {cite+p}`Balandat:botorch:2020`. 
+
+## How to run
+
+```python
+import numpy as np
+
+from poli import objective_factory
+
+from poli_baselines.solvers import LineBO
+
+problem_info, f_ackley, _, _, _ = objective_factory.create(
+    name="toy_continuous_problem",
+    function_name="ackley_function_01",
+    n_dimensions=2,
+)
+
+x0 = np.random.randn(2).reshape(1, -1).clip(-2.0, 2.0)
+y0 = f_ackley(x0)
+
+solver = LineBO(
+    black_box=f_ackley,
+    x0=x0,
+    y0=y0,
+    type_of_line="random",  # could also be "coordinate"
+)
+
+solver.solve(max_iter=10)
+```
diff --git a/docs/protein-optimization/using_poli_baselines/nsga_2.md b/docs/protein-optimization/using_poli_baselines/nsga_2.md
@@ -1,3 +1,61 @@
-# NSGA-2
+# Discrete NSGA-2
 
-[TODO: write]
+![Type of optimizer algorithm: discrete inputs](https://img.shields.io/badge/Type-discrete_inputs-blue)
+![Type of objective function: multi-objective](https://img.shields.io/badge/Output-multi--objective-red)
+
+
+## About
+
+The non-dominated sorting genetic algorithm (NSGA) is a common baseline for multi-objective optimization (see {cite:p}`Deb:NSGA-2:2002`).
+
+In this discrete-input version, we use a mating procedure based on randomly mutating parents as many times as specified upon creation. Our implementation is a wrapper around `pymoo`'s version of NSGA-2 {cite:p}`pymoo`. 
+
+## How to run
+
+Here is a minimal example on a two copies of the toy problem `aloha`:
+
+```python
+import numpy as np
+
+from poli.objective_repository import AlohaProblemFactory
+from poli.core.multi_objective_black_box import MultiObjectiveBlackBox
+
+from poli_baselines.solvers import DiscreteNSGAII
+
+# Hyperparameters
+population_size = 15
+batch_size = 10
+max_iterations = 100
+num_mutations = 1
+
+# Creating the aloha problem
+problem_factory = AlohaProblemFactory()
+f_aloha, _, _ = problem_factory.create()
+
+# Putting two copies together to make a multi-objective black box
+f = MultiObjectiveBlackBox(
+    info=f_aloha.info,
+    objective_functions=[f_aloha, f_aloha],
+)
+
+# Creating a random initial population
+x0 = np.random.choice(f.info.alphabet, size=(batch_size, 5))
+y0 = f(x0)
+
+# Creating an instance of the solver
+solver = DiscreteNSGAII(
+    black_box=f,
+    x0=x0,
+    y0=y0,
+    population_size=population_size,
+    num_mutations=num_mutations
+)
+
+# Running the evolution
+solver.solve(max_iter=max_iterations)
+print(f"Best solution: {solver.get_best_solution()}")
+```
+
+## See more
+
+- Our implementation uses `pymoo`'s version of `NSGA-2` {cite:p}`pymoo`, plus [a wrapper for discrete objective functions](https://github.com/MachineLearningLifeScience/poli-baselines/blob/aacc02a2ab17ebcf94f381e92222dcf7711690ec/src/poli_baselines/core/utils/pymoo/interface.py#L44).
diff --git a/docs/protein-optimization/using_poli_baselines/random_mutations.md b/docs/protein-optimization/using_poli_baselines/random_mutations.md
diff --git a/docs/protein-optimization/using_poli_baselines/template.md b/docs/protein-optimization/using_poli_baselines/template.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-poli.objective\_repository.foldx\_sasa`
	`1`	`+poli.objective\_repository.foldx\_sasa`
`2`	`2`	`======================================`
`3`	`3`
`4`	`4`	`.. automodule:: poli.objective_repository.foldx_sasa`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-poli.objective\_repository.foldx\_stability`
	`1`	`+poli.objective\_repository.foldx\_stability`
`2`	`2`	`===========================================`
`3`	`3`
`4`	`4`	`.. automodule:: poli.objective_repository.foldx_stability`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-poli.objective\_repository.gfp\_cbas`
	`1`	`+poli.objective\_repository.gfp\_cbas`
`2`	`2`	`====================================`
`3`	`3`
`4`	`4`	`.. automodule:: poli.objective_repository.gfp_cbas`