Phenix/DivCon Command Line Options
The Phenix package is primarily a command-line driven software engine using the phenix.refine execution script. Keeping with that philosophy, Phenix/DivCon has extended the Phenix command line options (and these are listed below). However, most users actually utilize the provided qbphenix script in order to run the correct tools at the right time. This is because Phenix/DivCon requires greater setup and management due to its reliance on fully protonated systems. In addition, analyses such as XModeScore and 3DRISM-based water picking use additional steps and tools outside of the purview of the phenix.refine tool. To see these switches in action, take a look at the examples below along with the Phenix/DivCon tutorial.
The following page is broken down into two sections. The first – and arguably most important – is the options for the qbphenix script provided within the package.
1. qbphenix Options
The qbphenix script options are broken down into various “Option Groups” based upon the expected applications of the Phenix/DivCon interface. All qbphenix options begin with a double dash (i.e. “‑‑”):
General Options
Option | Default | Description |
–jobID | none | The jobID can be thought of as the “basename” for the pdb, mtz, and cif files provided in a directory. The option is a handy shortcut for those who utilize the {basename}.pdb {basename}.mtz {basename}.cif Provide the name of the job. |
–pdbFile | none | Specify the name of PDB input file required for the refinement. |
–pdbID | none | Optionally, instead of providing the pdbFile as in the previous option, you can simply provide a PDBID which will be downloaded automatically from the PDB (note: depending upon your environment, use of this option may require that you set your proxy for wget/curl). |
–cifFile | none | Specify the name of the ligand CIF. This file is used to set protonation when MOE is used as the protonator; however, the stereochemical restraints for the species are not used. |
–dataFile | none | The datafile is the file which provides the experimental data used in subsequent calculations. There are generally three types or contexts:
|
–dir | none | (Optional) Specify a subDir name to run the job in this subDir. The new directory is made at runtime, and this option is useful when running multiple calculations in a single main directory and when you wish to organize your calculations based upon subdirectories. |
–qmMethod | pm6 | Set the quantum mechanics method to run ONIOM (QM/MM) or QM‑region refinement using the chosen Hamiltonian.
Acceptable Options: pm6, am1 |
–mmMethod | none | Set the molecular mechanics method to run ONIOM (QM/MM) or MM‑region refinement using the chosen force field.
Acceptable Options: amberff14sb amberff19sb amberff94 |
–qbOff | N/A | Flag to skip QM or QM/MM and only run conventional refinement using all of the other tools as set. |
–region-radius | 3.0 | Set the size of the main QM region. All residues within X angstroms from any atom of the ‑‑selection will be included in the QM calculation and the gradients will be included in the refinement. |
–buffer-radius | 2.5 | Set the size of the QM buffer region. All residues within X angstroms from any atom of the main QM region will be included in the QM calculation (however the associated QM gradients will not be included in the refinement). Note: this option should only be used during REGION refinement (and not ONIOM or full‑QM or full‑MM refinement). |
–selection | none | Specify ligand selection for the main, core QM region. Two selection “styles” are supported in addition to an automated algorithm to choose ligands of interest at runtime (Note: Mixing of styles is not supported):
|
–m | none | (Optional) Used to communicate the amount of resident memory (RAM) required for the QM/MM calculation. If not number is specified, the memory limit is calculated at runtime based upon the environment (using `free` or the PBS environment). If you wish to circumvent this environment, you may specify a limit such as 2gb. |
–np | 2 | The DivCon package is multithreaded for many of its most CPU‑intensive calculations, and the number of threads can be set on the command line. As a minimum, DivCon will use two threads during the calculation.
This option will also be “passed” to phenix.refine using its native threading command line option |
–ncycles | 3 | Specify the number of refinement macro cycles to run. |
–paramFile | none | (Optional) Provide the name of the file having any PHENIX options. This file is passed directly to phenix.refine at runtime and it should fit the Phenix standard. |
–phenixOptions | none | (Optional) Likewise, these options are passed directly to the phenix.refine command line at runtime and generally they are not processed in any way by qbphenix. |
–labels | none | (Optional) Specify labels corresponding to columns in mtz: e.g. “FP,SIFP” |
–resmax | none | (Optional) Specify the maximum resolution for X‑ray refinement. By default, the min/max resolutions will be defined as defaulted in phenix.refine and therefore this option should only be provided when you want to change that default behavior. |
–resmin | none | (Optional) Specify the minimum resolution for X‑ray refinement. By default, the min/max resolutions will be defined as defaulted in phenix.refine and therefore this option should only be provided when you want to change that default behavior. |
–skipcycle | none | (Optional) Occasionally, in the event that there is difficulty in the refinement, a way around the problem may be to run a step or two of conventional refinement prior to running QM or QM/MM refinement. This option turns on this functionality and the integer provided will set the script to skip running QM during the specified refinement macro cycle(s). |
Structure Preparation Options
Option | Default | Description |
–protonation | MOE | Choose the method to protonate the structure. These are the built in options which are available. You may choose to “Skip” protonation during the qbphenix run if you protonate the structure prior to refinement using a tool of your choice. Note: this option is used in all of the various contexts (such as general refinement, XModeScore and tautomerization, and so on).
Acceptable Options: MOE (using Protonate3D), AddH (using MOE’s AddH), Divcon, or Skip |
–autoBuildMOE | N/A | Enable auto build of missing sidechains using MOE’s built in tool. |
–enableAlt | N/A | (Experimental) Keep alternative conformations in MOE. |
–preparePDB | N/A | (Optional) In the event that you simply wish to protonate/prepare the structure using the above chosen methods, this tool will stop the script after preparation. |
XModeScore Specific Options
Option | Default | Description |
–XModeScore | NONE | Flag to run XModeScore to explore possible protonation states for a selected ligand (using the ‑‑selection option).
If an argument is provided it is assumed to be a directory which you have already populated with all necessary pdb files. Note: if the ‑‑protomers option is also provided, then all given tautomers for each file will also be generated. |
–exploreFlip | N/A | Flag to explore flip states for a selected ligand in XModeScore run. |
–protomers | 0 |
Choose protomer/tautomer states to be generated using DivCon within XModeScore. For examples: ‑‑protomers 0 = only tautomers for the current state. ‑‑protomers "‑1..1" = positve, negative states, and the current protonation state tautomers. ‑‑protomers "‑1..0" = negative state and current protonation state tautomers. ‑‑protomers "0..1" = positive state and current protonation state tautomers. ‑‑protomers 1 = positive state only. ‑‑protomers ‑1 = negative state only.
|
XModeScore Rescoring Options (To be performed on a previous set of calculations.) |
||
–rescore | N/A | Turn on the rescoring functionality. Provide XModeScore data log for rescoring. |
–removeOutliers | N/A | (Optional) Remove outliers in SE and ZDD during XModeScore rescoring. |
–skipStates | N/A | (Optional) Skip States during XModeScore data rescoring. For example: “1_0_2_‑1, 0_0_0_1” |
(Experimental) RISM Water Picking Options
Option | Default | Description |
–rismWater | none | Turn on the water picking functionality and add water molecules based on 3D RISM and X‑ray density.
The “DelWat” argument should be provided in the event that you wish to delate all input/o riginal waters that do not match the RISM peaks. Otherwise, the originally provided waters will be kept in the simulation. |
–rismFile | N/A | (Optional) Provide a prior binary 3DRISM density file if available. This option will “speed up” the calculation but it should only be chosen if the RISM density file coresponds to the XYZ coordinates provided. |
–rsigma | 9.0 | Set sigma cuttof for RISM waters added using the MOE interface to 3DRISM. |
–x0sigma | 3.0 | Set sigma cuttof for add X‑ray waters. These waters are added using Coot and they are kept regardless of their agreement with the RISM prediction. |
–xsigma | 2.5 | Set sigma cuttof for X‑ray waters in RISM. These waters are added using Coot and waters between xsigma and x0sigma are retained ONLY if they agree with the RISM prediction. |
(Experimental) MOE‑based Docking Options
Option | Default | Description |
–dock | none | Dock ligand into density with MOE and specify the directory for docked structures. |
–ligandFile | none | Specify the name of ligand file (mol2 or pdb) which will be docked into density using MOE. |
Debug Options
Option | Default | Description |
–help | N/A | Print qbphenix help |
–debug | N/A | (Advanced) Flag which prevents the automatic deletion of h5 and geo files. |
-verbose | 1 | (Advanced) Set the integer verbosity level to run DivCon. |
2. (Advanced Users) Direct phenix.refine options
Command Line Options
Below is a full list of command line options that have been added to phenix.refine once the libQB package has been installed.
Option | Default | Description |
qblib= | False | The keyword is required (qblib =True) if you wish to run the QM computations within PHENIX |
macro_cycle_to_skip= | -10 | Skip the DivCon run for the specified macro cycle of the refinement. When necessary the common choice is macro_cycle_to_skip=1 for when the starting structure is of questionable quality. Any negative value will turn off the skipping process and the QM calculation will be invoked at the beginning of the refinement. |
qblib_np= | 2 | Select the number of processor cores on which to run multi-threaded QM calculations. Setting this value to 2 (or higher) dramatically decreases the time of the refinement as compared to the value of 1. |
qblib_mem= | empty | Specify the upper memory limit to run QM calculations in in kb, mb, gb, or tb. For example, 2gb or 900 mb. The default is None or empty and the amount of memory will be automatically chosen during the QM run using either a percentage of the available memory as an upper limit or else ulimit as set by PBS, SGE, etc. |
qblib_method= | pm6 | Specify the QM method for the energy calculation in DivCon. Acceptable values are am1 and pm6. |
qblib_region_selection= | Request the region QM refinement by defining the center of the selection; for example, qblib_region_selection=”chain L and resname CLR and resid 1″ . The selection qblib_region_selection=”resname CLR” would define the multiple selection for all ligands with the name CLR. | |
qblib_region_radius= | 3.0 | The size of the main QM region in which all residues within X â„« from any atom of the center of the selection specified with ‘qblib_region_selection ‘ will be included. |
qblib_buffer_radius= | 2.5 | The size of the QM buffer region in which all residues within X â„« from any atom of the main QM region will be included in the calculation, but for which the standard, stereochemical restraint gradients will be employed. |
qblib_max_numberOfFailure | 10 | Quits the PHENIX refinement if the number of DivCon failures during the QM energy calculations exceeds the specified number. The large number of failures renders the QM refinement meaningless. |
Manual Contents
- Manual: Phenix/DivCon
- Installation
- Phenix/DivCon (Command Line) Tutorial
- Phenix/DivCon (MOE Interface) Tutorial for 1AZM Case Study
- Phenix/DivCon: FAQ
Explore the DivCon Plugin