CrystFEL - Data processing for serial crystallography ----------------------------------------------------- Copyright © 2012-2020 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 Mamoru Suzuki Thomas Grant Steve Aplin Oleksandr Yefanov Helen Ginn Nicolas Riebesel Yaroslav Gevorkov Omri Mor -------------------------------------------------------------------------------- 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 . -------------------------------------------------------------------------------- CrystFEL is a suite of programs for processing (and simulating) Bragg diffraction data from "serial crystallography" experiments, often (but not always) performed using an X-ray 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. - Many patterns (thousands) 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 data processing pipeline is defined by four programs: - indexamajig, for bulk indexing and integration of diffraction patterns - process_hkl, for quickly merging per-pattern lists of intensities into a single reflection list - partialator, for merging patterns more accurately (and much more slowly) using scaling, partiality modelling and post refinement - ambigator, for resolving indexing ambiguities There are two tools for calculating figures of merit for reflection data: - compare_hkl, for figures of merit that involve comparing two sets of data, like CC* and R_split - check_hkl, for figures of merit based on only one set of data, like completeness, redundancy and twinning tests Three tools are provided for visualising data: - cell_explorer, for examining distributions of lattice parameters - hdfsee, an image viewer - render_hkl, for turning reflection lists into pretty graphics CrystFEL can also simulate data, e.g. for methods development: - pattern_sim, which performs a Fourier image calculation - partial_sim, which calculates reflection intensities based on a partiality calculation and optionally plots the peaks in an image There are also five utility programs: - get_hkl, for doing various simple operations on reflection lists such as expanding by symmetry or adding noise - cell_tool, for doing operations on unit cells such as applying transformations or looking for indexing ambiguities - geoptimiser, for refining detector geometry. - list_events, for creating event lists from multi-event files. - make_pixelmap, for creating HDF5 pixel map files for other programs like Cheetah and OnDA - whirligig, for finding multiple shots from single crystals. There is also a folder full of scripts for achieving many related tasks, such as file format conversion. 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 API documentation created using Doxygen. Installation ------------ The terse installation instructions below should be enough if you're experienced with installing software from source. More detailed installation information is available on the website: https://www.desy.de/~twhite/crystfel/install.html Mandatory dependencies: - CMake 3.12 or later - HDF5 1.8.0 or later (1.10.0 or later preferred) - GNU Scientific Library (GSL) - Bison 2.6 or later - Flex - Zlib (1.2.3.5 or later preferred) "Optional" dependencies: - GTK2 or later (GTK3 preferred) - Cairo - Pango - gdk-pixbuf - NCurses - libPNG - libTIFF - FFTW3 - XGandalf (https://stash.desy.de/users/gevorkov/repos/xgandalf) "Optional" run-time dependencies: - Mosflm (https://www.mrc-lmb.cam.ac.uk/mosflm/mosflm/) - DirAx (http://www.crystal.chem.uu.nl/distr/dirax/) - XDS (http://xds.mpimf-heidelberg.mpg.de/) Note that "optional" means that you *can* install CrystFEL without them, however your installation will lack important components such as the visualisation tools and certain indexing algorithms. For processing electron diffraction or wide-bandwidth X-ray data, you should also install PinkIndexer from: https://stash.desy.de/users/gevorkov/repos/pinkindexer Installation follows the normal CMake procedure: $ mkdir build $ cd build $ cmake .. $ make $ sudo make install If external libraries have been installed in non-standard locations, you can set the path like this, for example for Xgandalf: cmake -DXGANDALF_INCLUDES=/path/to/xgandalf/include \ -DXGANDALF_LIBRARIES=/path/to/xgandalf/lib/libxgandalf.so The path to HDF5 can be set similarly: cmake -DHDF5_ROOT=/path/to/hdf5 (... /include, /lib etc) To install CrystFEL in a custom location, use: cmake -DCMAKE_INSTALL_PREFIX=/path/for/crystfel/installation Funding acknowledgements ------------------------ Development of CrystFEL is primarily funded by the Helmholtz Association. Partial funding for CrystFEL has previously been 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). - The BMBF German-Russian Cooperation "SyncFELMed", grant 05K14CHA (2014-2017). - BioStruct-X, a project funded by the Seventh Framework Programme (FP7) of the European Commission (2011-2016).