Appendix - HKL-2000 Installation

Obtaining HKL-2000 installation files

 

An HKL installer and executables of all programs can be obtained from https://hkl2000.hkl-xray.com . To download the programs, use the login id: hkl2000ftp. The password can be obtained through the automatic password system (see the web page) or by contacting HKL Research, Inc. via email.

Several versions of HKL-2000 are available on the FTP server. The latest version, which is described in this manual, is version 717. If the program has been updated since the initial version release, then the version may have a version extension, such as v717.1. The directory corresponding to this version has versions for several operating systems, as well as copies of the HKL Installer for each operating system. Each file will be compressed using standard compression used for that operating system. For example, if you are using Linux, use the command

> tar zxf HKL2000_v717.1_installer-Linux-x86_64.tar.gz

 

This will create the directory named after the downloaded file. The files contained within this directory will depend on the file downloaded. For example, the HKL installer file will contain a file access_prod, the HKL_installer, a README.txt file, and a directory of setup_files. The compressed file containing the Linux executables will contain a README.txt file, setup files for Bash or CShell (hkl_setup.sh and hkl_setup.csh, respectively), and bin, data, and lib directories.

 

License key

In order to run HKL-2000 or use the HKL Installer, you will need to obtain a license from HKL Research Inc. The license key is contained in a file cr_info. The traditional location of this file is in the /usr/local/lib directory. The HKL Installer will look for the file in this location but allows you to specify the location. To obtain the license key, you need to run the access_prod program on each machine that you plan to use for running the HKL-2000 programs. The access_prod program is main directory if you downloaded the installation file and in the bin directory if you downloaded the executables. Executing the access_prod results in the following text-based dialog (example answers to the prompts are shown in red):

 

 

