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: In refinement, provide reflection data (e.g. MTZ) file for refinement. This file is given directly to phenix.refine and therefore any format supported by Phenix is acceptable. For explicit water picking (using RISM) you should provide the CCP4 map. Finally, in the event that you wish to perform a Docking calculation, the MTZ file with map coefficients should be provided.
–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): PHENIX style: “chain A resname LIG resid 23” or DivCon or “URI” style: “/A/CRZ/501//, /A/LIG/23//” Choosing “auto” will automatically select all ligands (defined as non‑peptide/non‑nucleotide species)
–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

Explore the DivCon Plugin