Coherent Diffraction Imaging - Simulation Tools
An end-to-end Bragg Coherent Diffraction Imaging (BCDI) Python application using low computational resources with an easy to learn GUI: crystal lattice construction, X-ray scattering simulation, neural-network phase retrieval, and 3D visualization, in a single GUI.
![]() |
![]() |
![]() |
| Launcher | Material - crystal builder | Results - simulated Bragg peak |
![]() |
![]() |
![]() |
| 3D Viewer - diffraction simulation | 2D reconstruction | 3D Viewer - reconstruction |
pip install cdi-stoolsAfter installation, launch the GUI from any terminal:
cdi-st or cdi-stoolsSupport for other beamlines files is coming in future updates...
Note:
cdi-stships a Qt-based GUI. On Linux, you may need system Qt dependencies (sudo apt install libxcb-cursor0 libxkbcommon-x11-0on Ubuntu/Debian). On Windows and macOS the wheel includes everything.
Bragg Coherent Diffraction Imaging is a synchrotron technique that reconstructs the 3D shape and atomic-displacement field of nanocrystals by inverting the diffraction intensity around a Bragg peak. The intensity gives only |F(q)|², so reconstruction must recover the missing phase by iterative algorithms (HIO, RAAR, ER), more recently by neural networks.
CDI-ST integrates the entire workflow into one tool:
| Step | What you do | Where in the GUI |
|---|---|---|
| 1. Build a crystal | Define material, shape, orientation, optional defects | BCDI Simulation → Material |
| 2. Set the X-ray geometry | Beam energy, detector geometry, oversampling | BCDI Simulation → Beam |
| 3. Simulate diffraction | Compute the 3D Bragg peak | BCDI Simulation → Results |
| 4. Generate training data | Build a labeled dataset of (object, diffraction) pairs | BCDI Data Analysis → Generate Data |
| 5. Train an unsupervised NN | AutoPhase_NN: physics-driven, no ground truth | BCDI Data Analysis → AutoPhase_NN |
| 6. Train a supervised NN | CDI_NN: learning the phase mapping | BCDI Data Analysis → CDI_NN |
| 7. Reconstruct | HIO/RAAR/ER on their own, or a network seed refined by them | BCDI Data Analysis → Reconstruction |
| 8. Visualize and export | Interactive 3D viewer, ParaView VTI export | BCDI Data Analysis → 3D Viewer |
Choose from the preset materials (Al, Cu, Au, Pt, W, Fe, Si, Ge, SiC (3C and 4H), ZnO, GaN, Te, Fe3GeTe2, Fe5GeTe2) or import any CIF file. The crystal is built atom-by-atom from the unit cell, replicated to the requested supercell size.
You can:
- Select the particle shape: cube, sphere, cylinder, hexagonal prism, octahedron, dodecahedron
- Set the target oversampling ratio (controls how much of the diffraction volume the object occupies)
- Add strain fields: radial gradient, edge dislocation, random
- Add dislocations: edge / screw / mixed, at a configurable position with an arbitrary Burgers vector
The 3D lattice view (powered by Plotly) shows every atom in the supercell.
Select a reflection (h k l) from the auto-computed list of allowed peaks. The
search bounds each index separately from the geometry, so materials with a long
c axis keep their high-l reflections — (0 0 6) for Fe3GeTe2, (0 0 8) for
4H-SiC, (0 0 6) and (0 -1 10) for corundum. Typing any member of a family
finds that family, whichever member the table happens to list.
The Beam tab also lets you set:
- Beam energy (and the resulting wavelength)
- Detector geometry: pixel pitch, sample-to-detector distance, detector size
- Beam size in microns
- Detector preset: Maxipix (516×516), Eiger 2M...etc, custom rectangular
Detector preset auto-fills the geometry parameters.
CDI-ST computes the diffraction in two paths:
- Analytical path (cube/rectangular shapes, no strain): closed-form Fourier transform of the support
- FFT path (any shape, any strain field): full 3D FFT of the complex object
Output: 3D diffraction volume |F(q)|², displayed as 2D slices (qx-qy, qx-qz)
and in an interactive 3D Plotly viewer with iso-surface controls.
You can export the simulation as a .npz file ready for the data-analysis side,
or for use as ground truth when training NNs.
Generates a dataset of synthetic BCDI samples for NN training. Each sample contains the ground-truth phase, support, and the simulated diffraction intensity. You control:
- Number of samples (typically 2,000–10,000)
- Grid size (64³ recommended for training, 128³ for production inference)
- Materials (random or fixed)
- Particle size variation (random supercell multiplier)
- Random dislocations adds occasional edge/screw/mixed dislocations
- Random strain adds occasional radial/edge/random strain fields
Samples save as sample_XXXXX.npz and a manifest.json. Generation is
parallelizable and resumable.
AutoPhase_NN is a 3D dual-decoder convolutional network that learns to invert the
Fourier modulus constraint without ground truth. It predicts the object's
amplitude and phase such that |FFT(amp · exp(iφ))| matches the measured
magnitude. The loss is a normalized-magnitude error plus optional regularizers
on phase smoothness and support compactness. This is the network from (Yao, Yudong,
et al. npj Computational Materials 8.1 (2022) ) reimplemented for this codebase.
Training is GPU-accelerated (CUDA preferred) and converges in a few dozen epochs on 2,000+ samples. The best checkpoint is saved automatically.
A 3D U-Net that predicts the phase field from the diffraction magnitude, trained against the ground-truth phase from the data generator.
Use AutoPhase_NN when you don't trust your simulator's ground truth (or have none). Use CDI_NN when you have a high-fidelity simulator and want a direct mapping. Use both via the ensemble mode in the Reconstruction tab.
Load any .npz (simulated) or .h5 (experimental) BCDI file, or convert a
SPEC + EDF scan from ID01 directly via the dialog. Choose:
- HIO/RAAR/ER only — no neural network: the standard iterative algorithms from a random start. No checkpoint, no PyTorch, nothing trained - this is the option to use if you cannot run a network, and it is what most published BCDI work uses.
- AutoPhaseNet alone: one forward pass (~100 ms), with twin-image suppression and COM centering. A quick look.
- AutoPhaseNet → HIO/RAAR/ER refinement: network seed, then the classical algorithms polish it. The usual choice.
- Both networks averaged (AutoPhaseNet + PhaseUNet3D), optionally refined: averaging two independent guesses cancels some of the error each makes alone. Needs the second checkpoint.
If refinement comes out worse than the network alone, the network output is kept.
The output is a complex object (amplitude + phase), a binary support, the R-factor convergence curve, and 2D slices at the COM of the reconstruction.
For experimental data, the loader handles:
- Detector chip-gap masking (Maxipix, Eiger)
- Hot-pixel removal
- Beamstop / direct-beam streak removal
- Bragg-peak-centered cropping
- Optional q-space orthogonalization via xrayutilities (with
[id01]extra)
The viewer renders the reconstruction in three modes:
- Point cloud: every voxel above threshold, colored by amplitude / phase / strain, with per-voxel opacity weighted by intensity
- Isosurface: smoothed iso-shell with internal data points showing through
- Surface only: bare iso-mesh with edges visible
Render quality is chosen before rendering - Draft (15,000 points), Standard (60,000, the default), High (200,000) or Maximum (1,000,000). Higher settings also smooth the isosurface less, so density and strain stay distinguishable. On a 128³ reconstruction with 268,000 support voxels these take roughly 0.4 s, 0.5 s, 1.4 s and 1.4 s.
Controls:
- Threshold (% of peak amplitude), voxel size, opacity, colormap (Turbo by default)
- Color scale auto / manual (
vmin/vmax) - Clip plane on any axis
- Auto-update view: re-renders as soon as a setting changes, instead of pressing "Update view". Changes are coalesced briefly so dragging a slider does not start a render on every step.
- Mouse: left-drag rotate, right-drag pan, wheel zoom, double-click reset
- Export PNG snapshot or VTI (ParaView)
If you use CDI-ST in published research, please cite:
@software{saidi_cdi_st_2026,
author = {Saidi, Soufiane},
title = {CDI-ST: Coherent Diffraction Imaging — Simulation Tools},
year = {2026},
publisher = {GitHub},
url = {https://github.com/Refze/CDI-St}
}MIT — see LICENSE.
Soufiane SAIDI - saidisoufiane@hotmail.com
We heavily encourage you to use the in-app Reports & Suggestions button to send any type of feedback.
Built on the shoulders of the BCDI and python community: PyNX, BCDI-Utilities, cdiutils, Atomsk , xrayutilities, scikit-image, PyQt6, and the AutoPhaseNN paper by Yao et al.(2022) (https://doi.org/10.1038/s41524-022-00803-w).





