Improve README before the new release tag

README.md

@@ -1,12 +1,33 @@
 # 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)
+- [⌨️ Command line interface (CLI)](#️-command-line-interface-cli)
+- [📊 Benchmarking](#-benchmarking)
+- [📚 Citations](#-citations)
+- [⏩ Q-GPU](#-q-gpu)
+  - [Note to the current version](#note-to-the-current-version)
+  - [Testing](#testing)
+
 ## ⚙️ 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).
 
 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
@@ -28,7 +49,7 @@ micromamba create -n qligfep_new python=3.11 gfortran=11.3.0 openff-toolkit=0.16
 ```
 </details>
 
-### 🍎 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:
 
@@ -49,7 +70,7 @@ micromamba create -n qligfep_new python=3.11 gfortran=11.3.0 openff-toolkit=0.16
 ```
 </details>
 
-### 🛠️ 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.
 
@@ -75,135 +96,84 @@ 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.
-
-# Citations: #
-Q6:       https://doi.org/10.1016/j.softx.2017.12.001
-
-Q         https://doi.org/10.1016/S1093-3263(98)80006-5
-
-QligFEP:  https://doi.org/10.1186/s13321-019-0348-5
-
-QresFEP:  https://doi.org/10.1021/acs.jctc.9b00538
-
-# Q-GPU #
-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.
-
+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).
 
-## Authors ##
-Chiel Jespers, David Araripe, Willem Jespers, Mauricio Esguerra, Johan Åqvist, Hugo Gutiérrez‐de‐Terán
+# 📊 Benchmarking
 
+To check and reproduce QligFEP performance results, please refer to our [benchmarking repository](https://github.com/qusers/qligfepv2-BenchmarkExperiments).
 
-## 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.
+For the preprint describing the benchmarking results, see:
 
-To compile the qdyn engine source code, you need a CUDA compiler. The code has been tested with the following versions:
+> 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)
 
-- CUDA/10.1.243
-
-To succesfully install and compile the code (Fortran):
-
-```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
-
-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:
+# 📚 Citations
+Q6:       https://doi.org/10.1016/j.softx.2017.12.001
 
-```bash
-source ~/.bashrc
-env | grep qgpu
+Q         https://doi.org/10.1016/S1093-3263(98)80006-5
 
-QDIR=/Users/johndoe/software/qgpu
-```
+QligFEP:  https://doi.org/10.1186/s13321-019-0348-5
 
-Additiontally you can search for the main **Q-GPU** binary file with:
+QresFEP:  https://doi.org/10.1021/acs.jctc.9b00538
 
-```bash
-which qdyn
-```
+# ⏩ Q-GPU
 
+**Q-GPU** is an adaptation of **Q** version 5.06 to run on GPUs.
 
-## 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. 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:
 
 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. (<https://doi.org/10.1186/s13321-019-0348-5>).
+**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 test
+    ```
 
-# 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 -a gpu -t 100
+    ```

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)",
@@ -90,13 +97,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"

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]