Skip to content

docs: rewrite ESMFold2 guide around HIV-1 protease homodimer#182

Merged
markgeejw merged 6 commits into
developfrom
docs/using-esmfold2-nits
Jun 9, 2026
Merged

docs: rewrite ESMFold2 guide around HIV-1 protease homodimer#182
markgeejw merged 6 commits into
developfrom
docs/using-esmfold2-nits

Conversation

@timt51

@timt51 timt51 commented Jun 5, 2026

Copy link
Copy Markdown
Contributor

Summary

Rewrites the ESMFold2 Python-API tutorial around the HIV-1 protease — a textbook obligate homodimer — replacing the previous Interleukin-2 example (IL-2 is a monomer, so folding it as a two-chain complex was biologically wrong).

The guide now flows: define the protease → fold the complex (the biological dimer) → retrieve & visualize early → assess multi-chain confidence (pTM / ipTM / per-chain pTM / pairwise ipTM grid) with PAE & pLDDT plotscondition on an MSAco-fold with ritonavir (its real inhibitor; DNA/RNA shown as API snippets) → ESMFold2-Fast → a note on first-gen ESMFold → next steps.

Headers are nested to match the Boltz/Protenix tutorials (single # title, ## sections, ### sub-parts).

Notes / decisions

  • Executed against the dev backend with outputs committed. Clean run: protease dimer pTM 0.957 / ipTM 0.950 / complex pLDDT 0.940; MSA, ritonavir co-fold, ESMFold2-Fast, and first-gen ESMFold all succeed.
  • No em-dashes (consistent with this guide's house style), no dead/commented-out code cells, all cells carry ids.
  • The pairwise ipTM grid prints the SDK's chain-index keys (0/1) rather than A/B — kept intentionally.

Out of scope (flagged for the SDK team, not addressed here)

  • FoldModel.model_id (fold/models.py:49-50) is self-recursive; only safe because each model subclass shadows it. A bare FoldModel (unrecognized model id) RecursionErrors on .fold(). This is what made a stale dev-nb env fail until openprotein was updated.
  • ESMFold v1 result retrieval returned a transient 400 once on dev, then worked on retry.

🤖 Generated with Claude Code

timt51 and others added 3 commits June 4, 2026 19:06
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Restructure the ESMFold2 tutorial: fold the protease as a complex,
retrieve/visualize early, assess multi-chain confidence (pTM/ipTM/
pairwise ipTM grid + PAE/pLDDT plots), condition on an MSA, co-fold
with ritonavir, and cover ESMFold2-Fast and first-gen ESMFold. Cells
ship un-run with cleared outputs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Execute the rewritten notebook end-to-end on the dev backend: protease
dimer fold (pTM 0.957 / ipTM 0.950), confidence breakdown, PAE/pLDDT
plots, MSA-conditioned fold, ritonavir co-fold, ESMFold2-Fast, and
first-gen ESMFold all succeed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@timt51 timt51 requested a review from markgeejw June 5, 2026 03:49
@timt51

timt51 commented Jun 7, 2026

Copy link
Copy Markdown
Contributor Author

Updated the esmfold2 num_steps default reference from 200 to 100 in the guide, to match the default change in the client library (openprotein-python-private#233) and API spec (openprotein-api#9), driven by embeddings-svc#317 / backend-worker-esmfold2#8.

Note: this was a manual edit — the notebook was not re-run (as requested). That includes the printed fold(...) signature in the cached cell output, which I hand-edited to show num_steps: int = 100. A future re-run against the updated client will regenerate it identically. The explicit num_steps=50 calls in the examples are intentional overrides and were left unchanged.

@timt51 timt51 force-pushed the docs/using-esmfold2-nits branch from ff4eed1 to 7e0c347 Compare June 7, 2026 23:24
@markgeejw markgeejw merged commit 982af23 into develop Jun 9, 2026
2 checks passed
@markgeejw markgeejw deleted the docs/using-esmfold2-nits branch June 9, 2026 22:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants