Skip to content

Commit 793e06b

Browse files
miguelgondumiguelgondu
committed
Updates readme with instructions on how to build the documentation, and adds an intro to poli
1 parent 9495614 commit 793e06b

File tree

6 files changed

+368
-10
lines changed

6 files changed

+368
-10
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
.DS_Store
2+
.vscode/
3+
.ipynb_checkpoints/
24

35
# Example's working directory
46
examples/understanding_foldx/tmp

‎docs/protein-optimization/_toc.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ parts:
99
- file: getting_started/getting_started.md
1010
- caption: Using poli - the basics
1111
chapters:
12+
- file: using_poli/the_basics/intro_to_poli.ipynb
1213
- file: using_poli/the_basics/registering_an_objective_function.md
1314
- file: using_poli/the_basics/defining_a_problem_solver.md
1415
- file: using_poli/the_basics/optimizing_an_objective_function.md

‎docs/protein-optimization/getting_started/getting_started.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,4 +99,8 @@ for _ in range(5):
9999

100100
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.
101101

102+
## Conclusion
102103

104+
This tutorial showed you how to install `poli`, and register `white_noise`, which is available inside `poli` itself.
105+
106+
The next chapters explain the basics of `poli`, such as registering your own objective functions, defining problem solvers in `poli-baselines`, and optimizing.

