cell_tool: manipulate unit cells


cell_tool --find-ambi my_structure.cell [-y mypointgroup] [--tolerance=tols]
cell_tool --uncenter my_structure.cell [-o output.cell]
cell_tool --rings my_structure.cell [--highres=angstroms]
cell_tool --compare-cell reference.cell my_structure.cell [--tolerance=tols]
cell_tool --transform=op my_structure.cell
cell_tool --help


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

The unit cell can be given as a CrystFEL unit cell file, or alternatively as a PDB file.

Calculating powder ring positions

cell_tool --rings my_structure.cell [--highres=angstroms] [-y pg]

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.

If you additionally specify the point group using -y (see 'man crystfel' for how to specify point groups), symmetrically equivalent rings will be combined and multiplicities calculated.

Generating a primitive unit cell

cell_tool --uncenter my_structure.cell [-o output.cell]

This will generate a primitive unit cell representing the same lattice as the input. Add the -o option to write the result to a new unit cell file.

There are an infinite number of primitive unit cell for any lattice. This program generates only one of them.

Comparing unit cells

cell_tool --compare-cell reference.cell my_structure.cell [--tolerance=tols]

The program will compare the two cells, and report if my_structure.cell can be made to look similar to reference.cell applying any transformation matrix.

The tolerance tols is given as lengthtol,angtol, in percent and degrees respectively, which will be applied to the real-space unit cell axis lengths and angles. If either of the unit cells are centered, a primitive version of will be used for some of the comparison results. Read the output carefully.

Transforming a unit cell

cell_tool --transform=op my_structure.cell

The program will transform the unit cell according to op. Example: --transform=b,c,a means to permute the axes such that the new a axis matches the old b axis, and so on.

Finding indexing ambiguities

cell_tool --find-ambi my_structure.cell [-y pg] [--tolerance=tols]

The program will report all transformation matrices which produce a similar unit cell, to within the specified tolerance. The tolerance tols is given as lengthtol,angtol, in percent and degrees respectively, which will be applied to the real-space unit cell axis lengths and angles.

If you additionally give the true symmetry using -y, 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.

Example 1: Merohedral indexing ambiguity in photosystem I

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
Observed symmetry operations:
       Observed : 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:
  Observed -> 6 : -h-k,k,-l

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

Example 2: No indexing ambiguity in lysozyme

The space group of lysozyme crystals as described by PDB code 1VDS is P 43 21 2, so the point group is '422':

$ cell_tool --find-ambi 1VDS.pdb -y 422
Observed symmetry operations:
       Observed : hkl        -h,-k,l    -h,k,-l    -k,-h,-l   -k,h,l
                  k,-h,l     k,h,-l     h,-k,-l
Ambiguity operations:
Observed -> 422 : 

All of the apparently equivalent reflections are true symmetry equivalents according to point group 422, so there is no indexing ambiguity. No operations are produced by the left coset decomposition.

Exaple 3: "Accidental" ambiguity in myoglobin

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

$ 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:
       Observed : hkl         -h,-k,h+l   -h,k,-l     h,-k,-h-l
Ambiguity operations:
  Observed -> 2 : -h,-k,h+l

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.


This page was written by Thomas White.

Reporting bugs

Report bugs to

Copyright and Disclaimer

Copyright © 2012-2020 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

See also

crystfel indexamajig get_hkl

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