MOE/DivCon QMScore Preparation & Execution
Prior to running QMScore or any of QuantumBio’s tools, the protein/ligand structure(s) under consideration must be prepared. Since the tools are integrated with MOE, you should thouroughly read and understand the MOE documentation regarding structure preparation. If preferred, 3rd party tools can be used to prepare the structure and MOE’s import and database import functions can be used to parse these files. For more information for using MOE, you may contact Chemical Computing Group directly.
The workflow of MOE/DivCon QMScore involves the following steps:
- Prepare the receptors and ligands/poses involved in the calculation. This preparation process in MOE requires protonation (using Protonate3D), correct atomic charge and oxidation state assignment (double check using the Atom Manager), and any preliminary docking (using the MOE docker).
- Closely examine all error and warning produced by the MOE/DivCon tests to ensure that the receptor(s) and ligand(s) are not problematic.
- Verify the formal charges calculated by MOE.
- Set up the run parameters to QMScore.
- Execute QMScore either on a local machine or in parallel on a cluster.
- Analyze the QMScore results.
Click QuantumBio->QMscore Preparation… to see the following dialog:
Simulation Options
The QMScore dialog box under the QuantumBio menu provides an interface to the QMScore method and is broken down into the following elements:
Output: the output mdb file (including browse button) to allow the user to create a new MDB file or overwrite an old one. In the event that update is chosen, this option is not changeable.
Receptor & Ligand pull down menus: These menus may be used to choose the molecular input to be characterized using the simulation. These menus allow you to choose the atoms within the MOE window (e.g. Receptor Atoms and Ligand Atoms) or else from respective MDB files. These choices give you the option of running a Ligand MDB file with multiple poses or ligands against either the Receptor Atoms within the GUI or an MDB file that has the corresponding receptors. In the latter instance, you will need to make sure that there is a 1-to-1 correspondance between the two MDB files where the first Receptor should be scored against the first Ligand/Pose, the second Receptor should be scored against the second Ligand/Pose, and so on.
Structure: This section of the dialog box includes the various tests and structure preparation options that are available. You are of course free to use any tools available within MOE beyond these included tools, and these options are only provided in order to help facilitate your effort and to encourage correct and complete preparation prior to QM treatment. For more information on structure preparation, please see the MOE documentation and/or MOE support. Concerning the specific options provided, the testing infrastructure will test for various items including most importantly bad atom-atom contacts and other structural defects. These defects must be fixed prior to QM treatment. You may fix them with the various molecular mechanics minimization tools available within MOE. See tutorial for an example.
Charges: While molecular mechanics methods exhibit a passing interest in total charge, in reality the correct determination of charge is important to numerous preparation and docking simulations. Since the underlying QuantumBio methods only support closed shell calculations, this test will make sure that that calculation is closed shell. However, since the vast majority of biological systems are closed shell, a problem underscored at this position in the dialog box implies that there is most likely a preparation problem in the structure and MOE has determined (perhaps incorrectly) the formal charge or oxidation state of a molecule in the system. In order to address this problem, you should use the Atom Manager provided by MOE and double check to make sure that you – and MOE – have correctly assigned formal charges, oxidation states, and so on. You may change these items within the Atom Manager in order to manipulate the total charge. Once you have correctly assigned each charge, you should re-run Protonate3D, docking, or any other tool you used within MOE or other 3rd party software. For more information, see the MOE documentation under the Atom Manager. The colored circles represent the status of the charge where a green circle means that the total charge yields a closed shell, and a red circle means that the total charge yields an open shell. Separate readings to provided for ligand and receptor.
Hamiltonian: QuantumBio supports a number of key semiempirical Hamiltonians depending upon the context of the simulation. For QMScore, the following two Hamiltonians/elements are supported.
- AM1: H, Li, Be, B, C, N, O, F, Na, Al, Si, P, S, Cl, K, Ca, Zn, Ge, Br, I, Hg
- PM3: H, Be, C, N, O, F, Na, Mg, Al, Si, P, S, Cl, K, Ca, Zn, Ga, Ge, Ar, Se, Br, Cd, In, Sn, Sb, Te, I, Hg, Tl, Pb, Bi
Calculation (scaling): The scaling of the calculation should be chosen based upon the size of the structure to be considered. Generally, linear scaling should be used as this is the fastest approach; however, if the structure is very small or if convergence is becoming a problem, then Standard or cubic scaling can be chosen. Note, if the structure is smaller then the cross over point (approximately 500 atoms), DivCon will automatically switch to standard scaling in order to speed up the calculation.
LigOpt: Optionally, the ligand can be quantum mechanically optimized using the same Hamiltonian chosen above. When chosen, this optimization will happen prior to scoring the ligand, and the score that is returned is based upon this new conformation.
Shift: In order to improve convergence, DivCon employs Hillier’s level shifting method for converging closed shell calculations. The value in the text box corresponds to the starting shift value. DivCon will then attempt to converge at that value, and this shift value will double in the event of further convergence difficulties.
Generate Frequency (currently disabled): Calculate and use the vibrational frequency of the small molecule as a measure of the entropy lost upon binding within the QMScore. It is currently disabled in order to validate the use of the method for QMScore. The method will be reintroduced in a future version.
Generate PWD: Pairwise Energy Decomposition (PWD) can be calculated in order to measure the protein/ligand interactions and generate the interaction heat map.
Execution Buttons
Along the bottom of the QMScore widget, there are a number of options available for the simulation:
Run (available on Linux and Mac OS X): The simulation prepared in the preceeding steps may be run interactively using a single processor within the MOE environment. The MOE window will remain responsive during the simulation. In fact, depending upon the resources at your disposal, you may run additional simulations within the same session. The simulation is listed under the Cancel button in the upper right hand corner of the main MOE window, and you may cancel the simulation at any time. Warning: when run interactively within the MOE environment, the simulation will end of MOE is shutdown.
Create: Once a job has been prepared, the job may be saved for execution with moebatch on a separate computer such as a cluster or workstation.
Load: A previously generated QMScore mdb file can be loaded for further editing and parameter update. Hamiltonian, calculation options, and so on may be edited, however the molecular input of the calculation may not be changed. Note: this option may be removed in a future release.
Update: Once a QMScore mdb has been loaded using the Load button noted above, the Update button is pressed to update the mdb file.
Close: Close the QMScore preparation window.
MOEbatch Command Line Execution
Linux/Mac:
Once the preparation of the qmscore.mdb file is complete, the simulation can be executed using MOE’s batch program “moebatch” using the qmsmpi.svl SVL script. This call to moebatch is executed interactively on the command line within a shell environment, or it can be executed within the PBS or SGE queing systems. The following command line call – executed on the MDB file created in the steps above – will run the simulation:
% qbmoebatch -exec “run [‘qmsmpi.svl’, [‘qmscore.mdb’]]” -exit
The qbmoebatch execution supports coarse grained parallelism for the treatment of multiple protein/ligand complexes within the mdb file. For example, if there are 4 protein/ligand complexes within the mdb file, one can ask for 5 processors and expect perfect scaling. If less then 5 processors are requested, the complexes will be load balanced between these processors in order to complete the entire set. For 4 complexes, the recommended processor configurations are 1, 3, and 5 in order to experience perfect scaling. If there are 8 protein/ligand complexes, the configurations could be 1, 3, 5, or 9. And so on.
If qbmoebatch is run within the SGE or PBS environment, the calculation will automatically use the number of processors requested within the PBS or SGE settings. However, if the simulation is executed interactively within the shell environment, then an MPI machinefile must be created. When this file is named qbmachinefile.txt and placed within the current working directory, it will be picked up automatically and used by the simulation in order to distribute the job across the various processors available. In order to run across five processor cores on the localhost, the following machinefile will distribute the job accordingly:
cat qbmachinefile.txt localhost localhost localhost localhost localhost
If PBS or SGE is available, it is highly recommended that one of these non-interactive environments are used instead of running the simulation interactively on the command line. The underlying OpenMPI library used for the message passing interface will account for either environment upon the existence of the ${PBS_NODEFILE} or ${PE_HOSTFILE} respectively. Configuration of the queuing system is beyond the scope of this documentation. For more information, consider the PBS documentation (here) and SGE documentation for the parallel environment. An illustrative PBS script is provided:
#!/bin/bash #PBS -S /bin/bash #PBS -l nodes=2:ppn=7 #PBS -l pmem=1gb #PBS -j oe cd /net/`hostname -s`/scratch/$USER mkdir $PBS_JOBID ; cd $PBS_JOBID # Change the path and name for the MOE database. cp $PBS_O_WORKDIR/qmscore.mdb . qbmoebatch -exec "run ['qmsmpi.svl', ['qmscore.mdb']]" -exit cp qmscore.mdb $PBS_O_WORKDIR cp qmscore.h5 $PBS_O_WORKDIR
In addition to storing the scores in the QMScore MOE database, the QMScore application creates an HDF5 file in the same location and with the same name as the QMScore database (.h5 extension). This file contains additional data (for instance, PWD) that the application uses for post-execution analysis. Note that if you resubmit a QMScore database, those rows that have “Success” in the Status field are skipped.
Once the calculation is complete, the QMScore and PWD analysis can be performed interactively using the MOE graphical user interface.