‎docs/protein-optimization/using_poli/the_basics/intro_to_poli.ipynb

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# What is poli?"
8+
]
9+
},
10+
{
11+
"cell_type": "markdown",
12+
"metadata": {},
13+
"source": [
14+
"```{contents}\n",
15+
"```\n",
16+
"\n",
17+
"`poli` is a library for registering black box optimization functions, with a special focus on *discrete* sequence optimization. It stands for *Protein Optimization Library*, since some of the work done on drug design is done through representing proteins as discrete sequences, or sentences of amino acids.\n",
18+
"\n",
19+
"We also build `poli-baselines` on top, allowing you to define black box optimization algorithms for discrete sequences.\n",
20+
"\n",
21+
"These next chapters detail a basic example of how to use `poli` and `poli-baselines`. If you want to start coding now, continue to [the next chapter](./registering_an_objective_function.md)!\n",
22+
"\n",
23+
"After these, feel free to dive deeper into how `poli` works underneath in [the chapter about the details](./diving_deeper.md).\n",
24+
"\n",
25+
"The rest of this intro details the usual development loops we assume you'll follow when using `poli` and `poli-baselines`:"
26+
]
27+
},
28+
{
29+
"cell_type": "markdown",
30+
"metadata": {},
31+
"source": [
32+
"## The usual development loop"
33+
]
34+
},
35+
{
36+
"cell_type": "markdown",
37+
"metadata": {},
38+
"source": [
39+
"Black-box optimization algorithms inside `poli-baselines` are treated as **solvers** of **problems** defined using `poli`.\n",
40+
"\n",
41+
"We propose to you the following process for using `poli-baselines`' optimizers, or developing your own:"
42+
]
43+
},
44+
{
45+
"cell_type": "markdown",
46+
"metadata": {},
47+
"source": [
48+
"### Identify the objective function"
49+
]
50+
},
51+
{
52+
"cell_type": "markdown",
53+
"metadata": {},
54+
"source": [
55+
"Start by identify the black-box objective function you want to optimize, and check if it's already registered in `poli`, or available in `poli`'s objective repository.\n",
56+
"\n",
57+
"This can be done by running"
58+
]
59+
},
60+
{
61+
"cell_type": "code",
62+
"execution_count": 1,
63+
"metadata": {
64+
"vscode": {
65+
"languageId": "plaintext"
66+
}
67+
},
68+
"outputs": [
69+
{
70+
"name": "stdout",
71+
"output_type": "stream",
72+
"text": [
73+
"['white_noise']\n"
74+
]
75+
}
76+
],
77+
"source": [
78+
"from poli.core.registry import get_problems\n",
79+
"print(get_problems())"
80+
]
81+
},
82+
{
83+
"cell_type": "markdown",
84+
"metadata": {},
85+
"source": [
86+
"The output is a list of registered problems. If the function that you're interested in is not registered, you can check whether we have it in `poli`'s internal repository:"
87+
]
88+
},
89+
{
90+
"cell_type": "code",
91+
"execution_count": 2,
92+
"metadata": {},
93+
"outputs": [
94+
{
95+
"name": "stdout",
96+
"output_type": "stream",
97+
"text": [
98+
"['aloha', 'super_mario_bros', 'white_noise']\n"
99+
]
100+
}
101+
],
102+
"source": [
103+
"from poli.objective_repository import AVAILABLE_OBJECTIVES\n",
104+
"print(AVAILABLE_OBJECTIVES)"
105+
]
106+
},
107+
{
108+
"cell_type": "markdown",
109+
"metadata": {},
110+
"source": [
111+
"If the function isn't there, **implement it yourself!** An example of how to do this can be found in `poli_baselines/examples/00_a_simple_objective_function_registration`, or in our chapter on [registering optimization functions](./registering_an_objective_function.md).\n",
112+
"\n",
113+
"In what follows, we will use the `white_noise` objective function. You could drop-in your own function if desired."
114+
]
115+
},
116+
{
117+
"cell_type": "code",
118+
"execution_count": 3,
119+
"metadata": {},
120+
"outputs": [],
121+
"source": [
122+
"from poli import objective_factory\n",
123+
"\n",
124+
"problem_info, f, x0, y0, _ = objective_factory.create(\n",
125+
" name=\"white_noise\",\n",
126+
" force_register=True,\n",
127+
")"
128+
]
129+
},
130+
{
131+
"cell_type": "markdown",
132+
"metadata": {},
133+
"source": [
134+
"At this point, you can call `f` on arrays of shape `[b, L]`. In the specific case of `white_noise`, `L` can be any positive integer."
135+
]
136+
},
137+
{
138+
"cell_type": "markdown",
139+
"metadata": {},
140+
"source": [
141+
"### Using a solver, or creating your own"
142+
]
143+
},
144+
{
145+
"cell_type": "markdown",
146+
"metadata": {},
147+
"source": [
148+
"`poli-baselines` also comes with black-box optimizers out-of-the-box. You can find them inside the library.\n",
149+
"\n",
150+
"For example, let's use the `RandomMutation` solver, which takes the initial `x0` and randomly mutates it according to the alphabet provided in `problem_info`."
151+
]
152+
},
153+
{
154+
"cell_type": "code",
155+
"execution_count": 13,
156+
"metadata": {},
157+
"outputs": [
158+
{
159+
"name": "stdout",
160+
"output_type": "stream",
161+
"text": [
162+
"x0: [['1' '2' '3']]\n",
163+
"y0: [[1.58015034]]\n"
164+
]
165+
}
166+
],
167+
"source": [
168+
"from poli_baselines.solvers.simple.random_mutation import RandomMutation\n",
169+
"\n",
170+
"solver = RandomMutation(\n",
171+
" black_box=f,\n",
172+
" x0=x0,\n",
173+
" y0=y0,\n",
174+
" alphabet=problem_info.alphabet\n",
175+
")\n",
176+
"\n",
177+
"print(f\"x0: {x0}\")\n",
178+
"print(f\"y0: {y0}\")"
179+
]
180+
},
181+
{
182+
"cell_type": "markdown",
183+
"metadata": {},
184+
"source": [
185+
"Solvers implement a `next_candidate()` method, based on their history:"
186+
]
187+
},
188+
{
189+
"cell_type": "code",
190+
"execution_count": 14,
191+
"metadata": {},
192+
"outputs": [
193+
{
194+
"name": "stdout",
195+
"output_type": "stream",
196+
"text": [
197+
"{'x': [array([['1', '2', '3']], dtype='<U1')], 'y': [array([[1.58015034]])]}\n"
198+
]
199+
},
200+
{
201+
"data": {
202+
"text/plain": [
203+
"array([['1', '3', '3']], dtype='<U1')"
204+
]
205+
},
206+
"execution_count": 14,
207+
"metadata": {},
208+
"output_type": "execute_result"
209+
}
210+
],
211+
"source": [
212+
"print(solver.history)\n",
213+
"solver.next_candidate()"
214+
]
215+
},
216+
{
217+
"cell_type": "markdown",
218+
"metadata": {},
219+
"source": [
220+
"`RandomMutation` simply selects one token at random from the alphabet:"
221+
]
222+
},
223+
{
224+
"cell_type": "code",
225+
"execution_count": null,
226+
"metadata": {},
227+
"outputs": [
228+
{
229+
"data": {
230+
"text/plain": [
231+
"{'0': 0,\n",
232+
" '1': 1,\n",
233+
" '2': 2,\n",
234+
" '3': 3,\n",
235+
" '4': 4,\n",
236+
" '5': 5,\n",
237+
" '6': 6,\n",
238+
" '7': 7,\n",
239+
" '8': 8,\n",
240+
" '9': 9}"
241+
]
242+
},
243+
"execution_count": 16,
244+
"metadata": {},
245+
"output_type": "execute_result"
246+
}
247+
],
248+
"source": [
249+
"[alphabet_symbol for alphabet_symbol in solver.alphabet.keys()]"
250+
]
251+
},
252+
{
253+
"cell_type": "markdown",
254+
"metadata": {},
255+
"source": [
256+
"**If you are interested in building your own solver**, check out [the chapter detailing how `RandomMutation` is implemented](./defining_a_problem_solver.md)."
257+
]
258+
},
259+
{
260+
"cell_type": "markdown",
261+
"metadata": {},
262+
"source": [
263+
"### Optimizing"
264+
]
265+
},
266+
{
267+
"cell_type": "markdown",
268+
"metadata": {},
269+
"source": [
270+
"Once you have a black box objective function `f` and a solver on top, the optimization is quite easy:"
271+
]
272+
},
273+
{
274+
"cell_type": "code",
275+
"execution_count": 19,
276+
"metadata": {},
277+
"outputs": [],
278+
"source": [
279+
"solver.solve(max_iter=100)"
280+
]
281+
},
282+
{
283+
"cell_type": "code",
284+
"execution_count": 20,
285+
"metadata": {},
286+
"outputs": [
287+
{
288+
"name": "stdout",
289+
"output_type": "stream",
290+
"text": [
291+
"[['0' '2' '3']]\n"
292+
]
293+
}
294+
],
295+
"source": [
296+
"print(solver.get_best_solution())"
297+
]
298+
},
299+
{
300+
"cell_type": "markdown",
301+
"metadata": {},
302+
"source": [
303+
"Of course, this example is trivial. We dive deeper in the next chapters."
304+
]
305+
},
306+
{
307+
"cell_type": "markdown",
308+
"metadata": {},
309+
"source": [
310+
"## Conclusion"
311+
]
312+
},
313+
{
314+
"cell_type": "markdown",
315+
"metadata": {},
316+
"source": [
317+
"This chapter discusses the usual development loop using `poli` and `poli-baselines`:\n",
318+
"1. Start by identifying/building your objective function,\n",
319+
"2. continue by creating/using a solver in `poli_baselines`, and\n",
320+
"3. use the `solve` method to run a number of iterations from the solver.\n",
321+
"\n",
322+
"The next three chapters talk about another trivial example, diving deeper in the process of defining your own objective functions and solvers. You can continue there, or by checking [the currently implemented repository of objective functions inside `poli` TODO: ADD]()."
323+
]
324+
}
325+
],
326+
"metadata": {
327+
"kernelspec": {
328+
"display_name": "Python 3 (ipykernel)",
329+
"language": "python",
330+
"name": "python3"
331+
},
332+
"language_info": {
333+
"codemirror_mode": {
334+
"name": "ipython",
335+
"version": 3
336+
},
337+
"file_extension": ".py",
338+
"mimetype": "text/x-python",
339+
"name": "python",
340+
"nbconvert_exporter": "python",
341+
"pygments_lexer": "ipython3",
342+
"version": "3.9.17"
343+
}
344+
},
345+
"nbformat": 4,
346+
"nbformat_minor": 4
347+
}

‎docs/protein-optimization/using_poli/the_basics/intro_to_poli.md

Lines changed: 0 additions & 9 deletions
This file was deleted.

0 commit comments

Comments
 (0)