From ca50a26849c7e7bab6576239aaa4a8521e8e3146 Mon Sep 17 00:00:00 2001 From: Thomas White Date: Tue, 11 Feb 2020 11:50:15 +0100 Subject: Update README --- README | 159 ++++++++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 99 insertions(+), 60 deletions(-) (limited to 'README') diff --git a/README b/README index f1ed68c3..d74ea8c6 100644 --- a/README +++ b/README @@ -1,5 +1,5 @@ -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 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 @@ -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 . - -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). -- cgit v1.2.3