# dptech-corp/uni-gbsa architecture

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

- Interactive diagram: https://gitdiagram.com/dptech-corp/uni-gbsa
- Repository: https://github.com/dptech-corp/uni-gbsa

## Overview

#### Purpose and Entry Points
Uni-GBSA is a Python workflow package for protein–ligand binding free-energy estimation via MM/GB(PB)SA, supporting individual ligands, batch virtual screening, trajectory analysis, and parameter scanning. CLI dispatch is centralized in `unigbsa/CLI.py`; primary orchestration is in `unigbsa/pipeline.py`. Package metadata and console-script installation are defined by `setup.py`.

#### Primary Pipeline
The standard pipeline accepts a receptor PDB plus MOL/SDF ligands, then prepares topology, optionally optimizes/simulates each complex, runs MM/GB(PB)SA, and writes energy/decomposition outputs. The principal control boundary is `unigbsa/pipeline.py`, with default simulation and GBSA policy loaded from `unigbsa/data/default.ini` and MM/PBSA input from `unigbsa/data/mmpbsa.in`.

#### Topology and System Construction
Protein and ligand preparation produces GROMACS-compatible topology/system artifacts. This layer is implemented in `unigbsa/simulation/topology.py` and relies externally on GROMACS plus ACPYPE/GAFF-family ligand parameterization. It separates chemistry/topology generation from subsequent simulation execution.

#### Simulation Execution
Simulation modes include direct input-pose evaluation, energy minimization, and MD. `unigbsa/simulation/mdrun.py` drives runs, while `unigbsa/simulation/openmm-em.py` provides an OpenMM-based minimization path. GROMACS MDP stage definitions—ions, minimization, NVT/NPT, production MD—live under `unigbsa/simulation/mdp/`, making engine-specific execution inputs an explicit boundary.

#### GBSA/PBSA Calculation and Results
`unigbsa/gbsa/gbsarun.py` invokes the MM/GB(PB)SA calculation flow, backed by `unigbsa/gbsa/io.py` for result/input handling and `unigbsa/gbsa/parameters.py` for calculation parameters. This layer integrates the external `gmx_MMPBSA` runtime and converts simulation structures/trajectories plus topology/index groups into binding-energy results.

#### Parameter Scanning and Batch Evaluation
Parameter optimization for known experimental affinities is isolated in `unigbsa/scanparas/scan.py`; scan defaults/templates are in `unigbsa/data/scan.json` and `unigbsa/data/template.json`. The same pipeline model supports many ligands for one receptor, enabling virtual-screening throughput with configurable thread counts.

#### Runtime, Distribution, and Deployment
The material runtime is Python with Conda-installed GROMACS, `gmx_MMPBSA`, ACPYPE, OpenMPI, and mpi4py; OpenMM is also represented in the simulation layer. Containerized execution is supplied by `containers/Dockerfile` and related environment/deployment Dockerfiles. CI/CD and package publication are defined in `.github/workflows/CI.yml`, `.github/workflows/CD.yml`, and `.github/workflows/python-publish.yml`.

