Skip to content

Repository files navigation

🔊 SonoForge

A closed-loop DBTL optimization backbone for de novo design of the molecular biosensors & actuators that couple neurons to ultrasound

Author: Dr. Sanjay Anbu

Flagship target: gas-vesicle acoustic reporter genes (ARGs) — the genetically-encoded ultrasound contrast agents behind non-invasive, molecular brain–computer interfaces.

CI Python 3.10+ License: MIT Code style: ruff

Whitepaper · Roadmap · Architecture · Quickstart


Why this exists

Non-invasive, high-bandwidth brain–computer interfaces are moving away from electrodes and toward molecules — genetically-encoded proteins that let neurons talk to ultrasound. Two protein classes make this possible:

  • Biosensors (READ): gas vesicles — air-filled protein nanostructures (acoustic reporter genes) that scatter ultrasound and make gene expression / neural activity visible through intact tissue.
  • Actuators (WRITE): sonogenetic ion channels — mechanosensitive membrane proteins gated by focused ultrasound for cell-type-specific neuromodulation.

Engineering these molecules is a textbook Design–Build–Test–Learn (DBTL) problem over sparse, noisy, expensive wet-lab data. SonoForge is an open, reference implementation of the closed-loop optimization backbone such a program needs: it designs candidate proteins, models their physics, scores them against multi-objective goals under hard safety constraints, and learns the next, better library — round after round.

In one sentence: an automatic protein designer that invents ultrasound-coupling biomolecules, simulates and scores them, and iteratively improves them under a tolerability constraint — a working miniature of a closed-loop molecular-discovery platform for molecular neurotech.

What makes it different from a generic de novo pipeline

Generic de novo repo SonoForge
Target arbitrary binder on-mission acoustic reporter genes (+ sonogenetic-channel extension)
Sequence model one-hot / CNN Mamba/S4 protein language model (state-space), transfer-learned on sparse ARG data
Geometry Cα only SE(3)-equivariant frame flow-matching (PyTorch + JAX reference)
Scoring learned proxy only learned proxy + first-principles OpenMM molecular dynamics (collapse-pressure & mechanical observables)
Optimizer single-objective constrained multi-objective qNEHVI + GFlowNet/RL proposal + DPO preference optimization
Safety immunogenicity / de-immunization as a hard constraint (MHC-II epitope load)
Uncertainty point estimates ensembles + calibration reporting for expensive-oracle active learning
Delivery notebook typed API + Gradio app + MkDocs docs site (model democratization)

Every row maps to a line item in Merge Labs' ML Research Scientist job descriptions (De Novo Design · Bayesian Optimization · Computational Biophysics). See the whitepaper for the explicit mapping.

Architecture

flowchart TD
    A([Target: gas-vesicle shell proteins GvpA / GvpC]) --> LOOP

    subgraph LOOP [DBTL loop — repeats each cycle]
        direction TB
        D["1 · DESIGN<br/>SE(3) frame flow-matching invents backbones<br/>Mamba protein-LM assigns sequences"]
        B["2 · BUILD<br/>featurize · fold (ESMFold) · self-consistency"]
        T["3 · TEST — in-silico oracle<br/>• Contrast (acoustic scattering proxy)<br/>• Collapse pressure (OpenMM MD, physics prior)<br/>• Expressibility & solubility<br/>• Immunogenicity (MHC-II epitope load) — CONSTRAINT"]
        L["4 · LEARN<br/>Constrained multi-objective qNEHVI + GFlowNet/RL<br/>DPO on pairwise acoustic screens · UQ / calibration"]
        D --> B --> T --> L --> D
    end

    LOOP --> R([Pareto-optimal, de-immunized designs<br/>+ dashboard, report, structure gallery])
Loading

Quickstart

macOS / Linux

git clone https://github.com/sanjaydoc/sonoforge.git && cd sonoforge
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"                                   # core (fast, no GPU)
python scripts/download_data.py                           # fetch GvpA/GvpC seed data
python scripts/run_cycle.py --optimizer nsga2 --n-cycles 6   # run one DBTL loop

Windows (cmd)

git clone https://github.com/sanjaydoc/sonoforge.git && cd sonoforge
python -m venv .venv
.venv\Scripts\activate.bat
pip install -e ".[dev]"
python scripts\download_data.py
python scripts\run_cycle.py --optimizer nsga2 --n-cycles 6

