crystfel.7 7.24 KB
Newer Older
Thomas White's avatar
Thomas White committed
1
2
3
.\"
.\" CrystFEL main man page
.\"
Thomas White's avatar
Thomas White committed
4
.\" Copyright © 2012-2020 Deutsches Elektronen-Synchrotron DESY,
5
.\"                       a research centre of the Helmholtz Association.
Thomas White's avatar
Thomas White committed
6
7
8
9
10
11
.\"
.\" Part of CrystFEL - crystallography with a FEL
.\"

.TH CRYSTFEL 7
.SH NAME
Thomas White's avatar
Thomas White committed
12
CrystFEL \- data processing for FEL crystallography
Thomas White's avatar
Thomas White committed
13
14
15
16
17
18
19
20
21

.SH DESCRIPTION
CrystFEL is a suite of programs for processing Bragg diffraction data acquired with a free electron laser in a "serial" manner.  Some of the particular characteristics of such data which call for a specialised software suite are:

.RS
Each crystal is used for only one exposure, and there is no oscillation, rotation nor a large bandwidth or divergence.  Therefore, many or all reflections are partially integrated.
.PP
The crystals might be very small and the illumination highly coherent, leading to significant Fourier truncation effects on the detector.
.PP
Thomas White's avatar
Thomas White committed
22
Many patterns, numbering tens of thousands or more, are required, so high throughput automated processing is important.
Thomas White's avatar
Thomas White committed
23
24
25
26
27
.PP
The crystal orientations in each pattern are random and uncorrelated, which leads to special considerations during scaling and merging.
.RE

CrystFEL includes programs for simulating and processing patterns subject to the
Thomas White's avatar
Thomas White committed
28
above characteristics.  Fifteen programs form the core of CrystFEL.  They are:
Thomas White's avatar
Thomas White committed
29
30
31
32
33
34
35
36
37
38
39
40
41

.IP \fBindexamajig\fR
Batch indexing, integration and data reduction program, which produces a "stream" containing the indexing and integration results for each diffraction pattern.

.IP \fBpattern_sim\fR
A diffraction pattern simulation tool.

.IP \fBprocess_hkl\fR
A tool merging intensities from many patterns into a single reflection list, via the Monte Carlo method.

.IP \fBpartialator\fR
Full scaling and post-refinement process for accurate merging of data and outlier rejection.

Thomas White's avatar
Thomas White committed
42
43
.IP \fBambigator\fR
A tool for resolving indexing ambiguities.
Thomas White's avatar
Thomas White committed
44
45
46
47

.IP \fBget_hkl\fR
A tool for manipulating reflection lists, such as performing symmetry expansion.

Thomas White's avatar
Thomas White committed
48
49
50
.IP \fBcell_tool\fR
A tool for manipulating unit cell files, such as applying transformations.

Thomas White's avatar
Thomas White committed
51
52
53
.IP \fBcell_explorer\fR
A tool for examining the distributions of unit cell parameters.

54
.IP "\fBcompare_hkl\fR and \fBcheck_hkl\fR"
Thomas White's avatar
Thomas White committed
55
56
57
58
59
60
61
62
63
64
65
Tools for calculating figures of merit, such as completeness and R-factors.

.IP \fBpartial_sim\fB
A tool for calculating partial reflection intensities, perhaps for testing the convergence of Monte Carlo merging.

.IP \fBhdfsee\fR
A simple viewer for images stored in HDF5 format.

.IP \fBrender_hkl\fR
A tool for rendering slices of reciprocal space in two dimensions.

66
67
68
.IP \fBgeoptimiser\fR
A program to refine and optimize detector geometry.

Thomas White's avatar
Thomas White committed
69
70
71
72
73
74
.IP \fBlist_events\fR
A tool for creating lists of events from multi-event data files.

.IP \fBwhirligig\fR
A tool for locating runs of crystals with similar orientations, e.g. from 'mini rotation series' arising from the use of a slow extrusion sample injector.

Thomas White's avatar
Thomas White committed
75
76
77
.IP \fBmake_pixelmap\fR
A tool for for creating pixel maps for Cheetah, OnDA etc.

Thomas White's avatar
Thomas White committed
78
79
80
81
82
83
84
85
86
87
88
89
.PP
There is also a folder full of scripts for achieving many related tasks.

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

.PP
Please see the individual manual pages for the CrystFEL programs for detailed information.

