CELL_TOOL(1)

💅 cell_tool(1) — General Commands Manual, but make it cute

okay so bestie, welcome to cell_tool ✨ this is a page straight out of the General Commands Manual, and it's about manipulating unit cells. yes, the crystallography kind, not the prison kind 💀

---

✨ NAME ✨

cell_tool — manipulate unit cells 🧚

---

🌸 SYNOPSIS 🌸

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

---

🦋 DESCRIPTION 🦋

so what does cell_tool actually do? it performs various manipulations on unit cells, and the lineup is honestly kind of iconic 👑

• generating power ring positions
• comparing one unit cell to another
• calculating a primitive unit cell from a centered one
• searching for indexing ambiguities

the unit cell can be given as a CrystFEL unit cell file, or alternatively as a PDB file. either one, your call, no pressure 💖

---

🎀 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 🔥

⚠️ heads up bestie: screw axis and glide plane absences will not be taken into account, so some rings may be absent depending on the space group. it's not a bug, it's just how it is, ok? 😭

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. slay 💅

---

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

nnn and here's the thing — there are an infinite number of primitive unit cells for any lattice 😳 this program generates only one of them. just one. that's the whole vibe check.

---

🌈 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 by 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 will be used for some of the comparison results. read the output carefully, bestie, fr fr.

---

⭐ 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. main character behaviour tbh 🌟

💖 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 is 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! go on, be curious ✨).

🌸 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:
              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:
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. nothing. empty. ghost town.

🦋 Example 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. (yes, the original says "of of". we keep the lore 💀)

---

🫶 AUTHOR 🫶

this page was written by Thomas White. ty king 👑

---

💀 REPORTING BUGS 💀

report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>. they want to hear from you, bestie, don't be shy.

---

🌺 COPYRIGHT AND DISCLAIMER 🌺

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

cell-tool, and this manual, are part of CrystFEL.

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(7)
• indexamajig(1)
• get_hkl(1)

---

okay that's the whole page, you ate that 💅 go read the other ones too, iykyk. this has been the CELL_TOOL(1) page from the General Commands Manual — mwah, catch you in the next manpage 🎀✨🦋