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:

# Install python.app for GUI support
conda install -c conda-forge python.app

# Run with pythonw
pythonw -m gatewizard

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: Run with debug mode

gatewizard --debug

Solution: Look at error messages and reinstall problematic packages.

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: 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 process:

   pkill -f gatewizard
   

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 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: Look at gatewizard_logging.log in working directory
2. Run in debug mode: gatewizard --debug
3. Search issues: Check GitHub issues (if repository is public)
4. Provide details: When asking for help, include:
5. Operating system
6. Python version (python --version)
7. GateWizard version (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

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: Yes, with X forwarding: ssh -X user@server then run gatewizard

Q: Does GateWizard work with GPU acceleration? A: Not currently. Analysis is CPU-based.

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

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