PyNX: Python tools for Nano-structures Xtallography


PyNX stands for Python tools for Nano-structures Xtallography. It can be used for:

  • Coherent X-ray imaging simulation and analysis: coherent diffraction imaging (CDI), Ptychography, Wavefront propagation,…
  • Fast scattering calculations from large number of atoms and reciprocal space positions.

PyNX is fully optimised to use Graphical Processing Units, using either CUDA or OpenCL, to provide fast calculations with 1 to 3 orders of magnitude speedup compared to standard processor calculations.

PyNX scripts

PyNX can be used simply with command-line scripts for some applications (2D/3D CDI and 2D Ptychography). These can take generic files as input, such as CXI files (, or can analyse data directly from beamlines.

PyNX as a python toolkit

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

  1. pynx.scattering: X-ray scattering computing using graphical processing units, allowing up to 2.5x10^11 reflections/atoms/seconds (single nVidia Titan X). The sub-module``pynx.scattering.gid`` can be used for Grazing Incidence Diffraction calculations, using the Distorted Wave Born Approximation
  2. pynx.ptycho : simulation and analysis of experiments using the ptychography technique, using GPU (OpenCL). Examples are available in the pynx/Examples directory. Scripts for analysis of raw data from beamlines are also available, as well as using or producing ptychography data sets in CXI (Coherent X-ray Imaging) format.
  3. pynx.wavefront: X-ray wavefront propagation in the near, far field, or continuous (examples available at the end of Also provided are sub-modules for Fresnel propagation and simulation of the illumination from a Fresnel Zone Plate, both using OpenCL for high performance computing.
  4. pynx.cdi: Coherent Diffraction Imaging reconstruction algorithms using GPU for Coherent Diffraction Imaging, in 2D or 3D, for small-angle or Bragg diffraction data. This uses either CUDA or OpenCL, but CUDA is strongly recommended for 3D data (significant speedup).


PyNX is available from:


Version 3.X (2018-XX-XX)

Version 3.6.2 (2018-01-25)

  • Ptycho: id01 runner: add ‘livescan’ option to search for new data when analysing a given spec data file.
  • Ptycho runner: data2cxi will now export raw data, unless data2cxi=crop was used (corrected bug)
  • Use PYNX_PU environment variable to set language (CUDA/OpenCL/CPU) and/or gpu name and/or gpu rank
  • Ptycho and CDI: add CPU API (not yest accessible for ptycho runner scripts, only with new python API)

Version 3.6.1 (2017-12-19)

  • CDI runner: add roi= keyword to manually supply the region-of-interest.
  • CDI: add option to update the support based on the maximum value, instead of the average
  • CDI runner: add ‘support_post_expand’ keyword to shrink and/or expand the support by a few pixels after update
  • CDI: handle <0 observed intensities during initial scaling of object
  • CDI runner scripts: report poisson, gaussian and euclidian llk
  • CDI id01 runner script: add support for the Eiger detector
  • CDI: update examples
  • CDI runner: correctly take into account output_format keyword
  • CDI: correct some bugs with the OpenCL implementation
  • Ptycho: add operator-based python API (not yet used for command-line scripts)
  • Ptycho: add operator-based near field ptychography
  • Processing Unit API: allow to centrally select a GPU language and/or a device
  • Remove official support for Python 2.7. Now supporting Python>=3.4

Version 3.5.0 (2017-10-09)

  • CDI: use auto-correlation to estimate initial support, if none is supplied: AutoCorrelationSupport() operator
  • CDI: add runner script, allows to perform CDI analysis directly from spec and images files
  • CDI: better initial object scaling. ScaleObj operators implemented in CUDA and OpenCL
  • CDI scripts: allow rebinning input data, with different rebin values for each axis
  • CDI scripts: allow loading initial object from a file (npy, npz, mat, cxi)
  • CDI scripts: enable multiple runs
  • CDI and Wavefront Operators: enable sum of operators (experimental)
  • CDI: ML() Operator. Default nb cycles=1, allow using power (ML()**n) to change the number of cycles
  • Ptycho scripts: check for existence of CXI file if supplied.
  • Ptycho scripts: Bring object phase origin to zero if possible, before final save.
  • Ptycho scripts: add ability to export cropped data as CXI file, to save space.

Version 3.4.0 (2017-09-21)

  • CDI scripts: allow importing matlab mask files.
  • CDI scripts: if the mask is 2D and iobs 3D, apply the same mask to all frames
  • CDI scripts: handle 2D data
  • CDI: allow importing a support from a file.
  • CDI: allow to disable support update.
  • CDI: use auto-correlation to estimate initial support if none is supplied. Default threshold is 10%.
  • [Incompatible] CDI API: remove pixel_size_object and lambdaz arguments to CDI constructor

Version 3.3.4 (2017-09-14)

  • CDI: add import/export of diffraction data to/from CXI/hdf5 file format
  • CDI: add export of final phased object to CXI/hdf5 format (by default)
  • CDI: add import of mask from file
  • CDI scripts: add keywords data2cxi and output_format
  • CDI: add OpenCL version of SupportUpdate() operator
  • [BUG] For all operators, make sure Op1 * Op2 returns a new operator, to avoid altering Op1. Same for Op1**N
  • Ptycho: handle case when resized probe from previous result had an odd size.
  • [BUG] Ptycho: fix incorrect hdf5 softlink path to translation in CXI files

Version 3.3.1 (2017-07-19)

  • Ptycho: Correct probe simulation using new wavefront operator API
  • [BUG] error in CUDA context destruction

Version 3.3.0 (2017-07-19)

  • CDI, Ptycho: either CUDA or OpenCL operators are automatically loaded using e.g. ‘from cdi.operator import * ‘
  • CDI, Ptycho: automatically transfer data to/from GPU memory, using timestamps
  • Ptycho: using new wavefront operator API for Ptycho probe simulation
  • Wavefront: update examples
  • CDI: update id10 runner script
  • CDI: update examples
  • [Incompatible] FreePU(), ToPU() and FreeFromPU() operators are obsoleted

Version 3.2.2 (2017-07-04)

  • CDI: Fix CUDA ObjConvolve for 2D objects

Version 3.2.1 (2017-07-04)

  • Ptycho: Add generic handling of detector orientation and ptychography positions handling. Add correct default values for ptypy files.

Version 3.2.0 (2017-07-03)

  • CDI, wavefront: update examples using operators
  • CDI: add CUDA SupportUpdate and ObjConvolve operators
  • CDI id10 script: add the ability to use RAAR before HIO. Defaults to non-mandatory-shrinking
  • CDI: add HIO and RAAR detwin operators
  • CDI: add HIO, ER, RAAR and CF with positivity constraint
  • Ptycho: automatically adapt probe proagation range during analysis
  • Ptycho: add the ability to start from a focused circular aperture
  • Wavefront: add Thinlens, circular and rectangular mask operators
  • Wavefront: correct sign of final quadratic phase factor for FRT and Near Field propagation

See the full Changelog

Citation & Bibliography

If you use PyNX for scientific work, please consider including a citation:

  • If you use PyNX for coherent X-ray Imaging including ptychography:
  • If you use PyNX for GPU scattering calculations:
  • Cite the first PyNX article: J. Appl. Cryst. 44(2011), 635-640. A preprint version is also available on ArXiv:1010.2641
  • Give a link to the project:


The PyNX library is distributed with a CeCILL-B license (an open-source license similar to the FreeBSD one). See

Note that CPU computing of the pynx.scattering module uses the sse_mathfun.h header, which is distributed under the zlib license. See

See for more details about the license, copyright, as well as other possible issues regarding ptychography.


Installation steps
How to install PyNX using a python virtual environment

Command-line scripts

Scripts Reference
Documentation of scripts included in PyNX

API Documentation

API Reference
Documentation of modules included in PyNX

Indices and tables