System requirements¶

You will need at least 8GB RAM and 20GB of disk space.

Installing Docker for example simS2E pipeline¶

You do NOT need Docker for simS2E. You only need it for running the example simS2E pipeline that we provide. Docker is a new container technology (Think of it as a light-weight virtualbox) that can be run on your choice of OS. Instructions for installation can be found here:

https://docs.docker.com/installation/

Setting up the environment for simS2E¶

You need to clone the simS2E repository from GitHub into your local directory (I will refer to this directory as /host/path):

cd /host/path
git clone https://github.com/chuckie82/simS2E.git

You now have a copy of all the files/scripts in the sub-directories needed for simS2E:

/host/path/simS2E/workflow: Directory for run scripts
/host/path/simS2E/config: Directory for configuration files
/host/path/simS2E/data: Directory for reading/saving data
/host/path/simS2E/packages: Directory for installing software packages
/host/path/simS2E/modules: Directory for module specific scripts
/host/path/simS2E/tmp: Directory for storing temporary files
/host/path/simS2E/docs: Directory for online documentation

Go to the packages directory and run setup.sh. This will build all the packages as Docker containers; 1) FAST for FEL source, 2) WPG for optics, 3) pmi_demo for radiation damage to the sample, 4) SingFEL for diffraction patterns, 5) EMC for orientation recovery, and 6) DM for phase retrieval:

cd /host/path/simS2E/packages
./setup.sh

Now you are ready to run the simulation!!!

1 ) Let’s run the FEL source simulation using FAST:

docker run -it -v /host/path/simS2E:/simS2E fast:v0.1 /bin/bash

You are now inside the Docker container running bash on Ubuntu v14.04. The FAST package is installed under /home/packages and the simS2E directory is located under /simS2E.

Go to the workflow directory and run the example. This will generate a single FEL pulse:

cd /simS2E/workflow
./runFAST

This script runs master.sh which in turn runs master_fast.sh. All the simulation configuration is defined in /simS2E/config/config_sim_example. Let’s examine the configuration file:

nano /simS2E/config/config_sim_example

NUM_FELsource_OUT=1 means output 1 instance of the FEL pulse. FELsource=ppFAST means use the FAST package. FAST simulation parameters are defined under ###### ppFAST ######.

When the simulation is complete. Exit the docker container by typing “exit” or Contrl+D. FELsource output hdf5 file will be in /host/path/simS2E/data/sim_example/FELsource. You can examine the hdf5 file by running:

h5ls -r /host/path/simS2E/data/sim_example/FELsource/FELsource_out_0000001.h5

Note that the output hdf5 names and fields conform to the specifications of the simS2E framework.

2 ) Let’s run the optics simulation using WPG:

docker run -it -v /host/path/simS2E:/simS2E wpg:v0.1 /bin/bash

You are now inside the Docker container running bash on Ubuntu v14.04. The WPG package is installed under /home/packages and the simS2E directory is located under /simS2E.

Go to the workflow directory and run the example. This will generate the FEL pulse that will hit the sample after propagating through the SPB/SFX beamline optics:

cd /simS2E/workflow
./runWPG

When the simulation is complete. Exit the docker container by typing “exit” or Contrl+D. WPG output hdf5 file will be in /host/path/simS2E/data/sim_example/prop.

3 ) Let’s run the photon matter interaction simulation using PMI_DEMO:

docker run -it -v /host/path/simS2E:/simS2E pmi_demo:v0.1 /bin/bash

You are now inside the Docker container running bash on Ubuntu v14.04. The PMI_DEMO package is installed under /home/packages and the simS2E directory is located under /simS2E. Due to the license agreement, the PMI package is not available in this example simulation and demo version is used instead.

Go to the workflow directory and run the example. This will generate the scattering factors of the sample under going radiation damage over time:

cd /simS2E/workflow
./runPMI

The pdb file that specifies the initial atom positions and scattering factors is stored under /simS2E/data/sim_example/sample/sample.h5. When the simulation is complete, exit the docker container by typing “exit” or Contrl+D. PMI_DEMO output hdf5 file will be in /host/path/simS2E/data/sim_example/pmi.

4 ) Let’s run the diffraction simulation using SingFEL:

docker run -it -v /host/path/simS2E:/simS2E singfel:v0.1 /bin/bash

You are now inside the Docker container running bash on Ubuntu v14.04. The SingFEL package is installed under /home/packages and the simS2E directory is located under /simS2E.

Go to the workflow directory and run the example. This will generate the diffraction patterns of the sample under going radiation damage over time:

cd /simS2E/workflow
./runSingFEL

Let’s open the simulation configuration file again in /simS2E/config/config_sim_example. NUM_DIFFR_OUT=100 means generate 100 time evolution diffraction patterns. In order to run a meaningful simulation, try increasing this number to 50,000. DIFFR=singfel means use the SingFEL package. SingFEL parameters are defined under ###### SingFEL ######. When the simulation is complete, exit the docker container by typing “exit” or Contrl+D. SingFEL output hdf5 file will be in /host/path/simS2E/data/sim_example/pmi.