(Windows PowerShell: activate with .\.venv\Scripts\Activate.ps1 instead.)

Explore the results

# macOS/Linux
pip install -e ".[serve]" && streamlit run src/sonoforge/serve/dashboard.py
# Windows
pip install -e ".[serve]" && streamlit run src\sonoforge\serve\dashboard.py

Then open http://localhost:8501. Or serve to non-experts: python -m sonoforge.serve.api.

Real ML models (Mamba PLM, qNEHVI, GFlowNet — bigger install):

pip install -e ".[ml]"
python scripts/run_cycle.py --optimizer qnehvi --n-cycles 6      # Bayesian optimization (benchmark winner)

📖 Full step-by-step guide (all OSes, dashboard, ML, troubleshooting): RUN.md · every command annotated: How-To-Run-Commands.txt

The stack degrades gracefully: every heavy component (Mamba PLM, flow model, OpenMM, ESMFold) has a lightweight CPU fallback so the loop and tests run end-to-end on a laptop before any weights are downloaded.

Project layout

sonoforge/
├── docs/                 # MkDocs-Material site (GitHub Pages) — WHITEPAPER, PLAN, model/dataset cards
├── src/sonoforge/
│   ├── data/             # GvpA/GvpC + ARG sequences, structures, featurization, Candidate schema
│   ├── plm/              # Mamba/S4 protein language model: sequence design + property heads
│   ├── generative/       # SE(3) frame flow-matching backbone generator (PyTorch + JAX ref)
│   ├── physics/          # OpenMM MD → collapse-pressure / mechanical observables (first-principles priors)
│   ├── oracle/           # contrast + collapse-pressure + expressibility + immunogenicity oracles
│   ├── optimize/         # constrained multi-objective qNEHVI · GFlowNet/RL · DPO · UQ
│   ├── loop/             # DBTL orchestration
│   ├── serve/            # typed API + Gradio app + Streamlit dashboard (democratization)
│   └── utils/            # config, logging, seeding
├── configs/              # Hydra configuration
├── scripts/ · tests/ · benchmarks/ · Dockerfile · .github/workflows/

Status & roadmap

Phase Scope Status
0 Scaffold, docs & scientific plan
1 Data layer & Candidate schema (GvpA/GvpC, ARG panels)
2 Mamba/S4 protein language model (transfer learning)
3 SE(3) flow-matching generator (PyTorch + JAX)
4 Oracle stack — physics (GNM/OpenMM) + immunogenicity constraint
5 Closed loop — constrained qNEHVI + NSGA-II + GFlowNet + DPO + UQ
6 Serve, benchmark & report (API + Gradio + dashboard)

Live sub-task tracker: PLANNING.md · Detailed roadmap + acceptance tests: docs/PLAN.md · Technical design: docs/WHITEPAPER.md.

Results

Head-to-head on the closed loop — mean final feasible-front hypervolume across 5 seeds (identical budget: 6 cycles, library 16), immunogenicity as a hard constraint (higher is better):

optimizer final HV (mean ± std)
qNEHVI (BoTorch) 0.439 ± 0.016
NSGA-II 0.389 ± 0.019
random (baseline) 0.384 ± 0.014

Constrained Bayesian optimization wins decisively — its margin over both baselines exceeds the across-seed noise. Reproduce with python benchmarks/benchmark_optimizers.py. Full discussion in docs/RESULTS.md.

Scientific honesty

This is a methods and engineering reference platform. Oracles are in-silico proxies (clearly labelled as such), not validated wet-lab assays — the point is a rigorous, reproducible closed-loop backbone into which real experimental data streams plug directly. Wherever a signal is simulated, the code and docs say so. See docs/WHITEPAPER.md#limitations.

License & data notes

  • Code: MIT (see LICENSE).
  • Protein structures: freely available from RCSB PDB.
  • ESM-2 / ESMFold and any pretrained weights: released by their authors under their own terms — verify before commercial use.
  • Gas-vesicle and acoustic-reporter biology draws on published work from the Shapiro Lab and others; all references are cited in the whitepaper.

About

SonoForge is an open, closed-loop DBTL platform for de novo design of biomolecules that let neurons talk to ultrasound — the basis of non-invasive molecular brain–computer interfaces. It designs gas-vesicle acoustic reporter genes via SE(3) flow-matching, molecular dynamics, and constrained Bayesian optimization, RL, and preference learning.

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages