aboutsummaryrefslogtreecommitdiff
path: root/doc/man/align_detector.1.md
blob: c31e8758a14fb720cfad7553945a73dd57768e3d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
% align_detector(1)

NAME
====

align_detector - refine detector geometry


SYNOPSIS
========

align_detector -g _input.geom_ -o _output.geom_ -l _level_ [--out-of-plane] _millepede-files_


DESCRIPTION
===========

**align_detector** refines the detector geometry based on the calibration data
written by **indexamajig**.  The refinement takes into account all the
inter-dependencies between crystal orientations, cell parameters and the panel
positions, but is nevertheless very fast.  This is achieved using the
Millepede-II algorithm.  For more information, see
https://www.desy.de/~kleinwrt/MP2/doc/html/index.html

To refine the detector geometry, first make sure that the geometry file
includes hierarchy information.  For this, see **man crystfel_geometry**,
section **Detector hierarchy**.

Next, run **indexamajig** as usual, but with option **--mille**.  This will
produce several files named **mille-data-0.bin**, **mille-data-1.bin**,
**mille-data-2.bin** and so on - as many files as there were indexamajig
subprocesses (set with **indexamajig -j**).

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.

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** would refine the quadrant positions, **2** would refine the 2-by-1
panel "dominoes", and level **3** would refine the individual (roughly square)
ASICs.  Higher refinement levels will generally require more and
higher-resolution diffraction data.

The default behaviour is to refine only the position components in the x-y
plane, perpendicular to the beam.  In favourable circumstances, you can add
option **--out-of-plane** to refine the panel tilts and shifts out of this
plane.  However, be aware that this introduces additional cross-dependencies
and is less stable.

**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_
: Specify the input geometry filename.

**-o** _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.

**-l** _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 positions and tilts of the detector.


AUTHOR
======

This page was written by Thomas White.


REPORTING BUGS
==============

Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.


COPYRIGHT AND DISCLAIMER
========================

Copyright © 2023 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.

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), **adjust_detector**(1),
**crystfel_geometry**(5)