If the answer is y (yes), the access_prod program may automatically send an e-mail with a request for an access file: cr_info. It does not always work, though (depending upon how the email system is configured on your computer. If the answer is n (no) the program will produce the following info file. You may save the info file and afterwards "manually" send it to hkl@hkl-xray.com.

 

Please:

 

This is an example of an info file created by the access_prod program (comments in italic):

 

HOST-NAME: p4.med.state.edu

(extracted by the program - do not edit!)

NOTE: the field is limited in length to 30 characters

HOST-ID: -2035379618

(extracted by the program - do not edit!)

HOSTNAME: state.edu

(extracted by the program - do not edit!)

HW_PROV: sgi

(extracted by the program - do not edit!)

CPU-SERIAL: Linux, eth1, 94DE...

(extracted by the program - do not edit!)

INSTITUTION: State University

Licensee's Institution name

PI: John Doe

Principal Investigator or Group Leader

CONTACT: Jane Doe

Contact Person

DETECTORS: mar raxis4

Detector Format Families

NO-OF-DET: 2

List detectors you expect to use, like Eiger or Rigaku

PROVIDER: HKL Research, Inc

License Provider: Rigaku/MSC, HKL Research, etc.

VERSION: 717

Requested Version of the Program

EXPIR: noexpir

 

 

 

 

Using the HKL Installer

The default location of the HKL-2000 installation is in /usr/local/HKL/ in a directory named for the version number. This directory almost always requires elevated privileges, so you will have to start the program with sudo privileges (sudo ./HKL_installer). The installer will first verify that your license key is valid. The traditional location of the license key file (cr_info) is in /usr/local/lib. The text area at the bottom will provide details about your license (Figure 118).

The buttons at the bottom of the installer let you select which HKL version you would like to install. Select HKL-2000 to install the program described in this manual. Click "Continue" to see version specific license. You must accept the license to proceed (Figure 119).

 

 

 

Figure 118. Select to install HKL-2000

 

 

Figure 119. Read and Accept the HKL-2000 License

The following screen will let you select if you want to create a new HKL installation or upgrade an existing installation (Figure 120).

 

Figure 120. Create a new installation or upgrade an existing one

 

The next dialog allows you to specify the location of the program and the detector definition directory (Figure 121). The default locations for these are /usr/local/HKL and /usr/local/hklint, respectively. You may change these if you want to use another directory or do not have write permission for these directories. The default folder for HKL will include the version number. This page will also ask if you want to create a desktop icon to launch HKL-2000. Once you have things set up how you would like, click Install to finish the setup. The installer will then check if you have permission to write to these directories and install all the necessary files.

HKL-2000 can optionally use some CCP4 programs, and the HKL Installer will let you select the location of CCP4 (Figure 122).

If the installation is successful, you will see a confirmation screen (Figure 123).

Figure 121. Select the installation directory

Figure 122. External program selection

Figure 123. Finish the installation

Installing HKL-2000 in Windows HKL-2000 can be installed in Windows 10 (build 1703 or greater). This requires the activation of Windows Subsystem for Linux (WSL), which allows you to run a complete Bash shell in a sandbox alongside your Windows operating system, and installation of an X-windows implementation. Because this requires changes to your operating system, the procedure is beyond the scope of this manual. However, the instructions can be found on the HKL Research, Inc. website ( https://hkl-xray.com/windows-installation ). Once WSL and an X-windows client has been setup, installation of HKL-2000 essentially follows the instructions contained in this manual.

 

Installing HKL-2000 manually

 

If you would like to install HKL-2000 using the traditional method used before the HKL Installer was available, download and uncompress the executable directory in a suitable location. Typically, the executables are placed in the directory /usr/local/HKL, which requires system administrator privileges. You can also place executables in an arbitrary directory, for instance,/home/joe/programs/hkl. In that case, you have to set the environmental variable $HKLPATH to that directory. The exact command will depend on the shell you are using to run programs (this can be determined by typing echo $SHELL).

For Bourne-type shells (e.g., sh, bash, dash, etc.) the command is:

export HKLPATH=/home/joe/programs/hkl

For C-type shells (csh, tcsh, etc.) the command is:

setenv HKLPATH /home/joe/programs/hkl

 

HKL-2000 also requires a directory hklint for site files. Its default location is:

/usr/local/hklint

 

Typically, accessing this location requires administrator privileges, but it can be changed to an arbitrary location, by setting the environmental variable $HKLDIR.

For Bourne-type shells (e.g., sh, bash, dash, etc.) the command is:

export HKLDIR=<path>

For C-type shells (csh, tcsh, etc.) the command is:

setenv HKLDIR /home/joe/programs/hkl

 

 

The anom.dat file should be placed in this directory together with subdirectories containing the site files. The site file (def.site) of each detector (home or synchrotron) should be stored in its own directory. Each such directory should be appropriately named to identify the specific facility and the detector easily.

 

Example hklint directories:

  • /usr/local/hklint/Raxis4
  • /usr/local/hklint/Spring8-BL23-Quantum4
  • /usr/local/hklint/BNLX25-Quantum4

 

You can check how the environmental variables were set by typing the command:

 

env | grep HKL

 

To keep the values of the HKL environmental variables for subsequent logins, you should modify the configuration files for the shell you are using (~/.tcshrc, ~/.cshrc, ~./bashrc, etc.).

 

 

Starting HKL-2000

After you have installed HKL-2000 and placed the license file cr_info either in the /usr/local/lib directory or the directory you specified during installation, there are two ways to start the program. If you have used the HKL Installer, the program can be started from a terminal window by typing:

HKL2000

If you receive an error message "no display name and no $DISPLAY environment variable", it means that the X windows system is not working or not configured properly. On Mac OS X, you need to start the X11 application (from the Finder's Go menu, choose Applications, then choose Utilities and select X11). You should see the X11 icon in the dock, double click on it to open an xterm window and start HKL-2000 from this window.

If you receive an error message "Command not found", it means that HKLPATH is not in the executable command search path. Modify the environmental variable PATH or type a full path e.g. /usr/local/bin/HKL2000.

 

What files make up the HKL-2000 suite, and what do they do?

HKL2000 - The main program with the graphical user interface

access_prod - The program that prepares file necessary for license key generation. It has to be executed on each computer that will run the HKL-2000 suite.

anomalous - Anomalous signal analysis

cdir_t - Directory manipulation tools

denzo_3d - Auto-indexing, refinement, and integration; 3-D processing

hklfilename - Filename manipulation tools

hklsysinfo - Program that gathers information about computer resources

readheader - File header reader

scalepack - Scaling data comprising up to 2000 frames and 2 million reflections

scalepack16m - Scaling data comprising up to 2000 frames and 16 million reflections

scalepack8m - Scaling data comprising up to 2000 frames and 8 million reflections

scalepacklvirus - Scaling data comprising up to 3000 frames and 50 million reflections

scalepackmanyframes - Scaling data comprising up to 4000 frames and 2 million reflections

scalepackmf6500 - Scaling data comprising up to 6500 frames and 3 million reflections

scalepackribo - Scaling data comprising up to 2000 frames and 32 million reflections

scalepackvirus - Scaling data comprising up to 2000 frames and 32 million reflections

strat - Strategy and simulation

suser - Internal communication program

xdark - Dark current calculation

xdisp - Image display and measurement