VF-Unity-Parallelized

VF-Unity-Parallelized is a streamlined version of VirtualFlow, integrating the features of both VFVS (VirtualFlow for Virtual Screening) and VFLP (VirtualFlow for Ligand Preparation) into a cohesive workflow. Designed to operate seamlessly on SLURM systems, this workflow allows users to easily incorporate any docking software of their choice, ensuring maximum flexibility.

The core workflow involves users supplying a SMILES text file, the receptor of interest, and the docking parameters to facilitate large-scale docking simulations. Out-of-the-box, VF-Unity-Parallelized is configured to support docking with QuickVina 2.0 and Smina.

Execution within SLURM environments is highly optimized, with computations distributed in parallel across multiple CPUs and nodes. This design ensures efficient linear scaling relative to the number of molecules provided.

Prerequisites

Please clone the repository using:

git clone https://github.com/VirtualFlow/VFUparr.git

Please ensure that the following packages are installed:

• RDKit version 2021.09.5
• Open Babel 3.1.0
• Python 3.7.13
• SELFIES
• PyTorch version 2.0.1 (only required for the optional ML tranche-prioritization classifier described below; a CPU-only build is sufficient, a CUDA build is used automatically if available)

File Navigator

• DATA: This directory is where users can place the receptor file and the corresponding executables for running the docking process.
• OUTPUTS: This directory is designated for storing the results of the docking simulations.
• all.ctrl: Contains all user-specifiable parameters required for the screening process, including the docking parameterization.
• dataset_calc.py: A Python script for running the docking on specified ligands.
• submit.sh: A Slurm submission script for submitting an array of jobs for processing.
• ml_classifier.py: Optional FNN classifier that prioritizes candidate compounds before docking (see "Using the optional ML tranche-prioritization classifier" below).
• train_ml_classifier.py: One-shot script for training the classifier on a prescreen run's results.

Quick Start Guide

To get started with the docking simulations, follow the steps outlined below. These steps ensure that your configuration is correctly set up for your specific docking scenario:

1. Configure Receptor Location:

   • Open all.ctrl and specify the exact location of your receptor in the designated section.

2. Set Docking Parameters:

   • Within all.ctrl, enter the appropriate CENTER-X/Y/Z and SIZE-X/Y/Z coordinates to define your docking area.

3. Specify SMILES List Path:

   • In all.ctrl, input the path to your SMILES list file. This file is crucial for defining the molecular inputs for the simulation.
   • Ensure the file adheres to the format: each line contains a SMILES representation followed by a comma and the molecule ID (e.g., C[C@@H](N)C(=O)O, Molecule1). Lines must be separated by newline characters to distinguish between different molecular entries.

4. Slurm Cluster Account:

   • In submit.sh, replace TODO in #SBATCH --account=TODO with your actual Slurm cluster account name to ensure proper job submission.

5. Job Submission Configuration:

   • Adjust the number of jobs to submit for your docking calculation in submit.sh by modifying #SBATCH --array=1-999 accordingly. Ensure this number matches the MAX_NUM_JOBS parameter set in all.ctrl.

6. Executable Permissions:

   • Make sure the docking executables have the correct executable permissions by running chmod 777 ./DATA/qvina.

7. Submit Your Job:

   • Finally, submit your job to the Slurm cluster with the command: sbatch submit.sh.

By following these steps, you'll be properly set up to conduct your docking simulations. Ensure all paths and parameters are double-checked for accuracy before submitting your job.

Analyzing Your Jobs

Upon completion of docking calculations, the results will be systematically saved in the working directory of your repository. Look for files named following the pattern OUTPUT_*_*.txt, where each represents a different output from your simulations. These text files are comprehensive, containing vital information for each molecule processed:

• SMILES String: The unique identifier for the chemical structure of the molecule.
• Docking Score: A numerical value indicating the predicted affinity between the receptor and the ligand. A score of 10,000 indicates a failed docking calculation.
• Molecule ID: A specific identifier assigned to the molecule for easy reference.
• Input Ligand Location: The path to the file containing the input ligand used in the docking simulation.
• Docking Pose File Location: The path to the file showing the preferred orientation (pose) of the ligand when bound to the protein receptor.

This organized output allows for efficient analysis and interpretation of your docking simulations, enabling a deeper understanding of the interaction between molecules and their potential efficacy.

Using the optional ML tranche-prioritization classifier

For ultra-large SMILES libraries, VF-Unity-Parallelized supports an optional machine learning classifier that predicts which candidate compounds are likely to be high-affinity binders, so that only those compounds are docked. This is the FNN classifier described in the AdaptiveFlow manuscript's "Machine Learning Classifier for Tranche Prioritization" Methods section: a 4-layer feedforward network (1024 → 512 → 256 → 128 → 1, ReLU hidden activations, sigmoid output) trained on Morgan fingerprints (1024 bits, radius 2) and prescreen docking scores. It typically reduces the number of compounds docked by 30-70% while maintaining hit enrichment.

The classifier fits into the existing SLURM-array workflow as an additional, opt-in step, without changing how jobs are submitted or how ligands are chunked across array tasks:

1. Prescreen. Run the existing, unmodified workflow (all.ctrl + submit.sh + dataset_calc.py) on a small representative SMILES file (e.g., a few thousand molecules) to get real docking scores in the usual OUTPUT_*_*.txt files. No code changes are needed for this step.

2. Train. Run the training script once, on a login/interactive node (training only takes seconds -- it does not need a SLURM array):

   python3 train_ml_classifier.py
   

   This reads RECEPTOR_LOCATION and ML_MODEL_PATH from all.ctrl, collects every OUTPUT_*_*.txt file in the current directory, extracts (SMILES, docking score) pairs (skipping the failed-docking sentinel score of 10,000), and trains+saves the classifier.

3. Primary screen. Set USE_ML_CLASSIFIER=True in all.ctrl (and point ML_MODEL_PATH at the file saved above, if you changed the default), then point SMILES_FILES/NUM_MOLS at your full library and submit the primary screen as usual: sbatch submit.sh. Each array job will load the trained classifier and filter its own chunk of ligands -- keeping only compounds with predicted binding probability greater than ML_PROBABILITY_CUTOFF -- before handing the (smaller) chunk to the existing per-job docking pool. Filtered-out compounds are logged to ML_FILTERED_<chunk_1>_<chunk_2>.txt (SMILES and predicted probability) alongside the usual OUTPUT_<chunk_1>_<chunk_2>.txt files, so every input compound remains accounted for.

A classifier trained once for a given receptor can be reused across primary screens for that receptor without retraining -- just leave ML_MODEL_PATH pointing at the saved file.

ml_classifier.py can also be run directly (python3 ml_classifier.py) to execute a self-contained synthetic self-test that exercises training, persistence, and filtering without requiring any real docking runs.

New all.ctrl keys

• USE_ML_CLASSIFIER: master switch (True/False, default False).
• ML_MODEL_PATH: path to the trained classifier .pt file (default ./DATA/ml_classifier.pt).
• ML_PROBABILITY_CUTOFF: minimum predicted probability to retain a candidate for docking (default 0.5, per the manuscript).

Contributing

If you are interested in contributing to VirtualFlow, whether it is to report a bug or to extend VirtualFlow with your own code, please see the file CONTRIBUTING.md and the file CODE_OF_CONDUCT.md.

License

The project ist distributed under the GNU GPL v2.0. Please see the file LICENSE for more details.

Citation

Gorgulla, Christoph, et al. "VirtualFlow 2.0-The Next Generation Drug Discovery Platform Enabling Adaptive Screens of 69 Billion Molecules." bioRxiv (2023): 2023-04.