path: root/doc/man/pattern_sim.1

.\"
.\" pattern_sim man page
.\"
.\" Copyright © 2012-2020 Deutsches Elektronen-Synchrotron DESY,
.\"                       a research centre of the Helmholtz Association.
.\"
.\" 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-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 -p my.pdb -r -i myintensities.hkl

The unit cell geometry will be taken from the unit cell 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 a geometry description file (-g).  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.cell\fR"
.IP "\fB-p\fR \fIunitcell.pdb\fR"
.IP \fB--pdb=\fR\fIunitcell.pdb\fR
.PD
Specify the name of the file containing unit cell information, in PDB or CrystFEL format.

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

.PD 0
.IP "\fB-s\fR \fIn\fR"
.IP \fB--sample-spectrum=\fR\fIn\fR
.PD
Include \fIn\fR samples from the spectrum in the calculation.

.PD 0
.IP "\fB-x\fR \fItype\fR"
.IP \fB--spectrum=\fR\fItype\fR
.PD
Use \fItype\fR of spectrum.  \fItype\fR can be one of \fBtophat\fR, \fBsase\fR or \fBtwocolour\fR.  See the section \fBSPECTRUM TYPES\fR below.

.PD 0
.IP \fB--background=\fR\fIn\fR
.PD
Add \fIn\fR photons of Poisson-distributed background uniformly over the detector surface.

.PD 0
.IP \fB--no-fringes\fR
.PD
Suppress the subsidiary maxima of the shape transforms by setting I_latt(q) to zero beyond the first minimum of the function.

.PD 0
.B
.IP "\fB--beam-bandwidth=\fIval\fR"
.PD
Set the bandwidth, expressed as a decimal fraction applying to to wavelengths (not the photon energies), for the incident beam.  The default is \fB--beam-bandwidth=0.01\fR, i.e. 1%.\fR.
.PD
Note: When using the two-colour or SASE spectrum, the spectrum calculation actually takes this value to be the bandwidth applying to the photon energies instead of the wavelengths.  For small bandwidths, the difference should be very small.  Sorry for the horrifying inconsistency.

.PD 0
.B
.IP "\fB--photon-energy=\fIval\fR"
.PD
Set the central photon energy, in eV, for the incident beam.  The default is \fB--photon-energy=9000\fR, i.e. 9 keV X-rays.

.PD 0
.B
.IP "\fB--nphotons=\fIval\fR"
.PD
Set the number of photons per X-ray pulse.  The default is \fB--nphotons=1e12\fR.  A physically reasonable value is such that the pulse energy (number of photons multiplied by photon energy) is about 1 mJ.

.IP "\fB--beam-radius=\fIval\fR"
.PD
Set the radius of the X-ray beam, in metres.  The default is \fB--beam-radius=1e-6\fR, i.e. a beam of 2 microns' diameter.

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

The available options for \fB--spectrum\fR are:

.IP \fBtophat\fR
.PD
The spectrum samples will be distributed equidistantly either side of the specified photon energy to give a uniform distribution.

.IP \fBsase\fR
.PD
A self-amplified spontaneous emission (SASE) spectrum will be simulated, as follows.  First, a central photon energy will be chosen using a Gaussian distribution centered on the specified photon energy with a standard deviation of 8 eV.  A Gaussian spectrum will then be calculated using the specified bandwidth, and noise added to simulatie the SASE 'spikes'.

.IP \fBtwocolour\fR
.PD
The spectrum will consist of two Gaussian peaks separated by the specified bandwidth, each with a standard deviation of one fifth the specified bandwidth.

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