Phenix/DivCon Installation

Phenix/DivCon Installation

1. Prerequisites and basic installation instructions:

  • If you need access to the software installation package, contact sales@quantumbioinc.com for information and download instructions. If you attempt to run the software and have any difficulty, email support@quantumbioinc.com for additional information.
  • Platform Support:
    • Linux_x86: The primary distributions include CentOS/RHEL 5 and CentOS/RHEL 6, and the software is also regularly tested on newer versions of Fedora, Ubuntu, etc.
    • Mac OS X 64bit: The build for Mac OS X is built on Mac OS X v10.7.5 and should therefore run on any 64bit OS version which has come out since.
    • Platform Specific Notes:
      • macOS 10.13: There is an incompatibility between the libz libraries provided in this pacakge and the one provided by Apple. Therefore, you should perform the following steps: 
        rm /path/to/DivConSuite/darwin-i386/lib/libz.*
rm /path/to/DivConSuite/python/darwin-i386/lib/libz.*
  • Use of PHENIX/DivCon requires the installation of both the DivCon Discovery Suite as noted in the general Suite manual and the installation of Phenix 1.10 or later. Here are some version-specific notes:
    • Nightly/Dev versions: in our experience, the “dev” (or nightly build) versions of Phenix intermittently break any number of hooks and options. If you run into any trouble with a dev version, please shift to a newer/different version.
    • Phenix 1.13: There is a known typo on line 195 of file phenix-1.13-2998/modules/cctbx_project/mmtbx/refinement/minimization.py (which has since been fixed in later Phenix versions).

self.tmp_XYZ = self.model.gett_sites_cart()

should read:

self.tmp_XYZ = self.model.get_sites_cart()

    • Phenix 1.14: The more recent release builds of Phenix have broken compatibility with the h5py library used in our package. Therefore, in order to use this version of Phenix with the DivCon Discovery Suite, you need to use the follow these steps (this problem has been fixed in later Phenix versions and as of Phenix 1.15 this step is no longer required):
      1. Remove two h5py folders under phenix: 
        rm -rf ~/phenix-1.14-3260/base/lib/python2.7/site-packages/h5py
rm -rf ~/phenix-1.14-3260/base/lib/python2.7/site-packages/h5py-2.7.1-py2.7.egg-info
      2. Copy h5py-2.9.0-py2.7-linux-x86_64.egg from the DivCon Suite into Phenix: 
        cp ~/DivConDiscoverySuite-DEV.427/python/linux-x86_64/lib/python2.7/h5py-2.9.0-py2.7-linux-x86_64.egg ~/phenix-1.14-3260/base/lib/python2.7/site-packages/
    • Phenix 1.15: The more recent release builds of Phenix have fixed the above noted problems; however, a new issue has been introduced when using MOE as the CIF generator. In the final step of refinement, the Phenix Consortium has added a feature which writes out a CIF file for the refined ligand. While this can be useful, the write_model_cif_file routine appears to be brittle and will often throw a naked Python error. Until the Consortium has issued a fix, it is recommended that you add a “return” on line 595 immediately after the “def write_model_cif_file(self, f):” source code: 
      958:  def write_model_cif_file(self, f):
959:      return
960:      print >> self.log, "Writing refined structure to CIF file:   ....
    ......
  • If you wish to use MOE/DivCon plugins, you will need to run a fairly recent version of MOE. That said, the following notes are provided for specific MOE versions:
    • MOE2018 and MOE2019: With these versions of MOE, the built in CIF reader has become more sensitive to the older CIF file provided by Phenix. Therefore, MOE will error out when it encounters older files with the older “coval” bond type. In previous versions of MOE, the coval type was assumed to be a single bond. Making the following change will return the software to its previous functionality:

Add a line after line ~4194 [MOE2018] or ~4361 [MOE2019] or ~4385 [MOE2019] of $MOE/svl/io.svl/io_cif.svl
AFTER: local bondtype = rep [-1, length bondorder];
ADD: bondtype | bondorder == ‘coval’ = 1;

  • The package contains most of the 3rd party software used by the Suite; however, some basic system libraries are also be required. In most cases, these packages will already be installed on your system, but if you see errors that certain *.so files are missing when you try to run qmechanic, then your administrator may need to install some of them for you. The following line will install this software on a yum-based distribution. Other distributions will have similar package management facilities.
    • CentOS, Fedora, Amazon Linux, and other yum-based distributions: 
      sudo yum install bzip2-libs.x86_64 glibc.x86_64 keyutils-libs.x86_64 jq.x86_64 \
