next_inactive up previous



















Contents

Overview

In the development of experimental infrastructure, software is an important element which is often overlooked. For X-ray Coherent Diffractive Imaging (CDI), in particular, computational inversion of the measured diffraction intensity is an integral part of the image reconstruction process. The proliferation of phase retrieval algorithms has created the need for common software tools which encompass all these approaches. The NADIA (Nadia's Algorithms for Diffractive Imaging Analysis) software package aims to provide a set of phase retrieval tools which are robust, efficient and available to the wider CDI community.

In this documentation, we introduce the software package, NADIA, which is able to reconstruct and simulate X-ray diffraction data for plane-wave, Fresnel, ptychographic, phase-diverse and partially coherent (both spatially and temporally) CDI. To the best of our knowledge, this is the first standard software package which includes all of these different approaches. The software allows for any choice of iterative algorithm, including customised algorithms, and also includes the 'shrinkwrap' algorithm. For Fresnel CDI, additional complex constraints on the transmission function may also be used. The software consists of a C++ library, binding to IDL and command-line tools, in addition to example code and documentation. It has been tested on the Mac, Windows and Ubuntu operating systems. It is issued under the GNU public license.

It is assumed that readers of this manual are familiar with the relevant literature describing the CDI algorithms implemented in and we will therefore not repeat this information here. Please refer to any of the reviews  for more information on CDI. We intend that this manual is used in the following ways:

This version of the software is a development (beta) version and we welcome feedback on any aspect of the software package: functionality, installation, documentation etc. Please email cxs-software@physics.unimelb.edu.au for questions or comments.


Installation Instructions

The software is available for download from the software website as either,

For Windows users who only wish to use the IDL capabilities or command-line tools we recommend downloading the Windows binary file. For all other users, we recommend downloading the source code package.

Installing from Source Code

Linux

Currently the code depends on several other libraries which will need to be installed prior to installing this package:

Ubuntu users can easily install the external packages using the synaptic package manager . The packages are named libfftw3-dev, libtiff4-dev, liblapack, and libhdf4-dev.

Next, download our source code from the website and put it into an appropriate directory. Unzip and untar the source code:

  gunzip NADIA.0.5.tar.gz 
  tar -xvvf NADIA.0.5.tar

Change into the directory NADIA and compile the source code:

  cd NADIA
  ./configure 
  make

If ./configure doesn't finish by making a set of "Makefiles", the dependent libraries probably haven't been installed correctly or ./configure does not know their location.

The result of compilation (if successful) are libraries and header files (in the /lib and /include directories) and some example programs which are ready to execute.

The source files in the examples/ directory e.g. PlanarCDI_example.c demonstrate how the libraries can be used within a user's own code. The Makefile in examples/ shows how a user's code can be compiled and the libraries linked.

Mac

  1. Install Xcode. This is a big download and you first have to register as a developer. Once installed, this is a nice text editor too.
  2. Install fink but following their instructions exactly. You can use fink like apt get on Linux to install the fftw and hdf packages. Make sure you select the correct releases of these.
  3. Get and build the fftw, libtiff and hdf packages using fink
  4. Download the source code from the website
  5. Follow the install instruction for Linux, except, replace ./configure with
      ./configure --with-fftw_inc=/sw/include --with-fftw_lib=/sw/lib CXX=''g++ -arch i386'' --with-mfhdf_inc=/sw/include --enable-checking
    
    The ``-with'' flags will tell the compiler where to look for the external packages. The CXX="g++ -arch i386" relates to your computer's architecture. This is for a late 2010 Macbook pro running 10.6, try this, if it doesn't work, try looking up the relevant information for your computer.
  6. Type make, as in the Linux instructions.

Windows with Cygwin

Cygwin provides a Linux/Unix type environment for Windows (the interface is basically a Unix style terminal). Installing the NADIA source code in this environment is very similar to installing it in Linux/Unix and (in my opinion) makes modifying and recompiling the code a bit easier than it would be in Windows otherwise. First you will need to install Cygwin. You can do this by going to http://www.cygwin.com/, scrolling to the bottom of the page and clicking on "Install or update now (using setup.exe)". Open setup.exe and follow the installation instructions. Apart from the "Package Selection" screen, used the default options. When you get to the "Package Selection" screen leave "All" on "Default" and add the additional packages by searching for them and then clicking on them:

Note that you can update the packages which are installed after you've installed Cygwin just by clicking on setup.exe again (it remembers which are installed). If you get an error during the post-installation phase (error code 128) it maybe due to a virus checker interfering with the Cygwin installation.

Install the HDF4 libraries. There is no package for this in the package manager so go to http://www.hdfgroup.org/release4/obtain.html and download their Windows binary for your system (32 or 64 bit). Unzip the file using the standard Windows tool and install to a directory without any spaces (Cygwin sometimes struggles with spaces)

Some of the HDF files are named in such a way that the NADIA cannot find them. So go in to the bin directory of your HDF install (something like c:\HDF_Group\HDF\4.2.8\bin) and create some dynamic links:

ln -sf mfhdfdll.dll libmfhdf.dll ln -sf hdfdll.dll libdf.dll ln -sf szip.dll libsz.dll

Next, download NADIA here and put it into your home directory on Cygwin
(C:\cygwin\home\your_user_name). Open Cygwin and unzip and untar the package:

$ gunzip NADIA.0.5.tar.gz 
$ tar -xvf NADIA.0.5.tar

When you type ``ls'' you should see the directory "NADIA" plus a few others. Change into the NADIA directory:

$ cd NADIA
Tell the package where your hdf and szip libraries files are located (replace the "user_name" with your cygwin user name):
$ ./configure --with-mfhdf_lib=c:/HDF_Group/HDF/4.2.8/bin --with-mfhdf_inc=c:/HDF_Group/HDF/4.2.8/include --with-sz_lib=c:/HDF_Group/HDF/4.2.8/bin --with-df_lib=c:/HDF_Group/HDF/4.2.8/bin

If you get an error, check that the paths given to configure are correct; the lib directories should have files starting with "lib" and the include directory should have files ending in ".h". If configure worked correctly, compile the libraries and examples:

$ make

Hopefully you won't get any errors and when you look in the lib/ and include/ directories you will see some files. The libraries can be useful if you ever need to create your own code (similar to the examples). The examples show how the libraries can be used.

and run one of the examples. e.g.:

$ ./PlanarCDI_example.exe

If everything is working correcting, you should see some text output (counting the iterations). If you look at this directory in the Windows browser you should see that some .ppm image files are created which give you the reconstruction image for various number of iterations.

Have a look at the code in more detail to see what's going on:

$ xemacs PlanarCDI_example.c
and edit some variables to see what happens (eg. change the reconstruction algorithm). Then recompile and rerun the example:
$ make 
$ ./PlanarCDI_example.exe
-------------

Installing from the Windows Binary

Download the package (binary file) from the main webpage. Executing the .msi file should automatically start the installation. Select which directory you want the files to be installed in (if it is not your own machine you probably won't have permission to install into ``Program Files''). Once installed you can start using the library and command line executable files. Look at the README file which comes with the distribution to find out more.

To uninstall, go to "Control Panel", go to "Add/Remove program", find NADIA and remove it.


Tutorial for Getting Started

For Users on Osiris

Note: this section is only applicable to users who are members of the ARC Centre of Excellence in Coherent X-ray Science (CXS).

If you want to quickly use the software without the hassle of installing many packages, the simplest way is by logging into Osiris and using it there. This will also be useful to know how to do in the long run because the computing power available there is more than your laptop/desktop. The first step is to ask for an account on OSIRIS if you don't already have one (and are a member of CXS). Then follow the steps below for logging in, and for setting up and running the software.

Logging into Osiris from a Linux/Unix/Mac Machine

Open a terminal and type:

  ssh -X11 -2 osiris.ph.unimelb.edu.au
The "-X11 -2" enables you to view graphics on osiris.

Logging into Osiris from Windows

On Windows, you will need to install an ssh client. Many people (including me) recommend the program putty  for this. After you install it, test it works by logging into osiris:

  1. Open putty
  2. In the host name field type "@osiris.ph.unimelb.edu.au"
  3. Make sure the connection type is set to "ssh"
  4. Save these setting by typing in a saved session name. e.g "osiris", and clicking on "Save". Next time you open putty you can load these setting by clicking on "osiris" and then "Load".
  5. Now click on "Open". A terminal should open with a prompt asking for you password. After you enter it correctly you are logged into osiris.
  6. End your session by typing "exit"

You are now half way there. You can log in, but you won't be able to view any images which are stored on osiris yet. To be able to do this, you need to install an X-windows server (graphical information can be passed back to your computer once you have this). I found Xming  to be good. I installed it with the default options ("normal Putty").

I also found that I need to install Xming-fonts in order for the "emacs" text editor to display fonts correctly. During the set-up I ticked all the boxes so that all the fonts were installed.

Now, each time you want to log into osiris you will need to run Xming first. It will run in the background, so all you'll see when it's running is a small icon on the tool bar. You can close it once you've finished with your putty session.

Finally go into putty again, and load your "osiris" session.

  1. Configure it for X windows by clicking on "SSH" under "Connection" in the tree on the left hand side of the screen.
  2. Click on "X11"
  3. On the right hand side of the screen click on "Enable X11 forwarding".
  4. Click on "session" in the left-hand tree.
  5. And save these settings.
  6. You are now ready to test it. Click on "Open" and log in. Type "emacs test" and a window should pop up. Don't worry too much about what this is for now. Close the window and you are ready to start.


Setting up your environment on Osiris

Once you have successfully logged in, append your PATH variable to the directory where the NADIA programs are located. This can be done by typing:
  export PATH=$PATH:/data/DIXE/dixe/tags/rel_0.5/NADIA/bin

You now have available all of the command line tools listed here. Note that this will only work for your current session on osiris. To make it permanent, open the file ".bash_profile" in your home area:

  emacs .bash_profile
Add the line above to the end of the file, save and then close it (use the menu or type "xs" followed by "xc" while holding down the Ctrl key).

If you plan to work with IDL you will also need to update your LD_LIBRARY_PATH with the wrapper library path:

  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/data/DIXE/dixe/tags/rel_0.5/NADIA/interfaces/idl/
and update the IDL_PATH with the IDL module location:
  export IDL_PATH="${IDL_PATH}:\:/data/DIXE/dixe/tags/rel_0.5/NADIA/interfaces/idl/"

Running the Commandline Tool

The simplest way to run reconstruction is to use the CDI_reconstruction.exe command line tool. It takes three arguements as input:

If you don't give the seed value, "0" is used as the default, and if you don't give the reconstuction type, "planar" is assumed.

Test out the program by running it with one of the example configuration files:

   ./CDI_reconstruction.exe planar_example.config
You should see output telling you the iteration number and the error. The error is a measure of the difference between the diffraction data and the reconstructed diffraction (the usual chi squared given in the literature). You can kill the process at any time by typing Ctrl-C or you can wait for it to finish if you prefer.

Now look into the configuration file by typing:

   emacs planar_example.config
You can see that the data and support file names are given. Type:
   gthumb image_files/planar_support.tiff
to view the support. The data file can't be viewed with gthumb because it's in binary format, however you can convert it to a .ppm file using one of the other command line tools and then view it:
   dbin2ppm.exe image_files/planar_data.dbin planar_data.ppm 1024 1024 
   gthumb planar_data.ppm

The CDI_reconstruction.exe program outputs a .ppm file of the current magnitude of the estimated exit surface wave every 40 iterations. Type ``ls'' again to see a list of these files (they should look something like planar_x.ppm, where x is the iteration number). View them using gthumb. The reconstruction is slowly converging. Note that it may not completely converge as the number of iterations performed in this example is a lot less than usually used. The exit surface wave of the final iteration is saved as a complex binary file (with the file extension .cplx). You can view the magnitude and phase of the wave, by using the cplx2ppm.exe command, followed by the gthumb command. You can also use this file as the starting point for another reconstruction (see planar_example.config for instructions).

Now, try editing the configuration file:

   emacs planar_example.config
e.g. with a different combination of reconstuction algorithms, a different output rate, support file or shrink-wrap parameters etc. and see what happends.

A similar example exists for the Fresnel case. This can be run by first reconstructing the white field using 3-plane propogation:

   ./CDI_reconstruction.exe fresnel_example.config fresnel_wf
Then reconstruct the sample:
   ./CDI_reconstruction.exe fresnel_example.config fresnel

Using the C/C++ Library

The command line tools are useful to get started quickly, but if you want full flexibility with the code, it's best to learn a little bit of "c" and examples are provided for this as well. The same reconstruction as planar.config performs can be done using PlanarCDI_example.c. Compile this code using the Makefile:

   make
Now when you type ls you should see a filenamed PlanarCDI_example.exe. Run this.
   ./PlanarCDI_example.exe
You should find it gives almost exactly the same output as the CDI_reconstuction program did. Have a look at the source code: emacs PlanarCDI_example.c edit it and recompile using make to see what happens. Similarly, have a look at and Fresnel example: FresnelCDI_WF_example.c and FresnelCDI_example.c, and a simulation of the object from the planar example: PlanarCDI_simulation_example.c.

Later, if you write your own "c" code, it's easy to compile and link it with the libraries using the "Makefile" from the examples directory. Edit the "EXAMPLE_SRC" variable in the Makefile with the name of your ".c" file, then type "make" on the command line to compile it.

Using the Library in IDL

Some IDL wrappers have been written for the C++ library functions. This is useful for people who are more familiar with IDL than C, or want to take advantage of the graphing abilities of IDL. It will give greater flexibility than the command line program but doesn't allow you to use all the features of the C++ library.

Begin by copying the IDL examples to your working directory,

   cp /data/DIXE/dixe/tags/rel_0.5/NADIA/interfaces/idl/*_example.pro ./
and run them:
   idl planar_example.pro

Look at the .pro files to see what they do.

After Installing from Source

Open a terminal and follow the instruction given for ``Users on Osiris'', from Section 3.1.3 onwards. Replace the path to the software on osiris, ``/data/DIXE/dixe/tags/rel_0.5/NADIA/'' in the instructions, with the path where you installed the software.

After Installing from the Window's Binary

The software doesn't have a flash graphical user interface, but rather is a library and set of files which can be used to performing image reconstruction through various means: IDL, C++ and command lines tools. Brief instructions for how to get started for each of these options is described below.

IDL

If you have IDL installed, you can import the library routines by simply executing:
   .Compile NADIA_interface.pro
in IDL. Documentation for each of the routines can be found in Appendix B and on the website and examples are provided in the examples subdirectory of this distribution.

To run the IDL examples:

Command Line Tools

Some command line tools are provided for image reconstruction and for converting between different image file formats. The image reconstruction tool (CDI_reconstruction.exe) is not very flexible (for example it doesn't allow simulation to be carried out). So in general the IDL option is recommended. However, it does not require any extra software to be installed, for example IDL or mingw, so maybe useful, to quickly demonstrate the concepts of the algorithms to new users.

To use:

A description of each of the command line tools can be found in Appendix C.

C/C++

If you wish to run the software using C++ you should either be familiar with C/C++ or be willing to invest a bit of time to understand how to compile and write this type of code. For this reason it's not advised that a beginner attempts to run the C++ examples under Windows (unless in Cygwin). However, the benefit of using C/C++ is that it is more powerful and you will have greater flexibility with the software library. If your reconstruction requires a lot of computing power (for example you plan on run on osiris or similar, rather than a desktop), this is the best option in our opinion.

Five examples showing how to write c code using the NADIA software for CDI reconstruction and simulation are given in the ``examples'' directory. The header files for the NADIA software project can be found in the "include" directory and the libraries in the "bin" (libraries which the NADIA software depends on are also provided in this directory.

We will leave the details of how to compile in Windows to the users, as this will be compiler and system dependant. However, we do recommend compiling under mingw  with msys  because it is free; the code provided here was compiled with it, so I know it works; and because compilation is similar to linux/unix meaning you will be better trained for compiling on osiris or similar if the need arises.

Examples and Demos

The package consits of a set of examples which demonstrate how to use the library and tools of the software package for various reconstructions and simulations. Most are located in the examples subdirectory of the package.

The examples should be compiled automatically after installation (Section 2). To recompile (e.g. after making modifications to the examples), you may type "make" in the examples directory. To force a recompilation type "make clobber" followed by "make".

PlanarCDI_example.c
-
Reconstruction of plane-wave diffraction data (data from L. Whitehead ). The shrinkwrap algorithm is used to improve the reconstruction. A combination of the hybrid input-out (HIO) and the error-reduction (ER) algorithms are used.

PlanarCDI_example.sh
-
The same reconstruction as above will be performed using the CDI_reconstruction.exe command line program. A simple bash script and configuration file (planar_example.config and fresnel_example.config) shows how this tool can be used. Parts of the bash script can be uncommented to run Fresnel reconstruction or to run multiple times with a different starting seed.

PlanarCDI_simulation_example.c
-
An image of a sample (from L. Whitehead ) is used to simulate a diffraction pattern for planar CDI. The diffraction pattern is thresholded to make it more realistic and then CDI reconstruction is performed.

FresnelCDI_WF_example.c
-
This example demonstrates how the phase of a white field can be recovered and saved for use in Fresnel CDI reconstruction. The data set comes from C. Putkunz.

FresnelCDI_example.c
-
The result of the previous example is used in Fresnel CDI reconstruction. The error-reduction algorithm is used. The phase and magnitude of the transmission function are output to file.

FresnelCDI_simulation_example.c
-
This examples demonstrates how a Fresnel experiment can be simulated. It makes use of the object from the planar example and the white-field from the fresnel example. Because it uses the fresnel white-field reconstructed from data, you will need to run FresnelCDI_WF_example.exe first.

ComplexConstraint_example.c
-
This example builds on the Fresnel examples by demonstrating how complex and other constraints on the transmission function can be included in a reconstruction.

PhaseDiverse_example.c
-
This example shows how phase-diverse/ptychographic reconstruction can be performed. The example uses data from C. Putkunz which can be found on osiris at /data/cputkunz/phase_diverse_cdi/example_data.tar.gz It consists of 7 Fresnel diffraction images of the same object. For each image, the sample position is altered with respect to the focal point positions and/or transverse to the beam direction.

IDL examples
-
Examples for performing planar, Fresnel and phase-diverse/ptychographic reconstruction in IDL can be found in the directory NADIA/interfaces/idl, with the filenames planar_example.pro, fresnel_example.pro and phase_diverse_example.pro.


How Tos

In this section, we describe how a number of common tasks can be achieved using the software. More detail of the functionality available can be found in the doxygen documentation () and IDL routine documentation ().

In IDL

[language=IDL]
                            data = NADIA_READ_PPM(1024, 1024, 'data_file.ppm')
etc. or use one of IDLs built in libraries to get the input in matrix form.

<3> The reconstruction code must be initialised for either plane-wave, Fresnel white-field, Fresnel or phase diverse reconstruction.

In C++

[language=C++]
                            //Create a complex 2D field which will
                            //hold the result of the reconstruction.
                            Complex_2D object_estimate(nx,ny);
                            
                            //Create the planar CDI object which will
                            //be used to perform the reconstruction.
                            PlanarCDI planar(object_estimate);
                            
                            //set the support and intensity
                            planar.set_support(support,false);
                            planar.set_intensity(data);
In IDL
[language=IDL]
                                NADIA_INIT_PLANAR, data, support

Data Input/Output and Preparation

Read Image Files

The software is capable of accepting data in hdf, tiff or ppm image format. It can output as a grey scale tiff or ppm image with X bytes per pixel. In addition data can be read and stored as a binary file of doubles. This may be useful in situations where high prescision is required. Similarly, two dimensional arrays of complex numbers, such as those produced in the reconstruction, may be stored as a binary file of fftw  complex number types.

In C++

[language=C++]
  //read in the data
  Double_2D data;
  read_image(``data_file_name.tiff'', data);
  
  //read in the support shape
  Double_2D support;
  read_image(``support_file_name.tiff'', support);

In IDL

[language=IDL]
   data = NADIA_READ_PPM(1024, 1024, 'data_file.ppm')
etc. or use one of IDLs built in libraries to get the input in matrix form.


Write Image Files

Save the result to file.

In C++

[language=C++]
  //write out the result:
  // - as a complex binary file
  write_cplx(temp_str.str(),object_estimate);
  // - just the magnitude as an image
  Double_2D object_mag;
  object_estimate.get_2d(MAG,object_mag);
  write_image("mag.tiff",object_mag);

In IDL

[language=IDL]
  ; Record the complex field to a binary file
  NADIA_WRITE_CPLX, result, 'result_file.cplx'
The magnitude and phase of the complex matrix can be viewed and saved using the standard IDL routines.

Convert between different file formats

Output Data on a Log Scale

Subtract the darkfield

Merge (add or average) data files together

Determine the normalisation of the white-field to data

Get the autocorrelation function

Perform Reconstruction


Perform Plane-wave, Frensel and Fresnel White-Field Reconstruction

Whether it is performed in C++ or IDL, a plane-wave, Frensel and Fresnel white-field reconstruction consists of the following basic steps:

  1. Load input data - Functions are provided for reading and writing to various image formats. More information on this step is given in Section [*].

  2. Initialise the reconstruction library - Whether you are performing plane-wave, Fresnel or Phase-diverse/Ptycographic reconstruction, you must initialise the library with a number of input: the diffraction and support data, initial estimate, and parameters which describe the experimental set-up. Please refer to Sections [*] for specific instructions.

  3. Iterate - At this stage the iterative algorithms developed by [#!cite!#]are run. In the software library, an iteration can be performed simply by calling one function:

    In C++

    [language=C++]
            planar.iterate();
    

    In IDL

    [language=IDL]
            ; Perform one iteration. The exit-
            ; surface-wave is return to 'result'  
            result = NADIA_ITERATE()
            
            ; Perform 50 iterations
            result = NADIA_ITERATE(50)
    

    Various aspects of the reconstruction can be controlled, for example, the algorithm, the relaxation parameter and the shrinkwrap algorithm. How this can be achieve with the software is described in this section.

  4. Save the result - Refer to Section [*].


Perform Phase-Diverse/Ptychographic Reconstruction

Select the algorithm

By default plane-wave CDI uses the ... algorithm and Fresnel CDI uses the ... algorithm. This can be easily changed at any point in the reconstruction using the method

void PlanarCDI::set_algorithm(int alg)
Where the algorithm options are:
ER - error reduction
BIO - basic input-output
BOO - basic output-output
HIO - hybrid input-output
DM - difference map
SF - solvent-flipping
ASR - averaged successive reflections
HPR - hybrid projection reflection
RAAR - relaxed averaged alternating reflectors

For example, if you have an object of type FresnelCDI called ``fcdi'', and you wish to change the algorithm to HIO:

fcdi.set_algorithm(HIO)

In addition to this extensive list, custom algorithms can be used. Iterative reconstruction algorithms can be expressed as a combination of the following 5 operators: , , , and Where is the support projection and is the intensity projection. These can be combined to form a basis of 10 vectors (see Harray's review). The parameters to this method set the coefficient for each of these vectors. Note: the vector set is linearly dependant.

Please see page 22 of the H.M. Quiney review: TUTORIAL REVIEW, Coherent diffractive imaging using short wavelength light sources, Journal of Modern Optics, 2010, DOI: 10.1080/09500340.2010.495459

void Planar::set_custom_algorithm (double m1,
double 	m2,
double 	m3,
double 	m4,
double 	m5,
double 	m6,
double 	m7,
double 	m8,
double 	m9,
double 	m10	 
)

Parameters: m1 Coefficient to the term m2 Coefficient to the term m3 Coefficient to the term m4 Coefficient to the term m5 Coefficient to the term m6 Coefficient to the term m7 Coefficient to the term m8 Coefficient to the term m9 Coefficient to the term m10 Coefficient to the term

In IDL, the routine ... can be called to select the algorithm.

Update the support or use the shrink-wrap algorithm

Stop a reconstuction, save the result and restart at the same place

Modify the reconstruction algorithm by adding a new constraint

Refine the experimental parameters during reconstuction

Nominate a beam-stop area in plane-wave reconstruction

Perform a Simulation

Installation Options

Select Single or Double Precision

Compile the IDL wrapper

Performance

In designing the code we have tried to find a good balance between optimising the speed, reducing the memory used, and keeping the code modulare and simple to read. There is always room to improve the performance and we provide the figures below as a benchmark of the current state of the software in version . These values are independante of whether C/C++, IDL or the command-line tools are used.

Speed


Table 1: Iterations performed per second for a 10241#1 1024 pixel reconstruction. For phase-diverse/ptychography reconstruction, X is the number of iterations which could be perform for a single frame, non-phase-diverse/ptychography reconstruction of that type (i.e. from the first five rows of the table). The start-up time is a few seconds in each case.
  Iteration per Second
  Laptop Desktop
  Intel U2500 @ 1.20GHz i7-2600 CPU @ 3.40GHz
  1.5 GB memory 8 GB memory
PlanarCDI (ER) 3.3 16
PlanarCDI (HIO) 2.7 13
FresnelCDI - white field 2.0 7
FresnelCDI 2.7 10
FresnelCDI with Complex Constraints 1.8 7
Phase-Diverse/Ptychography (X-0.6)/N (X-2)/N
     


Memory

By default the fast fourier transform library used with is single precision. We found no noticible lose in performance or correctness by using single precision, however users may choose to use double precision fast fourier transforms by adding the flag ``-enable-double-precision'' to ``./configure'' during installation. The class Double_2D, despite its name, will also use the same precision as the fourier transform library and is single precision by default.


Table: The memory used. In total the memory used will be the factor given in the second coloumn of Figure 2 multiplied by pN2#2 . (N - image side length in pixels, p - precision in bytes, c - number of complex constraint regions, I - number of images, R - ratio of the total phase-diverse image size to a single N1#1 N image, X - number of arrays needed for a single reconstruction).
  Number of N1#1 N With p=4, N=1024
  pixel arrays used (MB)
PlanarCDI (ER) 4 17
PlanarCDI (HIO) 10 42
FresnelCDI - white field 4.5 19
FresnelCDI 8.5 36
FresnelCDI with complex constraints 11.5+c 57 (c=2)
Phase-Diverse/Ptychography I(1+X) + 2R 30,000 (I=400,M = 11002#2 ,
    X = FresnelCDI)
     


Directory Structure

NADIA/ ...... base directory, where ./configure and make should be executed from.
bin/ ...... contains the command-line tool executable files after compilation.
doc/ ...... contains configuration files for doxygen.
manual/ ...... contains the latex source for the software manual (this file).
examples/ ...... this directory stores all the examples.
image_files/ ...... stores images and data files used in the examples.
include/ ...... contains the source header files after compilation.
interfaces/ ...... a directory for wrapper code to languages other than C/C++.
idl/ ...... contains all IDL related code (source and examples).
lib/ ...... contains the static and dynamic C++ library after compilation.
src/ ...... a directory for the library source code.
tools/ ...... contains the source code for the command-line tools.

C++ Class Description

For the sake of advanced users we provide a description of the software library structure in this section. Figure 1 shows the relationship between the non-I/O class of the software, and lists the public member functions.

The reconstruction classes PlanarCDI, FresnelCDI and FresnelCDI_WF (shows in the shaded region of Figure 1, all inherit from the abstract base class, BaseCDI. Common functionality, for example the definition of the reconstruction algorithms is provided in BaseCDI. The reconstruction type PhaseDiverseCDI, which is capable of performing phase-diverse and ptycographic reconstruction accepts multiple objects of type BaseCDI.

Figure: The relationship between classes of the package.
3#3

BaseCDI

The fundamental class used for performing CDI reconstruction; an object of type "BaseCDI" allows planar CDI to be performed, and it is also used by the Fresnel reconstruction code (through inheritance). The reconstruction can be performed in the following way:

For cases where the beam-stop region must be excluded during reconstruction, you should call the set_beam_stop() method, to define the beam-stop region before running iterate().

PlanarCDI

FresnelCDI

The class used for performing Fresnel CDI reconstruction (for white-field reconstruction see FresnelCDI_WF). It inherits most methods from BaseCDI, so please look at the documentation of this class also. Although there are some differences in the underlying code between this class and the planar case, the interface is generally unchanged. Therefore users should refer to the instructions for BaseCDI to understand how to use a FresnelCDI object in their own code. Only the differences relevant to users will be documented here.

FresnelCDI_WF

This is the class used for reconstructing white-field data prior to running Fresnel reconstruction with FresnelCDI. It inherits most methods from BaseCDI, so please look at the documentation of this class also. Although there are some differences in the underlying code between this class and the planar case, the interface is generally unchanged. Therefore users should refer to the instructions for BaseCDI to understand how to use a FresnelCDI_WF object in their own code. Only the differences relevant to users will be documented here.

PhaseDiverseCDI

This class can be used to perform phase diverse or ptychographic reconstruction of either Fresnel or plane-wave CDI data. Any number of frames (also called local/single frames or probes in this documentation) may be added to the reconstruction. In order to perform a reconstruction, you will need to create either a new FresnelCDI or PlanarCDI object for each of these 'local' datasets. The FresnelCDI or PlanarCDI objects must then be passed to a PhaseDiverseCDI object. Because the each sub-iteration (ie. each iteration of a local frame) is performed using the code in FresnelCDI/PlanarCDI, all the functionality available in these classes is also available here. For example complex constraint can be set, shrink-wrap can be used, the estimate can be initialised using the results from a previous reconstruction etc. An example can be found in the /examples directory, demonstrating how to use PhaseDiverseCDI.

The displacement in position between 'local' frames may be either transverse to the beam direction, or longitudinal, along the beam direction. The longitudinal position (for FresnelCDI) is set when the FresnelCDI objects are initially constructed. Transverse positions are set when the FresnelCDI/PlanarCDI objects are added to the PhaseDiverseCDI object. This class allows the transverse positions to be automatically adjusted during reconstruction using the "adjust_positions" function.

The code allows for several options in the type of reconstruction which is done:

TransmissionConstraint

This class allows constraints on the transmission function (FresnelCDI) or exit-surface-wave (PlanarCDI), such as complex constraints to be used. To achieve this the user needs to: create an instance of this class configure it (for example by setting some ComplexConstraint objects and finally by passing this object to the reconstruction (through the PlanarCDI or FresnelCDI function "set_complex_constraint").

ComplexConstraint

This class is based on the paper "Use of a complex constraint in coherent diffractive imaging", J. N. Clark et. al., 2010. The notation used there is also used here. Users should have knowledge of this or similar papers before using this class.

A section of the reconstructed transmission function will be updated according to a restriction on the value of c (c = beta/delta). If the material is of a known element, then c can be fixed to the know value, and the phase and magnitude of the transmission function updated accordingly. Alternatively, c can be left to float, and calculated for each iteration from a mean over the defined region. The parameters alpha1 and alpha2 are used to control the strength of the constraint.

Instances of this class should be pass to a TransmissionConstraint object. If a sample consists of different regions which are locally homogeneous in element, multiple instances of this class should be created, each one defining a different region of the sample, and then each should be added to the TransmissionConstraint object.

Double_2D

This class represents a 2D field of doubles. Setter and getter methods are provided along with some other useful functions. This is a convenient form to store and pass image data in the reconstruction software. A better implementation of this class would use templates, but restricting the type to double is sufficient our needs.

Complex_2D

This class represents a 2D complex field. Setter and getter methods are provided along with some other useful functions (add, multiplying and fast Fourier transforming). Complex_2D objects are used in the CDI reconstruction to represent the ESW in a single plane.

Config

This class allows simple text files to be read and is used by the command line tool programs. The parser takes a file name and constructs key-value pairs for each line with the syntax:
key = value or
key = value_1 value_2 value_3 ...
White spaces are ignored and everything to the right of a "#" symbol is also ignored (this allows comments to be included in the config file. See example.config to see how it looks. If a key (as given by any of the methods below) is not found in the file, the status is set to FAILURE and the method returns either 0, an empty string or list.


IDL Routine Descriptions

The complete list of IDL routines provided with release 0.5 of the DIXE software is described below. This documentation can also be found on the project website and will be updated with new releases of the software.

13#13

Command-Line Tools

License

Copyright (C) 2011 The ARC Centre of Excellence in Coherent X-ray Science.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see COPYING). If not, see <http://www.gnu.org/licenses/>.

We also ask that you cite this software in publications where you made use of it for any part of the data analysis.


next_inactive up previous
TMir Danger Julius 2013-08-01