Curated examples

Copy the commands, run the example, compare the outputs.

Each walkthrough starts from the PyMACS repository root and keeps the packaged example folders untouched. Start with Example 1 unless another system matches your science better.

Before any example

Open a terminal in the PyMACS folder.

All commands below assume your first prompt is already inside the repository root, the folder that contains 1_AutomateGromacs.py, 2_AutomateGromacs.py, and Example_Choices/.

Sanity check
pwd
ls 1_AutomateGromacs.py 2_AutomateGromacs.py 3A_AutomateGromacs.py Example_Choices

Need PyMACS first?

Quick Start Install

Use this when you want to create a clean PyMACS run or working folder without manually downloading the repository or copying files yourself.

First, cd into the folder where you want the PyMACS files to appear. Your current working directory simply means the folder your terminal is presently pointing at. The command below temporarily clones PyMACS, copies everything into that folder, includes hidden files such as .gitignore and .gitattributes, skips the cloned repository's .git folder, and then removes the temporary clone when it is finished.

Checks that git is installed before doing anything. Warns before copying into a non-empty directory. Asks before overwriting similarly named files. Uses Git LFS when available and warns if large example assets may still be pointer files.
One-command installer
bash <<'EOF'
set -e

REPO_URL="https://github.com/schurerlab/Pymacs.git"
TMP_DIR="$(mktemp -d)"
TARGET_DIR="$(pwd)"

cleanup() {
  rm -rf "$TMP_DIR"
}

trap cleanup EXIT

echo "======================================"
echo " PyMACS Quick Start Install"
echo "======================================"
echo
echo "This will copy a fresh PyMACS instance into:"
echo "  $TARGET_DIR"
echo

if ! command -v git >/dev/null 2>&1; then
  echo "ERROR: git is not installed or not available in PATH."
  echo "Please install git first, then run this command again."
  exit 1
fi

if [ "$(find "$TARGET_DIR" -mindepth 1 -maxdepth 1 | wc -l)" -gt 0 ]; then
  echo "WARNING: This directory is not empty."
  echo "Files with the same names as PyMACS files may be overwritten."
  echo
  printf "Continue copying PyMACS into this directory? [y/N]: "
  read -r answer </dev/tty
  case "$answer" in
    y|Y|yes|YES) ;;
    *)
      echo "Install cancelled."
      exit 0
      ;;
  esac
fi

echo
echo "Cloning PyMACS into a temporary folder..."
git clone "$REPO_URL" "$TMP_DIR/pymacs"

cd "$TMP_DIR/pymacs"

if command -v git-lfs >/dev/null 2>&1 || git lfs version >/dev/null 2>&1; then
  echo "Git LFS detected. Pulling large tracked files..."
  git lfs install
  git lfs pull
else
  echo "WARNING: Git LFS was not detected."
  echo "Core PyMACS files will still be copied, but large example assets may remain as LFS pointer files."
  echo "Install Git LFS later and re-run this installer if you need the full example datasets."
fi

echo
echo "Copying PyMACS files into your current directory..."

