README file for Hex 6.12 Hex is an interactive molecular superposition and rigid-body docking program for use with "large" molecules such as protein domains and DNA fragments. Hex can read (and write) PDB and SDF coordinate files. Hex will run on most Windows-XP/Windows-7 and Linux PCs, and on recent Mac PowerPCs and PowerBooks. This version (19 March 2012) provides highly parallelised (CPU multi-threaded) and GPU-accelerated (using CUDA on Nvidia graphics cards) docking calculations. For Windows, download and double-click the self-installer: hex-6l-win.exe (Windows without CUDA) hex-6l-win-cuda.exe (Windows with CUDA) Similarly for the Mac, download one of the the disk image, and then double-click the package bundle contained within it: hex-6l-osx-intel.dmg (Intel Mac, OS X) hex-6l-osx-ppc.dmg (PowerPC Mac, OS X) For the 32-bit Linux versions, you will need to download the following files: hex_setup.bin (Installation script for Linux) and one of hex-6l-x32-ub9.10.tgz (Intel Linux 32-bit without CUDA) hex-6l-x32-ub9.10-cuda.tgz (Intel Linux 32-bit with CUDA) For 64-bit Linux versions, download one of the following: hex-6l-x64-ub9.10.tgz (Intel Linux 64-bit without CUDA) hex-6l-x64-ub9.10-cuda.tgz (Intel Linux 64-bit with CUDA) Pick the one that most closely matches your own or version of Linux. Generally, the 32-bit binaries should run on 64-bit machines. For Hex version 6l, "CUDA" means "CUDA version 4.1". The setup script is intended to simplify the installation process, and can normally be trusted to install Hex correctly, even if you have already installed an earlier version of the program. The script will add any necessary environment variables to your default shell environment. In cases where a central file server is used to serve files to different types of workstations, several different executables may be installed into a single hex installation directory. It is also safe to install version 5 into the same directory structure as earlier versions. If you prefer to install the program manually, you should create a hex directory, "cd" to that directory, and then uncompress the distribution files into it. For example, assuming you are installing the SGI version, use: zcat hex-6l-x32-ubuntu-9.10-cuda.tgz | tar xvpf - In order to make Hex work properly, your login script (either .login or .profile) should set the environment variable HEX_ROOT to the hex installation directory. You should also add Hex's bin directory to your PATH so that (a) you can run Hex, and (b) Hex can find the files it needs under HEX_ROOT. These two steps are normally performed by the hex_configure.bin script. Optionally, you can also specify directories that specify where Hex should start looking for colour files, macro files, and PDB files, and you can specify the location of a temporary cache directory (all except the hex installation directories are optional and must be created manually). You can also specify the default number of CPUs and GPUs to use on a multi-processor system, and request stereo graphics if your hardware supports stereo. Here's a C-shell example (I have these lines in my ~/.cshrc file) setenv HEX_ROOT /home/dritchie/hex # required setenv HEX_PDB . setenv HEX_MACROS . setenv HEX_COLOUR . setenv HEX_DATA /home/dritchie/hex_data setenv HEX_CACHE /tmp/dritchie/hex_cache setenv HEX_STARTUP /home/dritchie/hex/examples/startup.mac setenv HEX_CPUS 8 setenv HEX_GPUS 2 setenv HEX_MESSAGES yes setenv HEX_STEREO yes setenv HEX_CUDA_PATH /home/dritchie/hex/cuda64-4.1 setenv PATH ${PATH}:${HEX_ROOT}/bin # required For Bourne and Korn-shell users, the corresponding commands (in ~/.profile) would be: set HEX_ROOT = /home/dritchie/hex # required set HEX_PDB = . set HEX_MACROS = . set HEX_COLOUR = . set HEX_DATA = /home/dritchie/hex_data set HEX_CACHE = /tmp/dritchie/hex_cache set HEX_STARTUP = /home/dritchie/hex/examples/startup_v5.mac set HEX_CPUS = 8 setenv HEX_GPUS 2 set HEX_MESSAGES = yes set HEX_STEREO = yes set HEX_CUDA_PATH = /home/dritchie/hex/cuda64-4.1 set PATH = ${PATH}:${HEX_ROOT}/bin # required export PATH HEX_ROOT # required export HEX_PDB HEX_MACROS HEX_COLOUR HEX_DATA HEX_CACHE export HEX_STARTUP HEX_CPUS Stereo graphics is only available if you have a suitable graphics card AND if you have installed and configured the appropriate drivers. Please see the Hex Manual for more details. In addition to the README, PROBLEMS and LICENCE files, the hex directory should contain the following 7 directories: bin exe doc data examples pipes cache If you download the CUDA version you will also get a directory which contains the CUDA run-time libraries (currently using CUDA version 4.1): cuda64-4.1 cuda-4.1 Typing "hex" at the Unix command prompt should locate the script hex in the bin directory which then launches the appropriate executable from the exe directory. The exe directory may contain several executables The examples directory contains several PDB files and Hex macro files. Unless you set the above environment variables, Hex will first look in the examples directory for any macro and PDB files you want to use. The data directory contains the runtime data files necessary to colour and charge protein and DNA molecules, for example. The pipes directory contains scripts which allow the molecular structures in the current Hex scene to be written directly to external programs such as GRASP or Molscript. The basic installation includes a Manual and some examples. A more extensive list of examples is provided in the optional docking_examples.tgz file, which is available on the main Hex web page. A much more extensive set of docking test cases can be obtained from Zhiping Weng's group at: http://zlab.bu.edu/zdock/benchmark.shtml The largest single repository of 3D protein structures is the Protein Data Bank (PDB), hosted by Rutgers University at http://www.rcsb.org/pdb/. Installation Problems? Try looking at the PROBLEMS file in $HEX_ROOT. Please remember that "Hex" is essentially a research program and it is provided "as is", without any guarantee of updates or user-support. I will attempt to respond to any problems and I would welcome suggestions for future enhancements. Dave Ritchie INRIA Nancy Grand Est Nancy, France email: Dave.Ritchie AT inria.fr (please make your own AT sign) web: http://www.loria.fr/~ritchied/ Hex: http://hex.loria.fr/ HexServer: http://hexserver.loria.fr/