Introduction¶

TOPO is a unified coarse-grained model for globular and disordered proteins, built on the OpenMM engine — a Python library and command-line toolkit covering globular (folded) proteins, multi-domain proteins with disordered regions, and fully disordered proteins in one force field.

Given only a protein structure (a PDB or CIF file), TOPO automatically builds a one-bead-per-residue (alpha-carbon) structure-based model — bonds, angles, sequence-dependent torsions, screened electrostatics, and a Gō-like native-contact potential — and runs Langevin dynamics. Because the native state is the energy minimum by construction, TOPO is well suited to protein folding and unfolding, thermal/mechanical stability, and multidomain motions.

If you are new here, read The TOPO model: theory and force field for what the model is, then work through the TOPO Tutorials.

Note

Disorder is supported. Folded proteins are the core case, but residues declared in a disordered: section drop their native contacts and switch to a transferable, sequence-dependent potential — so TOPO also covers multi-domain proteins with IDRs (ordered and disordered residues in one chain) and, with every residue declared, fully disordered proteins (IDPs). See Disordered / IDR regions and Tutorial A.7 — A protein with intrinsically disordered regions (IDRs).

The model in one paragraph¶

TOPO keeps only the alpha-carbon of each residue and builds a potential with bonded terms (rigid or harmonic Cα–Cα bonds, a bimodal Gaussian backbone angle, and four-periodicity sequence-dependent torsions) and non-bonded terms (Debye–Hückel screened electrostatics between charged residues, and a 12-10-6 structure-based contact potential). Native contacts — pairs in contact in your input structure (via backbone hydrogen bonds detected by STRIDE, and backbone–sidechain / sidechain–sidechain heavy-atom proximity) — get attractive wells at their native Cα–Cα distances; all other pairs get a soft excluded-volume repulsion. The full functional forms, constants, and parameter sources are in The TOPO model: theory and force field.

Package layout¶

The codebase is organized into focused subpackages:

Module	Responsibility
`topo.core`	The model: `system` (builds forces), `models` (the `buildCoarseGrainModel` entry point), `geometry` (distance helpers).
`topo.parameters`	Force-field constants: per-residue mass/radii/charge, bond/angle constants, and the sequence-dependent dihedral table.
`topo.mdrun`	The simulation runner (`topo-mdrun`): build → set up → run the temperature protocol → finalize.
`topo.optimize`	The contact-nscale optimizer (`topo-optimize`).
`topo.analysis`	Native-contact (Q) analysis.
`topo.reporter`	The fixed-width state log writer and its parser.
`topo.utils`	Config parsing, the non-bonded contact builder, multi-copy replication, and run provenance.

Installation¶

TOPO depends on OpenMM (and ParmEd, MDAnalysis, mdtraj, NumPy, pandas, PyYAML), which are best installed from conda-forge, plus the external STRIDE (and optional PULCHRA) binaries. In brief:

mamba create -n topo -c conda-forge python">=3.9" openmm parmed \
    mdanalysis mdtraj numpy pandas pyyaml
mamba activate topo
pip install -e .

See How to install for the full step-by-step guide (both the editable/regular pip install and the no-install PYTHONPATH alternative), and External dependencies for STRIDE and the optional backmapping tools (PULCHRA, cg2all).

Running a simulation¶

Every run is driven by a plain-text control file (md.ini) and launched with any of the following equivalent forms:

topo-mdrun -f md.ini                 # installed console command
python -m topo.mdrun -f md.ini       # module form
python run_simulation.py -f md.ini   # the thin shim shipped in each tutorial

See Simulation control options for every md.ini option, Output files and the run log for the files a run produces, and TOPO Tutorials for hands-on walkthroughs.