LCLSGeom

LCLSwapping Geometry tool - miscellaneous functions for converting geometry files for LCLS geometry calibrations and optimizations.

Package Description

This repository aims at centralizing and uniformizing LCLS routines to write, convert and switch between different geometry files format. The main code mainly relies on the PSCalib repository that was designed by Mikhail Dubrovin. For reference frame definition, we will adopt the traditional (x,y,z) description: x being the first coordinate, y the second and z the third.

Reference Frame Definition & Convention

The geometry of an experiment can be defined using different frames. The first one involved is the psana frame used in metrology: the different translations x, y, z and rotation angles are measured and entered in .data file. Then those metrology data can be converted in Crystel format .geom file. At this point, those data can be chosen to be formatted in the CrystFEL format while being written in the psana system of coordinates or in the CrystFEL system. Finally, pyFAI uses another format and system of coordinates, but we will see that the latter does not matter much.

Nota Bene Every reference frame is defined at the Interaction Point (IP) which is defined as the point where the X-ray beam interacts with the sample.

CrystFEL or Laboratory Coordinate System

This is the traditional system of coordinates when conducting an experiment. According to the confluence documentation about detector geometry, the Lab frame is defined as such:

+x axis pointing from IP to the north

+y axis pointing from IP to the top

+z axis pointing from IP along the photon beam propagation direction

Psana Coordinate System

This is the coordinate system used in metrology measurements. According to the geometry_converter code, the psana coordinate system can be transformed into the Lab coordinate system by doing those operations:

Hence, in this system:

+x points towards the ground

+y points from left to right horizontally

+z is the opposite of the beam direction

This coordinate system is convenient for calibrating the geometry since the pixel space in matplotlib definition has the same axis as in the psana system. The top left corner of an image is the origin of the pixel space, the row-space being the vertical axis (i.e. the first dimension of an array) which in psana is the x-coordinate and the column-space being the horizontal axis (i.e. the second dimension of an array) which in psana is the y-coordinate.

PyFAI Coordinate System

PyFAI's coordinate system is defined as such:

Hence, in this system:

+x points towards the top

+y points from left to right horizontally

+z is along the beam direction

Geometry Format & Environment

Now that the different coordinate systems has been introduced, we will move on explaining how geometries are defined in each geometry file format.

Psana Format

This is an LCLS internal geometry file format. It uses a hierarchical representation of the detector: first come pixels, then asics, then panels, and then the IP. To be more consice, every children frame is defined in its parent frame. Parents can have multiple children, but every child only has one parent. For example, a geometry definition for the ePix10k2M detector (exp: mfxx49820) will look as such:

Every panel EPIX10KA:V1 frame origin is expressed in the CAMERA frame by six parameters: X0, Y0, Z0, ROT-Z, ROT-Y, ROT-X (if you want to take into account small angle deviations, the true rotations to be applied should rather be then (ROT-v + TILT-v)). The CAMERA object is the name given to the center of the detector. Likewise, the CAMERA frame origin is then expressed in the IP frame. Then, optimizing the geometry is only a matter of finding the optimal X0, Y0, Z0, ROT-Z, ROT-Y, ROT-X of the CAMERA origin in the IP frame, and further expressed the downstream object frames is the newly defined CAMERA frame.

For more information, go to detector geometry definition.

CrystFEL Format

The CrystFEL format is a more straight-forward way of defining a geometry. In a .geom file, there is no hierarchy involved, everything is expressed in the chosen system of coordinates. Let's stick with the previous example, here what the ePix10k2M .geom file will look like:

In a .geom file, it assumes that a geometry object is defined by a name 'piaj' where i is the panel index and j is the asic index. In the case of the ePix10k2M, i would lie between 0 and 15 (16 panels) and j would lie between 0 and 3 (4 asics per panel). Then, every geometry object 'piaj' has 11 parameters that defines the geometry as a whole:

