From ca77b07d659738420754be9f5b1996b641c8d71e Mon Sep 17 00:00:00 2001 From: David-Araripe Date: Tue, 18 Nov 2025 10:20:28 +0100 Subject: [PATCH 1/8] Update project.scripts order with a logical sequence of the commands we use to submit FEP calculations --- pyproject.toml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 1a81ef7f..e83b99ce 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -90,13 +90,13 @@ ignore = [ ] [project.scripts] -qligfep = "QligFEP.CLI.qligfep_cli:main_exe" -qmapfep = "QligFEP.CLI.qmapfep_cli:main_exe" -setupFEP = "QligFEP.CLI.setupFEP:main_exe" +qcog = "QligFEP.CLI.cog_cli:main_exe" +pdb2amber = "QligFEP.CLI.pdb_to_amber:main_exe" +qprep_prot = "QligFEP.CLI.qprep_cli:main_exe" qparams = "QligFEP.CLI.qparams_cli:main_exe" qlomap = "QligFEP.CLI.lomap_wrap_cli:main_exe" -pdb2amber = "QligFEP.CLI.pdb_to_amber:main_exe" +qmapfep = "QligFEP.CLI.qmapfep_cli:main_exe" +qligfep = "QligFEP.CLI.qligfep_cli:main_exe" +setupFEP = "QligFEP.CLI.setupFEP:main_exe" qligfep_analyze = "QligFEP.analyze_FEP:main_exe" -qprep_prot = "QligFEP.CLI.qprep_cli:main_exe" -qcog = "QligFEP.CLI.cog_cli:main_exe" ligalign = "QligFEP.CLI.lig_align_cli:main_exe" \ No newline at end of file From d14b363ed82d045c096d1ed9b13802dba6be5d1d Mon Sep 17 00:00:00 2001 From: David-Araripe Date: Tue, 18 Nov 2025 10:21:05 +0100 Subject: [PATCH 2/8] Update readme; reorder project scripts and add note about Q-GPU --- README.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 55268e96..24e31df7 100644 --- a/README.md +++ b/README.md @@ -75,15 +75,16 @@ Check [here](/src/QligFEP/settings/settings.py) for a list of different HPCs we Now you're set with the qligfep package. This includes the command-linde-interfaces (CLIs): -1. `qparams`: used to generate ligand parameters; +1. `qcog`: calculates the center of geometry (COG) of a ligand in a PDB/SDF file. If multiple ligands are found in sdf, the program will calculate the COG for all of them 2. `pdb2amber`: formats a PDB file to be used with Q's implementation of the AMBER forcefield; -3. `qlomap`: wraps `Lomap` to generate the `.json` perturbation mapping; -4. `qmapfep`: in-house developed method to generate the `.json` perturbation mapping, interactively visualize and add or remove edges. -5. `qligfep`: main CLI for running QligFEP simulations. -6. `setupFEP`: sets up all the the QligFEP files for a simulation, including protein and water systems. -7. `qligfep_analyze`: CLI to analyze the results of a QligFEP simulation. -8. `qcog`: calculates the center of geometry (COG) of a ligand in a PDB/SDF file. If multiple ligands are found in sdf, the program will calculate the COG for all of them -9. `qprep_prot`: creates an input file for qprep (fortran program) and runs it to either: 1) solvate the protein structure; 2) create the water sphere. +3. `qprep_prot`: creates an input file for qprep (fortran program) and runs it to either: 1) solvate the protein structure; 2) create the water sphere. +4. `qparams`: used to generate ligand parameters; +5. `qlomap`: wraps `Lomap` to generate the `.json` perturbation mapping; +6. `qmapfep`: in-house developed method to generate the `.json` perturbation mapping, interactively visualize and add or remove edges. +7. `qligfep`: main CLI for running QligFEP simulations. +8. `setupFEP`: sets up all the the QligFEP files for a simulation, including protein and water systems. +9. `qligfep_analyze`: CLI to analyze the results of a QligFEP simulation. +10. `ligalign`: aligns a set of ligands to a reference ligand based on their maximum common substructure (MCS). # Citations: # Q6: https://doi.org/10.1016/j.softx.2017.12.001 @@ -95,6 +96,9 @@ QligFEP: https://doi.org/10.1186/s13321-019-0348-5 QresFEP: https://doi.org/10.1021/acs.jctc.9b00538 # Q-GPU # + +> Note: the Q-GPU version is under active development and a publication describing its methods and performance is in preparation. For now, please refrain from using this version until the publication is out. + Version control of **Q-GPU**, an adaptation of **Q** version 5.06 running on GPUs. **Q** is a set of Molecular Dynamics (MD) tools tailored to the following specific kinds of free energy calculations: From c5fbced730fd008bc93a3d9f0d0834ba03d9e4ca Mon Sep 17 00:00:00 2001 From: David-Araripe Date: Tue, 18 Nov 2025 10:28:09 +0100 Subject: [PATCH 3/8] add benchmarking section to the readme --- README.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 24e31df7..c2f124e9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,22 @@ # QligFEP +## Table of Contents +- [⚙️ Installation](#️-installation) + - [🐧 Linux](#-linux) + - [🍎 MacOS](#-macos) + - [🛠️ Compiling Q for HPC (MPI support)](#️-compiling-q-for-hpc-mpi-support) +- [⌨️ Command line interface (CLI)](#️-command-line-interface-cli) +- [📊 Benchmarking](#-benchmarking) +- [📚 Citations](#-citations) +- [Q-GPU](#q-gpu) + - [Authors](#authors) + - [Installation](#installation) + - [NOTE to the current version](#note-to-the-current-version) + - [Troubleshooting](#troubleshooting) + - [Testing](#testing) + - [Benchmarking](#benchmarking) +- [VERSION NOTES](#version-notes) + ## ⚙️ Installation We recommend that you use `mamba` or, preferably, its lightweight version `micromamba`. Please check this link on how to [install it](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html). @@ -86,7 +103,11 @@ Now you're set with the qligfep package. This includes the command-linde-interfa 9. `qligfep_analyze`: CLI to analyze the results of a QligFEP simulation. 10. `ligalign`: aligns a set of ligands to a reference ligand based on their maximum common substructure (MCS). -# Citations: # +# 📊 Benchmarking + +For QligFEP performance results, please refer to our [benchmarking repository](https://github.com/qusers/qligfepv2-BenchmarkExperiments). + +# 📚 Citations: # Q6: https://doi.org/10.1016/j.softx.2017.12.001 Q https://doi.org/10.1016/S1093-3263(98)80006-5 From 9b2e1c136a15842dad1440401608cf862ec474eb Mon Sep 17 00:00:00 2001 From: David-Araripe Date: Tue, 18 Nov 2025 11:03:58 +0100 Subject: [PATCH 4/8] add QligFEPv2 preprint citation to the #benchmarking section --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c2f124e9..9f8c2f79 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # QligFEP ## Table of Contents + - [⚙️ Installation](#️-installation) - [🐧 Linux](#-linux) - [🍎 MacOS](#-macos) @@ -105,7 +106,11 @@ Now you're set with the qligfep package. This includes the command-linde-interfa # 📊 Benchmarking -For QligFEP performance results, please refer to our [benchmarking repository](https://github.com/qusers/qligfepv2-BenchmarkExperiments). +To check and reproduce QligFEP performance results, please refer to our [benchmarking repository](https://github.com/qusers/qligfepv2-BenchmarkExperiments). + +For the preprint describing the benchmarking results, see: + +> Alencar Araripe D, Díaz Holguín A, Poso A, van Westen GJP, Åqvist J, Gutiérrez-de-Terán H, et al. QligFEP-2: an automated workflow for small molecule free energy calculations in Q. ChemRxiv. 2025; [doi:10.26434/chemrxiv-2025-x3r3z](https://doi.org/10.26434/chemrxiv-2025-x3r3z) # 📚 Citations: # Q6: https://doi.org/10.1016/j.softx.2017.12.001 From a8ae3845c7cdc70f63e07e6971db93134f27d9cd Mon Sep 17 00:00:00 2001 From: David-Araripe Date: Thu, 20 Nov 2025 10:48:25 +0100 Subject: [PATCH 5/8] update readme and move authors list to pyproject.toml --- README.md | 158 +++++++++++++++---------------------------------- pyproject.toml | 9 ++- 2 files changed, 57 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index 9f8c2f79..c874f354 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,25 @@ # QligFEP +**Q** is a set of Molecular Dynamics (MD) tools tailored to the following specific kinds of free energy calculations: + +1. Free Energy Perturbation (FEP) +2. Empirical Valence Bond (EVB) +3. Linear Interaction Energies (LIE) + +This repository is devoted to **QligFEP**, an automated workflow for small molecule free energy calculations in Q. + ## Table of Contents - [⚙️ Installation](#️-installation) - - [🐧 Linux](#-linux) - - [🍎 MacOS](#-macos) - - [🛠️ Compiling Q for HPC (MPI support)](#️-compiling-q-for-hpc-mpi-support) + - [Linux](#linux) + - [MacOS](#macos) + - [Compiling Q for HPC (MPI support)](#️compiling-q-for-hpc-mpi-support) - [⌨️ Command line interface (CLI)](#️-command-line-interface-cli) - [📊 Benchmarking](#-benchmarking) - [📚 Citations](#-citations) -- [Q-GPU](#q-gpu) - - [Authors](#authors) - - [Installation](#installation) - - [NOTE to the current version](#note-to-the-current-version) - - [Troubleshooting](#troubleshooting) +- [⏩ Q-GPU](#-q-gpu) + - [Note to the current version](#note-to-the-current-version) - [Testing](#testing) - - [Benchmarking](#benchmarking) -- [VERSION NOTES](#version-notes) ## ⚙️ Installation @@ -24,7 +27,7 @@ We recommend that you use `mamba` or, preferably, its lightweight version `micro Once you have `micromamba` installed and have already cloned this repo, you can create the environment with: -### 🐧 Linux +### Linux ```bash micromamba create -n qligfep_new python=3.11 micromamba activate qligfep_new @@ -46,7 +49,7 @@ micromamba create -n qligfep_new python=3.11 gfortran=11.3.0 openff-toolkit=0.16 ``` -### 🍎 MacOS +### MacOS Similar to Linux, [clone the repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository), enter the `Q` directory with `cd Q/`, create the environment and install: @@ -67,7 +70,7 @@ micromamba create -n qligfep_new python=3.11 gfortran=11.3.0 openff-toolkit=0.16 ``` -### 🛠️ Compiling Q for HPC (MPI support) +### Compiling Q for HPC (MPI support) > 🖥️ **For HPC users only**: If you need MPI support for parallel simulations on HPC systems, you'll need to manually compile the MPI version of Q. @@ -112,7 +115,7 @@ For the preprint describing the benchmarking results, see: > Alencar Araripe D, Díaz Holguín A, Poso A, van Westen GJP, Åqvist J, Gutiérrez-de-Terán H, et al. QligFEP-2: an automated workflow for small molecule free energy calculations in Q. ChemRxiv. 2025; [doi:10.26434/chemrxiv-2025-x3r3z](https://doi.org/10.26434/chemrxiv-2025-x3r3z) -# 📚 Citations: # +# 📚 Citations Q6: https://doi.org/10.1016/j.softx.2017.12.001 Q https://doi.org/10.1016/S1093-3263(98)80006-5 @@ -121,92 +124,18 @@ QligFEP: https://doi.org/10.1186/s13321-019-0348-5 QresFEP: https://doi.org/10.1021/acs.jctc.9b00538 -# Q-GPU # - -> Note: the Q-GPU version is under active development and a publication describing its methods and performance is in preparation. For now, please refrain from using this version until the publication is out. - -Version control of **Q-GPU**, an adaptation of **Q** version 5.06 running on GPUs. - -**Q** is a set of Molecular Dynamics (MD) tools tailored to the following specific kinds of free energy calculations: - -1. Free Energy Perturbation (FEP) -2. Empirical Valence Bond (EVB) -3. Linear Interaction Energies (LIE) - -This version includes a translation of the original **Q** fortran code to C/CUDA and Python. - - -## Authors ## -Chiel Jespers, David Araripe, Willem Jespers, Mauricio Esguerra, Johan Åqvist, Hugo Gutiérrez‐de‐Terán - - -## Installation ## -The frontend is built on Python and will run in versions > 3.6. It mainly uses native python libraries and only needs numpy as additional package with no further dependencies. - -To compile the qdyn engine source code, you need a CUDA compiler. The code has been tested with the following versions: - -- CUDA/10.1.243 - -To succesfully install and compile the code (Fortran): +# ⏩ Q-GPU -```bash -unset SSH_ASKPASS -mkdir ~/software -cd ~/software -git clone https://yourgitusernamehere@github.com/qusers/qgpu.git -cd Q -git checkout refactor/qligfep-david -cd src/q6 -make -``` - -After this, also install the python package. You should be able to do it through: -```bash -cd Q -conda env create -f environment.yml -conda activate qligfep_new -# make sure you have the correct environment installed -python -m pip install -e . -``` - -After succesful compilation of **Q-GPU** you have to add the program to your system path by modifying your shell initiation script. -If your shell is bash, you can add the following lines to your .bashrc file using a text editor. The following assumes that your user name is "johndoe" and the home directory is "/Users/johndoe/": - -```bash -SOFT=/Users/johndoe/software -export QDIR=$SOFT/qgpu -export PATH=$QDIR/bin:$QDIR/src:$PATH -``` -Where $SOFT will be the place where your software folder is located at, e.g. /Users/johndoe/software +**Q-GPU** is an adaptation of **Q** version 5.06 to run on GPUs. -Once the q binaries are declared in your path you should be able to call all q binaries from your terminal. -To test that the path to your compiled **Q** binaries has been correctly assigned you can issue the following commands in the terminal: - -```bash -source ~/.bashrc -env | grep qgpu - -QDIR=/Users/johndoe/software/qgpu -``` - -Additiontally you can search for the main **Q-GPU** binary file with: - -```bash -which qdyn -``` - - -## NOTE to the current version ## -The Qprep tool from **Q** is needed for the preparation of molecular topology files required by the MD engine Qdyn. Currently, Qprep is provided as fortran code, which compiles on CPUs. The workflow for a **Q-GPU** free energy simulation consists then in: +## Note to the current version +The Qprep tool from **Q** is needed for the preparation of molecular topology files required by the MD engine Qdyn. Currently, Qprep is provided as fortran code, which is compiled upon installation. The workflow for a **Q-GPU** free energy simulation consists then in: - An initial topology preparation stage that runs on a regular CPU - MD sampling using Qdyn, which runs on a CUDA-based GPU - The FEP analysis tool (qfep) provided in python (running both in GPU or CPU) - -## Troubleshooting ## -If you receive error messages during compilation please report them to the program authors including the compiler used (e.g. CUDA), the compiler version (e.e. 10.1.243), and the error message. - +> ⚠️ Integration with the QligFEP workflow is currently under active development and not yet available. For now, we only provide instructions to run our test cases.publication describing Q-GPU and its performance is in preparation Please refrain from using this version until the publication is out. ## Testing ## **Q-GPU** includes various tests that compare the output of the original fortran code with the C/CUDA code. They are situated in the test folder and include: @@ -214,26 +143,37 @@ If you receive error messages during compilation please report them to the progr 1. interactions 2. physical-properties -The first folder includes test cases for the different type of interactions in **Q**, that is water-water (w-w), solute-solute (p-p) and Qatom-Qatom (q-q) interactions, and any mixture thereof. -These tests run a single point energy calculation and are compared with the output from Q5.07. The tests can be run separately following the instructions in each folder, or all at once using the run_test.py script (TODO!). +The first folder includes test cases for the different type of interactions in **Q**, that is water-water (w-w), solute-solute (p-p) and Qatom-Qatom (q-q) interactions, and any mixture thereof. These tests run a single point energy calculation and are compared with the output from Q5.07. -In the second folder, we provide test cases for the calculation of solvation free energies of side-chain mimics, and several protein-ligand binding cases (CDk2 and A2aAR, TODO!). The details for such calculations are described in our QligFEP paper: +To compile the code and run the tests, you must checkout the GPU feature branch and build the components individually in their respective folders. -- Jespers et al. (). +**Prerequisites:** +* Installation of QligFEP environment as described above. +* A CUDA compiler (Tested on CUDA/10.1.243) -## Benchmarking ## +**Steps:** -We have included a benchmark set of water spheres of sizes 10-30A (in increments of 5). Table generated with https://www.tablesgenerator.com/markdown_tables +1. **Checkout the feature branch:** + ```bash + git checkout feature/qgpu + ``` -| sphere | cpu Intel(R) Xeon(R) CPU E5-2650 v4 @ 2.20GHz Time in seconds | gpu NVIDIA GeForce GTX 1080 Time in seconds | -|--------|:-------------------------------------------------------------:|:--------------------------------------------:| -| 10A | 6.838 | 1.988 | -| 15A | 60.698 | 4.882 | -| 20A | 368.657 | 19.233 | -| 25A | 1257.150 | 59.948 | -| 30A | 4060.083 | 192.180 | +2. **Build the test suite (q6):** + Navigate to the `q6` folder and build: + ```bash + cd src/q6 + make + ``` -# VERSION NOTES: # +3. **Build the QGPU engine (core):** + Navigate to the `core` folder and build: + ```bash + cd ../core + make + ``` -**19/08/2020** -Generating first version of **Q-GPU** readme. +4. **Run the tests:** + Once compiled, you can run the test scripts. + ```bash + python runTEST.py + ``` \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index e83b99ce..5bc58c8c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,7 +10,14 @@ readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.10" license = { file = "LICENSE" } # keywords = [""] -authors = [{ name = "Willem Jespers", email = "w.jespers@lacdr.leidenuniv.nl" }] +authors = [{ name = "Willem Jespers", email = "w.jespers@rug.nl" }, + { name = "Chiel Jespers", email = "m.jespers@lacdr.leidenuniv.nl" }, + { name = "David Araripe", email = "david.araripe@rug.nl" }, + { name = "Shen Guo", email = "g.shen@rug.nl" }, + { name = "Mauricio Esguerra" }, + { name = "Johan Åqvist" }, + { name = "Hugo Gutiérrez de Terán" } +] # maintainers = [{ name = "", email = "" }] # TODO classifiers = [ "License :: OSI Approved :: GNU General Public License v2 (GPLv2)", From 5b5dd3e7817bd76a03dc57c346f44436781349c1 Mon Sep 17 00:00:00 2001 From: David-Araripe Date: Thu, 20 Nov 2025 10:54:56 +0100 Subject: [PATCH 6/8] correct test commands --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c874f354..30fda3b1 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,7 @@ QligFEP: https://doi.org/10.1186/s13321-019-0348-5 QresFEP: https://doi.org/10.1021/acs.jctc.9b00538 +# ⏩ Q-GPU # ⏩ Q-GPU **Q-GPU** is an adaptation of **Q** version 5.06 to run on GPUs. @@ -135,7 +136,7 @@ The Qprep tool from **Q** is needed for the preparation of molecular topology fi - MD sampling using Qdyn, which runs on a CUDA-based GPU - The FEP analysis tool (qfep) provided in python (running both in GPU or CPU) -> ⚠️ Integration with the QligFEP workflow is currently under active development and not yet available. For now, we only provide instructions to run our test cases.publication describing Q-GPU and its performance is in preparation Please refrain from using this version until the publication is out. +> ⚠️ Integration with the QligFEP workflow is currently under active development and not yet available. For now, we only provide instructions to run our test cases. A publication describing Q-GPU and its performance is in preparation. Please refrain from using this version until the publication is out. ## Testing ## **Q-GPU** includes various tests that compare the output of the original fortran code with the C/CUDA code. They are situated in the test folder and include: @@ -162,7 +163,7 @@ To compile the code and run the tests, you must checkout the GPU feature branch Navigate to the `q6` folder and build: ```bash cd src/q6 - make + make test ``` 3. **Build the QGPU engine (core):** @@ -175,5 +176,5 @@ To compile the code and run the tests, you must checkout the GPU feature branch 4. **Run the tests:** Once compiled, you can run the test scripts. ```bash - python runTEST.py + python runTEST.py -a gpu -t 100 ``` \ No newline at end of file From bb0fcb682c616963fe7d61bb2aa1ed1d1a9851de Mon Sep 17 00:00:00 2001 From: David-Araripe Date: Thu, 20 Nov 2025 10:59:54 +0100 Subject: [PATCH 7/8] duplicated header --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 30fda3b1..d86927aa 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,6 @@ QligFEP: https://doi.org/10.1186/s13321-019-0348-5 QresFEP: https://doi.org/10.1021/acs.jctc.9b00538 -# ⏩ Q-GPU # ⏩ Q-GPU **Q-GPU** is an adaptation of **Q** version 5.06 to run on GPUs. From bcdc146fb5c6cc8a81ec35a3c5e153cab0e219a3 Mon Sep 17 00:00:00 2001 From: David-Araripe Date: Thu, 20 Nov 2025 11:01:08 +0100 Subject: [PATCH 8/8] Bump up version --- src/QligFEP/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/QligFEP/__init__.py b/src/QligFEP/__init__.py index 4d1ab626..f0cea42b 100644 --- a/src/QligFEP/__init__.py +++ b/src/QligFEP/__init__.py @@ -4,7 +4,7 @@ def get_version(): if (Path(__file__).parent / "_version.py").exists(): from ._version import __version__ # noqa F401 else: - __version__ = "1.0.1" + __version__ = "2.1.0" return __version__ SRC = Path(__file__).parents[1]