path: root/doc/man/crystfel.7

.\"
.\" CrystFEL main man page
.\"
.\" Copyright © 2012 Thomas White <taw@physics.org>
.\"
.\" Part of CrystFEL - crystallography with a FEL
.\"

.TH CRYSTFEL 7
.SH NAME
CrystFEL \- data processing for FEL crystallography

.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
Many patterns, numbering tens of thousands or more, are required, so high throughput automated processing is import.
.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
above characteristics.  Four programs form the core of CrystFEL.  They are:

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

.PP
In addition, there is also:

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

.IP \fBpowder_plot\fR
A tool for the calculation of one-dimensional "powder" traces.

.IP \fBcompare_hkl\fR and \fBcheck_hkl\fR
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.

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

.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
H. N. Chapman. "CrystFEL: a software suite for snapshot serial crystallography". J. Appl. Cryst. 45. doi:10.1107/S0021889812002312
.PP
Please let us know (see below) about your publication, so we can include it in
the list of examples on the CrystFEL website.

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

A limitation of symmetry in the current version of CrystFEL is that it can only accept point groups in standard settings.  That means that the highest-order rotation axis must always be parallel to c*, monoclinic unit cells should have \fIc\fR as the unique axis and so on.  This is a limitation of the way your input, for example using the \fB-y\fR argument of \fBprocess_hkl\fR, is turned into CrystFEL's internal representation of symmetry, and so future versions should very soon be able to handle any setting.

The options are:

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


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

.SH AUTHOR
This page was written by Thomas White.

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

.SH COPYRIGHT AND DISCLAIMER
.PD 0
Copyright © 2012 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
.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 powder_plot (1),
.BR hdfsee (1),
.BR get_hkl (1),
.BR crystfel_geometry (5).