# arifmaulanaazis/gmxauto architecture

> Architecture diagram of the GitHub repository arifmaulanaazis/gmxauto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arifmaulanaazis/gmxauto
- Repository: https://github.com/arifmaulanaazis/gmxauto

## Overview

##### Project Type & Purpose
- gmxauto is an open-source, desktop GUI tool (not a web full-stack app) for automating GROMACS 2025.1 molecular dynamics workflows on Windows.
- It wraps the official GROMACS binaries (both CUDA GPU and CPU builds), providing a PyQt6 interface and Python orchestration modules for preparing, executing, monitoring, and logging multi-step MD simulations.

##### File Structure & Architectural Indicators
- Top-level Python modules:
- main.py – entry point
- gui_main.py – PyQt6 window & view layer
- command_runner.py – subprocess wrapper for GROMACS calls
- environment_manager.py – selects/configures GPU vs. CPU GROMACS PATH
- mdp_file_manager.py – prepares/validates .mdp parameter files
- gpu_command_builder.py – constructs CUDA-enabled command-line flags
- simulation_worker.py – orchestrates MD steps (energy minimization → equilibration → production) and log parsing
- gambar.py – application-level logging & progress display
- Vendor directories:
- gmx/… – bundled CUDA GROMACS binaries, libs, includes, force-fields, man pages
- gmx_cpu/… – bundled CPU-only GROMACS build
- README.md confirms PyQt6 front-end and Python back-end, with external dependency on GROMACS binaries.

a. User Interface (View)
- PyQt6 GUI (gui_main.py)
- Widgets to select CHARMM-GUI folder, hardware (GPU/CPU), simulation parameters
b. Controller / Orchestration Layer
- main.py: initializes GUI and thread pool
- simulation_worker.py: runs tasks in background threads
- environment_manager.py: points PATH to either gmx/ or gmx_cpu/
c. Model / Utility Modules
- mdp_file_manager.py: generates and validates .mdp files
- gpu_command_builder.py: builds GPU-specific "gmx mdrun" arguments
- command_runner.py: executes built commands, streams stdout/stderr
- gambar.py: captures logs in gmxauto.log and updates GUI progress
d. External Service / Dependencies
- GROMACS executables & libraries in gmx/ (CUDA) or gmx_cpu/ (CPU)
- File system: input (.gro/.top/.mdp), output (.xtc/.trr/.log/.cpt), structured result folders
- (Optional) Analysis tools: VMD, MDAnalysis, PyMOL (external post-processing)

##### Relationships & Data Flows
- User clicks “Run” → GUI triggers simulation_worker
- simulation_worker asks environment_manager to set PATH
- simulation_worker calls mdp_file_manager & gpu_command_builder → build input files & command arguments
- simulation_worker invokes command_runner → subprocess → gmx[.exe] (in gmx/ or gmx_cpu/)
- command_runner streams logs to gambar.py → GUI progress bar & gmxauto.log
- simulation_worker sequences steps: energy minimization → equilibration → production
- Outputs are collected in an organized directory per simulation
- Upon completion or failure, GUI notifies user and offers logs/viewers

##### Architectural Patterns & Principles
- MVC-inspired separation: gui_main.py (View), simulation_worker.py + main.py (Controller), mdp_file_manager/gpu_command_builder (Model/Business Logic)
- Modular design for hardware-specific differences (environment_manager toggles between two GROMACS installs)
- Threaded worker pattern (simulation_worker) to keep UI responsive
- Single responsibility for utility modules (command_runner only deals with subprocess, mdp_file_manager only with file formats)

##### Essential Elements
- Clear labels (module names, data formats)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% File System
    R1["README.md"]:::fs

    %% Application Layer
    subgraph "Application Layer"
        subgraph "Front-end (View)"
            GUI["PyQt6 GUI<br/>gui_main.py"]:::python
            Main["main.py"]:::python
        end
        subgraph "Controller & Business Logic"
            Worker["simulation_worker (Thread)<br/>simulation_worker.py"]:::python
            EnvMgr["environment_manager<br/>environment_manager.py"]:::python
            MDPMgr["mdp_file_manager<br/>mdp_file_manager.py"]:::python
            GPUBuilder["gpu_command_builder<br/>gpu_command_builder.py"]:::python
            CmdRunner["command_runner<br/>command_runner.py"]:::python
            Logger["gambar (Logging & Progress)<br/>gambar.py"]:::python
        end
    end

    %% GROMACS Layer
    subgraph "GROMACS Layer"
        GpuBin["gmx/bin/gmx.exe (CUDA)"]:::external
        CpuBin["gmx_cpu/bin/gmx.exe (CPU)"]:::external
    end

    %% File System I/O
    subgraph "File System"
        Inputs[".gro/.top/.mdp Inputs"]:::fs
        Outputs[".xtc/.log/.cpt Results"]:::fs
    end

    %% Connections
    R1 --> Main
    Main --> GUI
    GUI -->|"Run Click"| Worker
    Worker --> EnvMgr
    EnvMgr --> GpuBin
    EnvMgr --> CpuBin
    Worker --> MDPMgr
    Worker --> GPUBuilder
    MDPMgr -->|"prepare files"| CmdRunner
    GPUBuilder -->|"build flags"| CmdRunner
    CmdRunner -->|"exec"| GpuBin
    CmdRunner -->|"exec"| CpuBin
    CmdRunner -->|"stream logs"| Logger
    Logger --> GUI
    Worker --> Inputs
    Worker --> Outputs
    Worker --> GUI

    %% Click Events
    click R1 "https://github.com/arifmaulanaazis/gmxauto/blob/main/README.md"
    click Main "https://github.com/arifmaulanaazis/gmxauto/blob/main/main.py"
    click GUI "https://github.com/arifmaulanaazis/gmxauto/blob/main/gui_main.py"
    click Worker "https://github.com/arifmaulanaazis/gmxauto/blob/main/simulation_worker.py"
    click EnvMgr "https://github.com/arifmaulanaazis/gmxauto/blob/main/environment_manager.py"
    click MDPMgr "https://github.com/arifmaulanaazis/gmxauto/blob/main/mdp_file_manager.py"
    click GPUBuilder "https://github.com/arifmaulanaazis/gmxauto/blob/main/gpu_command_builder.py"
    click CmdRunner "https://github.com/arifmaulanaazis/gmxauto/blob/main/command_runner.py"
    click Logger "https://github.com/arifmaulanaazis/gmxauto/blob/main/gambar.py"
    click GpuBin "https://github.com/arifmaulanaazis/gmxauto/blob/main/gmx/bin/gmx.exe"
    click CpuBin "https://github.com/arifmaulanaazis/gmxauto/blob/main/gmx_cpu/bin/gmx.exe"

    %% Styles
    classDef python fill:#8ecae6,stroke:#023047,color:#000;
    classDef external fill:#a7c957,stroke:#023047,color:#000;
    classDef fs fill:#ffb703,stroke:#023047,color:#000;
```
