aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorThomas White <taw@physics.org>2020-02-11 11:50:15 +0100
committerThomas White <taw@physics.org>2020-02-11 11:50:15 +0100
commitca50a26849c7e7bab6576239aaa4a8521e8e3146 (patch)
tree48c955b87f76d99804e519703bb3885c5c33e199 /README
parenta607da9373e4cbf8609fac477ef5ecd3323ca234 (diff)
Update README
Diffstat (limited to 'README')
-rw-r--r--README159
1 files changed, 99 insertions, 60 deletions
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 <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).