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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
CrystFEL - Crystallography with a FEL
-------------------------------------
Copyright © 2012 Thomas White <taw@physics.org>
Copyright © 2012 Richard Kirian <rkirian@asu.edu>
Copyright © 2012 Andrew Aquila <andrew.aquila@cfel.de>
Copyright © 2012 Andrew Martin <andrew.martin@desy.de>
Copyright © 2012 Lorenzo Galli <lorenzo.galli@desy.de>
Please read the AUTHORS file for a full list of contributions and contributors.
See the COPYING file for licence conditions. Summary: GPLv3+.
Thank you for reading the documentation. :-)
CrystFEL is a suite of programs for processing (and simulating) Bragg
diffraction data acquired with a 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. Unique correction factors are
needed.
- The crystals are small, leading to significant Fourier truncation effects on
the detector.
- Many patterns (>10,000) 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 programs are:
- pattern_sim, for simulating patterns.
- indexamajig, a "batch indexer" and data reduction program.
It is used for finding hits, locating peaks, indexing
patterns and constructing lists of h,k,l,I,sigma(I) (or
similar) for each pattern.
- process_hkl, for merging per-pattern lists of intensities into a
single reflection list.
- partialator, for merging patterns more accurately (and much more
slowly) using post refinement.
In addition, there is also:
- get_hkl, for doing various simple operations on reflection lists.
- powder_plot, for turning image or reflection data into a histogram of
reciprocal space vector moduli and intensities (i.e. a
1D powder diffraction trace).
- compare_hkl, for working out the differences (e.g. a q-dependent
scaling factor) between two lists of reflections.
- check_hkl, for determining things like completeness.
- partial_sim, for calculating partial reflection intensities.
Included at no extra cost are:
- hdfsee, a simple viewer for images stored in HDF5 format.
- render_hkl, for turning reflection lists into pretty graphics.
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.
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.
Installation
------------
See the "INSTALL" file for the generic instructions on how to use the build
system. In short, it's the usual:
$ ./configure
$ make
$ make check
$ sudo make install
If you have libraries installed in strange places, you might want to do
something similar to one of these instead of the first step:
$ ./configure --with-opencl
$ ./configure --with-hdf5=/some/strange/location
$ ./configure --with-libtiff=/some/strange/location
$ ./configure --with-gsl=/some/strange/location
$ ./configure --disable-gtk
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 and GTK.
You must use an installation of the HDF5 library which is thread safe. That
means it must have been configured with the "--enable-threadsafe" option. Most
binary distributions appear NOT to be like this. If you don't have a thread
safe HDF5 library, just be sure not to use the "-j" option for any of the
CrystFEL programs.
If you're compiling on Mac OS X, where GTK, libPNG and libTIFF seem to be much
harder to come by, disable lots of things:
$ ./configure --disable-gtk --disable-png --disable-libtiff
If you get a screen full of errors of the following form:
<stuff>: undefined reference to `cblas_<something>'
Add "--enable-gsl-fudge" to your configuration parameters.
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.
Program name
------------
There seems to be a tendency to capitalise all the letters in the names of
programs in scientific publications. Sometimes the authors do this, other times
the journal capitalises them at the proof stage. It's as if they think it
somehow makes the name look more "computery", or perhaps "trademark-y".
Well, it's not 1970 any more, and programs are no longer input on punched cards.
That means we can have capitalisation any way we choose.
The name for the overall software suite is "CrystFEL", with this being the only
acceptable capitalisation. The individual programs should always be referred to
with all letters in lower case, exactly the same as the names of the binaries.
Put the names in quotes or italics if this sounds strange to you. The only
exception is if the name of the program comes at the start of a sentence, or in
a title, or similar position where a word would normally be capitalised.
In most cases, it will be more appropriate to refer to the overall suite than to
one of its constituent programs.
The following are NOT acceptable forms: "CRYSTFEL", "crystFEL", "Crystfel",
"INDEXAMAJIG" and "PATTERN_SIM". If you use any of these (particularly the
first one and the last two), the Capitalisation Monster will hunt you down and
eat you.
In addition, CrystFEL is made up of "programs", not "routines" nor "procedures".
(The "programs" in turn are made up from "routines" and "procedures", but unless
you are exploring the source code, there's no need for you to know about that).
I hope you can forgive the fussiness.
|
