GrainRecon

GrainRecon (initial site at Univ. Grenoble Alpes) is a code package for reconstructing 3D grain map, namely grain orientations, positions and shapes, from diffraction patterns of laboratory X-ray diffraction contrast tomography (LabDCT). The code was developed by Dr. Haixing Fang while he works at CNRS SIMaP laboratory and ESRF in Grenoble, France, together with Dr. Pierre Lhuissier at SIMaP and Prof. dr. Wolfgang Ludwig at MatéIS and ESRF. This work is part of the project Advanced Laboratory X-ray Microtomography funded by the Agence Nationale de la Recherche (ANR-18-CE42-0005). The code may be continuously updated as work progresses.

Brief introduction of LabDCT

LabDCT is a novel technique for 3D grain mapping using lab X-ray source, inspired by the principle of synchrotron DCT. In LabDCT, a conical white beam illuminates a sample and diffracted beams from grains fulfilling the Bragg's condition are recorded by a 2D detector behind the sample. Each diffraction spot contains a small variation of X-ray wavelenths as incident angles are slightly different given the same {hkl} of the same grain because of the cone beam geometry. In addition, spots projected onto the detector have different magnifications in directions perpendicular and parallel to the diffraction vector. These make LabDCT rather different from synchrotron DCT.

3(4) different methods have been developed

1. 'cpu' - run on cpu cores only and does not require GPU, relatively slow. It may take ~7 days to complete a volume with 6 million voxels;
2. 'gpu_cuda_Gt' - run on NVIDIA gpu and require CUDA driver, fast and robust. More suitable for a roughly known geometry;
3. 'gpu_cuda_comp' - run on NVIDIA gpu and require CUDA driver, fast and robust. Suitable for projections with serious spot overlapping;
4. 'gpu_cuda_index_compete' - run on NVIDIA gpu and require CUDA driver, based on brute force indexing and competing completeness for assigning orientation for un-indexed voxels. However, this method has not been optimized to be robust enough yet and thus so far not recommended to use.

How to use the code? Generally, 4 steps:

1) Prepare for recontruction

• run get_spots.m for spot segmentation from LabDCT projections;
• run get_tomo_slices_create_h5.m to obtain an hdf5 file for tomo volume mask;
• run get_geometry.m to get geometry information and/or set geometry parameters manually in setup_exp.m;
• set all parameters, including sample name, output folder, recontruction parameter etc. in setup_para.m.

2) Run grain mapping

• for a fresh reconstruction, execute the function run_GrainMapping_fullvol_fun.m by assinging a correct SampleFlag.
• for an interrupted reconstruction, execute the function run_GrainMapping_fullvol_fun_continue.m to continue where it has been interrupted.
• in the output folder, files in the format of e.g. 1DS.mat, pos1.mat, SeedingIndexing1.mat will be stored and the number corresponds to the iteration number. A file of para.mat records all the parameters.

3) Merge regions and identify grains

• run GrainMapping_assemble_vol.m, it will generate a .h5 file, a .dream3d file and a .xdmf file, which you can use ParaView for 3D visualization
• Optionally, you can force this function to use the strategy of "completeness competing" to correct suspicious voxels and compute for empty voxels. By default, grains with fewer than 5 voxels or with seeding completeness lower than a threshold will be checked by this strategy.

4) Geometry fitting

• If geometry is needed to be fitted (this is usually the case with the first time grain reconstruction), run GrainMapping_geo_fit.m to fit 7 parameters, including Lsam2sou, Lsam2det, dety00, detz00, tilt_x, tilt_y and tilt_z, and even additional parameters such as P0y, P0z, RotAxisOffset.
• After geometry fitting, you may repeat steps of 2-3 to redo/refine grain mapping results.
  

All the codes have been tested executable with a Matlab version 2020a or later.

Want to generate forward simulated LabDCT spot images ?

• run forward_simu_Fe_100um_6grains.m as an example with the option to use different geometry parameters

Run on linux cluster

