6 files changed, 174 insertions, 6 deletions
diff --git a/doc/man/cell_tool.1 b/doc/man/cell_tool.1
new file mode 100644
index 00000000..576943d0
--- /dev/null
+++ b/doc/man/cell_tool.1
@@ -0,0 +1,147 @@
+.\"
+.\" cell_tool man page
+.\"
+.\" Copyright © 2015-2019 Deutsches Elektronen-Synchrotron DESY,
+.\"                       a research centre of the Helmholtz Association.
+.\"
+.\" Part of CrystFEL - crystallography with a FEL
+.\"
+
+.TH CELL_TOOL 1
+.SH NAME
+cell_tool \- manipulate unit cells
+.SH SYNOPSIS
+.PP
+\fBcell_tool --find-ambi \fImy_structure.cell \fR[\fB-y \fImypointgroup\fR] [\fB--tolerance=\fItols\fR]
+.PP
+\fBcell_tool --uncenter \fImy_structure.cell \fR[\fB-o \fIoutput.cell\fR]
+.PP
+\fBcell_tool --rings \fImy_structure.cell \fR[\fB--highres=\fIangstroms\fR]
+.PP
+\fBcell_tool --compare-cell \fIreference.cell \fImy_structure.cell \fR[\fB--tolerance=\fItols\fR]
+.PP
+\fBcell_tool --transform=\fIop\fR \fImy_structure.cell
+.PP
+\fBcell_tool --help\fI
+
+.SH DESCRIPTION
+\fBcell_tool\fR performs various manipulations on unit cells, including generating power ring positions, comparing one unit cell to another, calculating a primitive unit cell from a centered one and searching for indexing ambiguities.
+.PP
+The unit cell can be given as a CrystFEL unit cell file, or alternatively as a PDB file.
+
+.SH CALCULATING POWDER RING POSITIONS
+.PP
+\fBcell_tool --rings \fImy_structure.cell \fR[--highres=\fIangstroms\fR] [-y \fIpg\fR]
+.PP
+This will generate a list of d-spacings and hkl values for the powder rings given by the unit cell file.  Note that screw axis and glide plane absences will not be taken into account, so some rings may be absent depending on the space group.
+.PP
+If you additionally specify the point group using \fB-y\fR (see 'man crystfel' for how to specify point groups), symmetrically equivalent rings will be combined and multiplicities calculated.
+
+.SH GENERATING A PRIMITIVE UNIT CELL
+.PP
+\fBcell_tool --uncenter \fImy_structure.cell \fR[-o \fIoutput.cell\fR]
+.PP
+This will generate a primitive unit cell representing the same lattice as the input.  Add the \fB-o\fR option to write the result to a new unit cell file.
+.PP
+There are an infinite number of primitive unit cell for any lattice.  This program generates only one of them.
+
+.SH COMPARING UNIT CELLS
+.PP
+\fBcell_tool --compare-cell \fIreference.cell my_structure.cell \fR[\fB--tolerance=\fItols\fR]
+.PP
+The program will compare the two cells, and report if \fImy_structure.cell\fR can be made to look similar to \fIreference.cell\fR applying any transformation matrix.
+.PP
+The tolerance \fItols\fR is given as lengthtol,angtol, in percent and degrees respectively, which will be applied to the real-space unit cell axis lengths and angles.
+
+.SH TRANSFORMING A UNIT CELL
+.PP
+\fBcell_tool --transform=\fIop\fR \fImy_structure.cell
+.PP
+The program will transform the unit cell according to \fIop\fR.  Example: \fB--transform=b,c,a\fR means to permute the axes such that the new \fIa\fR axis matches the old \fIb\fR axis, and so on.
+
+.SH FINDING INDEXING AMBIGUITIES
+.PP
+\fBcell_tool --find-ambi \fImy_structure.cell \fR[-y \fIpg\fR] [\fB--tolerance=\fItols\fR]
+.PP
+The program will report all transformation matrices which produce a similar unit cell, to within the specified tolerance.  The tolerance \fItols\fR is given as lengthtol,angtol, in percent and degrees respectively, which will be applied to the real-space unit cell axis lengths and angles.
+.PP
+If you additionally give the true symmetry using \fB-y\fR, the program will calculate the ambiguity operators, i.e. the operations which are not symmetry operators of the structure, but which nevertheless leave the lattice looking the same.
+.PP
+\fBExample 1: Merohedral indexing ambiguity in photosystem I\fR
+
+The space group of photosystem I crystals as described by PDB code 1JB0 is P63,
+so the point group is '6':
+
+$ cell_tool --find-ambi 1JB0.pdb -y 6
+.nf
+[...]
+Observed symmetry operations:
+              1 : hkl         -h-k,k,-l   -h-k,h,l    -h,-k,l     -h,h+k,-l
+                  -k,-h,-l    -k,h+k,l    k,-h-k,l    k,h,-l       h,-h-k,-l
+                  h+k,-h,l    h+k,-k,-l
+Ambiguity operations:
+         1 -> 6 : hkl         -h-k,k,-l
+.fi
+
+There are 12 reflections which cannot be distinguished between by the lattice alone, but only 6 of those are true symmetry equivalents according to the structure.  The transformation describing the indexing ambiguity as follows: "A reflection hkl will be confused with one with indices -h-k,k,-l".  Had the point group of the crystals been '622', there would have been no indexing ambiguity (try it!).
+
+.PP
+\fBExample 2: No indexing ambiguity in lysozyme\fR
+
+The space group of lysozyme crystals as described by PDB code 1VDS is P 43 21 2, so the point group is '422':
+
+.nf
+$ cell_tool --find-ambi 1VDS.pdb -y 422
+[...]
+Observed symmetry operations:
+              1 : hkl        -h,-k,l    -h,k,-l    -k,-h,-l   -k,h,l
+                  k,-h,l     k,h,-l     h,-k,-l
+Ambiguity operations:
+       1 -> 422 : hkl
+.fi
+
+All of the apparently equivalent reflections are true symmetry equivalents according to point group 422, so there is no indexing ambiguity.  The only operation produced by left coset decomposition is the identity operation.
+
+.PP
+\fBExample 3: "Accidental" ambiguity in myoglobin\fR
+
+The space group of myoglobin crystals as described by PDB code 3VAU is P2, so the point group is '2'.  Note that the "unique axis b" convention has been used for 3VAU (see "man crystfel" for information about specifying point groups):
+
+.nf
+$ cell_tool --find-ambi 3VAU.pdb -y 2_uab
+[...]
+  a     b     c         alpha   beta  gamma
+ 3.51  2.84  6.29 nm     90.00 105.50  90.00 deg
+[...]
+  a     b     c         alpha   beta  gamma
+ 3.51  2.84  6.33 nm     90.00 106.84  90.00 deg
+[...]
+Observed symmetry operations:
+              1 : hkl         -h,-k,h+l   -h,k,-l     h,-k,-h-l
+Ambiguity operations:
+         1 -> 2 : hkl         -h,-k,h+l
+.fi
+
+The transformations '-h,-k,h+l' and 'h,-k,-h-l', which correspond to indexing "diagonally", produce cells which look very similar to the original cell - a difference of only 0.4A and 1.34 degrees.  These two transformations are themselves related by a twofold rotation, which is a true symmetry of this crystal structure.  There is therefore only one ambiguity transformation.  The transformation is strange because it isn't one of the symmetries displayed by a monoclinic lattice in general.  This ambiguity has arisen because of of the particular unit cell parameters for this structure.
+
+.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 © 2015-2019 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
+.P
+cell-tool, 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),
+.BR indexamajig (1),
+.BR get_hkl (1)
diff --git a/doc/man/crystfel_geometry.5 b/doc/man/crystfel_geometry.5
index db444214..381d05aa 100644
--- a/doc/man/crystfel_geometry.5
+++ b/doc/man/crystfel_geometry.5
@@ -99,6 +99,9 @@ the axis encoding the slow scan index
 .IP fs
 .PD
 the axis encodes the fast scan index