Main entry points: [`unigbsa/pipeline.py`](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/pipeline.py) (Pipeline orchestration), [`unigbsa/gbsa/gbsarun.py`](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/gbsa/gbsarun.py) (MM/GB(PB)SA runner), [`unigbsa/simulation/mdrun.py`](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/simulation/mdrun.py) (GROMACS simulation runner), [`unigbsa/scanparas/scan.py`](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/scanparas/scan.py) (Affinity parameter scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Orchestration"]
  node_cli["CLI dispatcher<br/>Python CLI<br/>[CLI.py]"]
  node_pipeline["Pipeline orchestration<br/>Python workflow<br/>[pipeline.py]"]
  node_defaults["Default workflow policy<br/>INI defaults<br/>[default.ini]"]
end

subgraph group_simulation["System Preparation &amp; Simulation"]
  node_topology["Topology construction<br/>Python preparation<br/>[topology.py]"]
  node_mdrun["GROMACS simulation runner<br/>Python execution<br/>[mdrun.py]"]
  node_openmm_em["OpenMM minimization<br/>Python execution<br/>[openmm-em.py]"]
  node_mdp["GROMACS stage inputs<br/>MDP definitions"]
end

subgraph group_gbsa["Energy Calculation"]
  node_mmpbsa_input["MM/PBSA input<br/>Calculation input<br/>[mmpbsa.in]"]
  node_gbsarun["MM/GB&#40;PB&#41;SA runner<br/>Python calculation<br/>[gbsarun.py]"]
  node_gbsa_io["GBSA I/O<br/>Python result handling<br/>[io.py]"]
  node_gbsa_parameters["GBSA parameters<br/>Python parameters<br/>[parameters.py]"]
  node_results["Energy &amp; decomposition outputs<br/>Workflow artifacts"]
end

subgraph group_optimization["Batch &amp; Parameter Optimization"]
  node_scan["Affinity parameter scan<br/>Python optimization<br/>[scan.py]"]
  node_scan_defaults["Scan templates<br/>JSON templates<br/>[scan.json]"]
  node_scan_template["Scan result template<br/>JSON template<br/>[template.json]"]
end

subgraph group_delivery["Distribution &amp; Deployment"]
  node_package["Package installation<br/>Python packaging<br/>[setup.py]"]
  node_container["Container runtime<br/>Docker image"]
  node_ci["CI/CD &amp; publication<br/>GitHub Actions<br/>[CI.yml]"]
end

node_external_tools{{"Scientific runtimes<br/>External tools"}}

node_package -->|"installs console script"| node_cli
node_cli -->|"dispatches"| node_pipeline
node_pipeline -->|"loads policy"| node_defaults
node_pipeline -->|"prepares receptor and ligands"| node_topology
node_topology -->|"uses GROMACS and ACPYPE/GAFF"| node_external_tools
node_pipeline -->|"runs selected simulation mode"| node_mdrun
node_pipeline -.->|"can minimize with"| node_openmm_em
node_mdrun -->|"consumes stages"| node_mdp
node_mdrun -->|"executes GROMACS"| node_external_tools
node_openmm_em -->|"uses OpenMM"| node_external_tools
node_topology -->|"provides topology and index groups"| node_gbsarun
node_mdrun -->|"provides structures and trajectories"| node_gbsarun
node_pipeline -->|"requests scoring"| node_gbsarun
node_gbsarun -->|"uses calculation input"| node_mmpbsa_input
node_gbsarun -->|"reads and writes results"| node_gbsa_io
node_gbsarun -->|"applies parameters"| node_gbsa_parameters
node_gbsarun -->|"invokes gmx_MMPBSA"| node_external_tools
node_gbsa_io -->|"writes"| node_results
node_scan -->|"evaluates parameter candidates"| node_pipeline
node_scan -->|"loads scan defaults"| node_scan_defaults
node_scan -->|"uses output template"| node_scan_template
node_container -->|"provides runtime environment"| node_external_tools
node_ci -->|"tests and publishes"| node_package

click node_cli "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/CLI.py"
click node_pipeline "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/pipeline.py"
click node_defaults "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/data/default.ini"
click node_mmpbsa_input "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/data/mmpbsa.in"
click node_topology "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/simulation/topology.py"
click node_mdrun "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/simulation/mdrun.py"
click node_openmm_em "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/simulation/openmm-em.py"
click node_gbsarun "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/gbsa/gbsarun.py"
click node_gbsa_io "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/gbsa/io.py"
click node_gbsa_parameters "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/gbsa/parameters.py"
click node_scan "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/scanparas/scan.py"
click node_scan_defaults "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/data/scan.json"
click node_scan_template "https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/data/template.json"
click node_package "https://github.com/dptech-corp/uni-gbsa/blob/master/setup.py"
click node_container "https://github.com/dptech-corp/uni-gbsa/blob/master/containers/Dockerfile"
click node_ci "https://github.com/dptech-corp/uni-gbsa/blob/master/.github/workflows/CI.yml"

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_cli,node_pipeline,node_defaults toneBlue
class node_topology,node_mdrun,node_openmm_em,node_mdp toneAmber
class node_mmpbsa_input,node_gbsarun,node_gbsa_io,node_gbsa_parameters,node_results toneMint
class node_scan,node_scan_defaults,node_scan_template toneRose
class node_package,node_container,node_ci toneIndigo
class node_external_tools toneNeutral
```

## Components

### Entry & Orchestration

- [CLI dispatcher](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/CLI.py): Python CLI · Selects workflow mode and arguments. · `unigbsa/CLI.py`
- [Pipeline orchestration](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/pipeline.py): Python workflow · Coordinates preparation, simulation, and scoring. · `unigbsa/pipeline.py`
- [Default workflow policy](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/data/default.ini): INI defaults · `unigbsa/data/default.ini`

### System Preparation & Simulation

- [Topology construction](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/simulation/topology.py): Python preparation · Builds GROMACS-compatible protein–ligand systems. · `unigbsa/simulation/topology.py`
- [GROMACS simulation runner](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/simulation/mdrun.py): Python execution · Runs direct evaluation, minimization, or MD. · `unigbsa/simulation/mdrun.py`
- [OpenMM minimization](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/simulation/openmm-em.py): Python execution · Alternative OpenMM energy-minimization path. · `unigbsa/simulation/openmm-em.py`
- **GROMACS stage inputs**: MDP definitions · Defines ions, minimization, NVT/NPT, and production stages.

### Energy Calculation

- [MM/PBSA input](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/data/mmpbsa.in): Calculation input · `unigbsa/data/mmpbsa.in`
- [MM/GB(PB)SA runner](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/gbsa/gbsarun.py): Python calculation · Converts prepared systems and trajectories into binding energies. · `unigbsa/gbsa/gbsarun.py`
- [GBSA I/O](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/gbsa/io.py): Python result handling · `unigbsa/gbsa/io.py`
- [GBSA parameters](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/gbsa/parameters.py): Python parameters · `unigbsa/gbsa/parameters.py`
- **Energy & decomposition outputs**: Workflow artifacts

### Batch & Parameter Optimization

- [Affinity parameter scan](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/scanparas/scan.py): Python optimization · Fits calculation settings against known affinities. · `unigbsa/scanparas/scan.py`
- [Scan templates](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/data/scan.json): JSON templates · `unigbsa/data/scan.json`
- [Scan result template](https://github.com/dptech-corp/uni-gbsa/blob/master/unigbsa/data/template.json): JSON template · `unigbsa/data/template.json`

### Distribution & Deployment

- [Package installation](https://github.com/dptech-corp/uni-gbsa/blob/master/setup.py): Python packaging · Defines package metadata and console scripts. · `setup.py`
- [Container runtime](https://github.com/dptech-corp/uni-gbsa/blob/master/containers/Dockerfile): Docker image · `containers/Dockerfile`
- [CI/CD & publication](https://github.com/dptech-corp/uni-gbsa/blob/master/.github/workflows/CI.yml): GitHub Actions · `.github/workflows/CI.yml`

### Other components

- **Scientific runtimes**: External tools · GROMACS, ACPYPE/GAFF, gmx_MMPBSA, OpenMPI, and OpenMM.

## Connections

- Package installation → CLI dispatcher: installs console script
- CLI dispatcher → Pipeline orchestration: dispatches
- Pipeline orchestration → Default workflow policy: loads policy
- Pipeline orchestration → Topology construction: prepares receptor and ligands
- Topology construction → Scientific runtimes: uses GROMACS and ACPYPE/GAFF
- Pipeline orchestration → GROMACS simulation runner: runs selected simulation mode
- Pipeline orchestration → OpenMM minimization: can minimize with
- GROMACS simulation runner → GROMACS stage inputs: consumes stages
- GROMACS simulation runner → Scientific runtimes: executes GROMACS
- OpenMM minimization → Scientific runtimes: uses OpenMM
- Topology construction → MM/GB(PB)SA runner: provides topology and index groups
- GROMACS simulation runner → MM/GB(PB)SA runner: provides structures and trajectories
- Pipeline orchestration → MM/GB(PB)SA runner: requests scoring
- MM/GB(PB)SA runner → MM/PBSA input: uses calculation input
- MM/GB(PB)SA runner → GBSA I/O: reads and writes results
- MM/GB(PB)SA runner → GBSA parameters: applies parameters
- MM/GB(PB)SA runner → Scientific runtimes: invokes gmx_MMPBSA
- GBSA I/O → Energy & decomposition outputs: writes
- Affinity parameter scan → Pipeline orchestration: evaluates parameter candidates
- Affinity parameter scan → Scan templates: loads scan defaults
- Affinity parameter scan → Scan result template: uses output template
- Container runtime → Scientific runtimes: provides runtime environment
- CI/CD & publication → Package installation: tests and publishes