aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: c86a68aebb3d3fa22a2163fd7a42eead99cae217 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
CrystFEL - Data processing for serial crystallography
=====================================================

Copyright © 2012-2021 Deutsches Elektronen-Synchrotron DESY,
                      a research centre of the Helmholtz Association.

See AUTHORS as well as individual source code files for full details of contributors.

Introduction
------------

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.  Compared to rotation data,
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.

* Merging into lower symmetry point groups may require the resolution of
  indexing ambiguities.


Getting started
---------------

The best way to get started, after installation, is to run command ```crystfel```
to start the graphical user interface.


Installation
------------

CrystFEL installation is supported on GNU/Linux and Mac OS X.  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).

Here are the mandatory dependencies - you cannot install CrystFEL without these:

* Either [CMake](https://cmake.org/) 3.12 or later or [Meson](https://mesonbuild.com/) (Meson is preferred)
* [HDF5](https://www.hdfgroup.org/downloads/hdf5/) 1.8.0 or later (1.10.0 or later is required for many recent data formats)
* [GNU Scientific Library (GSL)](https://www.gnu.org/software/gsl/)
* [Bison](https://www.gnu.org/software/bison/) 2.6 or later
* [Flex](https://www.gnu.org/software/flex/)
* [Zlib](https://www.zlib.net/) (1.2.3.5 or later preferred for better decompression speed)

The following dependencies are "optional", in the sense that you can install
CrystFEL without them.  However, a CrystFEL installation without these will lack
important features such as the graphical user interface:

* GTK3 or later
* Cairo
* Pango
* gdk-pixbuf
* NCurses
* libPNG
* [libccp4](ftp://ftp.ccp4.ac.uk/opensource/)

Note that all of the dependencies mentioned above (including libccp4) should be
available from your Linux distribution's package manager, or from
[Homebrew](https://brew.sh/) on Mac OS.  You should not need to download and
install any of them separately from source, and we emphatically recommend
against trying to do so!

Note that using the libraries from the full CCP4 suite is not recommended.  CCP4
includes so many other libraries that it becomes very difficult to link using
the correct versions of everything.

Processing data relies on indexing algorithms.  The more of the following are
installed, the better your experience will be:

* [FFTW3](http://fftw.org/)
* [XGandalf](https://stash.desy.de/users/gevorkov/repos/xgandalf)
* [PinkIndexer](https://stash.desy.de/users/gevorkov/repos/pinkindexer)
* [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/)

Installation follows the normal CMake procedure:

```
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install
```

Or, with Meson:

```
$ meson . build
$ ninja -C build
$ sudo ninja -C build install
```


Licence
-------

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 <http://www.gnu.org/licenses/>.


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).