Examples of bash file for submitting jobs to ESRF slurm cluster:

1. go_SLURM_job_fullvol.slurm shows an example to submit a job to a cluster equipped with only CPU for reconstructing a full volume.
   
2. go_SLURM_job_subvol_array.slurm shows an example to submit a job to a cluster equipped with only CPU for reconstructing all subvolumes partitioned from a full volume.
   
3. go_SLURM_gpu_single_job.slurm shows an example to submit a job to a cluster equipped with GPU for reconstructing a full volume.
   

command example for reconstructing the sample "virtual_Fe_100um_6grains", which is available in the folder /Examples/virtual_Fe_100um_6grains/

sbatch go_SLURM_gpu_single_job.slurm

Example dataset

Three examples are available in ./Examples:

1. a virtual Fe sample containing 6 grains in a magnified geometry;
   
2. a virtual Fe sample containing 144 grains in both Laue-focusing and magnified geometries (exists only on Gitlab site);
   
3. an experimental AlCu alloy sample in a magnified geometry (exists only on Gitlab site).
   

Note

By default the code is designed for reconstructing cubic crystals. For other crystal symmetries, You may need to modify some code lines related to the crystal symmetry name.

License

This package is free to use, ditribute and adapt for non-commercial use only. See LICENSE for license rights and limitations (CC BY-NC 4.0). A mirror site is accessible here on Github.

Reference

The reconstruction algorithms and LabDCT implementation on conventional CT are presented in the following articles:
[1] H. Fang, W. Ludwig, P. Lhuissier, Reconstruction algorithms for grain mapping by laboratory X-ray diffraction contrast tomography, Journal of Applied Crystallography, 2022, 55, 1652-1663.
https://doi.org/10.1107/S1600576722010214.
[2] H. Fang, W. Ludwig, P. Lhuissier, Implementation of grain mapping by diffraction contrast tomography on a conventional laboratory tomography setup with various detectors, Journal of Applied Crystallography, 2023, 56, 810-824.
https://doi.org/10.1107/S1600576723003874.
[3] H. Fang, R. Granger, W. Ludwig, P. Lhuissier, 3D grain mapping by laboratory X-ray diffraction contrast tomography implemented on a conventional tomography setup, IOP Conference Series: Materials Science and Engineering, 2022, 1249.
https://iopscience.iop.org/article/10.1088/1757-899X/1249/1/012039/pdf.
Please cite the article if you use or get inspired by the code, algorithm or the implementation method presented here.

Know more about LabDCT or synchrotron DCT?

Read the following books and articles.

[1] Poulsen, H.F. (2004). Three-dimensional X-ray diffraction microscopy: mapping polycrystals and their dynamics, Springer, Berlin.
[2] Ludwig, W., Schmidt, S., Lauridsen, E.M. & Poulsen, H.F. (2008). J. Appl. Cryst. 41, 302-309.
[3] Ludwig, W., Reischig, P., King, A. Herbig, M., Lauridsen, E.M., Johnson, G., Marrow, T.J. & Buffière, J.Y. (2009). Rev. Sci. Instrum. 80, 033905.
[4] King, A., Reischig, P., Adrien, J. & Ludwig, W. (2013). J. Appl. Cryst. 46, 1734-1740.
[5] Van Aarle, W., Ludwig, W., King, A. & Penumadu, D. (2015). J. Appl. Cryst. 48, 334-343.
[6] Bachmann, F., Bale, H., Gueninchault, N., Holzner, C. & Lauridsen, E.M. (2019). J. Appl. Cryst. 52, 643-651.
[7] Fang, H., Juul Jensen, D. & Zhang, Y. (2020). Acta Cryst. A 76, 652-663.
[8] Fang, H., Juul Jensen, D. & Zhang, Y. (2021). IUCrJ 8, 559-573.

Contact emails: haixing.fang@esrf.fr or haixingfang868@gmail.com

Haixing Fang currently is a beamline scientist at beamline ID11 of ESRF