3. Usage

3.1 Main parameters

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

GriDock 1.0.6.3
Copyright 2008-2023, Alessandro Pedretti & Giulio Vistoli

Usage: gridock -f[FIRSTMOL] -l[LASTMOL] -o[OUTDIR] -p[CPUs] -s[STEP]
       -a[MODE] -t[TEMPLATE] -z[BOOL] -qr RECEPTOR DATABASE

 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.

3.1.1 DATABASE

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.

3.1.2 RECEPTOR

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:

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:

• Remove the co-crystallized molecules if they are close to active site in which you intend to dock the molecules.
• Add the hydrogens, checking if they are added correctly. A good method to do it, is the use of the specific function implemented in VEGA ZZ (Edit Add Hydrogens and check Protein in the Molecule type box).
• Fix the atom types and charges (Calculate Charges & Pot., choose AUTODOCK as Force field and Gasteiger as Charges).

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

• Select the atoms or the residues around the active site (View Select Custom, choose the Proximity tab). This step is required to lead the docking to the binding pocket. If you don't know the position of the binding site, you can consider the whole receptor.
• Run the Receptor.c script in Docking\AutoDock folder (File Run script) to save the receptor in PDBQT format and to run AutoGrid 4 to generate the maps of the binding pocket.

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

where:

3.4 Output files

Three output files are created In the current directory:

• receptror_database.csv
  It's a comma separated value file in which  the best solutions of each docking are stored ranked by binding energy. The meaning of each column in the file is:
   

  Column	Description
  MolID	Molecule serial number in the database.
  Pose	Best pose number. AutoDock can generate more than one pose and GriDock select the best one to rank it in the .csv file.
  Ki	Estimated inhibition constants (mM, millimolar at 298.15 K).
  Binding	Estimated free energy of binding (kcal/mol).
  Intermolecular	Final intermolecular energy (kcal/mol).
  VdW + Hbond + Desolv	Van der Waals + hydrogen bonds + desolvation energies (Kcal/mol)
  Electrostatic	Electrostatic energy (kcal/mol).
  Internal	Final total internal energy (Kcal/mol).
  Torsional	Torsional free energy (kcal/mol).
  Unbound	Unbound system's energy (kcal/mol).
  Molecule name	Name of the molecule in the database.

  This is an example of .csv output file:

  MolID; Ki; Binding; Intermolecular; VdW + Hbond + Desolv; Electrostatic; Internal; Torsional; Unbound; Molecule name
  240; 70,79; -9,75; -9,39; -8,99; -0,40; -1,56; 1,10; -0,09; okadaic acid
  274; 74,98; -9,72; -9,37; -9,19; -0,18; -1,46; 1,10; -0,01; rapamycin
  1761; 127,95; -9,40; -8,99; -9,01; 0,02; -1,56; 1,10; -0,05; Rapamune
  235; 156,44; -9,28; -10,45; -8,97; -1,47; -1,47; 1,92; -0,71; Leptomycin
  1354; 203,17; -9,13; -9,26; -8,61; -0,65; -1,00; 0,55; -0,58; salinomycin
  114; 223,06; -9,07; -10,17; -10,15; -0,02; -1,02; 1,10; -1,02; AM-251
  ...

   

• gridock_YYYYMMDD.log
  This is the log file including all information about the screening progress. The file name reports the creation date in the format year, month and day (YYYYMMDD) and if the calculation continues for more than one day, a new log file is generated for each day. This is a log file example:

16:11:34 ************************
16:11:34 INIT: GriDock 1.0.0.10 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.

• receptror_database_NN.zip
  This zip files include the docking results of each complex generated by AutoDock. They can be useful to analyze the docking results by a graphic software able to read the .dlg files (e.g. VEGA ZZ or MGLTools). You must remember that the .dlg file is readable if it's unpacked in the same directory of the receptor PDBQT file. NN is a progressive number assigned to a new zip archive when the previous reached the maximum size (usually 4 Gb).
  Each file in the zip archive has the following name:

receptor-database_NNNNNNNN.dlg

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