Troubleshooting¶

Common issues and solutions for GateWizard.

Installation Issues¶

Issue: ImportError with numpy.compat¶

Error Message:

ImportError: cannot import name 'OLD_NUMERIC_TYPES' from 'numpy.compat'

Cause: Version conflict between NumPy and Parmed.

Solution:

conda activate gatewizard
conda install -c conda-forge parmed=4.3.0 --force-reinstall

Issue: pdb4amber command not found¶

Error Message:

bash: pdb4amber: command not found

Cause: AmberTools not installed or environment not activated.

Solution:

# Check if environment is activated
conda activate gatewizard

# Verify AmberTools installation
which pdb4amber

# If not found, reinstall
conda install -c conda-forge ambertools=24

Issue: CustomTkinter not found¶

Error Message:

ModuleNotFoundError: No module named 'customtkinter'

Solution:

conda activate gatewizard
pip install customtkinter --force-reinstall

Issue: Display/GUI not appearing¶

On Linux:

# Install tkinter support
sudo apt-get install python3-tk

# Check DISPLAY variable
echo $DISPLAY

# If empty, set it
export DISPLAY=:0

On macOS:

# For the desktop app, use gatewizard-gui from Applications
# See https://github.com/franciscoadasme/gatewizard-gui#macos

On Windows WSL:

# Install X server on Windows (VcXsrv, X410)
# In WSL, set DISPLAY
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

Runtime Issues¶

Issue: GateWizard crashes on startup¶

Check 1: Verify Python version

python --version  # Should be 3.8+

Check 2: Check dependencies

python -c "import customtkinter"
python -c "import MDAnalysis"
python -c "import parmed"

Check 3: For the desktop app, check install logs (see gatewizard-gui README)

Issue: GUI appears but is unresponsive¶

Possible causes: - Large file being processed - System resources exhausted - Display server issues

Solutions: 1. Wait for operation to complete (check terminal for progress) 2. Close other applications to free memory 3. Restart display server 4. Check system resources: top or htop

Issue: Cannot load PDB file¶

Error: "Invalid PDB file" or "Cannot parse file"

Solutions: 1. Verify file format: Ensure it's a valid PDB file

head -n 5 your_file.pdb  # Should show ATOM/HETATM lines

1. Clean the PDB: Use Propka with "Clean PDB" option enabled

2. Check file permissions:

   ls -l your_file.pdb
   chmod 644 your_file.pdb  # If needed
   

3. Try different source: If from PDB database, download again

Analysis Issues¶

Issue: RMSD calculation fails¶

Error: "Cannot compute RMSD"

Possible causes: - Topology/trajectory mismatch - Atom selection returns no atoms - Missing frames

Solutions: 1. Verify topology matches trajectory:

# Check atom counts
grep "^ATOM" topology.pdb | wc -l
# Should match trajectory frame size

1. Test atom selection:
2. Try simpler selection: just "protein"

3. Verify selection syntax

4. Check trajectory integrity:

   import MDAnalysis as mda
   u = mda.Universe("topology.psf", "trajectory.dcd")
   print(f"Frames: {len(u.trajectory)}")
   

Issue: Trajectory loading is very slow¶

Causes: - Very large trajectory (>10GB) - Network storage (slow I/O) - Many atoms selected

Solutions: 1. Use more specific selection: "protein and name CA" instead of "protein" 2. Copy to local disk: Faster than network storage 3. Split trajectory: Analyze in smaller chunks 4. Use frame stride: Skip frames if possible

Issue: Energy plot shows weird values¶

Symptoms: - Extremely large/small values - Discontinuities - Unexpected units

Solutions: 1. Check unit selection: - Verify kcal/mol vs kJ/mol - Verify ps vs ns vs µs

1. Verify log files are sequential:
2. Check file order

3. Verify time assignments

4. Check for parsing errors:

5. Look at status messages

6. Verify log files are from NAMD

7. Plot individual files:

