path: root/doc/man/pattern_sim.1

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

.TH PATTERN_SIM 1
.SH NAME
pattern_sim \- Simulation of nanocrystal diffraction patterns
.SH SYNOPSIS
.PP
.B pattern_sim
\fB-g\fR \fIdetector.geom\fR \fB-b\fR \fImy.beam\fR \fB-p\fR \fImy.pdb\fR
[\fBoptions\fR] \fB...\fR
.PP
.B pattern_sim
\fB--help\fR

.SH DESCRIPTION

pattern_sim simulates diffraction patterns from small crystals probed with femtosecond pulses of X-rays from a free electron laser.  Typical use might be of the form:

pattern_sim -g mydetector.geom -b my.beam -p my.pdb -r -i myintensities.hkl

The unit cell geometry will be taken from the CRYST1 line in the PDB file you provide, and the intensities of the reflections will be interpolated from the reflection list file you provide.  The reflection list format is the same as that output by process_hkl and handled by get_hkl.  You also need beam and geometry description files (-b and -g respectively).  See `man crystfel_geometry' for details of how to create a geometry file.  Examples of both files can be found in the installation directory, which is normally /usr/local/share/doc/crystfel.

The result will be written to an HDF5 file in the current directory with the name `sim.h5'.

.SH OPTIONS

.PD 0
.IP "\fB-p\fR \fIunitcell.pdb\fR"
.IP \fB--pdb=\fR\fIunitcell.pdb\fR
.PD
Specify the name of the PDB file containing at least a CRYST1 line describing the unit cell.

.PD 0
.IP \fB--gpu\fR
.PD
Use the GPU to speed up the calculation.  Requires that OpenCL libraries and drivers are available, and that CrystFEL was compiled with OpenCL enabled.

.PD 0
.IP \fB--gpu-dev=\fRIn\fR
.PD
Use GPU device number \fIn\fR.  If you omit this option, the list of GPU devices will be shown when you run pattern_sim.

.PD 0
.IP "\fB-g\fR \fIfilename\fR"
.IP \fB--geometry=\fR\fIfilename\fR
.PD
Read the detector geometry description from \fIfilename\fR.  See \fBman crystfel_geometry\fR for more information.

.PD 0
.IP "\fB-b\fR \fIfilename\fR"
.IP \fB--beam=\fR\fIfilename\fR
.PD
Read the beam description from \fIfilename\fR.  See \fBman crystfel_geometry\fR for more information.

.PD 0
.IP "\fB-n\fR \fn\fR"
.IP \fB--number=\fR\fIn\fR
.PD
Simulate \fIn\fR patterns.  Default: \fB-n 1\fR.

.PD 0
.IP \fB--no-images\fR
.PD
Do not save any HDF5 files apart from the powder pattern (if requested).

.PD 0
.IP "\fB-o\fR \fIfilename\fR"
.IP \fB--output=\fR\fIfilename\fR
.PD
Write the pattern to \fIfilename\fR.  The default is \fB--output=sim.5\fR.  If more than one pattern is to be simulated (see \fB--number\fR), the filename will be postfixed with a hyphen, the image number and then '.h5'.

.PD 0
.IP \fB-r\fR
.IP \fB--random-orientation\fR
.PD
Make up a random orientation for each pattern simulated.

.PD 0
.IP \fB--powder=\fR\fIfilename\fR
.PD
Write the sum of all patterns to \fIfilename\fR.

.PD 0
.IP "\fB-i\fR \fIfilename\fR"
.IP \fB--intensities=\fR\fIfilename\fR
.PD
Get the intensities and phases at the reciprocal lattice points from \fIfilename\fR.

.PD 0
.IP "\fB-y\fR \fIpointgroup\fR"
.IP \fB--symmetry=\fR\fIpointgroup\fR
.PD
Use \fIpointgroup\fR as the symmetry of the intensity list (see \fB--intensities\fR).