Thomas White's avatar
Thomas White committed
90
91
92
93
94
.SH CITING CRYSTFEL
If CrystFEL was important for your research, please consider citing the
following article:
.IP
T. A. White, R. A. Kirian, A. V. Martin, A. Aquila, K. Nass, A. Barty and
Thomas White's avatar
Thomas White committed
95
H. N. Chapman. "CrystFEL: a software suite for snapshot serial crystallography". J. Appl. Cryst. 45. doi:10.1107/S0021889812002312
Thomas White's avatar
Thomas White committed
96
97
98
99
.PP
Please let us know (see below) about your publication, so we can include it in
the list of examples on the CrystFEL website.

100
101
102
.SH SYMMETRY IN CRYSTFEL
Without only a very few exceptions, CrystFEL is not interested in space groups.  Instead, it deals with point groups which embody the information about how data should be merged from different crystals.  Every space group belongs to exactly one point group, and you can look up the right one in the International Tables or using the symmetry tables accompanying the CrystFEL source (or to be found on the CrystFEL website in the Theory section).

Thomas White's avatar
Thomas White committed
103
You can append \fB_ua\fR\fIX\fR to any of the point group symbols listed below, where \fIX\fR is \fBa\fR, \fBb\fR or \fBc\fR.  This will specify the 'unique' axis for lattices which have one.
104

105
106
\fBThe default unique axis, where this makes sense, is c\fR.

Thomas White's avatar
Thomas White committed
107
108
Here is a list of all the possible crystallographic point groups, written as they will be accepted by CrystFEL.  Refer
to this list if you experience difficulty with "-y" at any time.
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

.IP Triclinic
\fB1\fR, \fB-1\fR.

.IP Monoclinic
\fB2/m\fR, \fB2\fR, \fBm\fR.

.IP Orthorhombic
\fBmmm\fR, \fB222\fR, \fBmm2\fR.

.IP Tetragonal
\fB4/m\fR, \fB4\fR, \fB-4\fR, \fB4/mmm\fR, \fB422\fR, \fB-42m\fR, \fB-4m2\fR, \fB4mm\fR.

.IP "Trigonal (rhombohedral axes)"
\fB3_R\fR, \fB-3_R\fR, \fB32_R\fR, \fB3m_R\fR, \fB-3m_R\fR.

.IP "Trigonal (hexagonal axes)"
\fB3_H\fR, \fB-3_H\fR, \fB321_H\fR, \fB312_H\fR, \fB3m1_H\fR, \fB31m_H\fR, \fB-3m1_H\fR, \fB-31m_H\fR.

.IP Hexagonal
\fB6/m\fR, \fB6\fR, \fB-6\fR, \fB6/mmm\fR, \fB622\fR, \fB-62m\fR, \fB-6m2\fR, \fB6mm\fR.

.IP Cubic
\fB23\fR, \fBm-3\fR, \fB432\fR, \fB-43m\fR, \fBm-3m\fR.

134
135
136
137
138
139
140
141
142
.SH FUNDING ACKNOWLEDGEMENTS
Development of CrystFEL is primarily funded by the Helmholtz Association via programme-oriented funds.

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

Additional funding for CrystFEL is provided by 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.

Thomas White's avatar
Thomas White committed
143
.SH AUTHOR
144
This page was written by Thomas White and Valerio Mariani.
Thomas White's avatar
Thomas White committed
145
146
147
148
149
150

.SH REPORTING BUGS
Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.

.SH COPYRIGHT AND DISCLAIMER
.PD 0
Thomas White's avatar
Thomas White committed
151
Copyright © 2012-2020 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
Thomas White's avatar
Thomas White committed
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
.PD
.PP
Please read the AUTHORS file in the CrystFEL source code distribution for a full list of contributions and contributors.
.P
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.
.P
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.
.P
You should have received a copy of the GNU General Public License along with CrystFEL.  If not, see <http://www.gnu.org/licenses/>.

.SH SEE ALSO
.BR indexamajig (1),
.BR process_hkl (1),
.BR partialator (1),
.BR pattern_sim (1),
.BR partial_sim (1),
.BR compare_hkl (1),
.BR check_hkl (1),
.BR render_hkl (1),
.BR hdfsee (1),
.BR get_hkl (1),
Thomas White's avatar
Thomas White committed
173
.BR cell_tool (1),
Thomas White's avatar
Thomas White committed
174
175
176
.BR geoptimiser (1),
.BR whirligig (1),
.BR list_events (1),
Thomas White's avatar
Thomas White committed
177
.BR make_pixelmap (1),
Thomas White's avatar
Thomas White committed
178
.BR crystfel_geometry (5).