Estimate a complex object from a coherent diffraction intensity array using composable JAX phase-retrieval recipes.
Full documentation: QoraPhase.
A diffraction detector measures how bright each part of a pattern is, but not the phase of the scattered X-ray wave. Without that phase, the pattern cannot simply be Fourier-transformed into an image of the object. This is the phase-retrieval problem in coherent diffraction imaging (CDI).
QoraPhase estimates a possible object from the measured intensity. It iterates between diffraction-space measurements and real-space constraints using algorithms such as ER, HIO, RAAR, and shrinkwrap. The result is a complex-valued object: amplitude and phase. It accepts centred 2D or 3D NumPy/JAX arrays, and can run on CPU or GPU.
A reconstruction that matches the measured intensity is not automatically the correct or unique object. The synthetic example below shows what the code can do; measured-data checks remain unresolved.
A 64×64 simulated object, its noiseless intensity, and the best of 8 random
starts from qp.reconstruct(intensity, starts=8) with no support given (it is
derived from the autocorrelation and shrinkwrapped). Relative error against the
true object: 7.9e-7. Script: examples/readme_figure.py. This is a recorded synthetic example, not a new measured-data result.
Read installation, the tutorial and array conventions. Then use recipes, constraints, diagnostics and alignment/PRTF.
Manual benchmark reproduction is in genetic algorithms and low-pass progression. Read the validation limits, report index and release history before interpreting results. The documentation hub generates API reference pages from the package docstrings.
Requires Python 3.12 or later and uv:
uv init --no-workspace --python 3.12 qoraphase-demo
uv add --directory qoraphase-demo qoraphaseFor Reconstruction.plot() and figure scripts, add the optional plot extra (uv add "qoraphase[plot]" or pip install "qoraphase[plot]").
This small API check reconstructs a centred synthetic Gaussian intensity, without a data file:
$ uv run -q --directory qoraphase-demo python -c "import numpy as np; import qoraphase as qp; y,x=np.indices((32,32))-16; result=qp.reconstruct(np.exp(-(x*x+y*y)/20)); print(result.amplitude.shape)"
(32, 32)The shape confirms execution, not reconstruction accuracy. The tutorial compares with a known object. For your own data, pass a centred 2D/3D intensity array, with mask=True for unusable pixels and support=True inside the object.
- Overview, installation and tutorial.
- Array conventions, input contract and recipes.
- Diagnostics, constraints, alignment and PRTF.
- Validation and limitations, research reports, CPU performance and GPU environment.
- Manual genetic-algorithm and low-pass benchmark reproduction; results are preserved with their provenance.
- Documentation site and generated API, changelog, release history and citation.
MIT, see LICENSE.
