Examples

These examples cover most of the calculations and analyses available in gmx_MMPBSA. Although each example focuses on a specific case, gmx_MMPBSA can process systems containing several components (e.g., metalloprotein-ligand or protein-DNA-ligand complexes). A single run can also combine multiple calculation types, such as GB with alanine scanning and per-residue decomposition, or PB with interaction entropy and pairwise decomposition.

Maintaining example documentation¶

Example README files under examples/ are the canonical copies used by gmx_MMPBSA_test and GitHub browsing. The MkDocs site reads published copies under docs/examples/.

When you edit an example README:

1. Change the file under examples/ only.
2. Run from the repository root:

python scripts/sync_example_docs.py

1. Commit both the examples/ change and the synced docs/examples/ copy.

CI runs python scripts/sync_example_docs.py --check and fails if the docs copies are stale.

The examples available through gmx_MMPBSA_test are defined in GMXMMPBSA/data/gmx_MMPBSA_test_manifest.json. When adding, removing, or renaming a testable example, update the manifest and run:

python scripts/validate_gmx_MMPBSA_test_docs.py

Jupyter notebooks¶

Two Jupyter notebooks are available for interactive use:

• Google Colab notebook: installs a conda-based CPU environment, runs bundled examples, supports uploaded user files, and displays results through the Python API.
• Local notebook: runs or loads local results, extracts data with the Python API, and plots energy terms with seaborn.

Systems¶

The following examples represent systems that gmx_MMPBSA can process and analyze. The list is not exhaustive; gmx_MMPBSA can also process other systems with compatible input structures.

• Protein-protein¹²³
• Protein-ligand¹²
• Protein-DNA¹²³
• Protein-glycan¹²³
• MMPBSA with membrane proteins¹²
• Metalloprotein-ligand¹²
• Multicomponent system (Comp_receptor)¹²³

Analyses¶

This section covers the analyses available in gmx_MMPBSA. Although each example focuses on a specific case, one run can combine several calculation types (e.g., GB with alanine scanning and per-residue decomposition, or PB with interaction entropy and per-residue decomposition).

• Single Trajectory Protocol¹²³
• Multiple Trajectory Protocol¹
• Binding free energy calculations
  • Binding free energy calculation with GB
  • ST MM/PB(GB)SA with explicit receptor waters¹
  • Binding free energy calculation with GBNSR6¹
  • Binding free energy calculation with linear PB (LPBE)¹
  • Binding free energy calculation with NonLinear PB (non-LPBE)¹
  • Binding free energy calculation with 3D-RISM model¹
• Alanine scanning¹²³
• Decomposition analysis¹²³
• Entropy
  • Interaction Entropy calculations¹²³
  • NMODE Entropy calculations¹
  • C2 Entropy calculations¹
• Stability calculations¹²³
• QM/MMGBSA calculations¹
• Correlation
• Python API extraction
• Local API/seaborn notebook

Input formats and force-field workflows¶

The examples below demonstrate preparation workflows for different input formats and force fields. The molecular systems shown are representative examples, not a list of supported receptor-ligand compositions. For example, a protein-protein tutorial under native AMBER or PSF/DCD does not mean that the workflow is restricted to protein-protein complexes. The same preparation principles apply to other systems when the resulting topologies, structures, trajectories, and molecular selections are compatible with gmx_MMPBSA or amber_MMPBSA.

Individual calculation models can impose narrower requirements. Review each tutorial's topology-conversion notes and the restrictions of the selected energy, entropy, decomposition, or membrane method.

Native AMBER inputs¶

Use native AMBER topologies and trajectories directly with amber_MMPBSA.

• Representative protein-protein example¹

GROMACS topologies prepared with CHARMM¶

These examples use supplied GROMACS topologies containing CHARMM parameters, including specialized membrane and LPH workflows.

• Representative protein-ligand example¹²
• Specialized membrane protein-ligand example (CHARMM-GUI)¹
• Specialized ligand example with LPH virtual sites¹

GROMACS topologies prepared with OPLS¶

• Representative protein-protein example

Converting PSF/DCD simulations¶

PSF and DCD files are preparation sources, not files read directly by gmx_MMPBSA. Convert them into a compatible topology, structure, trajectory, index, and receptor/ligand selections before analysis.

• Representative protein-protein conversion example