{"id":51310414,"url":"https://github.com/elkins-lab/resonance-flow","last_synced_at":"2026-07-01T03:03:34.513Z","repository":{"id":360560335,"uuid":"1250714856","full_name":"elkins-lab/resonance-flow","owner":"elkins-lab","description":"JAX-native differentiable protein folding framework integrating experimental NMR constraints (RDCs) and biophysical \"self-correction.\"  Several Jupyter Notebooks visualize the concepts.","archived":false,"fork":false,"pushed_at":"2026-06-12T20:25:14.000Z","size":719,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T21:32:41.862Z","etag":null,"topics":["bioinformatics","biophysics","computational-biophysics","differentiable-programming","jax","machine-learning","nmr-spectroscopy","protein-folding","structural-biology"],"latest_commit_sha":null,"homepage":"https://elkins.github.io/resonance-flow/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elkins-lab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T22:45:49.000Z","updated_at":"2026-06-12T20:24:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/elkins-lab/resonance-flow","commit_stats":null,"previous_names":["elkins/resonance-flow","elkins-lab/resonance-flow"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/elkins-lab/resonance-flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elkins-lab%2Fresonance-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elkins-lab%2Fresonance-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elkins-lab%2Fresonance-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elkins-lab%2Fresonance-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elkins-lab","download_url":"https://codeload.github.com/elkins-lab/resonance-flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elkins-lab%2Fresonance-flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34990855,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","biophysics","computational-biophysics","differentiable-programming","jax","machine-learning","nmr-spectroscopy","protein-folding","structural-biology"],"created_at":"2026-07-01T03:03:33.812Z","updated_at":"2026-07-01T03:03:34.507Z","avatar_url":"https://github.com/elkins-lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧬 Resonance-Flow: Differentiable Protein Structure Prediction with NMR Self-Correction\n\n[![Tests](https://github.com/elkins-lab/resonance-flow/actions/workflows/test.yml/badge.svg)](https://github.com/elkins-lab/resonance-flow/actions/workflows/test.yml)\n[![Docs](https://github.com/elkins-lab/resonance-flow/actions/workflows/docs.yml/badge.svg)](https://github.com/elkins-lab/resonance-flow/actions/workflows/docs.yml)\n[![codecov](https://codecov.io/gh/elkins-lab/resonance-flow/branch/main/graph/badge.svg)](https://codecov.io/gh/elkins-lab/resonance-flow)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Documentation](https://img.shields.io/badge/docs-mkdocs--material-blue.svg)](https://elkins-lab.github.io/resonance-flow/)\n[![PyPI version](https://img.shields.io/pypi/v/resonance-flow)](https://pypi.org/project/resonance-flow/)\n[![Python versions](https://img.shields.io/pypi/pyversions/resonance-flow)](https://pypi.org/project/resonance-flow/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)\n[![JAX](https://img.shields.io/badge/framework-JAX%20%2B%20Flax-9cf.svg)](https://jax.readthedocs.io/)\n\n**Resonance-Flow** is a JAX-native protein structure prediction framework that integrates differentiable biophysics with experimental NMR constraints. It allows models to \"self-correct\" by propagating gradients from physical violations (atomic clashes, bad geometry) and NMR observables (RDCs, NOE distances) back into the neural network architecture — end-to-end, with no manual refinement step.\n\n---\n\n## 🚀 Key Features\n\n- **JAX-Native Gradient Flow** — End-to-end differentiability from experimental constraints to model weights via `jax.grad`.\n- **Saupe Tensor RDC Loss** — Differentiable least-squares fitting of the alignment tensor at every forward pass (Bax \u0026 Tjandra 1997; Cornilescu et al. 1998).\n- **NOE Distance Restraints** — Flat-bottomed harmonic penalty on upper-bound violations, the primary 3D information source in protein NMR (Wüthrich 1986; Güntert et al. 1997).\n- **Biophysically Correct Geometry** — Bond length loss calibrated to the canonical Cα–Cα distance of 3.80 Å (Engh \u0026 Huber 1991).\n- **Differentiable Steric Clash** — Harmonic atom-overlap penalty with optional AMBER/CHARMM-style 1-2/1-3 bonded exclusions, powered by `jax-md`.\n- **RDC Quality Metric** — Built-in Q-factor and Q_free cross-validation (Cornilescu et al. 1998; Clore \u0026 Garrett 1999) for structural validation without additional tooling.\n- **Backbone Conformational Checks** — Pseudo-torsion angle calculation (Oldfield \u0026 Hubbard 1994) to verify secondary structure plausibility in Cα-only models.\n- **PBC Support** — Periodic boundary conditions for simulation-box contexts.\n- **Transformer-to-Coords** — A pre-LN Transformer architecture that maps amino acid sequences directly to physical 3D Cα coordinates.\n\n---\n\n## 🧠 The Concept: \"Self-Correction\"\n\nTraditional folding models are trained on static PDB snapshots.  Resonance-Flow instead teaches a model to *listen* to physical laws and NMR data during training itself:\n\n```\n  Sequence  →  [Transformer]  →  Cα Coordinates\n                                       │\n                  ┌────────────────────┼──────────────────────┐\n                  ▼                    ▼                       ▼\n           Steric Clash          Bond Length              RDC / NOE\n             Penalty               Loss                  Mismatch\n                  └────────────────────┼──────────────────────┘\n                                       │  ∇θ L_total\n                                       ▼\n                              [Optimizer Step]\n```\n\nGradients from every constraint flow back simultaneously into the model weights — the model learns not just from data, but from physics.\n\n---\n\n## 🛠️ Installation\n\n```bash\npip install resonance-flow\n```\n\nFor development (includes linting, type-checking, testing, and docs):\n\n```bash\ngit clone https://github.com/elkins-lab/resonance-flow.git\ncd resonance-flow\npip install -e \".[dev]\"\n```\n\n**Requirements:** Python 3.10+, JAX ≥ 0.4, Flax, Optax, jax-md, NumPy.\n\n---\n\n## 🧪 Quick Start\n\n### Run the self-correction demo\n\n```python\nfrom resonance_flow.train import main\n\nstate = main(num_steps=100)\n# Step   0 | Total Loss: 12.3421 | Steric: 0.0012 | Bond: 1.2034 | RDC: 0.0087\n# Step  10 | Total Loss:  4.1823 | ...\n# Step 100 | Total Loss:  0.0031 | ...\n```\n\n### Use individual loss functions\n\n```python\nimport jax.numpy as jnp\nfrom resonance_flow import (\n    get_steric_clash_loss,\n    get_bond_length_loss,\n    rdc_loss,\n    rdc_q_factor,\n    noe_upper_bound_loss,\n    estimate_nh_proxy_vectors,\n)\n\n# ── Steric clash (AMBER-style 1-2 bonded exclusion) ──────────────────────────\nclash_fn   = get_steric_clash_loss(exclude_bonded_range=1)\npositions  = jnp.array([[0.0, 0.0, 0.0], [4.0, 0.0, 0.0]])\natom_radii = jnp.array([1.5, 1.5])\nclash_fn(positions, atom_radii)          # → 0.0  (no overlap)\n\n# ── Bond length (Cα–Cα virtual bond, Engh \u0026 Huber 1991) ─────────────────────\nbond_fn  = get_bond_length_loss()        # default target = 3.8 Å\nca_chain = jnp.array([[0.0,0.0,0.0],[3.8,0.0,0.0],[7.6,0.0,0.0]])\nbond_fn(ca_chain)                        # → ~0.0\n\n# ── RDC loss (Saupe tensor fitting) ─────────────────────────────────────────\nnh_vecs      = jnp.array([[1.,0.,0.],[0.,1.,0.],[0.,0.,1.],\n                           [0.7,0.7,0.],[0.7,0.,0.7],[0.,0.7,0.7]])\nmeasured_rdc = jnp.array([10., -5., 2., 0., 4., 8.])\nrdc_loss(nh_vecs, measured_rdc)          # → scalar MSE\n\n# ── RDC Q-factor (structure quality; Q ≤ 0.20 = high quality) ───────────────\nrdc_q_factor(nh_vecs, measured_rdc)      # → 0 – 1 (lower is better)\ntrain_mask = jnp.array([True, True, True, False, False, False])\nrdc_q_free(nh_vecs, measured_rdc, train_mask)  # → Q-factor on held-out data\n\n# ── N-H proxy vectors from Cα coordinates (Cα-only models) ──────────────────\nca_coords = jax.random.normal(jax.random.PRNGKey(0), (10, 3))\nnh_proxy  = estimate_nh_proxy_vectors(ca_coords)   # → (8, 3) unit vectors\n\n# ── NOE upper-bound distance restraints (Wüthrich 1986) ─────────────────────\nnoe_pairs    = jnp.array([[0, 2], [1, 3]])\nupper_bounds = jnp.array([5.0, 4.5])\nnoe_upper_bound_loss(positions, noe_pairs[:1], upper_bounds[:1])  # → 0.0\n```\n\n---\n\n## 🎓 Interactive Tutorial Catalog\n\nExperience **Resonance-Flow** directly in your browser via Google Colab. These interactive Jupyter Notebook tutorials cover everything from basic biophysics to advanced structural self-correction.\n\n| Tutorial | Difficulty | Time | Action |\n| :--- | :--- | :--- | :--- |\n| **Self-Correction Demo** | ⭐ Beginner | 15 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins-lab/resonance-flow/blob/main/examples/interactive_tutorials/self_correction_demo.ipynb) |\n| **Biophysical Constraints** | ⭐ Beginner | 15 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins-lab/resonance-flow/blob/main/examples/interactive_tutorials/biophysical_constraints.ipynb) |\n| **Differentiable NMR** | ⭕ Intermediate | 25 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins-lab/resonance-flow/blob/main/examples/interactive_tutorials/differentiable_nmr.ipynb) |\n| **Transformer-to-Coords** | 🏔️ Advanced | 30 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins-lab/resonance-flow/blob/main/examples/interactive_tutorials/transformer_to_coords.ipynb) |\n\n---\n\n## 🔬 Scientific Basis\n\nAll loss functions and validation metrics are grounded in published, peer-reviewed NMR methodology:\n\n| Loss / Metric | Scientific Basis |\n|---|---|\n| RDC loss — Saupe tensor | Bax \u0026 Tjandra, *J. Biomol. NMR* 1997; Cornilescu et al., *JACS* 1998 |\n| RDC Q-factor | Cornilescu et al., *JACS* 1998; Clore \u0026 Garrett, *JACS* 1999 |\n| NOE distance restraints | Wüthrich, *NMR of Proteins and Nucleic Acids* 1986; Güntert et al., *J. Mol. Biol.* 1997 |\n| Cα–Cα bond distance (3.8 Å) | Engh \u0026 Huber, *Acta Crystallogr. A* 1991 |\n| N-H proxy vectors | Zweckstetter \u0026 Bax, *JACS* 2000 |\n| Bonded exclusion (1-2/1-3) | Cornell et al. (AMBER), *JACS* 1995; MacKerell et al. (CHARMM), *J. Phys. Chem. B* 1998 |\n| d_max = 21 700 Hz | Ottiger \u0026 Bax, *JACS* 1998 |\n\n---\n\n## 🧬 Architecture\n\n```\nTransformerCoordinatePredictor\n├── Embedding         (vocab_size=21, d_model=128)\n├── Positional Embed  (learned, max_len=512)\n├── N × Pre-LN Block\n│   ├── LayerNorm → MultiHeadDotProductAttention → Residual\n│   └── LayerNorm → FFN (4× expand, GELU) → Residual\n└── LayerNorm → Linear(3)   # → (batch, seq_len, 3) Cα coordinates\n```\n\nThe pre-LN (LayerNorm before attention) layout avoids gradient\nexplosion and follows the convention recommended by Xiong et al. 2020.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please open an issue or pull request. The project follows:\n\n- **Formatting + Linting:** `ruff` / `ruff format`\n- **Type checking:** `mypy`\n- **Testing:** `pytest` with coverage\n\n```bash\n# Run the full quality pipeline before submitting a PR\nruff check resonance_flow tests\nruff format resonance_flow tests\nmypy resonance_flow tests\npytest --cov=resonance_flow tests\n```\n\n---\n\n## 📚 Documentation\n\nFull theory, API reference, and examples at **[elkins-lab.github.io/resonance-flow](https://elkins-lab.github.io/resonance-flow/)**.\n\n---\n\n## ⚖️ License\n\nMIT © George Elkins\n\n---\n\n## 🔗 Related Projects\n\nResonance-Flow is the most complete end-to-end model in this ecosystem, depending on:\n\n- [diff-biophys](https://github.com/elkins-lab/diff-biophys) — Differentiable RDC, NOE, bond-length, and clash kernels\n- [synth-nmr](https://github.com/elkins-lab/synth-nmr) — NMR parameter libraries (chemical shifts, Karplus, RDC)\n- [synth-pdb](https://github.com/elkins-lab/synth-pdb) — Protein structure data generation\n- [torsion-tuner](https://github.com/elkins-lab/torsion-tuner) — Single-structure refinement using similar torsion-space kinematics\n- [diff-ensemble](https://github.com/elkins-lab/diff-ensemble) — Ensemble counterpart for IDPs\n\n---\n\n## 📖 Citation\n\n```bibtex\n@software{resonance_flow,\n  author  = {Elkins, George},\n  title   = {Resonance-Flow: Differentiable protein structure prediction with NMR self-correction},\n  year    = {2026},\n  url     = {https://github.com/elkins-lab/resonance-flow},\n  version = {0.1.3}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felkins-lab%2Fresonance-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felkins-lab%2Fresonance-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felkins-lab%2Fresonance-flow/lists"}