8. Remove all files
9. Add one at a time
10. Find problematic file

Issue: Time distribution is wrong¶

Symptoms: - Files overlap on time axis - Gaps in timeline - Wrong total duration

Solutions: 1. Check time assignments:

File1: 10 ns (not 10,000 ps)
File2: 50 ns
Result: 0-10 ns, 10-60 ns ✓

1. Verify file order:
2. Use drag-and-drop to reorder

3. Equilibration before production

4. Check for typos: 10 vs 100 ns makes big difference

5. Clear and reassign: Remove all files, re-add in order

Issue: Plot is empty or not updating¶

Solutions: 1. Verify data exists: Check status messages 2. Check plot ranges: Auto-scale or adjust manually 3. Verify columns selected: For NAMD analysis 4. Re-run analysis: Click "Run Analysis" again

Memory Issues¶

Issue: Out of memory error¶

Error: "MemoryError" or system freezes

Causes: - Trajectory too large for available RAM - Multiple large analyses in memory - Memory leak (rare)

Solutions: 1. Reduce atom selection: Use "name CA" instead of "protein" 2. Analyze in chunks: Split trajectory temporally 3. Close other applications: Free up RAM 4. Increase swap space (Linux):

sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Performance Issues¶

Issue: Analysis is very slow¶

Symptoms: - Progress bar barely moving - Hours for simple calculation - CPU not fully utilized

Solutions: 1. Use simpler selections: Fewer atoms = faster 2. Check system load: Close background processes 3. Use SSD storage: Faster I/O for trajectory reading 4. Verify not swapping: Check memory usage with htop 5. Update libraries: Newer versions may be faster

Issue: GUI is laggy¶

Solutions: 1. Reduce plot updates: Don't update every frame 2. Close unused tabs: Free resources 3. Lower display resolution: If using remote X 4. Restart application: Clear accumulated state

File/Path Issues¶

Issue: Cannot find output directory¶

Error: "Output directory does not exist"

Solutions: 1. Create directory:

mkdir -p /path/to/output

Issue: Cannot save results¶

Error: "Permission denied" or "Cannot write file"

Solutions: 1. Check write permissions:

ls -ld /path/to/directory
# Should show 'w' for write permission

chmod u+w /path/to/directory

Propka Issues¶

Issue: Propka calculation fails¶

Error: "Propka failed" or "Cannot calculate pKa"

Solutions: 1. Check PDB format: Must be valid PDB 2. Clean PDB first: Remove heteroatoms 3. Check residue names: Must be standard amino acids 4. Update Propka:

pip install --upgrade propka

Issue: Protonation states seem wrong¶

Verify: 1. pH value: Is it set correctly? 2. pKa values: Check against literature 3. Environment effects: Buried residues have shifted pKa

Solutions: - Review pKa table in results - Check pKa shifts - Compare with similar structures - Manually adjust if needed

Platform-Specific Issues¶

Linux¶

Issue: libGL error

libGL error: No matching fbConfigs or visuals found

sudo apt-get install libgl1-mesa-glx

Issue: Permission denied for conda Solution:

# Fix conda ownership
sudo chown -R $USER:$USER ~/miniconda3

macOS¶

Issue: App not trusted Solution:

# Allow running from unidentified developer
xattr -d com.apple.quarantine /path/to/gatewizard

Issue: Retina display scaling Solution: Adjust display settings in System Preferences

Windows (WSL)¶

Issue: X server not connecting Solution:

# In WSL, set DISPLAY correctly
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

# In X server (VcXsrv), disable access control

Issue: File path issues (Windows vs WSL paths) Solution: Use WSL paths (/mnt/c/...) inside WSL

Issue: VmmemWSL keeps using a lot of RAM after GateWizard closes¶

WSL2 is a virtual machine. Linux keeps file cache (MD logs, Python, Electron) and does not give that RAM back to Windows right away. Other Apps and extra Ubuntu terminals also count toward VmmemWSL. On a 16 GB PC this can push Windows to 80–90% and cause other apps to crash.

