@@ -77,10 +77,10 @@ login()
sequences = ["MSKGEELFTGVVPILVELDGDVNGHKFSVSGEGEGDATYGKLTLKFICTTGKLPVPWPTLVTTFSYGVQCFSRYPDHMKQHDFFKSAMPEGYVQERTIFFKDDGNYKTRAEVKFEGDTLVNRIELKGIDFKEDGNILGHKLEYNYNSHNVYIMADKQKNGIKVNFKIRHNIEDGSVQLADHYQQNTPIGDGPVLLPDNHYLSTQSALSKDPNEKRDHMVLLEFVTAAGITHGMDELYK"]
model = AutoModelForMaskedLM.from_pretrained(
- "Biohub/ESMC-6B",
+ "biohub/ESMC-6B",
device_map="auto",
).eval()
-tokenizer = AutoTokenizer.from_pretrained("Biohub/ESMC-6B")
+tokenizer = AutoTokenizer.from_pretrained("biohub/ESMC-6B")
inputs = tokenizer(sequences, return_tensors="pt", padding=True)
inputs = {k: v.to(model.device) for k, v in inputs.items()}
@@ -150,10 +150,10 @@ from transformers import AutoModel, AutoTokenizer
sequence = "MGSNKSKPKDASQRRRSLEPAENVHGAGGGAFPASQTPSKPASADGHRGPSAAFAPAAAEPKLFGGFNSSDTVTSPQRAGPLAGGVTTFVALYDYESRTETDLSFKKGERLQIVNNTEGDWWLAHSLSTGQTGYIPSNYVAPSDSIQAEEWYFGKITRRESERLLLNAENPRGTFLVRESETTKGAYCLSVSDFDNAKGLNVKHYKIRKLDSGGFYITSRTQFNSLQQLVAYYSKHADGLCHRLTTVCPTSKPQTQGLAKDAWEIPRESLRLEVKLGQGCFGEVWMGTWNGTTRVAIKTLKPGTMSPEAFLQEAQVMKKLRHEKLVQLYAVVSEEPIYIVTEYMSKGSLLDFLKGETGKYLRLPQLVDMAAQIASGMAYVERMNYVHRDLRAANILVGENLVCKVADFGLARLIEDNEYTARQGAKFPIKWTAPEAALYGRFTIKSDVWSFGILLTELTTKGRVPYPGMVNREVLDQVERGYRMPCPPECPESLHDLMCQCWRKEPEERPTFEYLQAFLEDYFTSTEPQYQPGENL"
-model = AutoModel.from_pretrained("Biohub/ESMC-6B", device_map="auto").eval()
-tokenizer = AutoTokenizer.from_pretrained("Biohub/ESMC-6B")
+model = AutoModel.from_pretrained("biohub/ESMC-6B", device_map="auto").eval()
+tokenizer = AutoTokenizer.from_pretrained("biohub/ESMC-6B")
sae = AutoModel.from_pretrained(
- "Biohub/ESMC-6B-sae-k64-codebook16384",
+ "biohub/ESMC-6B-sae-k64-codebook16384",
allow_patterns=["config.json", "layer_30.safetensors", "layer_60.safetensors"],
device=model.device,
)
@@ -176,11 +176,11 @@ For tutorials on how to use ESMC SAEs, see our [tutorials](https://github.com/Bi
## ESMFold2
-[ESMFold2](https://huggingface.co/Biohub/ESMFold2) is a state-of-the-art protein structure prediction model that combines ESMC (6B parameter) language model embeddings with a diffusion-based structure prediction architecture.
+[ESMFold2](https://huggingface.co/biohub/ESMFold2) is a state-of-the-art protein structure prediction model that combines ESMC (6B parameter) language model embeddings with a diffusion-based structure prediction architecture.
The model predicts high-resolution, all-atom 3D protein structures directly from amino acid sequences, with optional multiple sequence alignment (MSA) input for enhanced accuracy on challenging targets. ESMFold2 achieves state-of-the-art performance matching or exceeding AlphaFold3 across diverse evaluation datasets, while offering improved computational efficiency through optimized diffusion sampling and architectural innovations.
-Codebase, model weights, and model variants for ESMFold2 are available through [Hugging Face](https://huggingface.co/Biohub/ESMFold2)
+Codebase, model weights, and model variants for ESMFold2 are available through [Hugging Face](https://huggingface.co/biohub/ESMFold2)
### Running ESMFold2 Locally
@@ -232,9 +232,11 @@ with open("1mht_pred.cif", "w") as f:
f.write(result.complex.to_mmcif())
```
+> **AMD ROCm users:** use ROCm 6.4 with PyTorch 2.9 or newer.
+
### Running ESMFold2 Through the Biohub Platform
-Install the `esm` Python package
+Install the `esm` Python package
```
pip install esm@git+https://github.com/Biohub/esm.git@main
@@ -283,7 +285,7 @@ Informed by our risk assessments, we are releasing the source code and model wei
Evaluations: Prior to release, we conducted evaluations to inform our understanding of capability uplift for specific misuse-relevant functional tasks. The full details of these evaluations are available in our corresponding paper appendix.
-The Biohub Platform: We implement guardrails that detect and restrict the use of keywords and sequences corresponding to controlled pathogens and toxins on our freely accessible platform. For further details regarding these guardrails, please refer to our Biohub Platform Resources page. We recognize there are many legitimate reasons to use AI models to understand and model these sequences and proteins. If you are a researcher whose work is impacted by these guardrails, you can request elevated access to our platform via [Biohub.ai](http://Biohub.ai).
+The Biohub Platform: We implement guardrails that detect and restrict the use of keywords and sequences corresponding to controlled pathogens and toxins on our freely accessible platform. For further details regarding these guardrails, please refer to our Biohub Platform Resources page. We recognize there are many legitimate reasons to use AI models to understand and model these sequences and proteins. If you are a researcher whose work is impacted by these guardrails, you can request elevated access to our platform via [biohub.ai](https://biohub.ai).
Please follow our [Acceptable Use Policy](https://biohub.org/acceptable-use-policy/) when using the model.
diff --git a/cookbook/tutorials/README.md b/cookbook/tutorials/README.md
index abcec8a..f2d51d7 100644
--- a/cookbook/tutorials/README.md
+++ b/cookbook/tutorials/README.md
@@ -23,9 +23,10 @@ ESMC is a protein language model that embeds sequences into rich numerical repre
ESMFold2 predicts 3D protein structure from sequence, including DNA/RNA and small molecules.
-| Notebook | Colab Notebook | Description |
+| Notebook | Colab Notebook | Description |
| :---- | :---- | :---- |
-| Folding with ESMFold2 | `esmfold2.ipynb`
[](https://colab.research.google.com/github/biohub/esm/blob/main/cookbook/tutorials/esmfold2.ipynb) | Fold proteins in combination with DNA, RNA and small-molecule ligands.
+| Folding with ESMFold2 | `esmfold2.ipynb`
[](https://colab.research.google.com/github/biohub/esm/blob/main/cookbook/tutorials/esmfold2.ipynb) | Fold proteins in combination with DNA, RNA and small-molecule ligands. |
+| Binder design | `binder_design.ipynb`
[](https://colab.research.google.com/github/biohub/esm/blob/main/cookbook/tutorials/binder_design.ipynb) | Design antibodies and minibinders with high hit rates. Implements the protocol featured in our paper, which produced binders exhibiting nanomolar affinity, target specificity, and functional activity in laboratory assays. |
## **ESM3**
diff --git a/cookbook/tutorials/binder_design.ipynb b/cookbook/tutorials/binder_design.ipynb
new file mode 100644
index 0000000..a921958
--- /dev/null
+++ b/cookbook/tutorials/binder_design.ipynb
@@ -0,0 +1,884 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "b5b44288",
+ "metadata": {},
+ "source": [
+ "## [Tutorial](https://github.com/biohub/esm/tree/main/cookbook/tutorials): How to run minibinder + scFv design fully end-to-end.\n",
+ "\n",
+ "In this tutorial we will use [Modal](https://modal.com/) to parallelize binder design and synthesize a selection,\n",
+ "using the protocol described in the ESMC and ESMFold2 paper titled [\"Language Modeling Materializes a World Model of Protein Biology\"](https://biohub.ai/papers/esm_protein.pdf).\n",
+ "\n",
+ "Biohub used this approach to design minibinders and scFvs against five therapeutically relevant targets — PDGFRB, EGFR, PD-L1, CD45, and CTLA4 — spanning receptor tyrosine kinases, immune checkpoints, and cell-surface phosphatases. Binders exhibit nanomolar affinity, target specificity, and functional activity in laboratory assays."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4421cdaa",
+ "metadata": {},
+ "source": [
+ "### One-time setup"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "99783792",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Environment\n",
+ "! pip install esm@git+https://github.com/Biohub/esm.git@main\n",
+ "! pip install modal py3dmol pyarrow"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "d3de7d00",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Confirm you have a modal token, or make one\n",
+ "! modal token info # Check\n",
+ "# ! modal token new # Create"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "2ee89767",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Deploy (or redeploy after changing binder_design.py).\n",
+ "# This only needs to be run a single time, unless code in binder_design.py changes.\n",
+ "! modal deploy binder_design.py"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "dc8456da",
+ "metadata": {},
+ "source": [
+ "### Imports"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "37c03b59",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from itertools import product\n",
+ "from pathlib import Path\n",
+ "\n",
+ "import modal\n",
+ "import pandas as pd\n",
+ "import py3Dmol\n",
+ "from Bio.SeqUtils.ProtParam import ProteinAnalysis\n",
+ "from tqdm.auto import tqdm"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "1fe9a141",
+ "metadata": {},
+ "source": [
+ "### App setup"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "291d8bfe",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# ESMFold2Design = modal.Cls.from_name(\"esmfold2-design-jun1-11am\", \"ESMFold2DesignModal\")\n",
+ "ESMFold2Design = modal.Cls.from_name(\"esmfold2-design-jun1-12pm\", \"ESMFold2DesignModal\")\n",
+ "# Set 'use_scaling_critics' to evaluate with the additional critics.\n",
+ "# Off by default. But cells below were populated with them enabled.\n",
+ "app = ESMFold2Design(use_scaling_critics=False)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "159b63df",
+ "metadata": {},
+ "source": [
+ "### Run one job - interactive"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "826c88d1",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "'https://modal.com/id/fc-01KT1ZA3NQ0JTF2B4HNCR159NM'"
+ ]
+ },
+ "execution_count": 4,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "# ---- Option 1: Use presets. ----\n",
+ "# Relies on the registry in modal_binder_design.py::{TARGET_SEQUENCES,BINDER_PROMPT_FACTORIES}, which can be modified.\n",
+ "future = app.design.spawn(target_name=\"ctla4\", binder_name=\"minibinder\")\n",
+ "future.get_dashboard_url() # A clickable link to Modal dashboard"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "c1bda1a6",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# ---- Option 2: Provide your own sequences. ----\n",
+ "# Our pd-l1 sequence crop.\n",
+ "pdl1_sequence = \"AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKNIIQFVHGEEDLKVQHSSYRQRARLLKDQLSLGNAALQITDVKLQDAGVYRCMISYGGADYKRITVKVNA\"\n",
+ "# A sample of 'trastuzumab_framework_vhvl' template. From binder_design.py::BINDER_PROMPT_FACTORIES.\n",
+ "trastuzumab_framework_vhvl = \"EVQLVESGGGLVQPGGSLRLSCAAS#######YIHWVRQAPGKGLEWVARI#####TRYADSVKGRFTISADTSKNTAYLQMNSLRAEDTAVYYCSR###########WGQGTLVTVSSGGGSGGGSGGGSGGGSDIQMTQSPSSLSASVGDRVTITC###########WYQQKPGKAPKLLIY#######GVPSRFSGSRSGTDFTLTISSLQPEDFATYYC#########FGQGTKVEIK\"\n",
+ "future2 = app.design.spawn(\n",
+ " target_sequence=pdl1_sequence,\n",
+ " binder_sequence=trastuzumab_framework_vhvl,\n",
+ " is_antibody=True,\n",
+ ")\n",
+ "future2.get_dashboard_url() # A clickable link to Modal dashboard"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "e442e64e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# ---- Monitor ----\n",
+ "# Tail a function's output here in jupyter\n",
+ "! modal app logs esmfold2-design -f --function-call {future.object_id}"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "79ea37f3",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# ---- Load result ----\n",
+ "best_sequences, trajectory, critic_results = future.get()\n",
+ "print(\"Best sequences: \", best_sequences)\n",
+ "df = pd.DataFrame(critic_results)\n",
+ "df.drop(columns=[\"logits\", \"complex\"])"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 54,
+ "id": "d80597fa",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/3dmoljs_load.v0": "
\n
3Dmol.js failed to load for some reason. Please check your browser console for error messages.
\n
\n",
+ "text/html": [
+ "
\n",
+ "
3Dmol.js failed to load for some reason. Please check your browser console for error messages.
\n",
+ "
\n",
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/plain": [
+ "
"
+ ]
+ },
+ "execution_count": 54,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "# ---- Visualize ----\n",
+ "protein_complex = (\n",
+ " df[df.critic_name.eq(\"ESMFold2-Experimental-Cutoff2025\")].iloc[0].complex\n",
+ ")\n",
+ "(\n",
+ " py3Dmol.view(width=600, height=600)\n",
+ " .addModel(protein_complex.to_pdb_string(), \"pdb\")\n",
+ " .setStyle({\"chain\": \"A\"}, {\"cartoon\": {\"color\": \"green\"}}) # pyright: ignore\n",
+ " .setStyle({\"chain\": \"B\"}, {\"cartoon\": {\"color\": \"cyan\"}}) # pyright: ignore\n",
+ " .addStyle( # pyright: ignore\n",
+ " {\"not\": {\"atom\": [\"N\", \"C\", \"O\"]}},\n",
+ " {\"stick\": {\"colorscheme\": \"default\", \"radius\": 0.2}},\n",
+ " )\n",
+ " .center() # pyright: ignore\n",
+ " .zoomTo() # pyright: ignore\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "fc105292",
+ "metadata": {},
+ "source": [
+ "### Run a sweep - async"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "ac02bbaa",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " target_name | \n",
+ " target_sequence | \n",
+ " binder_name | \n",
+ " binder_sequence | \n",
+ " use_scaling_critics | \n",
+ " seed | \n",
+ " batch_size | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " pd-l1 | \n",
+ " None | \n",
+ " minibinder | \n",
+ " None | \n",
+ " False | \n",
+ " 0 | \n",
+ " 1 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " pd-l1 | \n",
+ " None | \n",
+ " minibinder | \n",
+ " None | \n",
+ " False | \n",
+ " 1 | \n",
+ " 1 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " | \n",
+ " | \n",
+ " designed_sequence | \n",
+ " iptm_score | \n",
+ " iptm_proxy_score | \n",
+ " selection_score | \n",
+ "
\n",
+ " \n",
+ " | target_name | \n",
+ " binder_name | \n",
+ " | \n",
+ " | \n",
+ " | \n",
+ " | \n",
+ " | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | pd-l1 | \n",
+ " minibinder | \n",
+ " 70 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.967982 | \n",
+ " 0.944397 | \n",
+ " 0.956190 | \n",
+ "
\n",
+ " \n",
+ " | 13 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.964470 | \n",
+ " 0.926216 | \n",
+ " 0.945343 | \n",
+ "
\n",
+ " \n",
+ " | 78 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.961920 | \n",
+ " 0.918186 | \n",
+ " 0.940053 | \n",
+ "
\n",
+ " \n",
+ " | 75 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.957516 | \n",
+ " 0.916083 | \n",
+ " 0.936799 | \n",
+ "
\n",
+ " \n",
+ " | 45 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.964665 | \n",
+ " 0.908466 | \n",
+ " 0.936566 | \n",
+ "
\n",
+ " \n",
+ " | ... | \n",
+ " ... | \n",
+ " ... | \n",
+ " ... | \n",
+ " ... | \n",
+ " ... | \n",
+ "
\n",
+ " \n",
+ " | trastuzumab_framework_vhvl | \n",
+ " 2 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.921884 | \n",
+ " 0.725663 | \n",
+ " 0.823773 | \n",
+ "
\n",
+ " \n",
+ " | 107 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.920620 | \n",
+ " 0.726391 | \n",
+ " 0.823506 | \n",
+ "
\n",
+ " \n",
+ " | 46 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.879064 | \n",
+ " 0.767323 | \n",
+ " 0.823194 | \n",
+ "
\n",
+ " \n",
+ " | 68 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.921196 | \n",
+ " 0.724139 | \n",
+ " 0.822668 | \n",
+ "
\n",
+ " \n",
+ " | 50 | \n",
+ " AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... | \n",
+ " 0.894414 | \n",
+ " 0.747255 | \n",
+ " 0.820834 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "168 rows × 4 columns
\n",
+ " "
+ ],
+ "text/plain": [
+ " designed_sequence \\\n",
+ "target_name binder_name \n",
+ "pd-l1 minibinder 70 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ " 13 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ " 78 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ " 75 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ " 45 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ "... ... \n",
+ " trastuzumab_framework_vhvl 2 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ " 107 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ " 46 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ " 68 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ " 50 AFTVTVPKDLYVVEYGSNMTIECKFPVEKQLDLAALIVYWEMEDKN... \n",
+ "\n",
+ " iptm_score iptm_proxy_score \\\n",
+ "target_name binder_name \n",
+ "pd-l1 minibinder 70 0.967982 0.944397 \n",
+ " 13 0.964470 0.926216 \n",
+ " 78 0.961920 0.918186 \n",
+ " 75 0.957516 0.916083 \n",
+ " 45 0.964665 0.908466 \n",
+ "... ... ... \n",
+ " trastuzumab_framework_vhvl 2 0.921884 0.725663 \n",
+ " 107 0.920620 0.726391 \n",
+ " 46 0.879064 0.767323 \n",
+ " 68 0.921196 0.724139 \n",
+ " 50 0.894414 0.747255 \n",
+ "\n",
+ " selection_score \n",
+ "target_name binder_name \n",
+ "pd-l1 minibinder 70 0.956190 \n",
+ " 13 0.945343 \n",
+ " 78 0.940053 \n",
+ " 75 0.936799 \n",
+ " 45 0.936566 \n",
+ "... ... \n",
+ " trastuzumab_framework_vhvl 2 0.823773 \n",
+ " 107 0.823506 \n",
+ " 46 0.823194 \n",
+ " 68 0.822668 \n",
+ " 50 0.820834 \n",
+ "\n",
+ "[168 rows x 4 columns]"
+ ]
+ },
+ "execution_count": 49,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "# ---- Select ----\n",
+ "\n",
+ "# Join all result_df's, with other fields in df broadcasted as metadata.\n",
+ "df_result = pd.concat(\n",
+ " [\n",
+ " row.result_df.assign(**row.drop([\"result\", \"result_df\"]).to_dict()) # pyright: ignore\n",
+ " for _, row in df_success.iterrows()\n",
+ " ],\n",
+ " ignore_index=True,\n",
+ " axis=0,\n",
+ ")\n",
+ "\n",
+ "# Filter minibinder designs with isoelectric point >= 6.\n",
+ "df_result[\"binder_sequence\"] = df_result.designed_sequence.str.split(r\"\\|\").str[1]\n",
+ "df_result[\"isoelectric_point\"] = [\n",
+ " ProteinAnalysis(seq).isoelectric_point()\n",
+ " for seq in tqdm(df_result.binder_sequence.values)\n",
+ "]\n",
+ "# Isoelectric point filter\n",
+ "df_filter = df_result[df_result.is_antibody | df_result.isoelectric_point.lt(6)]\n",
+ "\n",
+ "\n",
+ "# Select the top 84 designs from each (target, binder) combination\n",
+ "SCALING_CHECKPOINT_SUBSTRING = \"ESMFold2-Experimental-Fast-base\"\n",
+ "\n",
+ "\n",
+ "def select(df: pd.DataFrame) -> pd.DataFrame:\n",
+ " df = df.copy()\n",
+ " is_scaling = df.critic_name.str.contains(\n",
+ " SCALING_CHECKPOINT_SUBSTRING, regex=False, na=False\n",
+ " )\n",
+ " iptm_proxy = df.distogram_iptm_proxy.where(\n",
+ " ~df.is_antibody, df.cdr_distogram_iptm_proxy\n",
+ " )\n",
+ "\n",
+ " df[\"iptm_score\"] = df.iptm.where(~is_scaling)\n",
+ " df[\"iptm_proxy_score\"] = iptm_proxy.where(is_scaling)\n",
+ " scores = df.groupby(\"designed_sequence\", as_index=False).agg(\n",
+ " iptm_score=(\"iptm_score\", \"mean\"), iptm_proxy_score=(\"iptm_proxy_score\", \"mean\")\n",
+ " )\n",
+ " scores[\"selection_score\"] = 0.5 * scores.iptm_score.fillna(\n",
+ " 0\n",
+ " ) + 0.5 * scores.iptm_proxy_score.fillna(0)\n",
+ "\n",
+ " return scores.nlargest(min(len(scores), 84), \"selection_score\")\n",
+ "\n",
+ "\n",
+ "df_select = df_filter.groupby([\"target_name\", \"binder_name\"]).apply(\n",
+ " select, include_groups=False\n",
+ ")\n",
+ "df_select.to_parquet(save_dir / \"selection.parquet\", index=False)\n",
+ "df_select"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "b54a71de",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "df_result[df_result.critic_name.eq(\"ESMFold2-Experimental-Cutoff2025\")].drop(\n",
+ " columns=[\"complex\", \"logits\"]\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "851365c0",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "df_select"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "7e174c1e",
+ "metadata": {},
+ "source": [
+ "## Appendix"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3f79528d",
+ "metadata": {},
+ "source": [
+ "### Modal Primer"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4297bc4d",
+ "metadata": {},
+ "source": [
+ "- **info: ephemeral vs deployment** \n",
+ " Ephemeral = temporary app from `modal run` or `app.run()`, stopped when the client exits. Deployment = persistent named app from `modal deploy`, reused and observable across runs. ([modal.com](https://modal.com/docs/guide/apps?utm_source=openai))\n",
+ "\n",
+ "- **info: dashboard** \n",
+ " Generic dashboard/apps page: [https://modal.com/apps](https://modal.com/apps). Modal also prints app/deployment links during runs/deploys. ([modal.com](https://modal.com/docs/guide/apps?utm_source=openai))\n",
+ "\n",
+ "- **cli: ephemeral run** \n",
+ " ```bash\n",
+ " modal run path/to/app.py\n",
+ " ```\n",
+ "\n",
+ "- **cli: deploy/redeploy** \n",
+ " ```bash\n",
+ " modal deploy path/to/app.py\n",
+ " ```\n",
+ " Running this on an existing app name redeploys a new version. ([modal.com](https://modal.com/docs/reference/cli/deploy?utm_source=openai))\n",
+ "\n",
+ "- **local: ephemeral from Python** \n",
+ " ```python\n",
+ " with modal.enable_output():\n",
+ " with modal_app.run():\n",
+ " result = local_modal_obj.remote(...)\n",
+ " ```\n",
+ "\n",
+ "- **local: call a deployment** \n",
+ " ```python\n",
+ " Cls = modal.Cls.from_name(\"app-name\", \"ClassName\")\n",
+ " obj = Cls(...)\n",
+ " result = obj.method.remote(...)\n",
+ " ```\n",
+ " `Cls.from_name` references a class from a deployed app lazily. ([modal.com](https://modal.com/docs/reference/modal.Cls?utm_source=openai))"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "default",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.12.13"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/cookbook/tutorials/binder_design.py b/cookbook/tutorials/binder_design.py
new file mode 100644
index 0000000..8040f16
--- /dev/null
+++ b/cookbook/tutorials/binder_design.py
@@ -0,0 +1,1244 @@
+# /// script
+# requires-python = "<=3.13"
+# dependencies = [
+# "abnumber",
+# "esm@git+https://github.com/Biohub/esm.git@main",
+# "modal",
+# ]
+# ///
+"""
+Code for binder design with ESMFold2 and ESMC.
+
+As described in [Language Modeling Materializes a World Model of Protein Biology](https://biohub.ai/papers/esm_protein.pdf).
+"""
+
+import logging
+import math
+import os
+import random
+import string
+from dataclasses import dataclass
+from functools import cache, partial
+from typing import Any
+
+import biotite.structure
+import modal
+import numpy as np
+import torch
+import torch.nn.functional as F
+import torch.optim as optim
+from torch.distributed.algorithms._checkpoint.checkpoint_wrapper import (
+ CheckpointImpl,
+ apply_activation_checkpointing,
+ checkpoint_wrapper,
+)
+from transformers.models.esmc.modeling_esmc import ESMCForMaskedLM
+from transformers.models.esmc.modeling_esmc import (
+ UnifiedTransformerBlock as TransformerBlock,
+)
+from transformers.models.esmc.tokenization_esmc import ESMCTokenizer
+from transformers.models.esmfold2.modeling_esmfold2_common import (
+ CUE_AVAILABLE,
+ PairUpdateBlock,
+)
+from transformers.models.esmfold2.modeling_esmfold2_common import (
+ _seed_context as seed_context,
+)
+from transformers.models.esmfold2.modeling_esmfold2_experimental import (
+ ESMFold2ExperimentalModel,
+)
+from transformers.models.esmfold2.modeling_esmfold2_experimental import (
+ MSAEncoder as ESMFold2MSAEncoder,
+)
+
+from esm.models.esmfold2 import (
+ ELEMENT_NUMBER_TO_SYMBOL,
+ ProteinInput,
+ StructurePredictionInput,
+ load_ccd,
+ prepare_esmfold2_input,
+)
+from esm.models.esmfold2.constants import (
+ MOL_TYPE_NONPOLYMER,
+ PROTEIN_1TO3,
+ PROTEIN_3TO1,
+ RES_TYPE_TO_CCD,
+)
+from esm.utils.structure.protein_chain import ProteinChain
+from esm.utils.structure.protein_complex import ProteinComplex
+
+os.environ["HF_XET_HIGH_PERFORMANCE"] = "1"
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s: %(message)s")
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+# ---- Constants ----
+
+
+# General
+TOKENS = ["