.. image:: https://readthedocs.org/projects/bcdi/badge/?version=latest
   :target: https://bcdi.readthedocs.io/en/latest/?badge=latest
   :alt: Documentation Status
.. image:: https://img.shields.io/github/actions/workflow/status/carnisj/bcdi/python-package-3.10.yml?logo=GitHub
   :alt: GitHub Workflow Status
.. image:: https://deepsource.io/gh/carnisj/bcdi.svg/?label=active+issues&show_trend=true&token=N3Z0cklmQrG8kzZOVwGJhLd9
.. image:: https://img.shields.io/pypi/pyversions/bcdi?logo=PyPI&logoColor=%23FFFF00
   :alt: PyPI - Python Version
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3257616.svg
   :target: https://doi.org/10.5281/zenodo.3257616

BCDI: tools for pre(post)-processing Bragg and forward coherent X-ray diffraction imaging data
==============================================================================================

Introduction
============

BCDI stands for *Bragg coherent X-ray diffraction imaging*. It can be used for:

* pre-processing BCDI and forward CDI data (masking aliens, detector gaps ...) before
  phase retrieval

* post-processing after phase retrieval (phase offset and phase ramp removal, averaging,
  apodization, ...)

* data analysis on diffraction data (stereographic projection, angular
  cross-correlation analysis, domain orientation fitting ...)

* data analysis on phased data (resolution calculation, statistics on the retrieved
  strain ...)

* simulation of diffraction intensity (including noise, detector gaps, displacement
  field ...)

* creating figures for publication using templates

Considering that most parts of the analysis pipeline are actually beamline-independent,
we tried to reuse as much as possible code, and leverage inheritance when it comes to
facility or beamline-dependent details.

BCDI as a python toolkit
========================

BCDI can be used as a python library with the following main modules:

1) :mod:`bcdi.algorithms`: PSF and image deconvolution using Richardson-Lucy algorithm

2) :mod:`bcdi.experiment`: definition of the experimental geometry
   (beamline, setup, detector, diffractometer...).

3) :mod:`bcdi.graph` : generation of plots using predefined templates.

4) :mod:`bcdi.postprocessing`: methods for post-processing the complex output
   of a phasing algorithm. Stereographic projection of a diffraction peak or a
   reconstructed crystal. Automatic detection of reconstructed facets and statistics on
   facet strain.

5) :mod:`bcdi.preprocessing`: methods for pre-processing the diffraction
   intensity in Bragg CDI or forward CDI geometry.

6) :mod:`bcdi.simulation`: in BCDI geometry, calculation of the diffraction intensity
   based on FFT or kinematical sum. It can include a displacement field, noise,
   detector gaps etc... In forward CDI geometry, calculation of the Bragg peak
   positions in 3D for a mesocrystal, knowing the unit cell and unit cell parameter.

7) :mod:`bcdi.utils`: generic functions about data loading, fitting functions, cropping/
   padding, image registration, validation functions ...

8) :mod:`bcdi.xcca`: X-ray cross-correlation analysis related methods

The central module is :mod:`bcdi.experiment`, which contains all setup-related
implementation. This is the place where to look at if you want to add support for a new
beamline or detector.

Acknowledgment and third party packages
=======================================

We would like to acknowledge the following packages:

* xrayutilities: (c) Dominik Kriegner, Eugen Wintersberger.
  See: J. Appl. Cryst. 46, 1162-1170 (2013).

* nxsReady: (c) Andrea Resta @ SOLEIL SIXS

* image_registration.py: original code from Xianhui Xiao @ APS Sector 2.
  See: Opt. Lett. 33, 156-158 (2008).

* Some functions were adapted from PyNX: (c) Vincent Favre-Nicolin.
  See: http://ftp.esrf.fr/pub/scisoft/PyNX/ and J. Appl. Cryst. 49, 1842-1848 (2016).

* Anton Mikhailov for the turbo colormap.
  See https://ai.googleblog.com/2019/08/turbo-improved-rainbow-colormap-for.html

The following third-party packages are required:

* numpy, scipy, scikit-image, matplotlib, pyqt5, vtk, h5py, hdf5plugin, fabio,
  silx, xrayutilities

* lmfit: for scripts performing fits

* pytest: to run the tests

* pytables: to load the devices dictionnary for SIXS data

* moviepy, `imagemagick <https://imagemagick.org>`_ or
  `ffmpeg <https://ffmpeg.org/download.html>`_ for creating movies

Download & Installation
=======================

BCDI is available from:

* the Python Package Index: ``python -m pip install bcdi``
* or on `GitHub <https://github.com/carnisj/bcdi>`_, where you will find the latest
  version:

