Information


Documentation



pattern_sim: Simulation of nanocrystal diffraction patterns

Synopsis

pattern_sim -g detector.geom -p my.pdb [options] ...
pattern_sim --help

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

Options

-p unitcell.cell
-p unitcell.pdb
--pdb=unitcell.pdb

Specify the name of the file containing the unit cell information, in PDB or CrystFEL format.

--gpu
Use the GPU to speed up the calculation. Requires that OpenCL libraries and drivers are available, and that CrystFEL was compiled with OpenCL enabled.
--gpu-dev=n
Use GPU device number n. If you omit this option, the list of GPU devices will be shown when you run pattern_sim.
-g filename
--geometry=filename
Read the detector geometry description from filename. See man crystfel_geometry for more information.
-n n
--number=n
Simulate n patterns. Default: -n 1.
--no-images
Do not save any HDF5 files apart from the powder pattern (if requested).
-o filename
--output=filename
Write the pattern to filename. The default is --output=sim.5. If more than one pattern is to be simulated (see --number), the filename will be postfixed with a hyphen, the image number and then '.h5'.
-r
--random-orientation
Make up a random orientation for each pattern simulated.
--powder=filename
Write the sum of all patterns to filename.
-i filename
--intensities=filename
Get the intensities and phases at the reciprocal lattice points from filename.
-y pointgroup
--symmetry=pointgroup
Use pointgroup as the symmetry of the intensity list (see --intensities).
-t method
--gradients=method
Use method as way of calculating the molecular transform between reciprocal lattice points. See the section Gradient methods.
--really-random
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.
--min-size=min
--min-size=max
Generate random crystal sizes between min and max nanometres. These options must be used together.
--no-noise
Do not calculate Poisson noise.
-s n
--sample-spectrum=n
Include n samples from the spectrum in the calculation.
-x type
--spectrum=type
Use type of spectrum. type can be one of tophat or sase or twocolour. See the section on spectrum types below.
--background=n
Add n photons of Poisson-distributed background uniformly over the detector surface.
--no-fringes
Suppress the subsidiary maxima of the shape transforms by setting Ilatt(q) to zero beyond the first minimum of the function.
--beam-bandwidth=val

Set the bandwidth, expressed as a decimal fraction applying to to wavelengths (not the photon energies), for the incident beam. The default is --beam-bandwidth=0.01, i.e. 1%.

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.

--photon-energy=val
Set the central photon energy, in eV, for the incident beam. The default is --photon-energy=9000, i.e. 9 keV X-rays.
--nphotons=val
Set the number of photons per X-ray pulse. The default is --nphotons=1e12. A physically reasonable value is such that the pulse energy (number of photons multiplied by photon energy) is about 1 mJ.
--beam-radius=val
Set the radius of the X-ray beam, in metres. The default is --beam-radius=1e-6, i.e. a beam of 2 microns' diameter.

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:

$ gen-sfs mymodel.pdb "P6" 3

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 mymodel.pdb.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 -y. By default, gen-sfs 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 gen-sfs-ano script instead of gen-sfs.

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:

Ilatt(q) = sin2(pi*na*g.a)/sin2(pi*g.a) * sin2(pi*nb*g.b)/sin2(pi*g.b) * sin2(pi*nc*g.c)/sin2(pi*g.c)

na = number of unit cells in 'a' direction (likewise nb, nc)
g = reciprocal vector (1/d convention, not 2pi/d)

This is multiplied by a model of the underlying molecular transform, Imol(g). This can be approximated to varying levels of accuracy by the methods given by --gradients.

Expected intensities at the CCD are then calculated using:

I(g) = I0 * r2 * Ilatt(g) * Imol(g) * S

I0 = number of photons per unit area in the incident beam
r = Thomson radius
S = solid angle of corresponding pixel

Polarisation is not currently included in pattern_sim, although it is included in the analysis of Bragg peaks done by indexamajig.

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.

Gradient methods

The available options for --gradients as as follows:

mosaic
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.
interpolate
Interpolate trilinearly between six adjacent Bragg intensities. This method has intermediate accuracy.
phased
As 'interpolate', but take phase values into account. This is the most accurate method, but the slowest.

Spectrum types

The available options for --spectrum are:

tophat
The spectrum samples will be distributed equidistantly either side of the specified photon energy to give a uniform distribution.
sase
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'.
twocolour
The spectrum will consist of two Gaussian peaks separated by the specified bandwidth, each with a standard deviation of one fifth the specified bandwidth.

Author

This page was written by Thomas White.

Reporting bugs

Report bugs to taw@physics.org

Copyright and Disclaimer

Copyright © 2012-2015 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.

Please read the AUTHORS file in the CrystFEL source code distribution for a full list of contributions and contributors.

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.

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.

You should have received a copy of the GNU General Public License along with CrystFEL. If not, see http://www.gnu.org/licenses/.

See also

crystfel crystfel_geometry

If CrystFEL is installed on your computer, you can read this manual page offline using the command man pattern_sim.