Merge pull request #5 from ccdc-opensource/gold_multi

Added gold_multi.

Author: fatkinson-ccdc

scripts/ReadMe.md

@@ -9,8 +9,10 @@ This folder contains scripts submitted by users or CCDC scientists for anyone to
 - Performs a multi-component HBP calculation for a given library of co-formers. 
 
 ### Packing similarity dendrogram:
--  Construct a dendrogram for an input set of structures based on packing-similarity
-analysis
+- Construct a dendrogram for an input set of structures based on packing-similarity analysis.
+
+### GOLD-multi
+- Use the CSD Docking API and the multiprocessing module to parallelize GOLD docking.
 
 ## Tips 
 ### Searching tips:

scripts/gold_multi/.gitignore

@@ -0,0 +1 @@
+!target

scripts/gold_multi/README.md

@@ -0,0 +1,69 @@
+# GOLD and Multiprocessing
+
+## Introduction
+
+This repo contains a script, `gold_multi.py`, which is designed to illustrate how to use the [CSD Docking API](https://downloads.ccdc.cam.ac.uk/documentation/API/descriptive_docs/docking.html) and the standard Python [multiprocessing](https://docs.python.org/3.7/library/multiprocessing.html) module to parallelize GOLD docking. Also included is a simple example system to demonstrate the operation of the script.
+
+On a multi-core workstation, this approach should be suitable for docking some hundreds or thousands of ligands depending on the rigour of the docking protocol used; please consult the GOLD USer Guide for information about speed/accuracy tradeoffs in GOLD. Note that the script is not useful for running GOLD on an HPC compute cluster or on the Cloud: the CCDC provides the GOLD Cluster and GOLD Cloud tools for those use-cases. For further details, please contact [[email protected]](mailto:[email protected]).
+
+As ever when using multiprocessing techniques, increasing the number processes will at some point begin to degrade performance as available cores are saturated. At what point this happens will depend on the machine and the workload and thus can only really be determined by experimentation. A default of six was selected as the script was developed on an eight-core workstation and this seemed to give decent performance while leaving cores for other processes.
+
+The script is designed to be as simple as possible in order to not obscure the mechanisms of parallelization. Thus, for example, configuration of the docking is taken entirely from the GOLD conf file. There is also the limitation that only a single input file of ligands is accepted. In addition, the implementation of error-handling and logging is rather lightweight. If a proper application was required then these matters could be addressed.
+
+The script writes output to the directory specified in the GOLD configuration file, and the results can be inspected by loading the GOLD conf file in Hermes as normal (see the Hermes User Guide for details). A `bestranking.lst` file is also written, which records the best-scoring pose for each molecule. Other output normally written by GOLD is not created, although this could be implemented if necessary.
+
+The script partitions the input ligand file into chunks and uses the Docking API and multiprocessing to dock these chunks in parallel using named subdirectories for their output. The solution files for the chunks are then copied to the main output directory and the full `bestranking.lst` file compiled from the partial chunk versions. The intermediate subdirectories are currently kept, but the script could easily be modified to delete them or use anonymous temporary directories if disk usage was to be an issue.
+
+---
+## Requirements
+
+- [GOLD](https://www.ccdc.cam.ac.uk/solutions/csd-discovery/components/gold/) and the [CSD Python API](https://downloads.ccdc.cam.ac.uk/documentation/API/) installed.
+- Configuration File: `gold.conf`
+  
+## Licensing Requirements 
+
+CSD-Discovery, CSD-Enterprise and Research Partner suites would all be sufficient.
+
+## Instructions on Running
+
+To run the script, an environment with the CCDC Python API installed must be active. Further information is available in
+the [API installation notes](https://downloads.ccdc.cam.ac.uk/documentation/API/installation_notes.html).
+
+The script is designed to be run from the command line only (and not, for example, from within Hermes). The path to a GOLD configuration file may be provided as a command argument; if no argument is provided, it is assumed there will be a file `gold.conf` in the current working directory. 
+
+On Windows, the command would be (in the folder where this archive was unzipped)...
+
+```
+> python.exe .\gold_multi.py
+```
+
+On Linux or MacOS, an equivalent would be (first making the script executable)...
+
+```
+$ chmod u+x ./gold_multi.py
+
+$ ./gold_multi.py
+```
+
+In either case, add the option `--help` to show more information.
+
+```cmd 
+usage: gold_multi.py [-h] [--n_processes N_PROCESSES] [conf_file]
+
+positional arguments:
+  conf_file             GOLD configuration file (default='gold.conf')
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --n_processes N_PROCESSES
+                        No. of processes (default=6)
+```
+
+---
+## Note on the input files provided
+
+The example target provided (see the directory `target/`) is SYK tyrosine kinase ([5LMA](https://www.ebi.ac.uk/pdbe/entry/pdb/5lma)).
+
+The ligands in `input.sdf` were built from SMILES. If the name is a PDB code, it means the SMILES corresponded to the crystallographic ligand from that structure (with conventional ionization states assigned). If the name has a suffix, the SMILES is a manually-generated analogue. Note that not all these ligands can be correctly cross-docked into 5LMA, as there are induced-fit effects in SYK that GOLD cannot reproduce.
+
+> For feedback or to report any issues please contact [[email protected]](mailto:[email protected])

scripts/gold_multi/gold.conf

@@ -0,0 +1,82 @@
+  GOLD CONFIGURATION FILE
+
+  AUTOMATIC SETTINGS
+autoscale = 0.3
+
+  POPULATION
+popsiz = auto
+select_pressure = auto
+n_islands = auto
+maxops = auto
+niche_siz = auto
+
+  GENETIC OPERATORS
+pt_crosswt = auto
+allele_mutatewt = auto
+migratewt = auto
+
+  FLOOD FILL
+radius = 6
+origin = 0 0 0
+do_cavity = 1
+floodfill_atom_no = 0
+cavity_file = target/ligand.mol2
+floodfill_center = cavity_from_ligand
+
+  DATA FILES
+ligand_data_file input.sdf 5
+param_file = DEFAULT
+set_ligand_atom_types = 1
+set_protein_atom_types = 0
+directory = output
+tordist_file = DEFAULT
+make_subdirs = 0
+save_lone_pairs = 0
+fit_points_file = fit_pts.mol2
+read_fitpts = 0
+
+  FLAGS
+internal_ligand_h_bonds = 0
+flip_free_corners = 0
+match_ring_templates = 0
+flip_amide_bonds = 0
+flip_planar_n = 1 flip_ring_NRR flip_ring_NHR
+flip_pyramidal_n = 0
+rotate_carboxylic_oh = flip
+use_tordist = 1
+postprocess_bonds = 1
+rotatable_bond_override_file = DEFAULT
+solvate_all = 1
+
+  TERMINATION
+early_termination = 1
+n_top_solutions = 3
+rms_tolerance = 1.5
+
+  CONSTRAINTS
+force_constraints = 0
+
+  COVALENT BONDING
+covalent = 0
+
+  SAVE OPTIONS
+save_score_in_file = 1 comments
+save_protein_torsions = 1
+output_file_format = MACCS
+
+  WRITE OPTIONS
+write_options = NO_LINK_FILES NO_RNK_FILES NO_GOLD_LIGAND_MOL2_FILE 
+
+  FITNESS FUNCTION SETTINGS
+initial_virtual_pt_match_max = 3
+relative_ligand_energy = 1
+gold_fitfunc_path = plp
+score_param_file = DEFAULT
+
+  PROTEIN DATA
+protein_datafile = target/protein.mol2
+
+  CONSTRAINTS
+constraint protein_h_bond 10.0000 0.005000 3696
+
+