fs: vector in the chosen coordinate system of the fast dimension

ss: vector in the chosen coordinate system of the slow dimension

res: resolution of the detector (1/pixel size)

corner_x: position in x (chosen coordinate system) of the corner of this panel/asic. A corner is defined as the first point in the panel/asic to appear in the image data. Units are in pixel widths of the current panel/asic

corner_y: position in y (chosen coordinate system) of the corner of this panel/asic

coffest: position in z (chosen coordinate system) of this panel/asic from the position given by the camera length

min_fs: minimal pixel index of current panel/asic in fast dimension

max_fs: maximal pixel index of current panel/asic in fast dimension

min_ss: minimal pixel index of current panel/asic in slow dimension

max_ss: maximal pixel index of current panel/asic in slow dimension

no_index: do not matter

Nota Bene The reference frame can be chosen here. One can choose to write the pixel corner coordinates and vectors in the psana frame or the lab frame.

PyFAI Environment

PyFAI takes as an input a flattened pixel corner array (N_mods x dim(ss), dim(fs), 4, 3) where N_mods is the number of panels that the detector has, dim(ss) is the number of pixels in the slow-scan direction, dim(fs) the number of pixels in the fast-scan direction, 4 because a pixel has 4 corners, and 3 for the 3 coordinates.

Nota Bene Again, the reference frame can be chosen here. One can choose to write the pixel corner coordinates in the psana frame or the lab frame or pyFAI frame. PyFAI is really versatile, it is able to perform optimization given any frame where the pixel corner coordinates are expressed.

Motivation: Geometry Optimization Workflow

The final endpoint of this repository is to provide a central framework for dealing and handling geometry files for the calibration of the different LCLS expriments (mfx, mec, cxi...). This will help design a uniform geometry optimization workflow that aims to be applied for the calibration of all the different LCLS detectors (ePix10k2M, Jungfrau4M, ePix10ka...). This workflow will look like this:

Let's go into details:

Geometry Format Conversion

A geometry calibration starts with a psana .data file and is supposed to end with an optimal psana .data file. But pyFAI cannot comprehend this format, hence we need to have uniform scripts that are able to convert any geometry file format into another one, without affecting the geometry data. This will be handled by built-in functions from the PSCalib repository (.data to .geom and vice-versa) as well as some hand-coded functions (.geom to pyFAI format and vice-versa).

Optimization and Powder Preprocessing

PyFAI optimization will likely to need some preprocessing of the powder (as discussed in here) explaining why I am regrouping these two in one sub-category.

PyFAI provides a potential robust and fast geometry calibration workflow that was also described in here. PyFAI takes as an input a flattened pixel corner array (N_mods x dim(ss), dim(fs), 4, 3) where N_mods is the number of panels that the detector has, dim(ss) is the number of pixels in the slow-scan direction, dim(fs) the number of pixels in the fast-scan direction, 4 because a pixel has 4 corners, and 3 for the 3 coordinates. This pixel corner array is then used to instantiate a pyFAI Detector object where the optimization can be done given a powder data.

New Geometry Definition

Once the optimization is done, pyFAI will give 6 optimal parameters:

dist: distance IP-PONI where PONI is the Point of Normal Incidence

poni1: slow-scan coordinate of PONI

poni2: fast-scan coordinate of PONI

rot1: rotation over slow-scan direction

rot2: rotation over fast-scan direction

rot3: rotation over beam direction

Nota Bene These parameters in fact define the translations and rotations that need to be applied to correct the current detector frame.

Hence, once finally optimized, the correct geometry is obtained through adequate translations and rotations. Applying those to the uncalibrated X, Y, Z coordinates, we can then write a new CrystFEL .geom file, and finally write a new psana .data file thanks to the PSCalib code.

"La boucle est bouclée", the circle is complete in French!

Organization

The package structure is organized as follows:

