Introduction

TOPO (TOPOlogy-based coarse-grained model for folded prOteins) is a Python library and command-line toolkit for coarse-grained molecular dynamics of globular (folded) proteins, built on the OpenMM engine.

Given only a folded-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

TOPO simulates folded proteins. For intrinsically disordered proteins, the model that TOPO’s code base was originally adapted from (COSMO) is the more appropriate tool.

See also

For a feature-by-feature map of what TOPO does and which tutorial teaches each, see What TOPO does.

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. From the repository root:

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

This installs TOPO as an editable package (your source edits take effect immediately) and registers the topo-mdrun and topo-optimize console commands. STRIDE must be on your PATH for the contact potential (or supply a precomputed STRIDE file via stride_output_file). See the project README for a no-install (PYTHONPATH) alternative.

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.