CDIutils is a Python package to help X-ray Bragg Coherent Diffraction Imaging (BCDI) practitioners in their analysis and visualisation workflows. I developed the package during my PhD.

The package is designed to handle the three primary stages of a BCDI data processing workflow:

• Pre-processing (data centering and cropping)
• Phase retrieval: utilises PyNX for accurate phasing (refer to PyNX documentation).
• Post-processing (orthogonalisation, phase manipulation, strain computation etc.)

It is assumed that the phase retrieval is conducted using the PyNX package. The BcdiPipeline class runs all three stages and can manage connections to different machines, especially for GPU-based phase retrieval.

Some features of this package include:

• Flexibility in Hardware: While the phase retrieval stage may leverage GPUs, pre- and post-processing can be executed without GPU support.
• Utility Functions: The package provides utility functions to analyse processed data and generate plots suitable for potential publications.

For a visual wrap-up, see the associated poster presented at XTOP24:

Read the full documentation on Read the Docs

The documentation includes:

• Tutorials: Step-by-step guides for common workflows
• API Reference: Complete function and class documentation
• Examples: Jupyter notebook examples
• Installation Guide: Detailed setup instructions

Install directly from PyPI:

pip install cdiutils

Option 1: Create a new conda environment with all dependencies

# create conda environment directly from GitHub
conda env create -f https://raw.githubusercontent.com/clatlan/cdiutils/master/environment.yml

# activate the environment
conda activate cdiutils-env

# install cdiutils from PyPI
pip install cdiutils

Option 2: Install dependencies in your existing conda environment

# download and install dependencies using conda solver
conda env update -f https://raw.githubusercontent.com/clatlan/cdiutils/master/environment.yml

# install cdiutils from PyPI
pip install cdiutils

For development (includes documentation and testing tools):

# create development environment directly from GitHub
conda env create -f https://raw.githubusercontent.com/clatlan/cdiutils/master/environment-dev.yml

# activate the environment
conda activate cdiutils-dev-env

# install cdiutils in development mode (requires cloning)
git clone https://github.com/clatlan/cdiutils.git
cd cdiutils
pip install -e .

You can also install the latest development version directly from GitHub:

You can install the package directly from GitHub:

pip install git+https://github.com/clatlan/cdiutils.git

To update your environment with the latest commits:

pip install -I --no-deps git+https://github.com/clatlan/cdiutils.git

Note: Check out the dev branch for the latest features and bug fixes. The dev branch is not guaranteed to be stable.

Once the package is installed, you can try it right away using the notebook template directly accessible with the command:

prepare_bcdi_notebooks

This will generate a notebook templates in your current directory.

Once data are processed, the BcdiPipeline instance saves the data in .npz, .cxi and .vti files following the CXI file format convention (see https://www.cxidb.org/cxi.html). It also plots summary and debug figures such as:

• Summary Slice Plot
• Isosurface determination
• Different strain computation methods

If want to analyse and compare your reconstructions, check out the example notebook bcdi_reconstruction_analysis.ipynb in the examples folder. This notebook provides a comprehensive overview of the analysis process, including:

• Slice plots of any quantity you like (here phase) across different conditions:

• Reciprocal space plots in the orthogonal frame (lab frame)

• Histogram plots of any quantity you like across different conditions:

The cross section quiver is nice tool for visualising the strain and displacement fields and their relationship in BCDI data.

• The cross section quiver allows to plot cross section of strain and displacement field on the same plot.
• For different conditions

Contributions are welcome! Please feel free to submit a Pull Request.

If you encounter any issues or have questions:

1. Check the documentation for tutorials and API reference
2. Open an issue on the GitHub repository
3. Browse existing issues to see if your question has been answered