align_detector(1)

📦
version 0.13.0 · 2 versions
, in nixpkgs unstable

💅 align_detector — refine detector geometry ✨

okay so bestie, this is align_detector(1) from the General Commands Manual and it's literally about making your detector geometry chef's kiss accurate, no cap. buckle up 🎀

✨ NAME ✨

align_detector — refine detector geometry 🦋

🌸 SYNOPSIS 🌸

align_detector -g input.geom -o output.geom -l level [--out-of-plane]
millepede-files

💖 DESCRIPTION 💖

okay so align_detector takes the calibration data that indexamajig wrote out and uses it to refine your detector geometry. and the way it does this is genuinely iconic: it accounts for all the inter-dependencies between crystal orientations, cell parameters and the panel positions — like, as if one single giant minimisation had been run with every frame at once. main character energy fr 👑

but here's the slay part: the algorithm is nevertheless very fast — and that's thanks to the Millepede-II algorithm. for more info, go look at https://www.desy.de/~kleinwrt/MP2/doc/html/index.html 💜

so how do you actually do it? three steps, bestie, let's go 🫶

  1. first, make sure your geometry file includes hierarchy information. for this, see man crystfel_geometry, section Detector hierarchy.
  2. next, run indexamajig as usual, but with option --mille. this produces an additional output file with default name mille-data.bin (use --mille-file to set a different location). this file contains the calibration data that can be read by align_detector and show_residuals ✨
  3. finally, run align_detector, giving it the input geometry file, the "Mille" files, a refinement level and a filename for the updated geometry file. ⚠️ the input geometry file must match the file used for the indexamajig run — don't be out here swapping files, that's not the vibe 🙈

🎚️ refinement levels, iykyk

refinement level 0 allows only the overall detector position to vary. higher levels allow groups of panels to move according to the hierarchy. for example, for a CSPAD detector with hierarchy defined as in the example files:

  • level 1 refines the quadrant positions 🍓
  • level 2 refines the 2-by-1 panel "dominoes"
  • level 3 refines the individual (roughly square) ASICs

higher refinement levels will generally require more and higher-resolution diffraction data. no free lunch, bestie 😭

also! you can use indexamajig option --max-mille-level to reduce the size of the calibration data files — at the cost of limiting the maximum refinement level. trade-offs, amirite 💅

🌈 in-plane vs out-of-plane

the default behaviour is to refine only the position components in the x-y plane, perpendicular to the beam. that's the safe, comfy vibe 😌

in favourable circumstances you can add option --out-of-plane to refine the panel translations out of this plane. but be aware — this introduces additional cross-dependencies and is less stable. add option --out-of-plane-tilts to additionally refine the panel tilts out of the x-y plane, which is even less stable. 🔥💀

📷 the camera length situation

the overall detector z-position (camera length) is usually quite strongly correlated with the crystal cell parameters, making it difficult to refine. with high-resolution data, it can be possible, however. to refine the overall camera length, add --camera-length. 🎀

without this option, the overall camera length will not be altered — even with --out-of-plane. instead, only the z-positions of the panels relative to one another will be refined. periodt.

🧚 the pede dependency

align_detector relies on the program pede from the Millepede-II package. usually this will be installed as part of the CrystFEL installation procedure. if not, it can easily be installed from the Millepede-II repository at https://gitlab.desy.de/claus.kleinwort/millepede-ii ⭐

👑 OPTIONS 👑

  • -g input.geom, --geometry=input.geom — specify the input geometry filename. (yes, this is the one that has to match your indexamajig run 💖)
  • -o output.geom, --output=output.geom — specify the output geometry filename. ⚠️ note that the geometry file will be re-written, meaning that any formatting and comments will be lost. say goodbye to your cute comments, bestie 😭
  • -l level, --level=level — specify the refinement level. -l 0 refines the overall detector position only. the maximum refinement level is determined by the hierarchy of the detector. 🪜
  • --out-of-plane — additionally refine out-of-plane panel translations, relative to one another (see --camera-length). 🦋
  • --out-of-plane-tilts — additionally refine out-of-plane panel tilts. even more chaotic, see above 💀
  • --panel-totals — display the total translation and rotation changes for each panel. this does not affect the refinement or the output geometry file in any way — only the console output. purely a lil treat for your eyeballs 👀
  • --min-measurements=n — require at least n measurements contributing to a detector geometry parameter before updating that parameter. higher values give more stable refinement. note that there are two measurements per peak-reflection pair, because the position offsets are two dimensional. the default value is 100, i.e. at least 50 pairs are needed for each parameter. math is mathing 🧮
  • --big-errors — tell pede to be very tolerant of large residuals in the input data. add this option if an initial refinement fails due to too many "huge" rejects. 🙏

🫶 AUTHOR 🫶

this page was written by Thomas White. 💜

🐛 REPORTING BUGS 🐛

report bugs to taw@physics.org, or visit http://www.desy.de/~twhite/crystfel. we love a bug report, fr fr 🎀

copyright © 2023-2025 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.

align_detector, 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. (yes, that's the all-caps bit, it's serious 🫡)

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 🌈

okay that's the whole page bestie, go align that detector and slay 💖✨ this has been align_detector(1) from the General Commands Manual — no version or date was listed on the page, so consider this your official cute sign-off 🎀🦋

📦 where this page comes from