README.md

---
license: apache-2.0
language: en
library_name: pytorch
tags:
  - protein-dynamics
  - molecular-dynamics
  - torsion-angles
  - phase-oscillators
  - neural-ode
  - ramachandran
  - ml-for-biology
  - reservoir-computing
pipeline_tag: feature-extraction
---

# AlphaDynamics

**Compact sequence-only neural propagator for protein torsion dynamics.**

> 2.39× lower JSD than Microsoft Timewarp · 3000× fewer parameters · 64 phase oscillators

[![PyPI](https://img.shields.io/pypi/v/alphadynamics.svg)](https://pypi.org/project/alphadynamics/)
[![GitHub](https://img.shields.io/badge/github-krisss0mecom%2FAlphaDynamics-blue?logo=github)](https://github.com/krisss0mecom/AlphaDynamics)
[![Try in browser](https://img.shields.io/badge/🤗-Try_in_browser-yellow)](https://huggingface.co/spaces/krissss0/alphadynamics)
[![DOI](https://zenodo.org/badge/1211339504.svg)](https://doi.org/10.5281/zenodo.19788564)

A tiny (~123K parameter) neural propagator that, given only a protein sequence,
predicts an ensemble of torsion-angle (φ, ψ) trajectories matching the marginal
Ramachandran density of long-timescale molecular dynamics simulations.

On the canonical 4AA benchmark from `microsoft/timewarp` it produces densities
that are **2.39× closer to ground-truth MD** than Microsoft Research's Timewarp
model (396M parameters), at roughly **3000× fewer parameters**.

## Quickstart

### Try in your browser (no install)

👉 [**huggingface.co/spaces/krissss0/alphadynamics**](https://huggingface.co/spaces/krissss0/alphadynamics)

Type a peptide sequence, get an interactive Ramachandran plot in 30 seconds.

### Use locally

The simplest path — just type `alphadynamics` and answer the prompts:

```bash
pip install alphadynamics
alphadynamics
# Sequence (1-letter AA, e.g. AAAY): KLVFFAE
# How many independent trajectories? [16]: <Enter>
# How many timesteps per trajectory? [2500]: <Enter>
# Device (cuda/cpu/auto) [auto]: <Enter>
# Output file [...]: <Enter>
# Save Ramachandran plot? [b=both, p=PNG, h=HTML, n=no] [b]: <Enter>
```

Or as a one-liner for power users:

```bash
alphadynamics predict --sequence AAAY --n-ensemble 16 --rollout-steps 2500 --plot --plot-html -o traj.npz
```

### 3D backbone reconstruction (NEW in v0.4.0)

Convert torsion `.npz` to multi-model PDB you can open in PyMOL / VMD / ChimeraX:

```bash
alphadynamics predict --sequence KLVFFAE --output klvffae.npz
alphadynamics rebuild klvffae.npz -s KLVFFAE -o klvffae.pdb --diagnostics
pymol klvffae.pdb        # animate the trajectory
```

From Python:

```python
from alphadynamics import predict_torsion_ensemble, trajectory_to_pdb
traj = predict_torsion_ensemble("KLVFFAE", n_ensemble=4, rollout_steps=200)
trajectory_to_pdb(traj[0], "KLVFFAE", "klvffae.pdb")
```

Backbone heavy atoms only (N, Cα, C, O); deterministic NeRF reconstruction
(Parsons 2005) with Engh-Huber 1991 standard bond geometry. No ML, no training.

> ⚠️ Torsion errors accumulate along the chain; for long peptides
> (N > ~50) end-to-end displacement may be substantial. Use as
> diagnostic visualization, not high-resolution structure prediction.

### Or from Python (raw API):

```python
from alphadynamics import predict_torsion_ensemble

traj = predict_torsion_ensemble(
    "KLVFFAE",          # amyloid-β fragment
    n_ensemble=16,
    rollout_steps=2500,
    seed=42,
)
print(traj.shape)        # (16, 2500, 7, 2)  — ensemble × time × residues × [φ,ψ]
```

## Headline result

Canonical Ramachandran Jensen-Shannon divergence (val-only ground truth, 36
bins, no smoothing) on the canonical 4AA test set, averaged over three peptides
AAAY, AACE, AAEW:

| Model                  | Params | Mean JSD | 4AA wins | Notes                              |
| ---------------------- | -----: | -------: | :------: | ---------------------------------- |
| Microsoft Timewarp     |  396 M |    0.468 |   0 / 3  | published baseline                 |
| **AlphaDynamics**      |  123 K |  **0.196** | **3 / 3** | **2.39× lower**, **3000× smaller** |

Cross-validated against Top8000 PDB statistics (Richardson Lab, Duke). Forbidden
α-L region: 0.7–1.0% — at the MolProbity error level (0.5%) for real
high-resolution PDB structures, meaning the model honors atomic steric exclusion.

## How it works

A residue's torsion state `(φ, ψ)` is treated as a phase pair on a torus.
Conditioned on the amino-acid identity, position, and current angles, an MLP
emits per-residue oscillator parameters: an intrinsic frequency, a coupling
matrix, and an anchor phase. A phase-flow ODE then integrates the joint state
of 64 coupled oscillators with classical RK4 over a fixed horizon `t_max=4.0`
(8 substeps). The integrated phase state is decoded into a mixture of
axis-independent von Mises distributions per residue, from which the next
torsion frame is sampled. Rolled out autoregressively, this defines a
transferable sequence-only propagator over the torsion torus.

The architecture is the protein-dynamics application of a multi-year line of
work in phase-oscillator computation: REZON hardware (80 physical PCB
oscillators), `phase-entanglement-rc` (formal phase computing), and
`phase-cnot-neuroscience` (theta-gamma coupling validated on rat and human
LFP recordings).

## Files

- `ad_transfer_v2_clean_best.pt` (310 KB) — the main propagator, ~78K params
- `ad_init_full_1477_best.pt` (181 KB) — von Mises mixture prior, ~45K params

## Honest caveats

- **Density only, not kinetics.** Captures *where* the peptide spends time on
  the Ramachandran torus, not *when* transitions happen.
- **Backbone only.** No side-chain rotamers, no Cartesian xyz, no docking.
- **Trained on 4–98 residues.** Reliability degrades outside this range.
- **Monomer only.** No multimer / aggregation modeling.

## Best for

- Quick conformational triage before launching expensive MD
- Comparing peptide sequence variants / mutants
- Estimating α/β/PPII basin populations
- Sanity-checking before large compute commitment
- AI-for-bio baselines and benchmarks
- Biochemistry / biophysics teaching with interactive Ramachandran plots

## Citation

```bibtex
@software{gwozdz2026alphadynamics,
  author  = {Gwozdz, Krzysztof},
  title   = {AlphaDynamics: Compact sequence-only neural propagator
             for protein torsion dynamics},
  year    = {2026},
  url     = {https://github.com/krisss0mecom/AlphaDynamics},
  license = {Apache-2.0},
  doi     = {10.5281/zenodo.19788564}
}
```

## Author

**Krzysztof Gwozdz** — independent researcher, Poland 🇵🇱
<krisss0gwo@gmail.com>

This is a free contribution to the protein-dynamics community.

## License

Apache 2.0. Free for any use including commercial.

## Links

- 📦 [PyPI](https://pypi.org/project/alphadynamics/) — `pip install alphadynamics`
- 🐙 [GitHub](https://github.com/krisss0mecom/AlphaDynamics) — source code, issues, releases
- 🤗 [Spaces demo](https://huggingface.co/spaces/krissss0/alphadynamics) — try in browser
- 📚 [Zenodo paper v2](https://doi.org/10.5281/zenodo.19877815) — per-system version (predecessor)