Skip to content

Installation Guide

This guide provides detailed instructions for installing GateWizard on different platforms.

Prerequisites

Before installing GateWizard, ensure you have:

  • Conda (Miniconda or Anaconda): Download here
  • Git (for cloning the repository): Download here
  • Python 3.8+ (will be installed via conda)

Full API installation (Linux or WSL)

Use this when the new machine should build membranes, orient with MemPrO, and run OpenMM or GROMACS. NAMD stays a separate download.

conda create -n gatewizard -c conda-forge python sqlite ambertools=24 parmed=4.3.0 openmm cudatoolkit gromacs -y
conda activate gatewizard
pip install "gatewizard[full]"
pip install "mempro @ git+https://github.com/pstansfeld/MemPrO.git@v0.1.0"
python -c "import gatewizard; print(gatewizard.__version__)"
which pdb4amber
which mempro

On macOS, omit cudatoolkit. Prefer the CPU gromacs package. A CUDA GROMACS build in this same environment often stalls in the solver; see GROMACS: CPU vs CUDA.

The same stack from a git checkout:

git clone https://github.com/maurobedoya/gatewizard.git
cd gatewizard
conda env create -f environment.yml
conda activate gatewizard
pip install -r requirements-orientation.txt

environment.yml already installs the package with pip install -e ".[full]". The requirements file adds MemPrO, which PyPI cannot list inside the [full] extra.

For the desktop app, install gatewizard-gui separately. On first launch the GUI embeds its own micromamba runtime. That runtime is not this conda env. See Desktop GUI runtime (GROMACS / CUDA) below.

API package only

This installs the Python library without OpenMM or MemPrO:

conda create -n gatewizard -c conda-forge python sqlite ambertools=24 parmed=4.3.0 -y
conda activate gatewizard
pip install gatewizard
python -c "import gatewizard; print(gatewizard.__version__)"

Platform-Specific Instructions

Linux

GateWizard works natively on Linux. Follow the Quick Installation steps above.

Additional Notes: - Ensure you have tkinter support: sudo apt-get install python3-tk (Ubuntu/Debian) - For display issues, ensure X11 is properly configured

macOS

GateWizard works on macOS with some considerations:

# Follow the Quick Installation steps, then:

# If you encounter display issues:
conda install -c conda-forge python.app

Known Issues: - On Apple Silicon (M1/M2), some dependencies may require Rosetta 2

Windows

GateWizard is best used on Windows with WSL (Windows Subsystem for Linux):

Option 1: WSL (Recommended) 

# 1. Install WSL2 with Ubuntu
wsl --install

# 2. Inside WSL, follow the Linux installation instructions
# 3. Install X server on Windows (e.g., VcXsrv, X410)
# 4. Set DISPLAY environment variable in WSL
export DISPLAY=:0

Option 2: Native Windows (Experimental) 

# Use Anaconda Prompt
conda create -n gatewizard -c conda-forge python sqlite ambertools=24 parmed=4.3.0 -y
conda activate gatewizard
pip install gatewizard
python -c "import gatewizard; print(gatewizard.__version__)"

For the desktop app on Windows, use the gatewizard-gui Windows installer or the Linux/WSL build for the full MD workflow.

If Windows Task Manager shows VmmemWSL using several GB after you close the app, cap the VM — see Troubleshooting: VmmemWSL RAM.

Dependencies

Core Python Dependencies

Installed by pip install gatewizard:

  • Python ≥ 3.8
  • NumPy ≥ 1.21.0
  • Matplotlib ≥ 3.5.0
  • MDAnalysis ≥ 2.0.0
  • lipyphilic ≥ 0.12.0
  • freud-analysis ≥ 2.5.0
  • Propka ≥ 3.2.0
  • RDKit ≥ 2023.3.1
  • gemmi ≥ 0.6.5
  • psique ≥ 1.2.1

pip install "gatewizard[full]" also installs ParmEd and OpenMM. MemPrO is a separate pip line (requirements-orientation.txt or the GitHub tag v0.1.0). AmberTools, the conda ParmEd build, OpenMM’s CUDA toolkit, and CPU GROMACS come from conda, not from that pip extra.

Scientific Computing Dependencies

Must be installed via conda:

  • AmberTools 24 - Molecular dynamics preparation and analysis
  • Parmed 4.3.0 - Parameter/topology manipulation (must be from conda-forge)

External Requirements

  • NAMD - Required for NAMD equilibration (separate install; not on conda-forge)
  • Recommended: NAMD 3.0.1 or later (namd3)
  • Download from: NAMD Official Website
  • Must be on PATH or selectable via the GUI engine picker
  • OpenMM (optional for API users) - Python MD engine via conda-forge
  • conda install -c conda-forge openmm cudatoolkit on Linux/WSL with an NVIDIA driver for the CUDA platform
  • macOS uses Metal/OpenCL (no cudatoolkit)
  • Auto-selects CUDA → OpenCL → CPU; override with PLATFORM=CUDA when running equilibration scripts
  • GROMACS (optional) - Recommended via conda-forge; the GUI also installs a build into its embedded runtime
  • CPU (recommended default): conda install -c conda-forge gromacs
  • CUDA (Linux only, advanced): conda install -c conda-forge 'gromacs=*=nompi_cuda*'
  • System installs under /usr/local/gromacs (with GMXRC) are auto-detected
  • See the notes below before choosing the CUDA conda build

GROMACS: CPU vs CUDA (conda-forge)

GateWizard equilibration works with either a CPU or CUDA gmx. Prefer the CPU package unless you specifically need a conda CUDA GROMACS binary.

Goal Command / behavior
Reliable conda install conda install -c conda-forge gromacs
CUDA GROMACS (opt-in) conda install -c conda-forge 'gromacs=*=nompi_cuda*'
GPU OpenMM (separate) conda install -c conda-forge openmm cudatoolkit

