3. Usage

3.1 Main parameters

Running the program without parameters, the list of the implemented options is shown:

Copyright 2008-2022, Alessandro Pedretti & Giulio Vistoli

Usage: gridock -f[FIRSTMOL] -l[LASTMOL] -o[OUTDIR] -p[CPUs] -s[STEP]

 a -> add hydrogens: NONE, GEN, GENBO (default)
 f -> first molecule to dock (1)
 l -> last molecule to dock (the last one)
 o -> output directory (current directory)
 p -> number of CPUs (all available CPUs, SMP only)
 q -> shutdown when the calculation finishes (Windows only)
 r -> restart the screening
 s -> molecule step (1)
 t -> AutoDock template (default.dpf)
 z -> enable/disable the Zip output

The database must be in one of formats supported by VEGA.



It's the molecule database file name that can be in a format supported by VEGA. GriDock can perform also the docking of a single molecule and requires the ligand in PDBQT format instead of the database.



It's the receptor file name in PDBQT format with the polar hydrogens only. In the same directory of the receptor files must be present the grid files generated by AutoGrid4. To generate the PDBQT file and the grid maps you can use MGLTools or VEGA ZZ.


3.1.3 -a[MODE]

Add the hydrogens to each molecule in the database:

Mode Description
NONE No hydrogens will be added.
GEN Use the generic algorithm based on the bond geometry and atom hybridization.
GENBO Use the algorithm based on the bond order (default mode).


3.1.4 -f[FIRSTMOL]

Start the screening from the specified molecule number in the selected database. The default starting molecule to dock is the first one.


3.1.5 -l[LASTMOL]

Stop the screening when the specified molecule number is reached. The default value is the last molecule in the database.


3.1.6 -o[OUTDIR]

Set the directory in which the output files are stored. The default is the current directory.


3.1.7 -p[CPUs]

This parameter set the number of CPUs/cores used to perform the screening. The default value is the maximum number of CPUs installed in your system. This options don't have any effect if you are using the MPI version of GriDock because the nodes/CPUs are controlled by the mpiexec command.


3.1.8 -q

Power off the system when the calculation is finish. This option is available for Windows OS only.


3.1.9 -s[STEP]

Step increment to extract the molecules from the database (default 1).


3.1.10 -r

Restart the screening from the last saved molecule. Remember that to restart the screening the correct .csv file must be present.


3.1.11 -t[TEMPLATE]

Optionally, you can specify the template file used to pass the docking parameters to AutoDock4. The default template file is default.dpf (for more details, see the Template files section). The the default search path is the current directory, but if no file is found, GriDock search the template in the ...\VEGA ZZ\Data\Autodock directory (or .../vega/Data/Autodock directory for the Linux version).


3.1.12 -z[BOOL]

Enable/disable the creation of the Zip archive in which the AutoDock output complexes are stored. The Boolean values can be: 1/0, on/off, true/false and yes/no.


3.2 Preparing the input files

This section shows how it's possible to prepare the input files required by GriDock by VEGA ZZ. To do it, you need the structure of the target protein (receptor) and a database of molecules.


3.2.1 The receptor