+.IP \fInumber\fR
+.PD
+the index in this dimension should be fixed at \fInumber\fR.
 .RE
 .IP
 CrystFEL assumes that the data block defined by the 'data' property has a dimensionality equal to the axis with the highest value of \fIn\fR defined by the 'dim' property, and requires the user to provide information about each of the axes in the data block. When no 'dim' property is defined in the geometry file, CrystFEL assumes the data block to be 2-dimensional, with the two axes encoding slow scan and fast scan information respectively.
@@ -107,15 +110,18 @@ Note that this does indeed mean that you can assign the fast scan coordinates to
 
 Example:
 .RS
+.PD 0
 .IP
 dim0 = %
 .IP
 dim1 = ss
 .IP
 dim2 = fs
+.IP
+dim3 = 4
 .RE
 .IP
-The above snippet specifies that the data block is 3-dimensional. The first axis represents the event number, the second the slow scan panel coordinate, and the third the fast scan panel coordinate.
+The above snippet specifies that the data block is 3-dimensional. The first axis represents the event number, the second the slow scan panel coordinate, the third the fast scan panel coordinate, and the index in the final axis is always 4.
 
 .PD 0
 .IP \fBmin_fs\fR
diff --git a/doc/man/geoptimiser.1 b/doc/man/geoptimiser.1
index 369a36f1..3caba9c2 100644
--- a/doc/man/geoptimiser.1
+++ b/doc/man/geoptimiser.1
@@ -27,8 +27,10 @@ For a complete description of the optimization algorithm, see the following pape
 O. Yefanov, V. Mariani, C. Gati, T. A. White, H. N. Chapman, and A. Barty. "Accurate determination of segmented X-ray detector geometry". Optics Express 23 (2015) 28459. doi:10.1364/OE.23.028459.
 
 .PP