LCLS/
├── src/ # Main package
│ ├── init.py # Package initialization
│ ├── swap_geom.py # Main module
├── tests/ # Unit tests
│ ├── init.py # Test package initialization
│ ├── test_swap_geom.py # Tests for main module
│ ├── data/ # Geometry files for tests
│   ├── ePix10k2M_0-end.data # psana file for ePix10k2M (mfxx49820)
│   ├── Jungfrau4M_0-end.data # psana file for Jungfrau4M (cxil1015922)
│   └── Rayonix_0-end.data # psana file for Rayonix (mfxl1015222)
│ ├── figs/ # Figures for visual verification of tests
├── LICENSE # License file
├── README.md # Readme file
├── requirements.txt # Dependencies and requirements
└── setup.py # Setup script for packaging

Usage

The main module swap_geom.py consists in four pyFAI detector definition as well as four major conversion classes. One for each conversion needed: Psana to CrystFEL, CrystFEL to PyFAI, PyFAI to CrystFEL, and finally CrystFEL back to Psana.

PsanatoCrystFEL

This class takes as input a Psana geometry .data file, a path for the output CrystFEL .geom file, as well as the det_type for the adequate detector. At the moment, valid det_type are:

• "epix10k2M"
• "Rayonix" or "rayonix"
• "jungfrau4M"
• "Epix10kaQuad.{i}" where i stands for the quad index

Example of Usage

psana_file = 'path/to/geom/mfx/mfxx49820/0-end.data'
output_file = 'path/to/geom/mfx/mfxx49820/r0000.geom'
PsanatoCrystFEL(psana_file=psana_file, output_file=output_file, det_type="epix10k2M")

CrystFELtoPyFAI

This class takes as input a CrystFEL .geom file and the det_type for the adequate detector. One could choose to use the pixel coordinates from the corresponding Psana .data file by passing it to the optional argument psana_file. By default, the script assumes the CrystFEL .geom file was written in the Psana coordinate system. One can change that by passing the optional argument cframe from 0 (Psana) to 1 (Lab coordinates). At the moment, valid det_type are:

• "epix10k2M"
• "Rayonix" or "rayonix"
• "jungfrau4M"
• "Epix10kaQuad.{i}" where i stands for the quad index

Example of Usage

psana_file = 'path/to/geom/mfx/mfxx49820/0-end.data'  # Optional
geom_file = 'path/to/geom/mfx/mfxx49820/r0000.geom'
converter = CrystFELtoPyFAI(geom_file=geom_file, det_type="epix10k2M", psana_file=None, cframe=0)
pixel_array = converter.pix_pos   # Pixel coordinates fed to pyFAI
epix10k2M = converter.detector    # PyFAI Detector Object with correct pixel corner array

PyFAItoCrystFEL

This class takes as input a SingleGeometry PyFAI object sg, where the result of the optimization is stored, any Psana .data file to access the necessary segmentation infos of the detector, the initial pixel coordinates pixel_array that was fed to PyFAI, and a path for the CrystFEL .geom file output_file.

Example of Usage

psana_file = 'path/to/geom/mfx/mfxx49820/0-end.data'
pixel_array = CrystFELtoPyFAI_converter.pix_pos
output_file = 'path/to/geom/mfx/mfxx49820/r0008.geom'
PyFAItoCrystFEL(sg=sg, psana_file=psana_file, pixel_array=pixel_array, output_file=output_file)

CrystFELtoPsana

This class takes as input a CrystFEL .geom file, a valid det_type and a path for the output_file. However, at the moment, PSCalib converter code is only implemented for certain detectors. Valid det_types are:

• "epix10ka"
• "jungfrau"
• "cspad"
• "cspadv2"
• "pnccd"

Example of Usage

geom_file = 'path/to/geom/mfx/mfxx49820/r0008.geom'
output_file = 'path/to/geom/mfx/mfxx49820/r0008.data'
CrystFELtoPsana(geom_file=geom_file, det_type='epix10ka', output_file=output_file)