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)

This is the fastest way to get GateWizard up and running:

# 1. Create conda environment with scientific dependencies
conda create -n gatewizard -c conda-forge python sqlite ambertools=24 parmed=4.3.0 -y

# 2. Activate the environment
conda activate gatewizard

# 3. Install GateWizard from PyPI
pip install gatewizard

# 4. Launch GateWizard
gatewizard

Alternative: Development Installation

For developers or to install from source:

# 1. Clone the repository
git clone https://github.com/maurobedoya/gatewizard.git
cd gatewizard

# 2. Create environment from file
conda env create -f environment.yml

# 3. Activate the environment
conda activate gatewizard

# 4. Install in development mode
pip install -e .

# 5. Launch GateWizard
gatewizard

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

# Run using pythonw instead of python
pythonw -m gatewizard

Known Issues: - On Apple Silicon (M1/M2), some dependencies may require Rosetta 2 - CustomTkinter may have scaling issues on Retina displays

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
gatewizard

Dependencies

Core Python Dependencies

Automatically installed via pip:

  • Python ≥ 3.8
  • CustomTkinter ≥ 5.0.0 - Modern GUI framework
  • NumPy ≥ 1.21.0 - Numerical computing
  • Matplotlib ≥ 3.5.0 - Plotting and visualization
  • MDAnalysis ≥ 2.0.0 - Molecular analysis toolkit
  • Propka ≥ 3.2.0 - pKa calculations
  • RDKit ≥ 2023.3.1 - Ligand 2D structure visualization

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 3.0.1 - Required for molecular dynamics simulations and equilibration
  • Download from: NAMD Official Website
  • Must be installed separately and accessible in your system PATH

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 customtkinter; print('CustomTkinter:', customtkinter.__version__)"
python -c "import MDAnalysis; print('MDAnalysis:', MDAnalysis.__version__)"
python -c "import parmed; print('ParmEd:', parmed.__version__)"

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

# Launch GateWizard
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
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: 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: CustomTkinter GUI not appearing

Cause: Display configuration or tkinter missing.

Solution: 

# On Linux
sudo apt-get install python3-tk

# Reinstall CustomTkinter
pip install --force-reinstall customtkinter

# Check display
echo $DISPLAY  # Should show something like :0 or localhost:10.0

Issue: Module not found errors

Cause: Installation incomplete or wrong environment.

Solution: 

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

# Reinstall in development mode
cd /path/to/gatewizard
pip install -e . --force-reinstall

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 . --force-reinstall

# Restart GateWizard
gatewizard

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.