path: root/doc/man/partial_sim.1

.\"
.\" partial_sim man page
.\"
.\" Copyright © 2012-2018 Deutsches Elektronen-Synchrotron DESY,
.\"                       a research centre of the Helmholtz Association.
.\"
.\" Part of CrystFEL - crystallography with a FEL
.\"

.TH PARTIAL_SIM 1
.SH NAME
partial_sim \- calculate partial reflections
.SH SYNOPSIS
.PP
.BR partial_sim
\fB-o\fR \fIsimulated.stream\fR
\fB-g\fR \fIgeometry.geom\fR
\fB-p\fR \fIunitcell.pdb\fR
[\fIoptions\fR] \fB...\fR

.BR partial_sim
\fB--help\fR

.SH DESCRIPTION
partial_sim calculates the intensities of idealised partial reflections from crystals in random orientations, which is useful for testing the convergence of Monte Carlo integration or scaling/post-refinement techniques.

.P
You need to provide a CrystFEL geometry file (with \fB--geometry=\fR\fImy.geom\fR or \fB-g\fR \fImy.geom\fR), a file containing the unit cell to use for the simulation (with \fB--pdb=\fR\fImy.pdb\fR or \fB-p\fR \fImy.pdb\fR), and an output filename with \fB--output=\fR\fImy.stream\fR or \fB-o\fR \fImy.stream\fR.

For each randomly generated orientation, partial_sim calculates which reflections would appear on the detector with the specified beam parameters.  It calculates the partiality for each reflection and multiplies it by the fully integrated intensity to produce a partial intensity.  The fully integrated intensities can be taken from a file you provide (see below), otherwise they will be randomly generated (by taking the absolute value of a Gaussian random number, mean zero and standard deviation 1000).  All the partial intensities for the orientation are multiplied by an overall scaling factor, which is randomly generated with a Gaussian distribution with mean 1 and standard deviation 0.3.  The partial intensities are written to the output stream, and the process repeated for as many different orientations as you ask for (see below, default: 2).

.P
See
.BR "man crystfel_geometry"
for information about CrystFEL geometry description files.

.SH OPTIONS
.PD 0
.B
.IP "-i \fIfile.hkl\fR"
.B
.IP --input=\fIfile.hkl\fR
.PD
Take the fully integrated reflection intensities from \fIfile.hkl\fR, instead of generating them randomly.

.B
.IP "\fB-n\fR \fIn\fR"
Specify the number of different orientations to simulate.  Default: 2.

.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
.B
.IP "-r \fIrandom.hkl\fR"
.B
.IP --save-random=\fIrandom.hkl\fR
.PD
If you did not provide your own fully integrated reflection intensities, they will be generated randomly for you.  Use this option to save the random intensities for future comparisons.

.PD 0
.B
.IP "\fB-y\fR \fIpointgroup\fR"
.B
.IP "\fB--symmetry=\fR\fIpointgroup\fR"
.PD
When combined with with \fB-i\fR, specifies the symmetry of the input reflection list.  Otherwise, specifies the symmetry of the randomly generated intensities.

.PD 0
.B
.IP "\fB-c\fR \fIval\fR"
.B
.IP "\fB--cnoise=\fR\fIval\fR"
.PD
Add random values with a flat distribution to the components of the reciprocal lattice vectors written to the stream, simulating indexing errors.  The maximum value that will be added is +/- \fIval\fR percent.

.PD 0
.B
.IP "\fB--pgraph=\fR\fIfilename\fR"
.PD
Save a table of values to \fIfilename\fR containing, in resolution shells, the following columns: resolution shell centre in nm^-1, number of reflections in shell, mean partiality, maximum partiality.

.PD 0
.B
.IP "\fB--osf-stddev=\fR\fIval\fR"
.PD
Set the standard deviation of the distribution of overall scaling factors to \fIval\fR.  The distribution will be cut at zero, i.e. negative or zero scaling factors are not allowed.  The distribution will be Gaussian centered on 1.  The default is \fB--osf-stddev=2.0\fR.

.PD 0
.B
.IP "\fB--full-stddev=\fR\fIval\fR"
.PD
Set the standard deviation of the distribution of randomly generated full intensities to \fIval\fR.  The distribution will be Gaussian, centered on zero, and the absolute value will be taken (i.e. there will be no negative values).  The default is \fB--full-stddev=1000.0\fR.  This option has no effect if you also use \fB-i\fR or \fB--input\fR.

.PD 0
.B
.IP "\fB--noise-stddev=\fR\fIval\fR"
.PD
Set the standard deviation of the noise added to the partial intensities to \fIval\fR.  The noise will be Gaussian, and the same for all reflections.  The default is \fB--noise-stddev=20.0\fR.

.PD 0
.B
.IP "\fB-j\fR \fIn\fR"
.PD
Use \fIn\fR threads for simulation.  Default: 1.

.PD 0
.B
.IP "\fB--images=\fR\fIprefix\fR"
.PD
For each chunk in the output stream, write a 'sketch' image in HDF5 format to \fIprefix\fR\fB/sim-\fR\fINNN\fR\fB.h5\fR, where \fINNN\fR is the sequence number of the chunk in the output stream.  This option is incompatible with \fB-j\fR.  The intensities in the peaks in the sketches will be equal to the partial intensities in the stream, including noise and overall scaling factors. The images will also contain a random Poisson-distributed background according to \fB--background\fR.

.PD 0
.B
.IP "\fB--background=\fIval\fR"
.PD
Add a Poisson-distributed background with \fIval\fR photons to the sketches (see \fB--images\fR).  The default is \fB--background=3000\fR.\fR.

.PD 0
.B
.IP "\fB--beam-divergence=\fIval\fR"
.PD
Set the convergence angle (the full angle, not "half-angle"/"semi-angle") for the incident beam.  The default is \fB--beam-divergence=0.001\fR, i.e. 1 mrad.\fR.

.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 0
.B
.IP "\fB--profile-radius=\fIval\fR"
.PD
Set the radius of the scattering density surrounding each reciprocal lattice point, in m^-1.  The default is \fB--profile-radius=0.001e9\fR m^-1.

.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
.IP \fB--really-random\fR
.PD
Seed the random number generator using the kernel random number generator (/dev/urandom).  This means that truly random (although not "cryptographically random") numbers will be used for the orientation and crystal size, instead of the same sequence being used for each new run.

.IP "\fB--template-stream=\fImy.stream\fR"
.PD
Get the crystal cell parameters, orientations and the reflections to calculate from \fImy.stream\fR.  This allows you to re-calculate partial intensities using new beam parameters.  There must only be one crystal per chunk in the template.  If more than one thread is used (see \fB-j\fR), note that there is no guarantee that the order of crystals in the output stream will match that of \fImy.stream\fR.


.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-2018 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
.P
partial_sim, and this manaul, 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),
.BR process_hkl (1),
.BR partialator (1),
.BR pattern_sim (1),
.BR crystfel_geometry (5).