Installing HKL-2000

Installation of HKL-2000 uses an installer program that guides you through the installation process. The HKL installer and executables of all programs can be obtained from the HKL Research website (https://hkl-xray.com). Details of the installation process are contained in Appendix - HKL-2000 Installation beginning on page 128.

To install and run HKL-2000, you will need to obtain a license key from HKL Research. Details of the licenses are available on the website. Academic users who collect data at a synchrotron beamline where HKL-2000 is installed may obtain a 30-day license free of charge to reprocess their data. The license can be released for one computer up to 3 times per year.

To obtain the license key, you need to run the program (access_prod) program on each machine that you plan to install the HKL-2000 programs. Details of this are also in the Appendix - HKL-2000 Installation

Starting HKL-2000

The installer places an HKL-2000 icon (Figure 11) on the desktop that will launch the program. The icon will set important environmental variables and launch a terminal window that will display HKL-2000's runtime information.

Figure 11. The HKL-2000 Start Icon

 

The Installation Directory HKL-2000 can be installed in any location, but we strongly recommend the directory c:\HKL for Windows installations. The HKL Installer will ask where you would like HKL installed and will create an icon that will launch HKL-2000. If you are working with an older version of the suite, you can use a non-standard directory if you set the environmental variable $HKLPATH. For instance, if all programs are installed in the directory /home/janedoe/hkl2000 the following commands can simplify launching HKL. You may want to put these in your login scripts. For Bourne-type shells (sh, bash, dash, etc.): $ export HKLPATH=/home/janedoe/hkl2000 $ alias HKL2000=$HKLPATH/HKL2000 For C-type shells (csh or tcsh): $ setenv HKLPATH /home/user/prog2000 $ alias HKL2000 $HKLPATH/HKL2000 Then for both $ HKL2000

 

You may start HKL-2000 from a terminal if you wish. If the HKL-2000 suite has been installed in the default location (/usr/local) you can typically just type HKL2000. The HKL-2000 suite must be configured for your system, and a license key must be installed before it can be run. Installation and configuration of the suite are described in the Appendix. You must have permission to write files in the directory you start HKL-2000 because the program writes several files to the working directory.

Files created by HKL Filename.sca contains the scaled and reduced data. This is the end product of data reduction and the input for structure solution programs. It is important for structure deposition! scale.log is important for structure deposition! It contains detailed information about data scaling. The most important tables are at the bottom of the file. peaks.file is the file that contains peaks selected by the Peak Search routine reject is the list of rejected reflections created in scaling hklpredictionS is a binary file that contains a listing of predicted reflection positions den.in is a listing of the commands used to run the indexing den.out is a modified log file of the indexing scl.in is the Scalepack input file xdisp.in and xdisp.out are input and output files for the display program. filename_###.x (dot X files) contain tabulated data describing reflections for each individual frame. Some experimental details are found at the bottom of these files (i.e. x-beam, y-beam, cell parameters, refinement parameters for this frame.) - Description: Shaded sidebar with color bar accent

Site Definitions

To work with diffraction data, HKL needs to know details about the experimental setup. This information is stored as a data collection "site". Therefore, the first dialog to appear asks you to choose a site definition (detector and other site information) from the menu (Figure 12). You must select a site definition (or use the Site included option) before continuing to the program.

A site definition contains information about the experimental setup, such as the X-ray detector, goniostat, and X-ray source. The definition includes the detector name and type, the axes of rotation and misalignment parameters of the goniostat, the X-ray beam properties, and properties of the diffraction image files collected, especially the expected suffix for these files (e.g., *.img, *.osc, etc.). It contains the X and Y coordinates of the direct beam position on the detector, which are crucial pieces of information. The site files are traditionally stored in /usr/local/hklint but can be placed in any directory if the environmental variable $HKLDIR is set. If your installation of HKL-2000 was created using the installation program, then the icon it creates will automatically set this variable. This directory will contain one subdirectory for each site. Each site definition directory contains a "site file" called def.site where most of the settings are stored. These subdirectories may also contain other files such as detector calibration data (in the form of files called def.cal and denzo_nonunf) which are necessary for processing uncalibrated data. For synchrotron data processing, these files should be obtained from the synchrotron beamline.

 

Figure 12. The HKL-2000 launch and site selection screen.

 

The Site Included option

The site included option tells HKL-2000 to use a def.site that is located in the same directory as the data. This option can be convenient when sharing data or downloading data from ProteinDiffraction.org.

Creating a new site

To make a new site, click on the new site button. A new window with a field to give the new site name will open. This will create a new subdirectory in /usr/local/hklint or $HKLINT with the name you give (note that the user running the program will have to have permission to write to this directory). It's best to use a descriptive name that does not contain spaces. It can be helpful if the name indicates a time period, like home_Raxis_fall_2018 or 19-ID_2018_run3 (Figure 13). Now click on the detector type button, and select your detector. Some detector manufacturers have different models, and these are listed under each general detector heading. If your detector is not listed at all (unlikely, but theoretically possible), you will have to contact HKL Research (or your beamline coordinator) for the appropriate site file.

Figure 13. The "New Site" selection pane.

The most important values in the site file are the X-beam and Y-beam positions and goniostat type. Be sure to record them every time you collect data because they can fluctuate. The default values for newly created def.site files will almost always have incorrect values! You can change these by clicking on Site Configuration (see below) and make changes using the dialog. While not recommended, it is also possible to edit the appropriate line in the def.site file in the newly created subdirectory and then restart the program. Collecting and processing data with a well-characterized crystal (such as lysozyme) can ensure you are using a correct site definition.

 

 

Choose the appropriate goniostat type from the predefined list. Presently the following types of goniostats are available:

 

Once you've selected the correct detector and goniostat, click OK. The new site definition directory will be created with the appropriate files, including a def.site file. You will now get the main HKL‑2000 window.

 

Make sure the site file is correct! Click on Site Configuration on the top menu bar, and this will bring up a window with the site parameters (Figure 14 and Figure 15 ). You can verify that the detector is the right one, and you can specify important parameters like the X Beam and Y Beam Positions and the Wavelength and so on.

 

Features of the site creation dialog:

1.   You can load in data from an existing site file by clicking on the load site info button. This brings up a file navigation window where you can choose a site file (def.site). This is very useful for just changing the beam position.

2.   The anode type (and thus the wavelength) for rotating anode X-ray sources is specified in this window, while the wavelength for synchrotron X-rays is specified by data set in the main HKL‑2000 window (and is hopefully, but not guaranteed, to be correctly specified in the image file header -- check to make sure!).

3.   Clicking on save site info means that you are permanently editing or updating the file called def.site (in /usr/local/hklint/sitewhatever). For this you will need a password (which is provided to the Contact Person your group has specified with HKL Research). This is not a typical user option. Also, the user running the program must have permission to write to the directory that contains the site file (usually /usr/local/hklint/sitewhatever).

4.   You can use your updated site parameters without saving them to the def.site file by clicking the close button. The altered site parameters will remain in effect until you quit the program, after which time they will revert to the original values.

 

f3a

Figure 14. The main dialog for site creation.

f3b

Figure 15. The Advanced and Description tabs of the site configuration window.

What if I choose the wrong site because I wasn't sure? If you select the wrong site file, the display most likely will be distorted, which is what happens if you have selected the wrong detector type. If you select a site that specifies the same detector type as your images, the display will look normal, but the indexing and integration will fail if other parameters (i.e. the beam position) are incorrect. If you are lucky and the detector is correct and the goniostat description is compatible, you may be able to process your data. What is the meaning of the goniostat alignment windows? The windows describe the six mis-setting angles of a particular goniostat. The choice of the single axis goniostat allows only the first two mis-setting angles to be entered: 1) Angle around the beam 2) Angle describing the non-perpendicularity of the angle between beam and omega/spindle axis The other goniostat types require all six mis-setting angles to be defined. The four remaining angles are: 3) Omega zero 4) Deviation between nominal and actual kappa (chi) omega angle 5) Kappa zero 6) Deviation between nominal and actual kappa (chi) phi angle A change of the spindle axis direction requires a corresponding change of the first mis-setting angle by 180 degrees. This is equivalent to the Denzo command film rotation 180.