|  - to install the main branch, type:
|    ``python -m pip install git+https://github.com/carnisj/bcdi.git``
|  - to install a specific branch, type:
|    ``python -m pip install git+https://github.com/carnisj/bcdi.git@branch_name``

Add the flag ``--upgrade`` to the commands above in order to update an existing
installation.

Note that there are issues with installing scikit-image within an Anaconda environment.
In such situation, the workaround is to create instead a virtual environment using pip.

Please send feedback in `GitHub issues <https://github.com/carnisj/bcdi/issues>`_.

Documentation
=============

The documentation is available at: https://bcdi.readthedocs.io/en/latest/

Video Documentation
===================

All talks from the bcdiHackweek 2021 are available at the following links:

* Carnis, J. - BCDI package overview: https://youtu.be/g4jkzmz8JGk

* Li, N.  - data preprocessing: https://youtu.be/D-fl19Mi7Ao

* Carnis, J. - data preprocessing interactive: https://youtu.be/ddipN43HR1w

* Dupraz, M. - data postprocessing + viz: https://youtu.be/WyDzOkJJu8c

* Carnis, J. - all that is left in the BCDI package: https://youtu.be/egh8X6iI4Nw

* Richard, M.-I. - paraview Facet analyser: https://youtu.be/RarHeUIOu08

* Carnis, J. - bcdi Facet analyser: https://youtu.be/gucQk8p3vyk

* Simonne, D. - jupyter GUI for bcdi package: https://youtu.be/9SDcGfJqiVw

Related package `Cohere <https://github.com/AdvancedPhotonSource/cohere>`_:

* Harder, R. - Cohere package overview https://youtu.be/I1YOZoxddlE

License
=======

The BCDI library is distributed with a CeCILL-B license
(an open-source license similar to the FreeBSD one).
See http://cecill.info/licences/Licence_CeCILL-B_V1-en.html

Citation & Bibliography
=======================

If you use this package for scientific work, please consider including a citation using
the following DOI: 10.5281/zenodo.3257616

This package contributed to the following peer-reviewed publications:

* Y. Y. Kim, et al. Single Alloy Nanoparticle X-Ray Imaging during a Catalytic Reaction.
  Science Advances 7 (2021). DOI: 10.1126/sciadv.abh0757

* J. Carnis, et al. Facet-dependent strain determination in electrochemically
  synthetized platinum model catalytic nanoparticles. Small 2007702 (2021).
  DOI: 10.1002/smll.202007702
  Data available at CXIDB ID182: https://www.cxidb.org/id-182.html

* J. Carnis, et al. Twinning/detwinning in an individual platinum nanocrystal during
  catalytic CO oxidation. Nature Communications 12 (1), 1-10 (2021).
  DOI: 10.1038/s41467-021-25625-0

* J. Carnis, et al. Structural Study of a Self-Assembled Gold Mesocrystal Grain by
  Coherent X-ray Diffraction Imaging. Nanoscale 13, 10425-10435 (2021).
  DOI: 10.1039/D1NR01806J
  Data available at CXIDB ID183:  https://www.cxidb.org/id-183.html

* N. Li, et al. Mapping Inversion Domain Boundaries Along Single GaN Wires with Bragg
  Coherent X-ray Imaging. ACS Nano 14, 10305–10312 (2020). DOI: 10.1021/acsnano.0c03775

* N. Li, et al. Continu-ous scanning for Bragg coherent X ray imaging.
  Sci. Rep. 10, 12760 (2020). DOI: 10.1038/s41598-020-69678-5

* J. Carnis, et al. Towards a quantitative determination of strain in Bragg Coherent
  X-ray Diffraction Imaging: artefacts and sign convention in reconstructions.
  Scientific reports 9, 17357 (2019). DOI: 10.1038/s41598-019-53774-2

* W. Hua, et al. Structural insights into the formation and voltage degradation of
  lithium- and manganese-rich layered oxides. Nat Commun 10, 5365 (2019).
  DOI: 10.1038/s41467-019-13240-z

* G. Niu, et al. Advanced coherent X-ray diffraction and electron microscopy of
  individual InP nanocrystals on Si nanotips for III-V on Si electronics and
  optoelectronics. Phys. Rev. Applied 11, 064046 (2019).
  DOI: 10.1103/PhysRevApplied.11.064046

* S. Fernández, et al. In situ structural evolution of single particle model catalysts
  under ambient pressure reaction conditions. Nanoscale 11, 331-338 (2019).
  DOI: 10.1039/c8nr08414a
