How maurobedoya/gatewizard works
1. What this repo is
GateWizard is a Python package plus desktop GUI for membrane-protein preparation and MD equilibration/analysis. The architecture is centered on turning one or more structural inputs, usually PDB-based, into prepared systems, simulation inputs, and post-run analyses.
2. Top-level runtime entrypoint
The main application entrypoint is gatewizard/main.py. The package is organized so the GUI and command-line launch both route into the same core workflows rather than having separate business logic paths.
3. Core orchestration layer
gatewizard/core/ is the main application backbone. It contains:
- builder.py for assembling the prepared system from components
- preparation.py for protein cleanup and preprocessing
- structure_manager.py for structure inspection/manipulation
- mempro.py for membrane-protein orientation and membrane-related setup
- file_manager.py for managing generated artifacts and project folders
- job_monitor.py for tracking long-running external jobs and status updates
This is the layer the GUI and tools call into.
4. Feature-specific tool layer
gatewizard/tools/ exposes higher-level workflows:
- force_fields.py for force-field related choices/mapping
- ligand_parametrization.py for ligand parameter generation
- equilibration.py for simulation protocol setup
- validators.py for input and state validation
This layer appears to wrap or coordinate the core modules for user-facing operations.
5. Preparation pipeline
The preparation flow is likely: raw protein structure in -> clean/repair structure -> cap termini if needed -> assign protonation states -> generate prepared protein ready for membrane or ligand workflows. Supporting utilities in gatewizard/utils/protein_capping.py, gatewizard/utils/helpers.py, and gatewizard/utils/config.py indicate that this stage is opinionated and parameterized.
6. Membrane-system construction
Membrane-related functionality is a distinct boundary. The repo contains gatewizard/utils/bilayer_utils.py and a dedicated mempro integration, indicating a workflow that orients the protein, builds/places the bilayer, and prepares the combined membrane-protein system. The test fixtures under tests/equilibration_examples/popc_membrane/ show the output of this stage: prepared PDBs, topology files, logs, and status metadata.
7. Equilibration backends
The equilibration/ directory is a library of static protocol templates and scripts for multiple engines:
- GROMACS: .mdp protocol files
- NAMD: .inp configuration templates
- OpenMM: .inp templates plus Python helper scripts in equilibration/openmm/scripts/
This suggests the equilibration subsystem is template-driven: the app generates engine-specific run inputs and then hands execution to the external simulator.
8. Simulation support scripts
OpenMM has extra implementation support in equilibration/openmm/scripts/:
- reading inputs/parameters
- barostat configuration
- restraints
- rewrapping
- virtual force-switch handling
- a runnable openmm_run.py
These scripts are part of the runtime boundary between GateWizard’s generated protocols and the simulator execution environment.
9. Analysis subsystem
gatewizard/utils/analysis-style modules are split by engine:
- gromacs_analysis.py
- namd_analysis.py
- openmm_analysis.py
The tests/analysis_examples/ directory contains many end-to-end example scripts and saved outputs, which implies the analysis layer consumes trajectories/logs from each engine and produces summaries or plots with MDAnalysis/Matplotlib-style tooling.
10. External scientific dependencies
The architecture depends on several external tools that materially shape the flow:
- AmberTools / Parmed for topology and structure preparation
- Propka for pKa/protonation assignment
- MemPrO for membrane protein orientation
- NAMD, GROMACS, and OpenMM as execution backends
- RDKit and MDAnalysis for chemistry/trajectory support
These are not just libraries; they define the boundaries between internal orchestration and external scientific computation.
11. State, artifacts, and job tracking
The repo stores many intermediate and final artifacts on disk rather than in memory: prepared PDBs, prmtop/inpcrd files, restraint files, protocol summaries, logs, and status JSON. That implies the architecture is file-centric and workflow-oriented, with file_manager and job_monitor coordinating progress across stages.
12. Documentation, release, and validation
docs/ is a full MkDocs documentation site, while .github/workflows/ automates releases, docs deployment, and PyPI publishing. tests/ contains both unit tests and extensive fixture-based example workflows, which mirrors the real pipeline structure and is useful for validating architecture around each stage boundary.
Main entry points: builder.py Builder · equilibration.py Equilibration · tests Examples · preparation.py Preparation
Components 21
App
User entrypoints and orchestration
- Main app · Desktop/CLI launch path that enters the package workflows
gatewizard/main.py
Core
System preparation and workflow coordination
- Builder · Assembles prepared systems from structure, membrane, and ligands
gatewizard/core/builder.py - Preparation · Protein cleanup, repair, protonation, and prep logic
gatewizard/core/preparation.py - Structure mgmt · Inspection and manipulation of structural inputs
gatewizard/core/structure_manager.py - MemPro bridge · Membrane-protein orientation and membrane setup integration
gatewizard/core/mempro.py - File manager · Project folders and generated artifact handling
gatewizard/core/file_manager.py - Job monitor · Tracks long-running external jobs and status updates
gatewizard/core/job_monitor.py
Tools
User-facing workflow helpers
- Equilibration · Builds engine-specific simulation protocols
gatewizard/tools/equilibration.py - Force fields · Force-field selection and mapping support
gatewizard/tools/force_fields.py - Ligand prep · Generates ligand parameters for downstream workflows
gatewizard/tools/ligand_parametrization.py - Validators · Input and state validation for user-facing workflows
gatewizard/tools/validators.py
Utils
Shared scientific helpers and analysis
- Capping · Terminal capping and protein-specific preparation helpers
gatewizard/utils/protein_capping.py - Config · Central configuration and runtime options
gatewizard/utils/config.py - Helpers · Common utility functions used across workflows
gatewizard/utils/helpers.py - Bilayer utils · Membrane/bilayer construction helpers
gatewizard/utils/bilayer_utils.py - Analysis · Engine-specific trajectory and log analysis helpers
gatewizard/utils/gromacs_analysis.py
Equilibration
Engine-specific protocol templates and scripts
- Protocol templates · Static equilibration inputs for GROMACS, NAMD, and OpenMM
equilibration - OpenMM scripts · OpenMM runtime helpers for reading inputs, restraints, and execution
equilibration/openmm/scripts
CI
Release and publishing automation
- GitHub Actions · Release, docs deployment, and PyPI publishing workflows
.github/workflows
Tests
Example workflows and fixtures
- Examples · End-to-end example workflows and saved outputs for validation
tests
Connections 25
- Main app → Builder: launches · Application entrypoint routes into core orchestration
- Main app → Equilibration: exposes · Main app surfaces user-facing equilibration workflow
- Builder → Preparation: uses · Builder coordinates protein preparation steps
- Builder → Structure mgmt: uses · Builder depends on structural inspection and editing
- Builder → MemPro bridge: uses · Builder integrates membrane-protein setup when needed
- Builder → File manager: writes · Prepared systems and artifacts are persisted to project folders
- Builder → Job monitor: tracks · Long-running stages report status and progress
- Equilibration → Force fields: selects · Equilibration workflows depend on force-field decisions
- Equilibration → Ligand prep: coordinates · Ligand parameterization feeds the equilibration setup
- Equilibration → Validators: checks · Workflow inputs and state are validated before generation
- Equilibration → Protocol templates: renders · Protocol templates are materialized into runnable inputs
- Equilibration → OpenMM scripts: generates · OpenMM workflows use helper scripts at the runtime boundary
- Preparation → Capping: calls · Protein cleanup can cap termini and related endpoints
- Preparation → Config: reads · Preparation behavior is parameterized by configuration
- Preparation → Helpers: uses · Shared helpers support cleanup and prep logic
- MemPro bridge → Bilayer utils: uses · Membrane workflows use bilayer construction helpers
- MemPro bridge → File manager: stores · Membrane preparation artifacts are written to disk
- Analysis → Protocol templates: consumes · Analysis operates on outputs from engine-specific equilibration runs
- Docs site → Main app: documents · Docs explain the application entrypoint and workflows
- GitHub Actions → Docs site: deploys · Workflow publishes the documentation site
- GitHub Actions → Main app: releases · Workflow automates package release and publishing
- Examples → Builder: validates · Builder examples mirror system-preparation flows
- Examples → Equilibration: validates · Equilibration examples capture template-driven protocol generation
- Examples → Analysis: validates · Analysis examples exercise engine-specific post-processing
- Examples → MemPro bridge: validates · Membrane examples cover orientation and bilayer setup