Why CUDA GROMACS often fails or hangs

  • Installing gromacs=*=nompi_cuda* into an environment that already has OpenMM + cudatoolkit can stall for a very long time in the dependency solver (little or no log output after Pinned packages:).
  • Log lines about the CUDA Toolkit EULA or Anaconda Terms of Service are informational. Non-interactive installs (conda/micromamba with -y) do not wait for you to type “yes”.
  • If the CUDA solve is cancelled or times out, installing the CPU gromacs package normally succeeds quickly.
  • For GPU MD with GateWizard, OpenMM + cudatoolkit is usually enough. Use a system CUDA GROMACS (or GMXRC) if you need gmx on the GPU, or keep conda GROMACS on CPU.

Desktop GUI runtime (GROMACS / CUDA)

gatewizard-gui bootstraps an embedded micromamba env on first launch (see that repo’s README and runtime-install.log).

  • OpenMM: on Linux/WSL, if nvidia-smi sees a GPU, the GUI installs openmm + cudatoolkit into the embedded env (unless GATEWIZARD_SKIP_CONDA_CUDA=1).
  • GROMACS (default): the GUI installs the CPU conda-forge build. This avoids multi-hour CUDA solver hangs next to OpenMM’s toolkit.
  • GROMACS CUDA (opt-in): set GATEWIZARD_CONDA_GROMACS_CUDA=1 before launching the GUI. The bootstrap tries a frozen CUDA install with a short timeout, then falls back to CPU GROMACS if the solve stalls.
  • Quitting mid-install kills leftover micromamba processes for that env so a relaunch is not blocked by an orphaned solver.
  • Linux/WSL log: ~/.config/gatewizard-gui/runtime-install.log (look for [gromacs] starting… / failed / installed).
  • The embedded env is ~/.config/gatewizard-gui/mamba-env. sudo apt remove gatewizard-gui-linux leaves it. sudo apt purge gatewizard-gui-linux deletes that directory for the user who ran sudo. It does not remove a separate conda env such as ~/miniconda3/envs/gatewizard.

Manual API environments should follow the same preference: install CPU gromacs by default; only add the CUDA matchspec if you accept a long or fragile solve.

Verifying Installation

After installation, verify that everything works:

# Activate environment
conda activate gatewizard

# Check Python version
python --version  # Should be 3.8+

# Check key dependencies
python -c "import MDAnalysis; print('MDAnalysis:', MDAnalysis.__version__)"
python -c "import parmed; print('ParmEd:', parmed.__version__)"
python -c "import openmm; print([openmm.Platform.getPlatform(i).getName() for i in range(openmm.Platform.getNumPlatforms())])"

# Check AmberTools
which pdb4amber  # Should show path in conda environment

# Verify GateWizard API
python -c "import gatewizard; print(gatewizard.__version__)"

Upgrading GateWizard

To upgrade to the latest version from PyPI:

# Activate environment
conda activate gatewizard

# Upgrade GateWizard
pip install --upgrade gatewizard

# Verify new version
python -c "import gatewizard; print(gatewizard.__version__)"

Check for updates: You can check if a newer version is available: 

pip list --outdated | grep gatewizard

Force reinstall (if needed): If you encounter issues after an update: 

pip install --force-reinstall gatewizard

Troubleshooting Installation

Issue: conda GROMACS CUDA install hangs after “Pinned packages”

Cause: The gromacs=*=nompi_cuda* solve often conflicts with an environment that already has OpenMM/cudatoolkit. The solver can run for a very long time with almost no new log lines. EULA / Terms-of-Service messages in the log are not interactive prompts.

Solution: 

# Cancel the stuck install (Ctrl+C), then install CPU GROMACS:
conda install -c conda-forge gromacs -y

# Optional: use a system CUDA GROMACS / GMXRC instead of the conda CUDA build

For gatewizard-gui, leave the default (CPU GROMACS). Only set GATEWIZARD_CONDA_GROMACS_CUDA=1 if you explicitly want the timed CUDA attempt. See Desktop GUI runtime (GROMACS / CUDA).

Issue: ImportError with numpy.compat

Cause: Version conflict between NumPy and Parmed.

Solution: 

# Reinstall Parmed from conda-forge
conda install -c conda-forge parmed=4.3.0 --force-reinstall

Issue: pdb4amber command not found

Cause: AmberTools not properly installed or environment not activated.

Solution: 

# Ensure environment is activated
conda activate gatewizard

# Reinstall AmberTools
conda install -c conda-forge ambertools=24

Issue: Module not found errors

Cause: Installation incomplete or wrong environment.

Solution: 

# Ensure you're in the correct environment
conda activate gatewizard

# Reinstall the API
cd /path/to/gatewizard
pip install -e ".[full]" --force-reinstall
pip install -r requirements-orientation.txt

Tip: GateWizard follows semantic versioning. Check the releases page for changelog and new features.

For Development Installation

If you installed from source:

# Update repository
cd /path/to/gatewizard
git pull origin main

# Update dependencies if needed
conda env update -f environment.yml

# Reinstall
pip install -e ".[full]" --force-reinstall
pip install -r requirements-orientation.txt

# Re-verify import
python -c "import gatewizard; print(gatewizard.__version__)"

Uninstallation

To completely remove GateWizard:

# Remove conda environment
conda deactivate
conda env remove -n gatewizard

# Remove repository (if desired)
rm -rf /path/to/gatewizard

Next Steps

After successful installation:

  1. Read the User Guide to learn about features
  2. Try the example workflows
  3. Check the Troubleshooting Guide if you encounter issues

For additional help, please contact the developers or check the GitHub repository.