Molecular Dynamics Pre- & Post-Processing

A Python toolkit for MD simulation workflows — trajectory analysis, publication-ready plots, system preparation, and GROMACS automation.

• Highlights
• Installation
• Quick Start
• Package Structure
• CLI
• Design Philosophy
• Dependencies
• Documentation
• Contributing
• License

• Trajectory analysis — RMSD, RMSF, DCCM, SASA, radius of gyration, hydrogen bonds, native contacts, pairwise distances, DSSP secondary structure
• Dimensionality reduction — PCA, TICA, backbone torsion featurization, free energy surfaces
• Conformational clustering — RMSD distance matrix, GROMOS algorithm
• Publication-ready plots — one-liner matplotlib figures with proper axis labels and units
• System preparation — PDB fixing (OpenMM), ligand parameterization (RDKit), trajectory merge/slice/subsample
• GROMACS automation — bundled MDP templates, analysis wrappers, runtime monitoring scripts, and a CLI to manage them all
• Typed & tested — full type annotations, frozen dataclass results, Google docstrings

git clone https://github.com/FridrichMethod/mdpp.git
cd mdpp
pip install -e ".[dev]"

conda create -n mdpp python=3.12 -y && conda activate mdpp
conda install -c conda-forge pdbfixer -y
pip install -e ".[openmm,dev]"

from mdpp.core import load_trajectory
from mdpp.analysis import compute_rmsd
from mdpp.plots import plot_rmsd

traj = load_trajectory("md.xtc", topology_path="topol.gro")
result = compute_rmsd(traj, atom_selection="backbone")
ax = plot_rmsd(result)

import matplotlib.pyplot as plt
from mdpp.analysis import compute_rmsd, compute_rmsf, compute_dccm
from mdpp.plots import plot_rmsd, plot_rmsf, plot_dccm, plot_fes

fig, axes = plt.subplots(2, 2, figsize=(12, 10))
plot_rmsd(rmsd_result, ax=axes[0, 0])
plot_rmsf(rmsf_result, ax=axes[0, 1])
plot_dccm(dccm_result, ax=axes[1, 0])
plot_fes(fes_result, ax=axes[1, 1])
fig.tight_layout()

from mdpp.core import read_xvg, read_edr

df = read_xvg("rmsd.xvg")         # XVG → pandas DataFrame
df = read_edr("ener.edr")          # binary EDR → pandas DataFrame

from mdpp.prep import fix_pdb, strip_solvent

fix_pdb("raw.pdb", "fixed.pdb", pH=7.4)    # add missing atoms & hydrogens
dry = strip_solvent(traj, keep_ions=True)    # remove water

mdpp
├── core         Trajectory I/O · XVG/EDR parsers · atom selection · alignment
├── analysis     RMSD · RMSF · DCCM · SASA · Rg · H-bonds · contacts · DSSP · PCA · TICA · FES · clustering
├── plots        Time series · heatmaps · FES contours · scatter · Ramachandran · contact maps
├── prep         PDB fixing · ligand topology · trajectory merge/slice/subsample
├── data         GROMACS MDP parameter templates
└── scripts      Analysis wrappers · runtime tools · compilation helpers

mdpp list                               # list bundled utility scripts
mdpp list gromacs/analysis              # filter by category
mdpp show gromacs/runtime/restart.sh    # view a script
mdpp copy gromacs/analysis ./sim/       # copy scripts to working dir
mdpp mdps ./sim/                        # copy MDP templates

Every analysis function follows the same pattern:

result = compute_something(traj, *, keyword_args...)   # → frozen dataclass
ax = plot_something(result, *, ax=None)                 # → matplotlib Axes

• Input: md.Trajectory (from MDTraj) or a feature matrix
• Output: frozen @dataclass with unit-conversion properties (.time_ns, .rmsd_angstrom, etc.)
• Plotting: pass the result dataclass directly — labels and units are set automatically

Built on the scientific Python ecosystem:

Full documentation at mdpp.readthedocs.io.

Build locally:

pip install -e ".[docs]"
mkdocs serve                  # http://127.0.0.1:8000

# Lint & format
ruff check src/ tests/ --fix
ruff format src/ tests/

# Type check
mypy src/mdpp/

# Run tests
pytest

# Full pre-commit suite
pre-commit run --all-files

MIT — Zhaoyang Li