LauePy

Zhang, Y., J. N. Porter, M. J. Wilkin, R. Harder, W. Cha, R. M. Suter, H. Liu, et al. “Mapping Nanocrystal Orientations via Scanning Laue Diffraction Microscopy for Multi-Peak Bragg Coherent Diffraction Imaging.” Journal of Synchrotron Radiation 30, no. 4 (July 1, 2023): 796–806. https://doi.org/10.1107/S160057752300365X.

LauePy is a python-based code library that analyzes Laue diffraction patterns collected from many locations on a sample---either a polycrystal or separated nanocrystals---to obtain a crystal orientation map. The Laue diffraction data is collected on a large area detector while scanning a wide-band (or "pink") x-ray beam over a sample. As a complement to Bragg coherent diffraction imaging (BCDI), it has a distinct advantage over the more common orientation-mapping technique of electron backscatter diffraction (EBSD). Because scanning Laue analysis and BCDI use almost identical setups, one can be performed directly after the other simply by inserting or removing a monochrometor.

Installation & setup

APS beamline 34-ID-C

If you're using LauePy, there's a decent chance you're doing so at APS beamline 34-ID-C. In this case, all of the dependencies should already be installed on Sayre, and you just need to run the following commands for the initial setup:

ssh -Y cxduser@sayre
cd 34idc-work/<year>/<experiment>
conda activate lauepy
mkdir lauepy
git clone https://github.com/jacione/lauepy.git

Once this is done, you can (and should) skip the rest of this section.

Requirements

LauePy makes certain assumptions about the setup, process, and data management of your experiment. These assumptions are based on APS beamline 34-ID-C, where the code was developed.

Current requirements:

Linux operating system (for the compiled Euler binary)
Python 3.7 (other versions probably work but haven't been tested)
NVidia graphics card (for CUDA-accelerated calculation)
The experiment must be managed in SPEC.

While a limited framework has been laid for the expansion of the software beyond this beamline, it is not currently at a plug-and-play level.

Install

Clone the git repository here! Once you've downloaded it, you'll need to install it, preferably in its own environment. Navigate your terminal to the repository and run

pip install --upgrade pip
pip install build
python -m build
pip install .

Basic Usage

The easiest way to use LauePy is by running

python src/lauepy_scripts/gui.py

Note: The path must be relative to the toplevel LauePy directory for the submodules to import properly.

Each tab on the application window has a list of parameters which are linked to a configuration file. When the app is first opened, it loads an example configuration from lauepy/config_example/config.yml. Changes made to the configuration are automatically saved when any command is run.

The following sections describe each tab in the application. They also include descriptions of each editable parameter, along with their corresponding name in the config.yml file.

General Parameters

The "General" tab defines the experiment. Editing any of the first four parameters (and saving) will prompt LauePy to create a new working directory containing your config.yml file. The working directory, data, and spec file are located based on the conventions used at APS beamline 34-ID-C, as well as on the parameters provided by the user:

Working directory:
/home/beams/CXDUSER/{beamline}-work/{year}/{exp_id}/Analysis/lauepy_output/scan_{scan}{alt_id}
Data directory:
/home/beams/CXDUSER/{beamline}-data/{year}/{exp_id}/AD34idcLaue_{exp_id}{spec_seq}/{exp_id}{spec_seq}_S{scan:04}
SPEC file:
/home/beams/CXDUSER/{beamline}-data/{year}/{exp_id}/{exp_id}{spec_seq}.spec

From this tab, the user can run the full set of Laue analysis routines with a single click, or proceed to the other tabs for a more step-by-step approach.

| Parameter | Config name | Description | |---------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Scan | scan | Scan number in the experiment's SPEC file | | Alternate ID | alt_id | Alternative identifier to differentiate multiple analyses of the same scan. This string will appear as a suffix to the working directory name. To leave off, enter "None". | | Year | year | Year in which the data was taken | | Experiment ID | exp_id | Working directory name for this beamtime (e.g. "LauePUP422") | | SPEC sequence | spec_seq | Differentiates between multiple SPEC files created during a single beamtime. Appears as a suffix on the SPEC file name. | | Beamline | beamline | Identifies the beamline where this experiment took place (e.g. "34idc") | | Calibration | calibration | Detector calibration filepath. Unlike other parameters, clicking on the entry field will open a load-file dialog, which must be used to locate the calibration file. | | Substrate | substrate | Chemical formula for the substrate material. Must have a corresponding file in lauepy/src/crystals. If there is no crystal file for the material used in your experiment, you will need to make one. | | Sample | sample | Chemical formula for the sample material (see above). | | Show plots | show_plots | If true, produce and save plots at various stages of analysis | | Verbose | verbose | If true, print verbose output while running |

Image prep tab

The image prep routine makes it easier to find Laue peaks. It first extracts a substrate-only image by taking a pixel-wise quantile of the image stack. This keeps only those peaks which persist through the entire image stack. All images (substrate-only included) are then passed through several filters:

A selective median filter replaces "dead" and "hot" pixels with more locally appropriate values. This filter is not modifiable.
A Gaussian filter smooths out pixel-to-pixel noise. The rolling-ball (RB) method for background subtraction (used next) is highly sensitive to this type of noise. If not removed, it will often cause the RB filter to leave much of the original background, as well as many circular artifacts.
A series of rolling-ball filters remove large-scale background features, isolating the Laue peaks as bright points on a dark background.

| Parameter | Config name | Description | |--------------------|----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Quantile filter | prep_substrate_quantile | Determines the pixel-wise quantile to use when generating a substrate-only image. Recommended value: 0.5 | | Gaussian sigma | prep_substrate_sigma <br/> prep_sample_sigma | Width used in the Gaussian pre-filter. Generally, a value below 0.5 will reduce the effectiveness of the rolling-ball filter, while a value above 1.0 will reduce the visibility of dimmer peaks. Recommended value: 0.75 | | Rolling ball radii | prep_substrate_radii <br/> prep_sample_radii | Radii used for iterative rolling-ball background subtraction. Must be given in [square brackets]. Recommended value: [45, 15, 5] |

Peak finding tab

The peak-finding routine uses skimage.feature.peak_local_max() to return the coordinates of local maxima within each image. During this process, the substrate peaks are indexed first, using the substrate-only composite image. Then a mask is generated by taking a binary dilation of the set of all pixels whose values were above the substrate peak threshold. Applying this mask to the original image stack effectively removes the substrate peaks from the data, allowing the routine to focus instead on the (typi

Lauepy

Install / Use

README