Quickstart: 5-Minute BCDI Analysis#

This quickstart guide shows you how to run a complete BCDI analysis using BcdiPipeline in a Jupyter notebook.

Prerequisites#

  • CDIutils installed with PyNX support (see Installation)

  • BCDI scan data from a supported beamline

  • Jupyter notebook environment

Minimal Working Example#

Step 1: Import and Set Parameters

import os
import cdiutils

# define experiment parameters
beamline_setup = "id01"
experiment_file_path = "/path/to/experiment/file.h5"
sample_name = "Sample_Pt"
scan = 42

# set output directory
dump_dir = os.getcwd() + f"/results/{sample_name}/S{scan}/"

# load parameters and create pipeline
params = cdiutils.pipeline.get_params_from_variables(dir(), globals())
pipeline = cdiutils.BcdiPipeline(params=params)

Step 2: Preprocess Data

# run preprocessing with optional parameter overrides
pipeline.preprocess(
    preprocess_shape=(200, 200, 200),
    voxel_reference_methods=["max", "com", "com"]
)

Step 3: Phase Retrieval

# run PyNX phase retrieval
pipeline.phase_retrieval(
    nb_run=50,
    nb_run_keep=10,
    support_threshold="0.15, 0.40"
)

Step 4: Postprocess Results

# analyse phasing results and run postprocessing
pipeline.analyse_phasing_results()
pipeline.select_best_candidates(nb_of_best_sorted_runs=5)
pipeline.mode_decomposition()

# calculate strain and displacement
pipeline.postprocess(voxel_size=5)  # 5 nm voxels

Step 5: Visualise Results

# interactive 3D visualisation
pipeline.show_3d_final_result()

# or browse phasing results interactively
pipeline.phase_retrieval_gui()

That’s it! Your results are saved in the dump_dir including:

  • CXI files with reconstruction

  • Strain and displacement maps

  • VTK files for visualisation

  • Analysis figures

Understanding the Output#

After postprocess(), access results programmatically:

# access structural properties dictionary
props = pipeline.structural_props

amplitude = props["amplitude"]  # reconstructed amplitude
support = props["support"]  # binary support mask
phase = props["phase"]  # unwrapped phase (radians)
displacement = props["displacement"]  # atomic displacement (angstroms)
het_strain = props["het_strain"]  # heterogeneous strain (%)

# voxel size in metres
voxel_size = props["voxel_size"]
print(f"Resolution: {voxel_size[0]*1e9:.2f} nm/voxel")

Next Steps#

Customise processing:

See BcdiPipeline User Guide for detailed parameter tuning

Complete notebook example:

Check bcdi_pipeline_example.ipynb

Beamline-specific examples:
Advanced workflows:

Learn about Coordinate Systems and Transformations for manual processing

Common Issues#

PyNX not found:

Install PyNX: https://pynx.esrf.fr/en/latest/install.html

Wrong detector geometry:

Verify beamline_setup matches your beamline (e.g., “id01”, “p10”, “sixs”)

Memory errors:

Reduce preprocess_shape or increase binning

Phase retrieval fails:

Adjust support_threshold (try “0.20, 0.35” range)

See Troubleshooting for more solutions.