Commit ca50a268 authored by Thomas White's avatar Thomas White
Browse files

Update README

parent a607da93
CrystFEL - Crystallography with a FEL
-------------------------------------
CrystFEL - Data processing for serial crystallography
-----------------------------------------------------
Copyright © 2012-2020 Deutsches Elektronen-Synchrotron DESY,
a research centre of the Helmholtz Association.
......@@ -33,6 +33,8 @@ Authors:
Yaroslav Gevorkov <yaroslav.gevorkov@desy.de>
Omri Mor <omor1@asu.edu>
--------------------------------------------------------------------------------
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
......@@ -45,8 +47,7 @@ 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 <http://www.gnu.org/licenses/>.
Thank you for reading the documentation. :-)
--------------------------------------------------------------------------------
CrystFEL is a suite of programs for processing (and simulating) Bragg
diffraction data from "serial crystallography" experiments, often (but not
......@@ -54,116 +55,154 @@ 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.
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:
that:
- Merging into lower symmetry point groups may require the resolution of
indexing ambiguities.
indexing ambiguities.
CrystFEL includes programs for simulating and processing patterns subject to the
above characteristics. The main programs are:
above characteristics. The main data processing pipeline is defined by four
programs:
- indexamajig, a "batch indexer" and data reduction program.
- indexamajig, for bulk indexing and integration of diffraction patterns
- process_hkl, for merging per-pattern lists of intensities into a
single reflection list.
- process_hkl, for quickly merging per-pattern lists of intensities into
a single reflection list
- cell_explorer, for examining distributions of lattice parameters.
- partialator, for merging patterns more accurately (and much more
slowly) using scaling, partiality modelling and
post refinement
- ambigator, a tool for resolving indexing ambiguities,
- ambigator, for resolving indexing ambiguities
- geoptimiser, for refining detector geometry.
There are two tools for calculating figures of merit for reflection data:
- whirligig, for finding multiple shots from single crystals.
- compare_hkl, for figures of merit that involve comparing two sets of
data, like CC* and R_split
- partialator, for merging patterns more accurately (and much more
slowly) using post refinement.
- 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:
In addition, there is also:
- cell_explorer, for examining distributions of lattice parameters
- get_hkl, for doing various simple operations on reflection lists.
- hdfsee, an image viewer
- compare_hkl, for working out the differences (e.g. a q-dependent
scaling factor) between two lists of reflections.
- render_hkl, for turning reflection lists into pretty graphics
- check_hkl, for determining things like completeness.
CrystFEL can also simulate data, e.g. for methods development:
- pattern_sim, for simulating patterns.
- pattern_sim, which performs a Fourier image calculation
- partial_sim, for calculating partial reflection intensities.
- partial_sim, which calculates reflection intensities based on a
partiality calculation and optionally plots the peaks
in an image
- hdfsee, a simple viewer for images stored in HDF5 format.
There are also five utility programs:
- render_hkl, for turning reflection lists into pretty graphics.
- 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 pixel maps for Cheetah, OnDA etc.
- 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.
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.
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 development
documentation created using GTK-Doc.
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
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, FFTW3 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 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
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)
cmake -DHDF5_ROOT=/path/to/hdf5 (... /include, /lib etc)
To install CrystFEL in a custom location, use:
-DCMAKE_INSTALL_PREFIX=/path/for/crystfel/installation
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.
cmake -DCMAKE_INSTALL_PREFIX=/path/for/crystfel/installation
Funding acknowledgements
------------------------
Development of CrystFEL is primarily funded by the Helmholtz Association via
programme-oriented funds.
Development of CrystFEL is primarily funded by the Helmholtz Association.
Partial funding for CrystFEL has previously been provided by:
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).
- "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).
- 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.
- BioStruct-X, a project funded by the Seventh Framework Programme (FP7) of the
European Commission (2011-2016).
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment