Writes a chapter on how to get started

Author: miguelgondu

docs/protein-optimization/_toc.yml

@@ -4,20 +4,19 @@
 format: jb-book
 root: index.md
 parts:
+  - caption: Getting started
+    chapters:
+      - file: getting_started/getting_started.md
   - caption: Using poli - the basics
-    numbered: true
     chapters:
-      - file: using_poli/the_basics/intro_to_poli.md
       - file: using_poli/the_basics/registering_an_objective_function.md
       - file: using_poli/the_basics/defining_a_problem_solver.md
       - file: using_poli/the_basics/optimizing_an_objective_function.md
       - file: using_poli/the_basics/diving_deeper.md
   - caption: Using poli - examples
-    numbered: true
     chapters:
       - file: using_poli/optimization_examples/protein-stability-foldx/optimizing_protein_stability.ipynb
   - caption: Understanding FoldX
-    numbered: true
     chapters:
     - file: understanding_foldx/00-installing-foldx.md
     - file: understanding_foldx/01-single-mutation-using-foldx/index.ipynb

docs/protein-optimization/getting_started/getting_started.md

@@ -0,0 +1,102 @@
+# Getting started
+
+In this chapter, we share with you how to install `poli`, and get started with registering objective functions.
+
+## Installing locally
+
+Unfortunately, we only support **Linux** and **MacOS** for now.
+
+### Installing conda
+
+`poli` is built on top of manipulating `conda` environments. It is therefore important for you to **install conda**. [Follow the documentation of Anaconda itself](https://conda.io/projects/conda/en/latest/user-guide/install/index.html).
+
+Test that your installation went through by writing
+
+```bash
+$ conda --version
+conda 23.7.2
+```
+
+It's okay if you have another version. Read more about [supported versions of `conda` (TODO:ADD)]().
+
+### Installing `poli`
+
+We recommend creating an environment called `poli-base`. **The only dependency `poli` has is `numpy`**:
+
+```bash
+$ conda create -n poli-base python=3.9
+$ conda activate poli-base
+$ pip install numpy
+```
+
+Right now, we only support two ways of installing `poli`: by cloning the repo and installing, or using `pip` and `git+`. [TODO: change from my fork to MLLS repo after merging]
+
+::::{tab-set}
+
+:::{tab-item} Installing using `pip +git`
+
+If you are not interested in debugging, you can simply run
+
+```bash
+# in the poli-base env
+pip install git+https://github.com/miguelgondu/poli.git
+```
+
+:::
+
+:::{tab-item} Installing for debugging
+
+If you are interested in debugging locally, clone and install as follows: 
+
+```bash
+# in the `poli-base` env.
+$ git clone [email protected]:miguelgondu/poli.git
+$ cd ./poli
+$ pip install -e .
+```
+
+:::
+
+::::
+
+### Testing your installation
+
+To make sure everything went well, you can test your `poli` installation by running
+
+```bash
+$ python -c "from poli.core.registry import get_problems ; print(get_problems())"
+[]
+```
+
+If the installation isn't fresh/the only one in your system, you might actually get some registered problems.
+
+## Running `poli` in Colab
+
+With a little effort, you can run `poli` in Colab. [Check this example](https://colab.research.google.com/drive/1-IISCebWYfu0QhuCJ11wOag8aKOiPtls).
+
+
+## Your first `poli` script
+
+As you might have noticed, you can get a list of the registered problems using the `get_problems` method inside `poli.core.registry`. You can also get a list of objective functions available for installing/registration using `from poli.objective_repository import AVAILABLE_OBJECTIVES`:
+
+```bash
+$ python -c "from poli.objective_repository import AVAILABLE_OBJECTIVES ; print(AVAILABLE_OBJECTIVES)"
+[..., 'white_noise']
+```
+
+Let's write a small script that installs `white_noise` from the repository:
+
+```python
+# see examples/minimal_working_example.py
+from poli import objective_factory
+
+problem_info, f, x0, y0, run_info = objective_factory.create(name="white_noise")
+
+x = np.array([[1]])  # must be of shape [b, d], in this case [1, 1].
+for _ in range(5):
+    print(f"f(x) = {f(x)}")
+```
+
+If we run this script, `poli` will ask us to confirm that we want to register/install `"white_noise"` as an objective function (you can deactivate this confirmation step by passing the flag `force_register=True` to `.create`). Afterwards, it will print 5 evaluations of the objective function on the same input.
+
+

docs/protein-optimization/index.md

@@ -1,6 +1,24 @@
-# Tutorials on protein optimization
+# Tutorials on protein optimization using poli
 
-This book contains documentation on how to measure protein's properties (e.g. stability, solubility...) using tools like FoldX. [Work in Progress]
+This book contains documentation on how to use `poli` and `poli-baselines`, our tools for creating and optimizing black box objective functions.
+
+At its core, `poli` allows you to isolate calls to complicated objective functions which might, for example, depend on simulators, binaries, or a weird version of the Java runtime.
+Our promise is: if you can run your objective function reliably in a `conda` environment, then you can register it and call it from other projects without having to worry about re-installing all the dependencies.
+
+`poli` comes batteries-included. By this, we mean that there are already a collection of black box objective functions you could register and use out-of-the-box. Examples include:
+- standard white noise,
+- computing the stability of proteins and their mutations from a wildtype `pdb`,
+- optimizing the number of jumps Mario performs in a Super Mario Bros level sampled from the latent space of a Variational Autoencoder.
+- optimizing the QED and penalized logP of small molecules, presented as either SELFIES or SMILES. [WIP]
+
+On top of `poli`, we provide `poli-baselines`, a collection of black-box optimization algorithms (focusing especially on *discrete* sequences). Examples include
+- Random mutations,
+- Evolutionary and genetic algorithms like CMA-ES, or NSGA-2 [WIP],
+- Bayesian Optimization in latent space [WIP].
+
+A good place to start is the next chapter! [Go to Getting Started](./getting_started/getting_started.md).
+
+## Contents
 
 ```{tableofcontents}
 ```