.PD 0
.IP "\fB-t\fR \fImethod\fR"
.IP \fB--gradients=\fR\fImethod\fR
.PD
Use \fImethod\fR as way of calculating the molecular transform between reciprocal lattice points.  See the section \fBGRADIENT METHODS\fR below.

.PD 0
.IP \fB--really-random\fR
.PD
Seed the random number generator using the kernel random number generator (/dev/urandom).  This means that truly random numbers for the orientation and crystal size, instead of the same sequence being used for each new run.

.PD 0
.IP \fB--min-size=\fR\fImin\fR
.IP \fB--min-size=\fR\fImax\fR
.PD
Generate random crystal sizes between \fImin\fR and \fImax\fR nanometres.  These options must be used together.

.PD 0
.IP \fB--no-noise\fR
.PD
Do not calculate Poisson noise.


.SH REFLECTION LISTS

You'll need to create a file containing the intensities of the reflections.  The normal way to do this is to use CCP4 via the "gen-sfs" script in CrystFEL's script folder.  Run it like this:

$ \fBgen-sfs\fR \fImymodel.pdb\fR \fB"\fR\fIP6\fR\fB"\fR \fI3\fR

You need to give the PDB model, the symmetry of the output reflections (use the lowest symmetry space group with the right point group), and optionally the maximum resolution in Angstroms.  If you don't specify the resolution, it'll use 3 Angstroms.

The reflections will be output as \fImymodel.pdb\fR.hkl ready for input to pattern_sim.  You'll need to give the Laue class of the symmetry you gave to gen-sfs, "6/m" in this case, to pattern_sim with \fB-y\fR.  By default, \fBgen-sfs\fR calculates the values for CuKa radiation (8.3 keV, 1.5 A).  It will not calculate the anomalous contribution to scattering, i.e. the differences in intensities between Bijoet pairs.  Both of these are the default behaviour for "sfall" in CCP4, so read the manual for that for further details.  If you need something different, get the "ano_sfall.com" script from James Holton and use the
\fBgen-sfs-ano\fR script instead of \fBgen-sfs\fR.

.SH CALCULATION DETAILS

The lattice transform from the specified number of unit cells is calculated
using the closed-form solution for a truncated lattice faceted on the
(001), (010) and (100) planes:
.IP
I_latt(q) =  sin^2(pi*na*g.a)/sin^2(pi*g.a)
           * sin^2(pi*nb*g.b)/sin^2(pi*g.b)
           * sin^2(pi*nc*g.c)/sin^2(pi*g.c)
.IP
na = number of unit cells in 'a' direction (likewise nb, nc)
.br
 g = reciprocal vector (1/d convention, not 2pi/d)
.PP
This is multiplied by a model of the underlying molecular transform, I_mol(g).
This can be approximated to varying levels of accuracy by the methods given by
\fB--gradients\fR.
.PP
Expected intensities at the CCD are then calculated using:
.IP
I(g) = I0 * r^2 * I_latt(g) * I_mol(g) * S
.IP
I0 = number of photons per unit area in the incident beam
 r = Thomson radius
 S = solid angle of corresponding pixel
.PP
Polarisation is not currently included in pattern_sim, although it is included
in the analysis of Bragg peaks done by \fBindexamajig\fR.
.PP
Poisson counts are generated from the expected intensities using Knuth's
algorithm.  When the intensity is sufficiently high that Knuth's algorithm
would result in machine precision problems, a normal distribution with
standard deviation sqrt(I) is used instead.

.SH GRADIENT METHODS

The available options for \fB--gradients\fR as as follows:

.IP \fBmosaic\fR
.PD
Take the intensity of the nearest Bragg position.  This is the fastest method and the only one supported on the GPU, but the least accurate.

.IP \fBinterpolate\fR
.PD
Interpolate trilinearly between six adjacent Bragg intensities. This method has intermediate accuracy.

.IP \fBphased\fR
.PD
As 'interpolate', but take phase values into account.  This is the most accurate method, but the slowest.

.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
Copyright © 2012 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
.P
pattern_sim, and this manual, are part of CrystFEL.
.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 crystfel (7)
and
.BR crystfel_geometry (5).