Information


Documentation



Are you processing your data at SLAC/LCLS?

If so, you can use the pre-installed version. Type one of the following to set up your environment. For the very latest development version (with the latest features, and the latest bugs), use one of:

$ source /reg/g/cfel/crystfel/crystfel-dev/setup-sh
$ source /reg/g/cfel/crystfel/crystfel-dev/setup-csh

e.g. for version 0.6.3, use:

$ source /reg/g/cfel/crystfel/crystfel-0.6.3/setup-sh
$ source /reg/g/cfel/crystfel/crystfel-0.6.3/setup-csh

Use the .sh version if your shell is sh, bash or zsh. Use the .csh version if you use tcsh. If you don't know, your shell is probably bash.

If you use the development version, read /reg/g/cfel/crystfel/crystfel-dev/ChangeLog every now and again to see what's changed.

Are you processing your data at CFEL?

CrystFEL is installed in the CFEL software stack on Maxwell. Look on Confluence for instructions.

Are you using SBGrid?

CrystFEL is installed and supported at SBGrid Consortium laboratories.

Brief installation instructions

Terse installations instructions can be found in the README file in the CrystFEL source code. It's the usual ./configure, make and make install routine. Prerequisites are: HDF5 (version 1.8.0 or later), FFTW3 (built as a shared library) and the GNU Scientific Library (GSL). For a full installation, you will also need GTK, Cairo, Pango, GDK-pixbuf, libPNG and libTIFF. Optionally, you can add OpenCL for GPU accelerated simulation of diffraction patterns. At least one out of MOSFLM (from CCP4, or separately installed) or DirAx should be installed, preferably both. XDS and Felix can also optionally be used.

Detailed installation instructions - GNU/Linux

Here is a step-by-step procedure to get CrystFEL compiled and running on a reasonably recent installation of GNU/Linux. This assumes that you are starting from a fresh installation of Linux, so some common libraries might be installated already (which makes things a lot easier!). If things are not compiling properly, please double check that each library has been configured correctly.

Note that most users will be able to install almost all of CrystFEL's dependencies from their Linux distribution's package manager. This should be done wherever possible, because it's much easier to do and less likely to cause problems later. Most of CrystFEL's dependencies are commonly-used packages which are useful to have anyway.

1. Get the CrystFEL code

See the download page for details of how to download CrystFEL.

2. Download and install ZLib

Skip this step if ZLib is already installed. ZLib is almost certainly available from your distribution's package manager, so install it from there instead. Be sure to install the development files (perhaps in a package called zlib-dev or zlib-devel) as well.

The latest version of the Z library is available here, or probably through your distribution's package manager. If you have to install from source code, compilation and installation follows the standard procedure:

$ ./configure
$ make
$ make install

3. Download and install HDF5 libraries

HDF5 is the file format which is used by CrystFEL, and the source code for the libraries is maintained by the HDF Group. You need HDF5 version 1.8.0 or later.

Skip this step if HDF5 is already installed. If it's available from your distribution's package manager, then install it from there instead. Be sure to install the development files (perhaps in a package called hdf5-dev or hdf5-devel) as well.

Get the latest release of HDF5 from the HDF website. To configure and install HDF5 suitably, use the following command:

$ ./configure --enable-threadsafe --with-pthread=/usr --prefix=/usr

The last --prefix option is not mandatory, but installs the HDF5 libraries into a default system folder for easy linking and later compiling. If this is not specified than HDF5 is installed into the current directory, which might be confusing.

The options --enable-threadsafe --with-pthread=/usr make the HDF5 library thread safe. This is not strictly necessary for the core CrystFEL programs, but some other programs which use CrystFEL's routines might need it, so you might save some trouble in the future if you enable it now.

After ./configure ... , the compilation of this library is just like usual:

$ make
$ make install

If you installed HDF5 to somewhere other than /usr, remember where you installed it and give that same path to CrystFEL's ./configure with the option --with-hdf5= in step 9.

4. Download and install FFTW3

Skip this step if FFTW3 is already installed. If it's available from your distribution's package manager, then install it from there instead. Be sure to install the development files (perhaps in a package called fftw3-dev or fftw3-devel) as well.

Get the latest release of FFTW . Then configure with:

$ ./configure --enable-shared

Then make and make install the library.

5. Download and install GSL

GSL is almost certainly available from your distribution's package manager, so install it from there instead. Be sure to install the development files (perhaps in a package called gsl-dev or gsl-devel) as well.

Get the latest release of GSL. No extra configure options are necessary for the compilation of this library, just do the standard configure, make and make install.

6. Download and install GTK

Install GTK+-2.0 from your distribution's package manager, from which it is almost certainly available. Be sure to install the development files (perhaps in a package called gtk+-2.0-dev or gtk+-2.0-devel) as well. Don't try to install this manually from source (here) unless you have some good reason, beacuse GTK has many dependencies of its own.

7. Optional: Install CCP4

If CCP4 is not already installed, and if you'd like to use MOSFLM indexing, calculate structure factors for simulation or convert data into a MTZ files, you'll need to install it. Go to the CCP4 website and follow the instructions there.

Check that CCP4 is installed and working properly by running ipmosflm on a command line. You should see a brief welcome message and a prompt, and no errors or warnings.

8. Optional: Install DirAx

If you'd like to index patterns using DirAx, you'll need to install it separately. Follow the instructions on the DirAx website.

Check that DirAx is installed and working properly by running dirax on a command line. You should see a brief welcome message and a prompt, and no errors or warnings.

9. Optional: Set up OpenCL

If you'd like to use GPU acceleration to simulate diffraction patterns much faster, you'll need a working OpenCL environment. For NVIDIA graphics cards, follow the instructions on their website. If you do this, add --with-opencl to the configuration options for CrystFEL in step 9.

10. Install CrystFEL

Once all of the dependencies of CrystFEL are properly installed, compiling CrystFEL should be straightforward. In the parent CrystFEL folder, just use ./configure, make and make install.

Developer Documentation

If you are a developer, and would like to read detailed information on the libcrystfel API, add --enable-gtk-doc to your ./configure command line for CrystFEL.

Detailed installation instructions - Mac OS X

Most dependencies can be installed with macports. As described on the Macports webpage, this entails installing Xcode first (and also the Xcode command line utilities), which is very simple to accomplish through the Mac "App Store" application. Macports installs easily via its GUI-based installer. It's a good idea to update macports once installed:

> sudo port -v selfupdate
> sudo port upgrade outdated

With macports installed, the following will install most of the CrystFEL dependencies:

> sudo port install pkgconfig gsl fftw-3 pango gdk-pixbuf2 gtk-doc gtk2 hdf5

If you are installing from the Git repository, you need to edit autogen.sh and change the line libtoolize to glibtoolize, and additionally install automake and autoconf:

> sudo port install automake autoconf

Download the CrystFEL source and configure in this way:

> ./configure --with-hdf5=/opt/local --with-libtiff=/opt/local

Then just make and make install.

Pre-compiled CCP4 Mac binaries may be installed vie the GUI-based installer available at the CCP4 web page. Once it is installed, the CCP4 environment should be set up via the script, for example:

> source /Applications/ccp4-6.2.0/bin/ccp4.setup-sh

Most people will want to put this in the startup script of course.