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.
Install & Run
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
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.
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
Run gmx --version. If it works, you can continue directly to PyMACS installation instead of replacing a working setup.
Use the PyMACS companion installer when you want a reproducible system-wide GROMACS build that stays visible from your normal shell and Conda environments.
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.
System simulation engine
Automation scripts and workflow
cgenff and mdanalysis
Run Example 1
Conda manages the Python environments. GROMACS remains a shared system-level simulation engine.
Step 1 — Install PyMACS
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.
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
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.
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
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.
Step 4 — Run Example 1
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
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
Run Step 2 in the analysis/simulation environment. This executes minimization, NVT, NPT, and production MD.
conda activate mdanalysis
python 2_AutomateGromacs.py
Step 3A recenters the trajectory, calculates stability and flexibility metrics, extracts binding-pocket contacts, and prepares network-ready tables.
python 3A_AutomateGromacs.py
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
Interpretation checks