To prepare the receptor, you need a 3D model without connectivity errors and completed with all hydrogens. A crystal structure download from the Protein Data Bank (it's the most common scenario), can't be used "as is", but it must be prepared:

if one or more error messages are shown, the receptor structure has problems (e.g. wrong connectivity, misplaced hydrogens, etc).


3.2.1 The database

The database must be in one of the formats supported by VEGA and VEGA ZZ (usually Access, Merck MMD, Mol2, ODBC data source, SQLite, SDF and Zip) and must contain 3D structures with or without hydrogens. If you have a 2D database, you must convert it to 3D by VEGA ZZ (consult its manual).
If you need to dock a single molecule, you can convert it to the MDL Mol format and rename the file from .mol to .sdf.


3.3 Running the screening

In the most common cases, it's enough to specify two parameters only in the command shell to perform the screening:

gridock receptor.pdbqt database.sdf

In this way, all molecules (ligands) included in database.sdf file will be docked in receptor.pdbqt structure. Each ligand is pre-processed automatically, adding the hydrogens by bond order method.

If you want to run the MPI version on Windows operating system:

mpiexec.exe -wdir Y:\ -map Y:=<GRIDOCK_DATA> -env VEGADIR <VEGA_ZZ_SHARED_DIR>
            -hosts <LIST_OF_THE_HOSTS>
            -noprompt <VEGA_ZZ_SHARED_DIR>\GriDockMPI.exe -a none Y:\receptor.pdbqt Y:\database.sdf


<GRIDOCK_DATA>    The full UNC path of the shared directory in which the data files are stored (for more details, see Windows MPI installation procedure).
<LIST_OF_THE_HOSTS>   The list of the host to use for the calculation. It must have the following format:

where N is the number of the hosts, NTHREAD_N is the number of thread that will be started at the specifeid node (usually one for each CPU/core) and HOSTNAME_N is the host name.


<VEGA_ZZ_SHARED_DIR>   VEGA ZZ installation directory shared by the master node (for more details, see Windows MPI installation procedure).


3.4 Output files

Three output files are created In the current directory:

16:11:34 ************************
16:11:34 INIT: GriDock started on Linux
16:11:34 INIT: Local time Thu, 11 Dec 2008 17:11:34
16:11:34 INIT: 16 Dual Core AMD Opteron(tm) Processor 875 detected
16:11:34 INIT: Used CPUs: 16
16:11:34 INIT: AutoDock4/VEGA directory: "/hd1/home/warp/Vega"
16:11:34 INIT: Receptor file: "rdrp_q2xp15.pdbqt"
16:11:34 INIT: Database file: "ChemBank.sdf"
16:11:34 INIT: AutoDock output archive: "rdrp_q2xp15-ChemBank.zip"
16:11:34 INIT: Energy output file: "rdrp_q2xp15-ChemBank.csv"
16:11:34 INIT: Temporary file directory: "/tmp"
16:11:34 INIT: First molecule to dock: 1
16:11:34 INIT: Last molecule to dock: last in database
16:11:34 INIT: Molecule step/s: 1
16:11:34 INIT: AutoDock template file: "/hd1/home/warp/Vega/Data/Autodock/default.dpf"
16:11:34 INIT: AMMP time-out: 120 sec.
16:11:34 INIT: AutoDock time-out: 1200 sec.
16:11:34 INIT: VEGA time-out: 120 sec.
16:11:34 INIT: Add hydrogen to the ligand: yes
16:11:34 INFO: Starting AutoDock - Molecule 1 (tyrphostin [bis-tyrphostin] 270-059)
16:11:34 INFO: Starting AutoDock - Molecule 4 (Anandamide (20:3, n-6))
16:11:35 INFO: Starting AutoDock - Molecule 3 (tyrphostin [bis-tyrphostin] B42 270-168)

The time of the events is referred to the Greenwich Mean Time (GMT) and the local time is shown in the third line. When a single docking is finish, two lines are stored in the log:

16:11:47 INFO: Molecule 9 - Docking finished (0m 12s)
16:11:47 DOCK: Molecule 9 - Best model 4, Best Binding energy = -7.63 kcal/mol, Ki = 2.54 uM

The former informs that the docking is finish in a defined time (12 seconds in the example) and the latter indicates what solution/pose is selected by GriDock (4) on the basis of the binding energy (-7.63 kcal/mol) and inhibition constants (Ki = 2.54 uM).
An error record could be present in the log, if a problem is found:

16:16:03 ERROR: Molecule 110 - Atom/s with unassigned potential

This message means the molecule to dock has one or more atoms with unassigned potential and that's possible when it contains elements or atom types not included in the AutoDock/Amber force field.

16:47:40 ERROR: Molecule 1084 - AutoDock time-out - process killed

To avoid the lost of one or more CPUs when AutoDock 4 is spending too computational time or is in an infinite loop (it could be possible in few cases), GriDock kills the AutoDock when its process runs over the time-out. When this situation is true, the previous line is printed to the log file. The same check is achieved for VEGA also and the time-out values can be set in the GriDock preference file.


where NNNNNNNN is the serial number of the docked ligand in the database.