Install & Run

A first-run path for new users.

The recommended first experience is the curated protein-ligand walkthrough. It shows the full rhythm of PyMACS without asking a new user to design a new simulation from scratch.

Step 0 — Get the simulation engine

Install GROMACS once. Use it everywhere.

PyMACS uses GROMACS for molecular-dynamics setup, equilibration, production simulation, trajectory processing, and related workflows. The companion installer keeps the simulation engine at the system level so your normal shell and PyMACS Conda environments can share the same gmx executable.

Linux WSL2 GROMACS 2026.3 NVIDIA CUDA Conda-independent
Quick install command
git clone https://github.com/Joey305/gromacs-installation.git
cd gromacs-installation
chmod +x install_gromacs.sh
./install_gromacs.sh
hash -r
source /etc/profile.d/gromacs.sh
gmx --version
Already have GROMACS?

Run gmx --version. If it works, you can continue directly to PyMACS installation instead of replacing a working setup.

Local Linux / WSL2 workstation

Use the PyMACS companion installer when you want a reproducible system-wide GROMACS build that stays visible from your normal shell and Conda environments.

University cluster / HPC / SLURM environment

Use the GROMACS module or administrator-managed installation provided by the institution whenever appropriate. PyMACS can work with alternate GROMACS executables supported by the project.

1

GROMACS

System simulation engine

2

PyMACS

Automation scripts and workflow

3

Python environments

cgenff and mdanalysis

4

First simulation

Run Example 1

/usr/local/bin/gmx
base cgenff mdanalysis future environments ordinary shell

Conda manages the Python environments. GROMACS remains a shared system-level simulation engine.

Step 1 — Install PyMACS

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.
PyMACS 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

Step 2 — Configure environments

Create the Python environments and verify gmx inside them.

After GROMACS is available, install PyMACS, create the two recommended Conda environments, and confirm that both environments still resolve to the same shared system gmx executable.

Environment setup and verification
conda env create -f environment_cgenff.yml
conda env create -f environment_mdanalysis.yml

conda activate base
which gmx
gmx --version

conda activate mdanalysis
which gmx
gmx --version

conda activate cgenff
which gmx
gmx --version
which gmx should point to /usr/local/bin/gmx in the shared workstation workflow. gmx --version confirms that GROMACS works before you spend time debugging PyMACS itself. type -a gmx helps diagnose Conda shadowing if an environment later exposes a different executable.

Step 3 — Final prerequisites

Know what needs to exist first.

PyMACS automates a difficult workflow, but the scientific inputs still matter. Start from a curated example, then change one thing at a time when moving to a new system.

A working GROMACS executable. Local Linux and WSL2 users can use the companion installer; HPC users should use the module or managed build provided by their institution. The PyMACS repository files, including MDP templates and force-field folders The cgenff environment for setup and ligand conversion The mdanalysis environment for simulation control, analysis, plotting, and reports Ligand CGenFF files when running ligand or cofactor systems

Step 4 — Run Example 1

Follow the workflow in order.

1

Create a clean run folder

Keep each system in its own directory so generated topologies, trajectories, CSV tables, plots, and logs stay reproducible.

mkdir -p RUNS/Example_CPD32 && cd RUNS/Example_CPD32
2

Prepare the system

Run Step 1 in the cgenff environment. This cleans the structure, builds topologies, places solvent and ions, and writes the energy-minimization input.

conda activate cgenff
python 1_AutomateGromacs.py --pdb CPD32_9G94.pdb
3

Run equilibration and production

Run Step 2 in the analysis/simulation environment. This executes minimization, NVT, NPT, and production MD.

conda activate mdanalysis
python 2_AutomateGromacs.py
4

Analyze the trajectory

Step 3A recenters the trajectory, calculates stability and flexibility metrics, extracts binding-pocket contacts, and prepares network-ready tables.

python 3A_AutomateGromacs.py
5

Render networks and reports

Step 3B creates ligand-residue network views when the required contact tables exist. Step 4 assembles the final figurebook.

python 3B_NETWORX.py
python 4PDF4MD.py

Before production MD

The three stabilization stages.

Interpretation checks

Do these before trusting the story.

Read mdrun.log after every stage; it records commands and setup decisions.
Inspect em.gro, nvt.gro, and npt.gro before trusting production output.
Check RMSD and Rg before interpreting contacts.
Treat contact maps as evidence of proximity and persistence, not direct binding free energy.
Review CGenFF penalty scores for ligands before publication-grade conclusions.