alphadynamics

AlphaDynamics

Compact phase-flow neural propagator for protein torsion dynamics.

This repository ships two complementary releases of AlphaDynamics:

Release	Type	What it gives you	Status
v0.3.0 (latest, 2026-05-01)	sequence-only product	pip install alphadynamics → predict torsion ensembles from a sequence string, no MD seed required	Beta product release
v2.0-preprint (2026-04-29)	per-system paper	per-protein surrogate trained from seed MD; full reviewer-hardening audit, Zenodo DOI	Published preprint (paper)

Both releases share the same phase-flow architecture; v0.3.0 focuses on broad usability (one model, any sequence) and v2 focuses on per-protein fidelity (one model per protein, audited against MD).

---

v0.3.0 — sequence-only product (2026-05-01)

2.39× lower JSD than Microsoft Timewarp · 3000× fewer parameters · 64 phase oscillators · pip install alphadynamics

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 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.

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

Quickstart

pip install alphadynamics

That installs the code. Pretrained weights (a few MB) are downloaded automatically on first use into ~/.cache/alphadynamics/weights/.

Interactive mode (easiest, since v0.3.1)

Just type the command alone:

alphadynamics

It prompts you for the sequence, ensemble size, timesteps, and output path (all with sensible defaults), runs the prediction, and prints the Ramachandran basin populations on the spot. Good for first-time users and quick exploration.

Predict from the command line (power users)

alphadynamics predict --sequence AAAY --n-ensemble 16 --rollout-steps 2500 -o aaay.npz

Output aaay.npz has shape (16, 2500, 4, 2) — ensemble × time × residues × [phi, psi] in radians.

Predict from Python

from alphadynamics import predict_torsion_ensemble

traj = predict_torsion_ensemble(
    "AAAY",
    n_ensemble=16,
    rollout_steps=2500,
    seed=42,          # deterministic
)
print(traj.shape)     # (16, 2500, 4, 2)

3D backbone reconstruction (auto-generated since v0.4.1)

Since v0.4.1, alphadynamics predict automatically generates both .npz and .pdb. You can open the PDB directly in PyMOL / VMD / ChimeraX:

alphadynamics predict --sequence KLVFFAE -o klvffae.npz
# Wrote: klvffae.npz  (torsion trajectory)
# Wrote: klvffae.pdb  (3D backbone, automatic)

pymol klvffae.pdb        # animate the trajectory

The PDB contains backbone heavy atoms only (N, Cα, C, O); no side chains, no hydrogens. Uses NeRF (Parsons 2005) with Engh-Huber 1991 bond geometry — fully deterministic, zero ML.

To skip PDB generation: --no-pdb. To customize: --pdb-out path.pdb, --pdb-frames N. Manual rebuild (e.g. for old .npz files): alphadynamics rebuild file.npz -s SEQ -o file.pdb.

Or from 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")

Per-frame diagnostics:

from alphadynamics import trajectory_diagnostics
diag = trajectory_diagnostics(traj[0])
print(f"Rg = {diag['rg_mean']:.2f} ± {diag['rg_std']:.2f} Å")
print(f"end-to-end = {diag['end_to_end_mean']:.2f} Å")

⚠️ Note: torsion errors accumulate along the chain; for long peptides (N > ~50) end-to-end displacement can be substantial even for small per-residue errors. Use as diagnostic visualization, not as high-resolution structure prediction.

Other CLI commands