-For minimal basic use, you need to provide a stream file with diffraction patterns, a geometry file to optimize, a filename for the output optimized geometry, and
-the name of two rigid group collections defined in the geometry file: one describing which panels in the detector are physically connected (and hence whose geometry should be optimized as if they were a single panel), and one to describe which panels are attached to the same underlying support (whose position and orientation are likely to be correlated).
+For minimal basic use, you need to provide a stream file with diffraction patterns, a geometry file to optimize, a filename for the output optimized geometry, and the name of two rigid group collections defined in the geometry file: one describing which panels in the detector are physically connected (and hence whose geometry should be optimized as if they were a single panel), and one to describe which panels are attached to the same underlying support (whose position and orientation are likely to be correlated).
+
+.PP
+If you leave out the \fB-g\fR option, the geometry file from the stream's audit information will be used.  This is usually what you want.
 
 .PP
 See \fBman crystfel_geometry\fR for information on how to create a file describing the detector geometry, and guidelines to define the required rigid groups and rigid groups collections.
@@ -49,7 +51,7 @@ Give the filename of the stream from which to read the indexed patterns.
 .IP "\fB-g\fR \fIfilename\fR"
 .IP \fB--geometry=\fR\fIfilename\fR
 .PD
-Read the detector geometry to optimize from the \fIfilename\fR file.
+Read the detector geometry to optimize from \fIfilename\fR.  If this option is omitted, the geometry file from the stream's header will be used (see \fB--input\fR), if present.
 
 .PD 0
 .IP "\fB-o\fR \fIfilename\fR"
@@ -139,7 +141,7 @@ This page was written by Valerio Mariani, Oleksandr Yefanov and Thomas White.
 Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.
 
 .SH COPYRIGHT AND DISCLAIMER
-Copyright © 2014-2018 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
+Copyright © 2014-2019 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
 .P
 geoptimiser, and this manual, are part of CrystFEL.
 .P
diff --git a/doc/man/indexamajig.1 b/doc/man/indexamajig.1
index 95db227a..1866231a 100644
--- a/doc/man/indexamajig.1
+++ b/doc/man/indexamajig.1
@@ -423,6 +423,8 @@ These set low-level parameters for the Felix indexing algorithm.
 .IP \fB--xgandalf-no-deviation-from-provided-cell\fR
 .IP \fB--xgandalf-max-lattice-vector-length=\fIn\fR
 .IP \fB--xgandalf-min-lattice-vector-length=\fIn\fR
+.IP \fB--xgandalf-max-peaks=\fIn\fR
+.IP \fB--xgandalf-fast-execution\fR
 .PD
 These set low-level parameters for the XGANDALF indexing algorithm.
 .IP
@@ -435,6 +437,10 @@ These set low-level parameters for the XGANDALF indexing algorithm.
 \fB--xgandalf-no-deviation-from-provided-cell\fR if a prior unit cell was provided, and this flag is set, the found unit cell will have exactly the same size as the provided one.
 .IP
 \fB--xgandalf-min-lattice-vector-length\fR and \fB--xgandalf-min-lattice-vector-length\fR minimum and maximum possible lattice vector lengths (unit is A). Used for fitting without prior lattice as starting point for gradient descent, so the final minimum lattice vector length can be smaller/highier as min/max. Note: This is valid for the uncentered cell, i.e. the P-cell! Default is 30A and 250A respectively.
+.IP
+\fB--xgandalf-max-peaks\fR maximum number of peaks used for indexing. For refinement all peaks are used. Peaks are selected by increasing radius. Limits the maximum execution time for patterns with a huge amount of peaks - either real ones or false positives. Default is 250.
+.IP
+\fB--xgandalf-fast-execution\fR Shortcut to set --xgandalf-sampling-pitch=2 --xgandalf-grad-desc-iterations=3
 
 .SH INTEGRATION OPTIONS
 .PD 0
diff --git a/doc/man/partial_sim.1 b/doc/man/partial_sim.1
index 72655758..d7b91040 100644
--- a/doc/man/partial_sim.1
+++ b/doc/man/partial_sim.1
@@ -148,6 +148,12 @@ Set the central photon energy, in eV, for the incident beam.  The default is \fB
 .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.
 
diff --git a/doc/man/partialator.1 b/doc/man/partialator.1
index 1a6d30d3..f0491616 100644
--- a/doc/man/partialator.1
+++ b/doc/man/partialator.1
@@ -169,8 +169,9 @@ If you prefer, you can specify the ambiguity operator by specifying the apparent
 .PD 0
 .IP \fB--force-bandwidth=\fIbw\fR
 .IP \fB--force-radius=\fIR\fR
+.IP \fB--force-lambda=\fIR\fR
 .PD
-Set the X-ray bandwidth or initial profile radius for all crystals before proceeding, overriding the values from the stream.  Bandwidth is given as a fraction, i.e. \fB--force-bandwidth=0.0013\fR means 0.13 percent (approximate FWHM).  Radius is given in  nm^-1.
+Set the X-ray bandwidth, initial profile radius or wavelength for all crystals before proceeding, overriding the values from the stream.  Bandwidth is given as a fraction, i.e. \fB--force-bandwidth=0.0013\fR means 0.13 percent (approximate FWHM).  Radius is given in nm^-1.  Wavelength is given in Angstroms.
 
 .SH PARTIALITY MODELS