shopt -s dotglob nullglob
for item in "$TMP_DIR/pymacs"/*; do
  base="$(basename "$item")"
  if [ "$base" = ".git" ]; then
    continue
  fi

  if [ -e "$TARGET_DIR/$base" ]; then
    printf "Overwrite existing %s? [y/N]: " "$base"
    read -r overwrite </dev/tty
    case "$overwrite" in
      y|Y|yes|YES)
        rm -rf "$TARGET_DIR/$base"
        ;;
      *)
        echo "Skipping $base"
        continue
        ;;
    esac
  fi

  cp -R "$item" "$TARGET_DIR/"
done

echo "Cleaning up temporary clone..."
cleanup
trap - EXIT

cd "$TARGET_DIR"

echo
echo "Done. PyMACS has been copied into:"
echo "  $TARGET_DIR"
echo
echo "Next recommended steps:"
echo "  conda env create -f environment_cgenff.yml"
echo "  conda env create -f environment_mdanalysis.yml"
echo
echo "Then follow the Step 1 / Step 2 / Step 3 workflow on this page."
EOF

Best first run

Example 1: Protein-ligand

The shortest full demonstration of setup, production MD, ligand analysis, NETWORX output, and a final figurebook.

Best for

New users, teaching demos, environment checks, and the standard protein plus small-molecule workflow.

Files this example uses

input/CPD32_9G94.pdb Starting protein-ligand structure
parameters/A1D.str CGenFF stream file for A1D
parameters/A1D.cgenff.mol2 CGenFF MOL2 file for A1D
prepared_system/ Reference setup outputs
completed_run/ Reference MD and analysis outputs
1

Prepare a clean working copy

Run this from the PyMACS repository root. It activates the setup environment, creates a disposable run folder, and copies the required input and ligand files.

Terminal commands
conda activate cgenff
mkdir -p RUNS/example1_beginner_test
cd RUNS/example1_beginner_test
cp ../../Example_Choices/Example1/input/CPD32_9G94.pdb .
cp ../../Example_Choices/Example1/parameters/A1D.str .
cp ../../Example_Choices/Example1/parameters/A1D.cgenff.mol2 .
Expected: You should now be inside RUNS/example1_beginner_test with CPD32_9G94.pdb, A1D.str, and A1D.cgenff.mol2.
2

Run Script 1 setup

This builds the CHARMM/CGenFF-compatible GROMACS system: cleaned coordinates, topology, box, solvent, ions, and EM input.

Terminal commands
python ../../1_AutomateGromacs.py --pdb CPD32_9G94.pdb --ligand A1D
Expected: Look for topol.top, complex.gro, solv_ions.gro, index.ndx, atomIndex.txt, and em.tpr.
3

Run EM, NVT, NPT, and short production MD

Switch to the MD/analysis environment and run a small CPU-only test. Increase --ns later after the workflow works.

Terminal commands
conda activate mdanalysis
python ../../2_AutomateGromacs.py --mode ligand --ligand A1D --ns 0.25 --compute CPU --headless
Expected: Look for em.gro, nvt.gro, npt.gro, md_0_1.xtc, md_0_1.tpr, md_0_1.edr, and md_0_1.log.
4

Analyze ligand stability and contacts

Script 3A recenters the trajectory, makes RMSD/RMSF/Rg plots, detects ligand contacts, and writes analysis tables.

Terminal commands
python ../../3A_AutomateGromacs.py --mode ligand --ligand A1D --headless
Expected: Look for Final_Trajectory.pdb, Final_Trajectory.xtc, binding_pocket_only files, and Analysis_Results/.
5

Build networks and the figurebook

NETWORX turns contact tables into ligand-residue network figures. The PDF script packages finished plots into a review-ready report.

Terminal commands
python ../../3B_NETWORX.py --ligand A1D
python ../../4PDF4MD.py
Expected: Look for Analysis_Results/NETWORX/ and MD_ANALYSIS_FIGUREBOOK.pdf.

Beginner guardrails

  • Use this example first if you are unsure where to start.
  • Keep --ns 0.25 until the full command chain finishes once.
  • Do not rename A1D files unless you also update every topology and command reference.

Second example

Example 2: Cofactor-aware receptor

Shows retained non-protein components and multi-chain topology handling.

Best for

Users with a main ligand plus a retained cofactor, cholesterol-like component, heme, ion, or other important context molecule.

Files this example uses

input/9UWJ.cif Starting receptor structure
parameters/A1E.str Main ligand CGenFF stream file
parameters/A1E.cgenff.mol2 Main ligand MOL2 file
parameters/CLR.str Retained cofactor stream file
parameters/CLR.cgenff.mol2 Retained cofactor MOL2 file
completed_run/ Reference MD-stage outputs
1

Prepare a clean working copy

Run this from the PyMACS repository root. It copies the receptor, main ligand, and retained cofactor files into a fresh run folder.

Terminal commands
conda activate cgenff
mkdir -p RUNS/example2_beginner_test
cd RUNS/example2_beginner_test
cp ../../Example_Choices/Example2/input/9UWJ.cif .
cp ../../Example_Choices/Example2/parameters/A1E.str .
cp ../../Example_Choices/Example2/parameters/A1E.cgenff.mol2 .
cp ../../Example_Choices/Example2/parameters/CLR.str .
cp ../../Example_Choices/Example2/parameters/CLR.cgenff.mol2 .
Expected: You should now have 9UWJ.cif plus A1E and CLR parameter files in the run folder.
2

Run Script 1 with ligand and cofactor named

A1E is the main ligand for analysis. CLR is retained as a cofactor/context component so setup does not discard it.

Terminal commands
python ../../1_AutomateGromacs.py --pdb 9UWJ.cif --ligand A1E --cofactors CLR
Expected: Look for topol.top, component registry JSON files, cofactor topology includes, solv_ions.gro, and em.tpr.
3

Run EM, NVT, NPT, and a short MD test

This keeps the run intentionally short and CPU-safe while you confirm the cofactor-aware path works.

Terminal commands
conda activate mdanalysis
python ../../2_AutomateGromacs.py --mode ligand --ligand A1E --cofactors CLR --ns 0.25 --compute CPU --headless
Expected: Look for md_0_1.xtc, md_0_1.tpr, md_0_1.edr, md_0_1.gro, and stage logs.
4

Analyze the main ligand while retaining context

The analysis targets A1E but keeps CLR as biological context rather than treating it as the ligand of interest.

Terminal commands
python ../../3A_AutomateGromacs.py --mode ligand --ligand A1E --cofactors CLR --headless
Expected: Look for Analysis_Results/ with ligand stability plots, contact tables, and interaction summaries.
5

Render interaction networks and report

Run these after 3A creates the contact and interaction tables.

Terminal commands
python ../../3B_NETWORX.py --ligand A1E
python ../../4PDF4MD.py
Expected: Look for NETWORX figures and, when enough figures exist, MD_ANALYSIS_FIGUREBOOK.pdf.

Beginner guardrails

  • Use --cofactors for retained non-protein components that are not the main analysis ligand.
  • If setup drops CLR, rerun Script 1 and check the ligand/cofactor names.
  • The packaged completed_run folder is mainly an MD-stage reference for this example.

Biological assembly

Example 3: RNA/protein assembly

Demonstrates biological-system setup and simulation for mixed biomolecular assemblies.

Best for

RNA-protein systems, mixed biomolecular assemblies, and non-ligand workflows where the question is about the biological complex.

Files this example uses

input/1URN.pdb Starting RNA-protein structure
prepared_system/ Reference RNA/protein topology and restraint files
completed_run/Final_Trajectory.* Reference processed trajectory files
completed_run/Analysis_Results/ Reference biological analysis outputs
completed_run/MD_ANALYSIS_FIGUREBOOK.pdf Reference figurebook
1

Prepare a clean working copy

Run this from the PyMACS repository root. This example has no separate ligand parameter files.

Terminal commands
conda activate cgenff
mkdir -p RUNS/example3_beginner_test
cd RUNS/example3_beginner_test
cp ../../Example_Choices/Example3/input/1URN.pdb .
Expected: You should now be inside RUNS/example3_beginner_test with 1URN.pdb.
2

Run Script 1 setup

Run Script 1 interactively or with only the input file so PyMACS can handle chain and component interpretation.

Terminal commands
python ../../1_AutomateGromacs.py --pdb 1URN.pdb
Expected: Look for RNA/protein topology includes, topol.top, index.ndx, solv_ions.gro, and em.tpr.
3

Run EM, NVT, NPT, and short biological MD

Biological mode tells Script 2 this is not a ligand-centered simulation.

Terminal commands
conda activate mdanalysis
python ../../2_AutomateGromacs.py --mode biological --ns 0.25 --compute CPU --headless
Expected: Look for md_0_1.xtc, md_0_1.tpr, md_0_1.edr, md_0_1.gro, and stage logs.
4

Analyze the biological assembly

Script 3A creates chain-aware stability, secondary-structure, and biomolecular interaction outputs where supported.

Terminal commands
python ../../3A_AutomateGromacs.py --mode biological --headless
Expected: Look for Analysis_Results/, Final_Trajectory files, RMSD/RMSF outputs, DSSP outputs, and chain interaction summaries.
5

Build the figurebook

Use this once the analysis folder contains plots worth packaging.

Terminal commands
python ../../4PDF4MD.py
Expected: Look for MD_ANALYSIS_FIGUREBOOK.pdf.

Beginner guardrails

  • Choose biological mode, not ligand mode.
  • Do not expect A1D/A1E/PTC-style ligand files in this example.
  • Use the packaged completed_run folder to compare chain-level outputs.

Advanced

Example 4: PROTAC ternary complex

Highlights ternary-complex bookkeeping, contacts by component, geometry, networks, and PROTAC reporting.

Best for

PROTACs, ternary complexes, targeted-degradation systems, and users who need component-aware contact analysis.

Files this example uses

input/5T35.pdb Starting ternary-complex structure
parameters/PTC.str PROTAC CGenFF stream file
parameters/PTC.cgenff.mol2 PROTAC MOL2 file
prepared_system/ Reference VHL/BRD4/PTC setup outputs
completed_run/ Reference MD-stage outputs
1

Prepare a clean working copy

Run this from the PyMACS repository root. It copies the ternary-complex input and PTC parameter files into a fresh run folder.

Terminal commands
conda activate cgenff
mkdir -p RUNS/example4_beginner_test
cd RUNS/example4_beginner_test
cp ../../Example_Choices/Example4/input/5T35.pdb .
cp ../../Example_Choices/Example4/parameters/PTC.str .
cp ../../Example_Choices/Example4/parameters/PTC.cgenff.mol2 .
Expected: You should now have 5T35.pdb, PTC.str, and PTC.cgenff.mol2 in the run folder.
2

Run Script 1 setup

PTC is the PROTAC-like molecule. Script 1 still prepares the system through the standard setup path.

Terminal commands
python ../../1_AutomateGromacs.py --pdb 5T35.pdb --ligand PTC
Expected: Look for topol.top, protein partner topology files, PTC includes, solv_ions.gro, atomIndex.txt, and em.tpr.
3

Run EM, NVT, NPT, and short PROTAC MD

Use protac mode and a short CPU run first. Ternary systems can be expensive, so smoke-test before a long run.

Terminal commands
conda activate mdanalysis
python ../../2_AutomateGromacs.py --mode protac --ligand PTC --ns 0.25 --compute CPU --headless
Expected: Look for md_0_1.xtc, md_0_1.tpr, md_0_1.edr, md_0_1.gro, and stage logs.
4

Run quick PROTAC analysis

The dedicated PROTAC script checks component roles, scans a smaller frame window, and writes component-aware outputs.

Terminal commands
python ../../3_PROTAC_Analysis.py --ligand PTC --quick-test --headless
Expected: Look for Analysis_Results/PROTAC/ with QC files, contact summaries, networks, and component plots.
5

Build the PROTAC figurebook

Use this after PROTAC analysis creates a manifest and enough figures.

Terminal commands
python ../../4PDF4MD.py
Expected: Look for PROTAC_MD_ANALYSIS_FIGUREBOOK.pdf, or a standard figurebook if only standard figures are present.

Beginner guardrails

  • Choose protac mode for Step 2.
  • Use --quick-test before full PROTAC analysis.
  • Keep atomIndex.txt because the PROTAC analyzer uses component atom ranges.

If something breaks

Most failures are folder, environment, or filename problems.

Before debugging the science, confirm the simple pieces: you are in the run folder, Conda is active, GROMACS is visible, and the copied files have the expected names.

Wrong folder

pwd
ls

You should be inside a folder under RUNS/ before running Scripts 1-4.

Missing GROMACS

gmx --version

If this fails, activate the environment or module that provides GROMACS before continuing.

Missing outputs

find . -maxdepth 2 -type f | sort | head -80

Use this to see what the scripts actually wrote before assuming a later step failed.