This is normal WSL behavior, not a leftover GateWizard process (the backend log should already show a clean shutdown).

Solution: Cap the VM from Windows. Create %UserProfile%\.wslconfig (for example C:\Users\YourName\.wslconfig) with:

[wsl2]
memory=4GB
swap=2GB

On a 16 GB machine, 4GB leaves headroom for Windows. Use 6GB if WSL feels tight while GateWizard is open.

Then in PowerShell (Windows, not Ubuntu):

wsl --shutdown

Reopen Ubuntu / GateWizard. Task Manager should keep VmmemWSL near that cap instead of growing for minutes after you quit.

A local equilibration started from the GUI is detached on purpose and can keep using RAM until that job finishes. Remote cluster jobs do not run inside WSL.

Issue: App window not visible (icon appears in taskbar but window is off-screen or invisible)

This can happen after a crash, a display configuration change, or when the WSLg graphics server enters a bad state.

Solution (step by step):

1. Kill any running GateWizard GUI process:

   pkill -f gatewizard-gui
   

2. Reset the saved window position:

   python3 -c "
   import json
   p = '/home/$USER/.config/gatewizard/config.json'
   with open(p) as f:
       cfg = json.load(f)
   cfg['gui']['last_window_x'] = None
   cfg['gui']['last_window_y'] = None
   with open(p, 'w') as f:
       json.dump(cfg, f, indent=2)
   print('Window position reset')
   "
   

3. If the window is still not visible, restart the WSL graphics server:

   # Run in PowerShell (Windows side)
   wsl --shutdown
   

   Then reopen your WSL terminal and launch gatewizard-gui-linux again. WSLg restarts automatically.

Note: If you use VcXsrv or X410 instead of WSLg, close and reopen the X server application instead.

Getting More Help¶

If you're still experiencing issues:

1. Check logs: GUI runtime log at ~/.config/gatewizard-gui/runtime-install.log (Linux/WSL) — see gatewizard-gui install docs
2. Search existing threads: Discussions and GitHub issues
3. Ask the community: Post in Discussions (use labels api or gui as appropriate).
4. Provide details: When asking for help, include:
5. Operating system
6. Python version (python --version)
7. GateWizard API version (python -c "import gatewizard; print(gatewizard.__version__)")
8. Error messages (full traceback)

9. Steps to reproduce

10. Contact developers:

11. Constanza González: constanza.gonzalez.villagra@gmail.com
12. Mauricio Bedoya: mbedoya@ucm.cl
13. Francisco Adasme: fadasme@ucm.cl

FAQ¶

Q: How much RAM do I need? A: Minimum 4GB, 8GB+ recommended. Large trajectories may need 16GB+.

Q: Can I run GateWizard remotely? A: For the desktop app, use X forwarding or WSLg on a remote WSL host and launch gatewizard-gui-linux. For scripting, use the Python API (import gatewizard).

Q: Does GateWizard work with GPU acceleration? A: OpenMM can use CUDA when openmm + cudatoolkit are installed and an NVIDIA driver is present. GROMACS GPU builds are separate — prefer conda CPU gromacs (or a system CUDA gmx); see Installation. Trajectory analysis is CPU-based.

Q: Can I automate GateWizard? A: Python API is available for scripting (see API documentation).

Q: conda/micromamba GROMACS CUDA install hangs — do I need to accept a license? A: No. EULA / Terms-of-Service lines in the log are not interactive prompts (-y is already used). The hang is almost always the dependency solver. Cancel and install CPU gromacs, or for the GUI leave the default / see GATEWIZARD_CONDA_GROMACS_CUDA in Installation.

Q: What trajectory formats are supported? A: DCD, XTC, TRR, NetCDF, and others via MDAnalysis.

Q: How do I cite GateWizard? A: Citation information to be added.

This troubleshooting guide is continuously updated. Last update: October 2025