CrystFEL - Crystallography with a FEL ------------------------------------- Copyright © 2012-2017 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association. Authors: Thomas White Richard Kirian Kenneth Beyerlein Andrew Aquila Andrew Martin Lorenzo Galli Chun Hong Yoon Kenneth Beyerlein Karol Nass Nadia Zatsepin Anton Barty Cornelius Gati Fedor Chervinskii Alexandra Tolstikova Wolfgang Brehm Valerio Mariani Parker de Waal Takanori Nakane Keitaro Yamashita Marmoru Suzuki Thomas Grant CrystFEL is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. CrystFEL is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with CrystFEL. If not, see . Thank you for reading the documentation. :-) CrystFEL is a suite of programs for processing (and simulating) Bragg diffraction data acquired with a free electron laser. Some of the particular characteristics of such data which call for a specialised software suite are: - The sliced, rather than integrated, measurement of intensity data. Many, if not all reflections are partially integrated. Unique correction factors are needed. - The crystals are small, leading to significant Fourier truncation effects on the detector. - Many patterns (>10,000) are required - high throughput is needed. - The crystal orientations in each pattern are random and uncorrelated, meaning that: - Merging into lower symmetry point groups may require the resolution of indexing ambiguities. CrystFEL includes programs for simulating and processing patterns subject to the above characteristics. The main programs are: - indexamajig, a "batch indexer" and data reduction program. - process_hkl, for merging per-pattern lists of intensities into a single reflection list. - cell_explorer, for examining distributions of lattice parameters. - ambigator, a tool for resolving indexing ambiguities, - geoptimiser, for refining detector geometry. - whirligig, for finding multiple shots from single crystals. - partialator, for merging patterns more accurately (and much more slowly) using post refinement. In addition, there is also: - get_hkl, for doing various simple operations on reflection lists. - compare_hkl, for working out the differences (e.g. a q-dependent scaling factor) between two lists of reflections. - check_hkl, for determining things like completeness. - pattern_sim, for simulating patterns. - partial_sim, for calculating partial reflection intensities. - hdfsee, a simple viewer for images stored in HDF5 format. - render_hkl, for turning reflection lists into pretty graphics. - list_events, for creating event lists from multi-event files There is also a folder full of scripts for achieving many related tasks. CrystFEL mostly works with images stored in HDF5 format, unit cell data in PDB format, and reflection lists in plain text format (i.e. not MTZ). There are scripts for converting both ways between plain text reflection lists and MTZ files. Standard "man" pages are provided for documentation, or you can invoke any program with the argument "--help" to get a summary of options. There are some example geometry and beam description files in doc/examples, and development documentation created using GTK-Doc. Installation ------------ See the "INSTALL" file for the generic instructions on how to use the build system. In short, it's the usual: $ ./configure $ make $ make check $ sudo make install If you have libraries installed in strange places, you might want to do something similar to one of these instead of the first step: $ ./configure --with-opencl $ ./configure --with-hdf5=/some/strange/location $ ./configure --with-libtiff=/some/strange/location $ ./configure --with-gsl=/some/strange/location $ ./configure --disable-gtk At a minimum, you will need the HDF5 library (version 1.8.0 or later) and the GNU Scientific Library (GSL). For a full installation, you will also need libTIFF, libPNG, Cairo and GTK2. All of these should be installed from your distribution's package manager. Be sure to install the development files for each package, which will have a name like "gtk+-2.0-dev" or "gtk+-2.0-devel", depending on which distribution you use. If you're compiling on Mac OS X, where GTK, libPNG and libTIFF seem to be much harder to come by, disable lots of things: $ ./configure --disable-gtk --disable-png --disable-libtiff If you get an error mentioning fftw3 and telling you to recompile with -fPIC, then your version of FFTW3 is not compiled in a suitable way. You'll need to install it again (from source) adding "--enable-shared" to its ./configure command line. If you get an error about "cairo_surface_show_page" in src/scaling-report.c, simply edit the file and comment that line out. Partialator will then not be able to produce a useful scaling report, but the rest of CrystFEL will work properly. If you are installing from Git, the following extra things apply: - You must run "./autogen.sh" to generate "configure" and other files before proceeding as detailed above. - If you have an old version of Automake (less than 1.10), or an old version of Autoconf (less than 2.60), you'll need to add the following line near the top of Makefile.am: docdir = ${datadir}/doc/${PACKAGE} - If your Automake version is less than 1.11, you'll need to comment out the reference to AM_SILENT_RULES in configure.ac, like this: dnl AM_SILENT_RULES([yes]) - You will not be able to use the "--enable-gtk-doc" option to configure unless you have at least version 1.9 of gtk-doc installed. Funding acknowledgements ------------------------ Development of CrystFEL is primarily funded by the Helmholtz Association via programme-oriented funds. Additional funding for CrystFEL is provided by "X-Probe", a project of the European Union's 2020 Research and Innovation Program Under the Marie Skłodowska-Curie grant agreement 637295 (2015-2018). Additional funding for CrystFEL is provided by the BMBF German-Russian Cooperation "SyncFELMed", grant 05K14CHA (2014-2017). Past funding for CrystFEL has been received from BioStruct-X, a project funded by the Seventh Framework Programme (FP7) of the European Commission.