Initial cell_tool (implementing find_ambi only)

1 files changed, 141 insertions, 0 deletions

diff --git a/doc/man/cell_tool.1 b/doc/man/cell_tool.1
new file mode 100644
index 00000000..eb8a4adf
--- /dev/null
+++ b/doc/man/cell_tool.1
@@ -0,0 +1,141 @@
+.\"
+.\" 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 --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.
+.PP
+Note that the comparison is quite limited in the current version.   The transformation matrix applied to \fImy_structure.cell\fR is restricted to positive integer (or zero) components, so if \fImy_structure.cell\fR is smaller than the reference, you might need to try swapping the arguments.  Even then, it might miss a relationship if one axis is needs to be (say) half the length while another needs to be double.  The centering is also ignored.
+
+.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)