krb5-libs.x86_64 libcom_err.x86_64 libselinux.x86_64 openssl098e.x86_64
    • Ubuntu, Debian, and other apt-get -based distributions (note: the 32bit libs are only required for the installer. The “tar-ball” installer can be used to circumvent this requirement): 
      sudo apt-get install ia32-libs bc bzip2 libc keyutils krb5-kdc bash openssl perl gzip jq
  • To install the DivCon Discovery Suite, download the package from the link provided (email sales@quantumbioinc.com to request a download link) and run the installer. You may install the software in your own directory and administrator privileges are not required. Both an installer image and a tar-ball image are available and the software may be installed using any of these steps:
    • Option #1 (Installer – Linux): 
      chmod +x DivConDiscoverySuite-b####-linux-installer.bin
./DivConDiscoverySuite-b####-linux-installer.bin
    • Option #2 (Installer – Mac): 
      tar zxvf DivConDiscoverySuite-b####-osx-installer.app.tar.gz
open DivConDiscoverySuite-b####-osx-installer.app
    • Option #3 (Installer – cross-platform tar ball): 
      tar zxvf DivConDiscoverySuite-b####.tar.gz

Please NOTE: For Option #3, if you wish to use CSH/TCSH, then you will need to update the QBHOME environment variable found on line 6 of the /path/to/DivConDiscoverySuite/etc/qbenv.csh file by replacing the IN_INSTALLDIR string to match the root path to your installation.

  • To install the license file, if you don’t already have a license file, request one from sales@quantumbioinc.com then copy the file into the package etc/ directory (be sure the name the file “license”). 
    gunzip provided_license_file.gz
cp provided_license_file /path/to/DivConDiscoverySuite-b####/etc/license

2. Environment Variables and Executing Phenix/DivCon

Once both Phenix and DivCon have been installed, the environment needs to be updated to include both packages. This is done by sourcing files in both packages either for tcsh/csh or bash.

Bash:

% source /path/to/phenix-1.9-####/phenix_env.sh
% source /path/to/DivConDiscoverySuite-b####/etc/qbenv.sh

Tcsh/csh:

% source /path/to/phenix-1.9-####/phenix_env
% source /path/to/DivConDiscoverySuite-b####/etc/qbenv.csh

Note: due to a bug in some versions of tcsh/csh, you should not include any environment variable (e.g. $HOME) in the source line above.

3. Install QuantumBio-supplied plugins to MOE from CCG

The DivCon Discovery Suite includes SVL files within the svl directory to extend the functionality of MOE and MOE/batch specifically for X-ray refinement. To install this plugin, use the following steps:

  • Option #1: For system-wide installation of the QuantumBio MOE menu, add the following line to the end of the $MOE/lib/moe-menus file:include “/path/to/DivConSuite-bXXXX/moe-menus”
  • Option #2: Or for user-specific installation of the QuantumBio MOE menu, add the following line to the end of the $HOME/moe-menus file (create this file if it does not exist):include “/path/to/DivConSuite-bXXXX/moe-menus”
  • Make sure the MOE bin directory is in your path so that it will be picked up by the execution script.export PATH=/path/to/MOE####/bin:${PATH} # for sh/bash
    setenv PATH /path/to/MOE####/bin:${PATH} # for csh/tcsh
  • For MOE2015, with the QuantumBio-provided SVL files can be loaded and run using the following on the command line: 
    /path/to/DivConSuite-bXXXX/bin/qbmoe     # to start MOE GUI 
/path/to/DivConSuite-bXXXX/bin/qbmoebatch    # to start MOE/batch command line
  • For MOE2016, CCG removed the MOE_SVL_LOAD environment variable and it is no longer used. Therefore, you must perform the following steps within your home directory: 
    mkdir -p $HOME/moefiles/svl # create local MOE system directories.
cd $HOME/moefiles/svl ; ln -s /path/to/DivConSuite-bXXXX/svl qb.svl # create symbolic link to supplied SVL

Note: going forward, you must keep this link updated for each package distribution provided by QuantumBio. Each time QuantumBio distributes a new package and your organization installs it, you must update this link to the new DivConSuite-bXXXX/svl directory.

4. Test Environment

When both environment files are sourced, phenix.refine will automatically load DivCon and its tools. For example, to see the new command line options, run the following command:

  phenix.refine --show-defaults


.... 
qbio { 
qblib = False 
qblib_file_target = '' 
qblib_target_method = None 
.... 
}

The rest of this manual provides additional information on the available command line options, best practices, and tutorials. Certainly, Contact US for additional guidence if you run into any trouble.

Manual Contents

Explore the DivCon Plugin