You can examine the hdf5 file by running:

cd /host/path/s2eDocs/modules/diffr
python diagnostic_singfel.py /host/path/simS2E/data/sim_example

You should observe two matplotlib plots: 1) photon field and 2) photon count. You may need to install h5py, matplotlib and numpy to run this script.

5 ) Let’s run the orientation recovery simulation using EMC:

docker run -it -v /host/path/simS2E:/simS2E emc:v0.1 /bin/bash

You are now inside the Docker container running bash on Ubuntu v14.04. The EMC package is installed under /home/packages and the simS2E directory is located under /simS2E.

Go to the workflow directory and run the example. This will generate the 3D diffraction volume after orientation recovery. Note that EMC may take many hours to converge to a solution. On my Linux box, it takes about a day:

cd /simS2E/workflow
./runEMC

Let’s open the simulation configuration file again in /simS2E/config/config_sim_example. ORIENT=EMC specifies the EMC algorithm for orientation recovery. The EMC parameters are defined under ###### EMC ######. When the simulation is complete, exit the docker container by typing “exit” or Contrl+D. EMC output hdf5 file will be in /host/path/simS2E/data/sim_example/orient.

6 ) Let’s run the phase retrieval simulation using DM:

docker run -it -v /host/path/simS2E:/simS2E dm:v0.1 /bin/bash

###### DM ###### You are now inside the Docker container running bash on Ubuntu v14.04. The DM package is installed under /home/packages and the simS2E directory is located under /simS2E.

Go to the workflow directory and run the example. This will generate the 3D electron density.:

cd /simS2E/workflow
./runDM

Let’s open the simulation configuration file again in /simS2E/config/config_sim_example. PHASE=DM specifies the Difference Map algorithm for phase retrieval. The DM parameters are defined under ###### DM ######. When the simulation is complete. Exit the docker container by typing “exit” or Contrl+D. DM output hdf5 file will be in /host/path/simS2E/data/sim_example/phase.

Setting up Sphinx for documenting simS2E simulation¶

You need clone the simS2E repository from GitHub:

git clone https://github.com/chuckie82/start-to-end.git

The index.rst is the master ReST for your project.

You may already have sphinx installed – you can check by doing:

python -c 'import sphinx'

If that fails install the latest version with:

> sudo easy_install -U Sphinx

Let’s see if we can build our html:

make html

If you now open your favorite internet browser and type _build/html/index.html, you should see the documentation website.

To update the document on the web, just push your changes:

git add *.rst
git commit -m "Update all documents"
git push -u origin master

That’s it! Now you are ready to

Introduction¶

Documentation for FEL source simulation can be found on this page.

Data access¶

Data in archive can be exported using web browser. Initial FEL source can be downloaded from here:

FEL source web site

with authentication (xfel/desy account)

FEL source web site

If you use this dataset, please acknowledge [SALDIN99].

Output data description¶

The output data is expected in hdf5 format, and the glossary can be found below. FEL source module is responsible for writing out in the format specified below.

Diagnostic (diagnostic_felsrc.py)¶

Fig.1. Pulse irradiance XY map (number of photons per pixel), the title contains size of the pixel;

Fig.2. Pulse time structure, the title contains the pulse energy value.

Input data description¶

The input data is expected in hdf5 format, and the glossary can be found in the link below.

Diagnostic (diagnostic.py)¶

Fig.1. Pulse irradiance XY map (number of photons per pixel), the title contains size of the pixel;

Fig.2. Plot of pulse time structure before and after propagating, the title contains the propagated pulse energy value.

About WPG¶

WPG, WaveProperGator is an interactive simulation framework for coherent X-ray wavefront propagation. WPG provides intuitive interface to the SRW library. The application examples oriented on European XFEL design parameters.

Online documentation page

Input/Output data description¶

The input/output data is expected in hdf5 format, and the glossary can be found below. Photon matter interaction module is responsible for reading in and writing out in the format specified below.

Python script for HDF¶

Script on bitbucket

Input/Output data description¶

The input/output data is expected in hdf5 format, and the glossary can be found below. Coherent diffraction module is responsible for reading in and writing out in the format specified below.

Diagnostic¶

Python script displays /data/data and /data/diffr at completion of the module execution.

Scaling behaviour of SingFEL¶

Calculation time using single processor vs number of atoms is non-linear, perhaps quadratic.

Detector number of pixels: 131x131

Benzoic acid: 15 atoms Chignolin: 2484 atoms 2YBE: 3240 atoms 2NIP: 4735 atoms 4AS4: 4963 atoms

Input/Output data description¶

Test

The input/output data is expected in hdf5 format, and the glossary can be found below. Orientation determination module is responsible for reading in and writing out in the format specified below.

Diagnostics of reconstructed 3D diffraction volume¶

EMC reconstruction parameters..

Input/Output data description¶

The input/output data is expected in hdf5 format, and the glossary can be found below. Phasing module is responsible for reading in and writing out in the format specified below.