# biocoder007/jiggle architecture

> Architecture diagram of the GitHub repository biocoder007/jiggle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/biocoder007/jiggle
- Repository: https://github.com/biocoder007/jiggle

## Overview

Jiggle is a desktop molecular-dynamics application for running OpenMM simulations while viewing the evolving protein structure and live metrics. The user selects a PDB and simulation settings; the worker repairs and prepares the structure, minimizes and equilibrates it, then streams production frames and metrics to the UI, which updates the viewer and plots and supports saving results. The README documents additional capabilities such as pause/resume, chain detection, frame saving, and exports. Some worker and UI code was only excerpted, so undocumented links are omitted.

Main entry points: [`ui/main_window.py`](https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py) (Main window), [`core/simulation_worker.py`](https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py) (Simulation worker), [`main.py`](https://github.com/biocoder007/jiggle/blob/main/main.py) (App launcher), [`core/analysis.py`](https://github.com/biocoder007/jiggle/blob/main/core/analysis.py) (Metric calculations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_launcher["App launcher<br/>[main.py]"]
  node_controls["Run configuration<br/>[main_window.py]"]
  node_structure_input["Structure input<br/>[main_window.py]"]
  node_window["Main window<br/>[main_window.py]"]
end

subgraph group_simulation["Simulation workflow"]
  node_worker["Simulation worker"]
  node_preparation["Structure preparation"]
  node_forcefields["Force-field catalogue<br/>[forcefields.py]"]
  node_dynamics["Minimize and equilibrate"]
  node_production["Production dynamics"]
end

subgraph group_analysis["Live analysis"]
  node_metrics["Metric calculations<br/>[analysis.py]"]
  node_metric_stream["Frame and metric stream"]
end

subgraph group_results["Viewing and results"]
  node_viewer["3D structure viewer"]
  node_plots["Live plots<br/>[main_window.py]"]
  node_result_export["Result export<br/>[main_window.py]"]
end

node_user(("User"))
node_md_libraries["OpenMM and PDBFixer"]

node_user -->|"starts app"| node_launcher
node_launcher -->|"opens window"| node_window
node_user -->|"sets options"| node_controls
node_user -->|"chooses PDB"| node_structure_input
node_controls -->|"configures run"| node_window
node_structure_input -->|"supplies structure"| node_window
node_window -->|"populates choices"| node_forcefields
node_window -->|"starts worker"| node_worker
node_worker -->|"resolves parameters"| node_forcefields
node_worker -->|"prepares structure"| node_preparation
node_preparation -->|"repairs structure"| node_md_libraries
node_worker -->|"runs preparation"| node_dynamics
node_dynamics -->|"builds and runs system"| node_md_libraries
node_worker -->|"runs production"| node_production
node_production -->|"advances simulation"| node_md_libraries
node_worker -->|"calculates metrics"| node_metrics
node_metrics -->|"returns measurements"| node_metric_stream
node_worker -->|"emits frames"| node_metric_stream
node_metric_stream -->|"delivers updates"| node_window
node_window -->|"updates coordinates"| node_viewer
node_window -->|"updates plots"| node_plots
node_user -->|"requests export"| node_result_export
node_window -->|"exports results"| node_result_export
node_user -.->|"pauses or resumes"| node_worker
node_user -.->|"saves live frame"| node_viewer

click node_launcher "https://github.com/biocoder007/jiggle/blob/main/main.py"
click node_controls "https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py"
click node_structure_input "https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py"
click node_worker "https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py"
click node_preparation "https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py"
click node_forcefields "https://github.com/biocoder007/jiggle/blob/main/core/forcefields.py"
click node_dynamics "https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py"
click node_production "https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py"
click node_metrics "https://github.com/biocoder007/jiggle/blob/main/core/analysis.py"
click node_metric_stream "https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py"
click node_window "https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py"
click node_viewer "https://github.com/biocoder007/jiggle/blob/main/ui/viewer_template.html"
click node_plots "https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py"
click node_result_export "https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_controls,node_structure_input,node_window,node_user toneBlue
class node_worker,node_preparation,node_forcefields,node_dynamics,node_production toneAmber
class node_metrics,node_metric_stream toneMint
class node_viewer,node_plots,node_result_export toneRose
class node_md_libraries toneIndigo
```

## Components

### Desktop interface

- [App launcher](https://github.com/biocoder007/jiggle/blob/main/main.py): `main.py`
- [Run configuration](https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py): `ui/main_window.py`
- [Structure input](https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py): `ui/main_window.py`
- [Main window](https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py): `ui/main_window.py`

### Simulation workflow

- [Simulation worker](https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py): `core/simulation_worker.py`
- [Structure preparation](https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py): `core/simulation_worker.py`
- [Force-field catalogue](https://github.com/biocoder007/jiggle/blob/main/core/forcefields.py): `core/forcefields.py`
- [Minimize and equilibrate](https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py): `core/simulation_worker.py`
- [Production dynamics](https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py): `core/simulation_worker.py`

### Live analysis

- [Metric calculations](https://github.com/biocoder007/jiggle/blob/main/core/analysis.py): `core/analysis.py`
- [Frame and metric stream](https://github.com/biocoder007/jiggle/blob/main/core/simulation_worker.py): `core/simulation_worker.py`

### Viewing and results

- [3D structure viewer](https://github.com/biocoder007/jiggle/blob/main/ui/viewer_template.html): `ui/viewer_template.html`
- [Live plots](https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py): `ui/main_window.py`
- [Result export](https://github.com/biocoder007/jiggle/blob/main/ui/main_window.py): `ui/main_window.py`

### Other components

- **User**
- **OpenMM and PDBFixer**

## Connections

- User → App launcher: starts app (evidence: `README.md`)
- App launcher → Main window: opens window (evidence: `main.py`)
- User → Run configuration: sets options (evidence: `README.md`)
- User → Structure input: chooses PDB (evidence: `README.md`)
- Run configuration → Main window: configures run (evidence: `ui/main_window.py`)
- Structure input → Main window: supplies structure (evidence: `README.md`)
- Main window → Force-field catalogue: populates choices (evidence: `ui/main_window.py`)
- Main window → Simulation worker: starts worker (evidence: `ui/main_window.py`)
- Simulation worker → Force-field catalogue: resolves parameters (evidence: `core/simulation_worker.py`)
- Simulation worker → Structure preparation: prepares structure (evidence: `README.md`)
- Structure preparation → OpenMM and PDBFixer: repairs structure (evidence: `README.md`)
- Simulation worker → Minimize and equilibrate: runs preparation (evidence: `README.md`)
- Minimize and equilibrate → OpenMM and PDBFixer: builds and runs system (evidence: `core/simulation_worker.py`)
- Simulation worker → Production dynamics: runs production (evidence: `README.md`)
- Production dynamics → OpenMM and PDBFixer: advances simulation (evidence: `README.md`)
- Simulation worker → Metric calculations: calculates metrics (evidence: `core/simulation_worker.py`)
- Metric calculations → Frame and metric stream: returns measurements (evidence: `core/simulation_worker.py`)
- Simulation worker → Frame and metric stream: emits frames (evidence: `README.md`)
- Frame and metric stream → Main window: delivers updates (evidence: `README.md`)
- Main window → 3D structure viewer: updates coordinates (evidence: `README.md`)
- Main window → Live plots: updates plots (evidence: `ui/main_window.py`)
- User → Result export: requests export (evidence: `README.md`)
- Main window → Result export: exports results (evidence: `ui/main_window.py`)
- User → Simulation worker: pauses or resumes (evidence: `README.md`)
- User → 3D structure viewer: saves live frame (evidence: `README.md`)