mosaic

Name: mosaic
Author: adaptyvbio

7installs20forks

How to install mosaic?

adaptyvbio/protein-design-skills/mosaic

$npx -y skills add adaptyvbio/protein-design-skills --skill mosaic

Installs into the current project.

Summary

Multi-objective, gradient-based protein binder design with Mosaic. Use this skill when: (1) Composing several structure or sequence models into one design objective, (2) Optimizing binders against a custom loss rather than a fixed pipeline, (3) Wanting gradient descent over seque

Files · 1

View on GitHub

SKILL.md

1	# Mosaic Multi-Objective Design
2
3	[Mosaic](https://github.com/escalante-bio/mosaic) (Escalante Bio) is a JAX framework
4	for "functional, multi-objective protein design using continuous relaxation." It
5	optimizes a soft sequence by gradient descent over a continuous relaxation of
6	sequence space, in the lineage of ColabDesign, RSO, and BindCraft, with one key
7	difference: it composes multiple learned objectives from different models in a single
8	differentiable loss.
9
10	## When Mosaic fits
11
12	Mosaic is a framework for custom objectives, not a one-click method. The README is
13	explicit: it "may require substantial hand-holding (tuning learning rates, etc),
14	often produces proteins that fail simple in-silico tests, [and] should be combined
15	with standard filtering methods." Reach for it when a fixed pipeline cannot express
16	the objective you need. For a turnkey binder run, use `bindcraft` instead.
17
18	## Prerequisites
19
20	\| Requirement \| Minimum \| Recommended \|
21	\|-------------\|---------\|-------------\|
22	\| Python \| 3.11+ \| 3.11 \|
23	\| Framework \| JAX with CUDA or TPU \| JAX CUDA 12 \|
24	\| GPU VRAM \| 24GB \| 48GB+ (depends on predictors used) \|
25
26	JIT compilation makes the first call to any loss slow; later calls are fast.
27
28	## Install
29
30	Mosaic runs locally on a JAX GPU or TPU build. It has no CLI and no Modal
31	integration; you drive it through the marimo notebooks or the Python API.
32
33	```bash
34	git clone https://github.com/escalante-bio/mosaic && cd mosaic
35	uv sync --group jax-cuda # or --group jax-tpu / --group jax-cpu
36	uv add jax[cuda12] # may be needed for a GPU build
37	uv run marimo edit examples/example_notebook.py
38	```
39
40	Ready-made examples include `esmfold_minibinder.py`, `esmfold_vhh.py`,
41	`boltzgen_pipeline.py`, and `batched_protenix.py`.
42
43	## Core idea
44
45	A design objective is built from `LossTerm` objects that you add and scale with plain
46	Python arithmetic, then hand to an optimizer.
47
48	```python
49	import mosaic.losses.structure_prediction as sp
50
51	# Compose a loss from interface, confidence, and inverse-folding terms
52	design_loss = (
53	sp.BinderTargetContact()
54	+ sp.WithinBinderContact()
55	+ 0.05 * sp.TargetBinderPAE()
56	+ 0.05 * sp.BinderTargetPAE()
57	+ 0.025 * sp.IPTMLoss()
58	+ 0.1 * sp.PLDDTLoss()
59	)
60	```
61
62	Loss terms can wrap one model used several ways (for example a structure predictor
63	scoring both the binder-target complex and the binder as a monomer). Composing
64	different architectures also lowers the chance of finding adversarial sequences that
65	fool a single predictor.
66
67	### What you can compose
68
69	\| Category \| Options \|
70	\|----------\|---------\|
71	\| Structure predictors \| AF2, Boltz-1, Boltz-2, Protenix, OpenFold3, ESMFold2 \|
72	\| Generative / design \| BoltzGen, Proteina-Complexa \|
73	\| Inverse folding \| ProteinMPNN, SolubleMPNN, AbMPNN \|
74	\| Language models \| ESM-2, ESM-C, AbLang, trigram \|
75	\| Property heads \| Stability (megascale-trained) \|
76
77	### Optimizers
78
79	\| Optimizer \| Use \|
80	\|-----------\|-----\|
81	\| `simplex_APGM` \| Default; proximal gradient / mirror descent on the probability simplex \|
82	\| `batched_simplex_APGM` \| The same, vmapped over many designs \|
83	\| `gradient_MCMC` \| Discrete moves for fine-tuning a sequence \|
84
85	A reasonable `simplex_APGM` step size is about `0.1 * sqrt(binder_length)`.
86
87	## Worked example: ranking with ipSAE
88
89	The published [Nipah competition recipe](https://blog.escalante.bio/180-lines-of-code-to-win-the-in-silico-portion-of-the-adaptyv-nipah-binding-competition/)
90	optimizes a design loss on Boltz-2, then ranks candidates with a separate
91	multi-sample loss built from ipTM and ipSAE. The multi-sample loss is a method on the
92	Boltz2 model, not a free function:
93
94	```python
95	from mosaic.models.boltz2 import Boltz2
96
97	boltz2 = Boltz2()
98	ranking_loss = boltz2.build_multisample_loss(
99	loss=1.00 * sp.IPTMLoss()
100	+ 0.5 * sp.TargetBinderIPSAE()
101	+ 0.5 * sp.BinderTargetIPSAE(),
102	features=design_features,
103	num_samples=6,
104	recycling_steps=3,
105	)
106	```
107
108	On the Adaptyv Nipah de novo target, this recipe produced 8 binders out of 9 tested
109	designs at nanomolar affinity, the highest hit-rate of any method on that target in the
110	public results. That is a small, expert-tuned sample on one hard target, not a guarantee
111	across targets, so treat Mosaic as a high-ceiling option that

People who liked this also viewed

6 picks

Type

mosaic

7installs20forks

View on GitHub

How to install mosaic?

adaptyvbio/protein-design-skills/mosaic

$npx -y skills add adaptyvbio/protein-design-skills --skill mosaic

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Mosaic Multi-Objective Design
2
3	[Mosaic](https://github.com/escalante-bio/mosaic) (Escalante Bio) is a JAX framework
4	for "functional, multi-objective protein design using continuous relaxation." It
5	optimizes a soft sequence by gradient descent over a continuous relaxation of
6	sequence space, in the lineage of ColabDesign, RSO, and BindCraft, with one key
7	difference: it composes multiple learned objectives from different models in a single
8	differentiable loss.
9
10	## When Mosaic fits
11
12	Mosaic is a framework for custom objectives, not a one-click method. The README is
13	explicit: it "may require substantial hand-holding (tuning learning rates, etc),
14	often produces proteins that fail simple in-silico tests, [and] should be combined
15	with standard filtering methods." Reach for it when a fixed pipeline cannot express
16	the objective you need. For a turnkey binder run, use `bindcraft` instead.
17
18	## Prerequisites
19
20	\| Requirement \| Minimum \| Recommended \|
21	\|-------------\|---------\|-------------\|
22	\| Python \| 3.11+ \| 3.11 \|
23	\| Framework \| JAX with CUDA or TPU \| JAX CUDA 12 \|
24	\| GPU VRAM \| 24GB \| 48GB+ (depends on predictors used) \|
25
26	JIT compilation makes the first call to any loss slow; later calls are fast.
27
28	## Install
29
30	Mosaic runs locally on a JAX GPU or TPU build. It has no CLI and no Modal
31	integration; you drive it through the marimo notebooks or the Python API.
32
33	```bash
34	git clone https://github.com/escalante-bio/mosaic && cd mosaic
35	uv sync --group jax-cuda # or --group jax-tpu / --group jax-cpu
36	uv add jax[cuda12] # may be needed for a GPU build
37	uv run marimo edit examples/example_notebook.py
38	```
39
40	Ready-made examples include `esmfold_minibinder.py`, `esmfold_vhh.py`,
41	`boltzgen_pipeline.py`, and `batched_protenix.py`.
42
43	## Core idea
44
45	A design objective is built from `LossTerm` objects that you add and scale with plain
46	Python arithmetic, then hand to an optimizer.
47
48	```python
49	import mosaic.losses.structure_prediction as sp
50
51	# Compose a loss from interface, confidence, and inverse-folding terms
52	design_loss = (
53	sp.BinderTargetContact()
54	+ sp.WithinBinderContact()
55	+ 0.05 * sp.TargetBinderPAE()
56	+ 0.05 * sp.BinderTargetPAE()
57	+ 0.025 * sp.IPTMLoss()
58	+ 0.1 * sp.PLDDTLoss()
59	)
60	```
61
62	Loss terms can wrap one model used several ways (for example a structure predictor
63	scoring both the binder-target complex and the binder as a monomer). Composing
64	different architectures also lowers the chance of finding adversarial sequences that
65	fool a single predictor.
66
67	### What you can compose
68
69	\| Category \| Options \|
70	\|----------\|---------\|
71	\| Structure predictors \| AF2, Boltz-1, Boltz-2, Protenix, OpenFold3, ESMFold2 \|
72	\| Generative / design \| BoltzGen, Proteina-Complexa \|
73	\| Inverse folding \| ProteinMPNN, SolubleMPNN, AbMPNN \|
74	\| Language models \| ESM-2, ESM-C, AbLang, trigram \|
75	\| Property heads \| Stability (megascale-trained) \|
76
77	### Optimizers
78
79	\| Optimizer \| Use \|
80	\|-----------\|-----\|
81	\| `simplex_APGM` \| Default; proximal gradient / mirror descent on the probability simplex \|
82	\| `batched_simplex_APGM` \| The same, vmapped over many designs \|
83	\| `gradient_MCMC` \| Discrete moves for fine-tuning a sequence \|
84
85	A reasonable `simplex_APGM` step size is about `0.1 * sqrt(binder_length)`.
86
87	## Worked example: ranking with ipSAE
88
89	The published [Nipah competition recipe](https://blog.escalante.bio/180-lines-of-code-to-win-the-in-silico-portion-of-the-adaptyv-nipah-binding-competition/)
90	optimizes a design loss on Boltz-2, then ranks candidates with a separate
91	multi-sample loss built from ipTM and ipSAE. The multi-sample loss is a method on the
92	Boltz2 model, not a free function:
93
94	```python
95	from mosaic.models.boltz2 import Boltz2
96
97	boltz2 = Boltz2()
98	ranking_loss = boltz2.build_multisample_loss(
99	loss=1.00 * sp.IPTMLoss()
100	+ 0.5 * sp.TargetBinderIPSAE()
101	+ 0.5 * sp.BinderTargetIPSAE(),
102	features=design_features,
103	num_samples=6,
104	recycling_steps=3,
105	)
106	```
107
108	On the Adaptyv Nipah de novo target, this recipe produced 8 binders out of 9 tested
109	designs at nanomolar affinity, the highest hit-rate of any method on that target in the
110	public results. That is a small, expert-tuned sample on one hard target, not a guarantee
111	across targets, so treat Mosaic as a high-ceiling option that

People who liked this also viewed

6 picks

Type