HKL-2000 and HKL-3000 can now be installed in Windows 10 systems, giving you the flexibility to install the software in the three most popular operating systems (Linux, iOS, and Windows). The instructions provided here are equally valid for HKL-2000 and HKL-3000 versions 715 and above.
HKL-2000/HKL-3000 for Windows 10 works with the Windows Subsystem for Linux and requires several steps to prepare your system before installation. In a nutshell, you must enable the Linux component of Windows (Bash), install a third-party X-server (if you don’t already have one), and create an HKL directory all users have access to. If you are installing HKL-3000, you should first install the HKL-3000 prerequisites (i.e. CCP4 with Shelx and Coot).
We recommend that you use an administrator account to perform the following steps.
Enable the Windows Subsystem for Linux
Your Windows version must be Windows 10 build 1703 or greater.
There are several ways you can enable the Windows Subsystem for Linux (WSL), which allows you to run a complete Bash shell in a sandbox alongside within your Windows operating system. Official instructions for installing this feature can be found at https://msdn.microsoft.com/en-us/commandline/wsl/install_guide, and we recommend you follow Microsoft’s instructions. We recommend creating your Bash user using the same username and password as the Windows account you are using.
We have tested the following procedure with the Ubuntu installation available through the Windows Store.
Working with the Windows Linux Subsystem
After installing a Linux distribution on Windows, click on the Windows Start Menu Icon and select the Bash Icon from the alphabetical list, or type Bash. For Ubuntu installations, this icon will be named “Bash on Ubuntu on Windows.” If you right-click on this icon, you can pin the icon to your start menu or taskbar.
In Bash, your Linux home directory will be /home/[user_name]. Your Windows drive is accessible at “/mnt/c”. Therefore, your Windows home directory is “/mnt/c/Users/[user_name]”.
To make navigation easier, you may create links between your Linux directories and Windows folders. (The HKL Installer, a program that will guide you through the HKL-2000/HKL-3000 installation process, will create a link /home/[user_name]/win_home that points to your Windows home directory.)
Data should be kept on Windows side so they are accessible to both Bash and Windows. The program and the data you work with should be on Drive C (within the Linux file system is OK). You may want to create a link to make accessing the data easier (i.e. ln -s /mnt/[drive]/[windows data directory] /home/[user]/data ).
From Windows, you can find your Linux files at:
C:\Users\USERNAME\AppData\Local\Lxss\home\USERNAME
You will have to enable “show hidden folders” in Windows Explorer.
Update the Bash installation and install some required libraries
Open a Bash shell and issue the following commands to install pre-requisites.
$ sudo apt-get update $ sudo apt-get install libglu1 libxmu6 xterm tcsh tcl
Install an X-windows implementation
HKL will have to forward graphical information from the Bash environment to the Windows environment. HKL-3000 has been tested with Xming, but may also work with others such as Cygwin/X. You will need to install all available font packages (i.e., Xming-fonts-7-7-0-10-setup.exe).
Install HKL-3000 pre-requisites in Windows
These pre-requisites are not necessary for HKL-2000 installations.
- Install CCP4 with Shelx and Coot from http://www.ccp4.ac.uk/download
Be sure to update CCP4 after installation.
Download and unzip the HKL Installer for Windows 10
You can obtain a copy of the HKL-3000 Installer for Windows from
using the password provided to you by HKL Research. Be sure to get the Windows version. It will be named HKL_installer_v###-for_Windows10.zip.
Unzip the installer using your preferred method (i.e., Right-click and “Extract All...”).
Obtain a License Key (cr_info file)
Run access_prod_win.bat (double click to run – the extension “.bat” will probably not be visible) and obtain a license key for HKL-2000/HKL-3000 from HKL Research. You may either email the access_prod results to hkl@hkl-xray.com or use the HKL License Management System at https://myhkl.hkl-xray.net/login.php . This latter option is only available for some users. For more details, refer to the HKL Research web page: http://www.hkl-xray.com/license-key .
Prepare a directory for HKL
Like many crystallographic programs, HKL needs some directories that every user will have access to. The Bash installation will be different for each user, so HKL Research recommends that you create an HKL directory on the root of the main drive (C:\HKL).
- Copy the HKL license key (cr_info) to this directory
- Create a folder for HKL Site Files (C:\HKL\hklint)
If you choose to use the default locations of the HKL Installer (not recommended), you will need to use a Bash shell to prepare for the HKL installation. The default locations of the key files and directories and the Bash commands to prepare them are below.
- License Key File: /usr/local/lib/cr_info
- Site File Directory: /usr/local/hklint
- HKL Program Directory: /usr/local/HKL
$ sudo mv /mnt/c/path/to/cr_info /usr/local/lib
$ sudo mkdir /usr/local/hklint
$ sudo chmod a+rwx /usr/local/hklint
$ sudo mkdir /usr/local/HKL
$ sudo chmod a+rwx /usr/local/HKLStart the Windows X-windows program
Once started, the X-windows program will run in the background until needed. The HKL Installer and HKL need to forward information from the Bash shell to the X-windows programs and will do so by issuing the command “export DISPLAY=:0”. Issue this command any time you need to run a graphical program from Windows Bash shell. If you ever see the error “Couldn’t connect to the display :0”, ask yourself if you forgot to start the X-server. Be aware that some X-windows programs can only be run by one Windows user at a time.
Run the HKL Installer
Your Window’s account must have administrator privileges to install HKL. Run HKL_installer_win.bat by double-clicking on it. It will guide you through the installation process.
The installer will first verify that your license key is valid. The text area at the bottom will provide details about your license. The buttons at the bottom of the interface window let you select which HKL version you would like to install: HKL-2000, HKL-3000sm (for small molecules), or HKL-3000. Click “Continue” to see version specific license agreement. You must accept the license conditions to proceed.
The next screen will let you choose if you want to create a new HKL installation or to upgrade an existing installation. If you have selected either HKL-3000sm or HKL-3000, you will be presented with a dialog requesting the location of the external programs used by HKL-3000. The installer may be able to determine the location of some of these programs based on your environmental variables. If you still need to select some programs, the installer can search for the files for you. Use the “Select” button at the bottom of the dialog to select a parent directory that contains one or more of the necessary programs.
The next dialog window allows you to specify the location of the program and the detector definition directory. The default locations for these are /usr/local/HKL and /usr/local/hklint. 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. The example shown below uses non-standard locations that would not require root privileges.
The installer will then check if you have permission to write to these directories and run checks to see if the external programs are installed correctly. If everything looks good, click “Install” to finish the setup.
You may want to add this icon to your start menu or pin it to your taskbar.
Launching HKL
As a reminder, your X-windows program must be running before starting HKL.
If you let the installer create an icon, you can now use it to launch HKL-3000. It will launch a Bash shell, set the display variable, and Launch HKL.
If a part of the HKL display is obscured by the taskbar, you can either:
- Edit the “Taskbar Settings” to automatically hide the taskbar (right-click on the Taskbar)
- Change the scaling for app in “Display Settings” (right-click on the Desktop)
Need some test data?
Visit ProteinDiffraction.org. You'll find there complete image datasets and site files for over 3000 macromolecules. Data that corresponds to the tutorial on the HKL Research web page and the tutorials on our YouTube channel can be found at https://proteindiffraction.org/project/Hhr_1wq6/ .
When you download a dataset from ProteinDiffraction.org, the corresponding site file will be in a directory within the “hklint” directory. Copy this directory to your HKLINT directory (suggested C/HKL/hklint/). You may name this directory anything you want. Unlike on Linux Systems, you cannot use a link (a shortcut in Windows) as a directory in HKLINT; therefore, if you want the “ADSC-Q4” to also be called “Hhr_1wq6”, you must copy and rename the directory. A shortcut will not work
Adding another user
To make it easier for other users to have access to HKL, copy the desktop launcher to your HKL installation directory (i.e. C\HKL). Other users can then right-click on the icon to pin the launcher to their Start Menu and/or taskbar, copy this icon to their desktop, or make a shortcut to it. Remember that some X-windows programs will only allow one user to have an active client running at a time, so close your X-windows program before trying to run HKL on another account.
Each user that wishes to run HKL must run Bash to activate the Windows Subsystem for Linux, update Bash, and install the libraries specified above (and here). There is no need for each user to issue the Powershell command (Enable-WindowsOptionalFeature).
$ sudo apt-get update $ sudo apt-get install libglu1 libxmu6 xterm tcsh tcl
Each user must also activate CCp4. To do this, run (double click) the “InstallEnv” script, usually located in C:\CCp4-7\7.0 .
The user can then start the X-windows program and launch HKL using their copy of the icon. If you need to create the icon, the target should be similar to:
C:\Windows\System32\bash.exe -c "cd;export DISPLAY=:0;/mnt/c/HKL/HKL3000_v715/HKL3000;sleep 100"