alphadynamics

AlphaDynamics — predict protein torsion ensembles

This skill is for running the locally-installed alphadynamics package (authored by Krzysztof Gwozdz, the user). It predicts an ensemble of (phi, psi) trajectories for a peptide sequence — useful for:

• Quick Ramachandran ensemble analysis
• Comparing sequence variants / mutants
• Estimating alpha/beta/PPII basin populations
• Sanity-checking before launching real MD

Workflow

1. Get sequence from user

If user gave a 1-letter amino-acid sequence (e.g. AAAY, KLVFFAE), use it directly. If unclear, ask once.

Calibrated scope is 4-15 aa. Sequences longer than 20 aa are outside the calibrated scope — predictions still run, but warn the user that the propagator does not exchange information across residues, so aggregate Ramachandran density for long diverse chains tends toward an "average amino-acid" pattern. For chains >20 aa prefer per-residue Ramachandran panels over the aggregate plot. The package emits a soft UserWarning automatically for N>20.

2. Run prediction

Use the CLI directly (it auto-downloads weights from GitHub Releases on first use, into ~/.cache/alphadynamics/weights/):

alphadynamics predict --sequence <SEQ> --n-ensemble <N> --rollout-steps <T> --device cpu -o /tmp/<SEQ>.npz

Sane defaults (use unless user asks otherwise):

• Quick exploration: --n-ensemble 4 --rollout-steps 200 (~10 sec on CPU)
• Standard: --n-ensemble 16 --rollout-steps 2500 (~5-15 min on Jetson CPU,

faster on GPU/x86)

Prefer --device cpu on Jetson Orin (8GB unified RAM is fragile for GPU torch). Prefer --device cuda on dedicated NVIDIA boxes.

3. Analyze output

The output is an .npz file with torsions of shape (ensemble, time, residues, [phi, psi]), all in radians.

Inline Python analysis the user will care about:

import numpy as np
d = np.load('/tmp/<SEQ>.npz', allow_pickle=True)
t = d['torsions']
phi_deg = np.degrees(t[..., 0].flatten())
psi_deg = np.degrees(t[..., 1].flatten())

def basin(plo, phi_, slo, shi):
    return ((phi_deg >= plo) & (phi_deg <= phi_) &
            (psi_deg >= slo) & (psi_deg <= shi)).mean() * 100

print(f"alpha-helix R    : {basin(-130,-30,-90,30):.1f}%")
print(f"beta-sheet       : {basin(-180,-90,70,180):.1f}%")
print(f"PPII extended    : {basin(-90,-30,100,180):.1f}%")
print(f"alpha-helix L    : {basin(30,100,-10,90):.1f}%  (sterically forbidden)")

Report the basin populations to the user with a one-line interpretation (e.g. "Dominantly PPII / extended; some alpha-helix; alpha-L below 2% which means model honours steric exclusion correctly").

4. Optional: plot Ramachandran

If user explicitly asks for a plot AND matplotlib is available, save a 2D histogram PNG. Otherwise skip — terminal output is enough.

import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
plt.hist2d(phi_deg, psi_deg, bins=50, range=[[-180,180],[-180,180]], cmap="viridis")
plt.xlabel("phi (deg)"); plt.ylabel("psi (deg)")
plt.title(f"AlphaDynamics — {seq}")
plt.colorbar(label="count")
plt.savefig("/tmp/<SEQ>_rama.png", dpi=120)

5. Compare two sequences

If user wants to compare (e.g. wild-type vs mutant), run prediction for each, then report basin populations side by side. Highlight which basin shifted most.

Hard limits — be honest with the user

The user IS the author of this model. Don't oversell. Be honest about:

• Density only, not kinetics. Model captures where the peptide spends

time on the Ramachandran torus, not when transitions happen. Don't claim residence times or transition rates.

• Calibrated scope is 4-15 aa. The training corpus mixed 4AA + N=48 +

N=98 mdCATH peptides, but the phase-flow propagator couples oscillators within a residue and does NOT exchange information across residues. At lengths above ~20 aa the per-residue signal collapses toward an "average amino-acid" Ramachandran. Aggregate plots for two diverse 30-aa chains will look indistinguishable. Use per-residue panels above ~20 aa.

• Backbone only. No side-chain rotamers, no Cartesian xyz, no docking.
• Headline benchmark: mean Ramachandran JSD 0.196 on the canonical 4AA

test set (3 held-out tetrapeptides AAAY/AACE/AAEW), vs Microsoft Timewarp 0.468 — 2.39× lower JSD at ~3000× fewer parameters. Beyond 4AA, longer- chain numbers were measured on internal mdCATH holdouts (not a public head-to-head test set) and become uninformative for aggregate density above ~20 aa.

• Initial torsions are sequence-conditioned (AD-Init prior) by default

since v0.3.9, not uniform random. Pass init_model_name=None to fall back to the legacy uniform random seed.

Available models

ad_transfer_v2_clean (default)  — main propagator, 78K params
ad_init_full_1477               — von Mises mixture prior, 45K params

Use the default. Since v0.3.9, AD-Init is also automatically used as the initial-torsion sampler (sequence-conditioned seed instead of uniform random) — no need to load it manually.

Resources

• Source: https://github.com/krisss0mecom/AlphaDynamics
• PyPI: https://pypi.org/project/alphadynamics/
• Paper v2 (per-system, related work): Zenodo DOI 10.5281/zenodo.19877815