About wpg

The simulations based on wave optics have become indispensable for beamline design for highly coherent novel X-ray sources such as X-ray Free Electron Lasers (XFEL).

We present a new interactive framework package for coherent and partially coherent X-ray wavefront propagation simulations – “WaveProperGator” (WPG).

The package has been developed at European XFEL to facilitate for the end users (beamline scientists and XFEL users) the design, and optimization of X-ray optics to meet their experimental requirements. Our package uses the SRW C/C++ library and its Python binding for wavefront propagation simulations. The tool allows for changing source and optics parameters and visualizing the results interactively.

The framework is cross-platform: it runs reliably on Linux, MS Windows 7, and Mac OS X. Using IPython as a web-frontend enables users to run the code on a remote server as well as on their local personal computer. One can use popular Python libraries (such as scipy, numpy, matplotlib) for pre- and post-processing as well as for visualization of the simulation results.

The wavefronts are saved in hdf5 format for the eventual further processing and start-to-end simulations of experiments. The HDF5 format allows for keeping the calculation history within a single file, thus facilitating communication between various scientific groups, as well as cross-checking with other simulation results. The WPG source code together with guidelines for installation and application examples are available on the web.

Several application examples, specific for XFEL, will be presented.

Source code aviable at GitHub https://github.com/samoylv/WPG


If you use the WPG for your research, we would appreciate it if you would refer to the following papers:

1. Samoylova, L., Buzmakov, A., Chubar, O. & Sinn, H. WavePropaGator: Interactive framework for X-ray FEL optics design and simulations. // Journal of Applied Crystallography 08/2016; 49(4) pp. 1347-1355. DOI:10.1107/S160057671600995X http://journals.iucr.org/j/issues/2016/04/00/zd5006/index.html

Getting started



On Ubuntu Desktop

New method

Install using Conda:

Download conda installer from https://www.anaconda.com/distribution/ or install using pip

pip install conda

after that in WPG root folder:

conda create -n wpg3 -y  --file requirements.txt
conda activate wpg3

Depricated method

Install dependencies:

sudo apt-get update
sudo apt-get install -y build-essential python-dev unzip python-numpy python-matplotlib
sudo apt-get install -y python-pip python-scipy python-h5py
sudo pip install jupyter

Download sources:

wget http://github.com/samoylv/WPG/archive/develop.zip

Extract package (this will create a new directory “WPG-develop”):

unzip develop.zip

Change into the new directory:

cd WPG-develop

Build library. This will download and build FFTW2 and SRW:

make all

Start the jupyter notebook server. This should launch a new jupyter session in your web browser.

cd samples

If the notebook does not appear in a fresh web browser tab (window), direct your browoser to _`<http://localhost:8888 <http://localhost:8888>`_.

Mac OS X

Install dependencies. You should have XCode and MacPorts installed.

sudo port install py27-numpy py27-h5py py27-matplotlib

For ipython notebook:

sudo port install py27-tornado py27-zmq py27-nose py27-jinja2
py27-sphinx py27-pygments py27-readline py27-ipython py27-scipy

For wget automatic downloading:

sudo port install wget

Download sources:

wget --no-check-certificate http://github.com/samoylv/WPG/archive/develop.zip

Extract package

unzip develop.zip

Change the directory

cd WPG-develop

Build library. This will download and build FFTW2 and SRW

make all

Run jupyter notebook server:

cd samples

If you have encounter errors while running the notebook containing messages such as

ValueError: unknown locale: UTF-8

please try setting the following environment variables:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

Add these lines to your ~/.profile to make them permanent.

On xfel server

You can run the notebook server on a remote machine (e.g. a powerful cluster with heaps of memory) and connect to the server from your local machine via ssh tunnel. Do achieve this, do the following steps.

1.) Log in to the remote machine and issue the command

jupyter-notebook --no-browser --port YOUR_UNIQUE_PORT_NUMBER --notebook-dir WPG_WORKING_DIRECTORY

Here, YOUR_UNIQUE_PORT_NUMBER is the port number that the server will use to communicate to the client later. Pick a number larger than 1024.

To avoid different users use the same port number, please visit Simulation web-site to register your port number in the table.

2.) Setup ssh tunnel to the server. Leave the terminal window open from which you connected to the server and open a new terminal window. Issue the command

#If you have Linux or Mac OS X local machine, use the following command

ssh -l <your_user_name> -f -N <server_name>  -LYOUR_UNIQUE_PORT_NUMBER:localhost:YOUR_UNIQUE_PORT_NUMBER

On Windows you can use putty and setup ssh tunnel as described here: putty.pdf

Open your local browser with the following web address: http://localhost:YOUR_UNIQUE_PORT_NUMBER

On MS Windows

You should have installed python2.7 with modules numpy, matplotlib, h5py and ipython. If these modules have not been installed yet, you can download a free python bundle with preinstalled packages here

Download WPG package and unpack it.

Download Our small brunch of SRW library and unpack it in any folder.

Copy the following files from the SRW folder to WPG folder:

  • SRW-feature-srw_lite/env/work/srw_python/lib/srwlpy2_x64.pyd to WGP/wpg

Rename srwlpy2_x64.pyd to srwlpy.pyd

Run `ipython notebook ` in `WGP/samples`

If you have SRW already installed

Either add the directory SRW_Dev/env/work/srw_python to your $PYTHONPATH or copy the file srwlpy.so under that directory to WPG/wpg/.

wpg module

This module contains utils and classes for X-ray wavefront propagation.

The most propagation methods based on SRW library.