How dptech-corp/uni-gbsa works
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: pipeline.py Pipeline orchestration · gbsarun.py MM/GB(PB)SA runner · mdrun.py GROMACS simulation runner · scan.py Affinity parameter scan
Components 19
Entry & Orchestration
- CLI dispatcher · Selects workflow mode and arguments.
unigbsa/CLI.py - Pipeline orchestration · Coordinates preparation, simulation, and scoring.
unigbsa/pipeline.py - Default workflow policy
unigbsa/data/default.ini
System Preparation & Simulation
- Topology construction · Builds GROMACS-compatible protein–ligand systems.
unigbsa/simulation/topology.py - GROMACS simulation runner · Runs direct evaluation, minimization, or MD.
unigbsa/simulation/mdrun.py - OpenMM minimization · Alternative OpenMM energy-minimization path.
unigbsa/simulation/openmm-em.py - GROMACS stage inputs · Defines ions, minimization, NVT/NPT, and production stages.
Energy Calculation
- MM/PBSA input
unigbsa/data/mmpbsa.in - MM/GB(PB)SA runner · Converts prepared systems and trajectories into binding energies.
unigbsa/gbsa/gbsarun.py - GBSA I/O
unigbsa/gbsa/io.py - GBSA parameters
unigbsa/gbsa/parameters.py - Energy & decomposition outputs
Batch & Parameter Optimization
- Affinity parameter scan · Fits calculation settings against known affinities.
unigbsa/scanparas/scan.py - Scan templates
unigbsa/data/scan.json - Scan result template
unigbsa/data/template.json
Distribution & Deployment
- Package installation · Defines package metadata and console scripts.
setup.py - Container runtime
containers/Dockerfile - CI/CD & publication
.github/workflows/CI.yml
Other components
- Scientific runtimes · GROMACS, ACPYPE/GAFF, gmx_MMPBSA, OpenMPI, and OpenMM.
Connections 23
- 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