# SIMEX Users Manual¶

## Acknowledgements¶

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 654220

## Introduction¶

simex_platform provides a software platform for simulation of experiments at advanced laser and x-ray light sources. All aspects of a typical experiment, the photon source, light transport through optics elements in the beamline, interaction with a target or sample, scattering from the latter, photon detection, and data analysis can be modelled. A simulation can contain, one, several, or all of these parts.

As an example, consider a coherent imaging experiment using x-ray free electron laser (XFEL) radiation: A molecule, cluster, or nanocrystal is irradiated by highly brilliant, ultrashort x-ray pulses, these scatter from the sample get detected in an x-ray detector.

The x-ray photons will ionize and destroy the sample after a very short time, typically of the order of a few tens to a few hundreds of femtoseconds (1 fs = 1x10^-15 s). By using x-ray pulses that are even shorter, of the order of a few femtoseconds, this radiation damage can, at least partly, be avoided, i.e. the sample is probed before destruction. The scattered photons are registered in a area pixel detector and the scattering (diffraction) pattern can be analyzed to infer structural informaton about the sample, i.e. the 3D electron density and the position of atoms within the molecule.

simex_platforms provides scriptable python user interfaces to a number of advanced simulation codes for the various stages of the experiment: Photon Source, Photon Propagation, Photon-Matter Interaction, Photon Diffraction and Scattering, Photon Detection, and Photon Data Analysis. Additionaly, simex_platform defines data interfaces such that the involved simulation codes can “talk” to each other. E.g. output from a photon source calculation can be fed into the photon propagation simulation.

The simex_platform library is open-source, but some of the interfaced simulation codes are not. In such cases, the user has to acquire the simulation code and install on his system.

## Installation¶

### From sources¶

First obtain the source code by either cloning the repository:

$> git clone https://github.com/eucall-software/simex_platform  or by downloading and extracting the zip archive. After downloading (and extracting), switch into the top level directory: $> cd simex_platform


#### Software dependencies¶

The build process will fetch and install a number of third party libraries, such as hdf5, mpich, and boost. Resolving all dependencies for all libraries certainly goes beyond the scope of this project at the present time and has to be taken care of by the user. The following lists the minimum required software needed to build the external simulation tools:

• wget
• boost (version > 1.54) + header files
• hdf5 (version >= 1.8.4) + header files
• python2.7
• python-numpy
• python-scipy
• python-h5py
• python-cython
• python-setuptools
• python-matplotlib
• python-dill
• build-essential
• bz2 libraries (libbz2-dev)
• GSL (libgsl0-dev)
• FFTW3 (libfftw3-dev) or MKL
• lapack
• cmake
• C/C++ and Fortran compilers, e.g. gcc
• unzip

NOTE 1 (Intel(R) MKL(R)): If you want to link against Intel(R) MKL(R), make sure that the Intel(R) MKL(R) environment variables are set. This is typically done by running one of the scripts in $INTEL_HOME/bin/, where$INTEL_HOME is the root directory of the Intel(R) MKL(R) installation, e.g. /opt/intel/2015.

NOTE 2 (BOOST): Sometimes boost_mpi is not built although all libraries (default) where requested as per project.conf in the boost build directory. Append a “using mpi ;” to that file (without the quotes) to enforce building boost_mpi.

NOTE 3 (BOOST): It has been observed that newer versions of boost (>1.61), if linked against mpich, require libmpich.so.12, which might not be available on all systems, especially not completely updated clusters. Use boost.1.60 or lower if this problem occurs. You can find out by running ldd on libboost_mpi.so.

#### Building¶

The build process has three stages: configuration, building, and installing.

##### Configuration via cmake¶

This step requires a dedicated build directory. Create one, and change into it:

$> mkdir build$> cd build


Configuration is done by issuing:

$> cmake ..  Usefull cmake flags are: 1. Installation prefix: $> cmake -DCMAKE_INSTALL_PREFIX=/path/to/some/directory ..

2. Wave propagation with OpenMP:

$> cmake -DSRW_OPTIMIZED=ON ..  1. Build the documentation: $> cmake -DBUILD_DOC=ON ..

1. Developer install:

$> cmake -DCMAKE_INSTALL_PREFIX=.. ..  This is recommended for simex_platform developers. In this way, you will be able to run the unittests without having to recompile. 2. Create deb packages: $> cmake -DPACKAGE_MAKE=ON -DCMAKE_INSTALL_PREFIX=/usr ..
$> make package  Probably you will have to call cmake two times because for some unknown reason CMake creates .tgz archives in the first time. The package can then be installed system-wide along with all necessary dependencies: $> dpkg -i <package_name>
$> apt-get install -f  on another computer with Debian based OS. Simex will be installed in /usr/… , Tests are installed in /usr/share/simex/… and should be system-wide available. Calling dpkg with –instdir option allows to change installation dir. In this case simex_vars.sh should be modified manually to set paths correctly. 1. Disable/activate modules: $> #Disable all modules
$> cmake -DUSE_MODULES_DEFAULT=OFF [...]$> #Enable all modules (this is the default)
$> cmake -DUSE_MODULES_DEFAULT=ON [...]$> #Disable all moules except the one named wpg
$> cmak -DUSE_MODULES_DEFAULT=OFF -DUSE_wpg=ON [...]  ###### Troubleshooting¶ On some systems cmake fails to find the paths for some of the third party libraries like boost, armadillo etc. If this should be the case, consult the corresponding FindXXX.cmake scripts in the CMake directory and in your system’s configuration for how to help cmake find these libraries. An example for how to specify paths for boost and armadillo are given in the install.sh script that comes with the sources. ##### Building the library¶ After successful completion of cmake, just type: $> make


On machines with more than 1 CPU, compilation can be sped up with:

$> make -jN  where N is the number of CPUs to consume. An example build & installation script is provided (install.sh). It might need manual adjustment as indicated. ##### Installation¶ Finally, after make returns, install the compiled software into the installation directory: $> make install


Make sure that the user has write access to the installation directory, or use:



### Docker¶

We also provide docker images. Docker is a rather new technology, think of it as a “lightweight virtualbox”, i.e. a docker container ships all software dependencies including hardware abstraction and OS components along with the executable. To run a docker container, you first need the docker environment. Get it for your OS from https://www.docker.com/products/overview. Then, download the simex docker container using the following shell command:

docker pull yakser/simex


or:

docker pull yakser/simex:devel


The latter contains all test files.

#### Getting started¶

The docker command accepts certain parameters on the command line. Of special interest here are:

-it  -> to have interactive session and pseudo-TTY).
-v <full_path_to_source_dir/dest_dir> -> to mount data from host (should contain your script and necessary data). Several mounts are possible as well (repeat -v ...). All data that is needed should be mounted, otherwise it will be unavailable inside a Docker container.
-w -> working directory inside the container. Set it if relative paths are used in your python script.
-u <UID>:<GID> - user id and group id (not names, because they are not set in the Docker container). Container will run as root if this is omitted and mpirun will complain.

##### Examples¶
1. Run unit tests. We do not need to mount any additional folders:

$> docker run -it -u id -u:id -g -w /opt/simex_platform/Tests/python/unittest yakser/simex:devel Test.py  Some tests will fail in the moment due to known bugs in the diffraction calculator “singfel”. 1. Run some user script script.py in /home/user/somedata_and_script directory: $> docker run -it -v /home/user/somedata_and_script:/data -u id -u:id -g -w /data yakser/simex script.py


#### Updating docker container¶

To update an existing container, simply do:

$> docker pull simex  or: $> docker pull simex:devel


## Environment settings¶

simex_platform is a python library, hence python needs to be aware of its location. To this end, run the command:

$> source <install_prefix>/bin/simex_vars.sh  after installation. ## Testing¶ Testing the installation. By default, the installation also creates the unittest suite. You can switch this option off by appending the flag -DINSTALL_TESTS=OFF to the cmake command. It is advised to run the test suite to check your installation: $> cd Tests/python/unittest
$> python Test.py -v 2>&1 | tee Test.log  This will run the entire test suite and pipe the output to the file Test.log. A final test report is appended. NOTE 4 (Large Test Files): If you pulled the sources via git and encounter test failures where the test log mentions something like “hdf file could not be read”, make sure you issued a “git lfs pull” command at least once. This is not a standard git command, you have to install git-lfs (e.g. via https://git-lfs.github.com/). ## Usage¶ The intended usage scheme of simex_platform is that of a python module in either an interactive (i)python session or a python script. Hence, the first thing to do is to import the module. >>> import SimEX  A good starting point for finding examples on how to use simex_platform modules are the tests under  Tests/python/unittest/SimExTest/. Each Calculator is tested, and the test-suite PhotonExperimentSimulation/PhotonExperimentSimulationTest.py contains some simex_platform workflow examples for complete start-to-end simulations. ## Contribute¶ • Source Code github.com/eucall-software/simex_platform • Issue Tracker: github.com/eucall-software/simex_platform/issues ## Support¶ If you are having issues, please let us know at carstendotgroteatxfeldoteu . ## License¶ The project is licensed under the GPL open source license version 3. ## Reference Manual¶ module DiffractionAnalysis: Module that hosts the DiffractionAnalysis class. class SimEx.Analysis.DiffractionAnalysis.DiffractionAnalysis(input_path=None, pattern_indices=None, poissonize=True, mask=None)[source] Bases: SimEx.Analysis.AbstractAnalysis.AbstractAnalysis Class DiffractionAnalysis: Class that implements common data analysis tasks for diffraction data. Parameters: • input_path (str) – Name of file or directory that contains data to analyse. • pattern_indices (int || sequence of int || "all") – Identify which patterns to include in the analysis (default “all”). • poissonize (bool) – Whether to add Poisson noise to the integer photon numbers (default True). • mask (numpy.array) – Mask to multiply on each pattern. Example pattern_indices: pattern_indices=1 pattern_indices=[1,2,3] pattern_indices=range(1,10) pattern_indices=”all” animatePatterns(output_path=None, logscale=False, offset=0.1)[source] Make an animated gif out of the given patterns. Parameters: output_path (str) – Where to save the animated git. logscale (bool) – Whether to apply logarithmic scaling to the z axis (color). offset (float) – Offset to apply if logarithmic scaling is on. IOError – File exists or parent directory not found. mask Query the mask. patternGenerator()[source] Yield an iterator over a given pattern sequence from a diffraction file. pattern_indices Query pattern indices attribute. plotPattern(operation=None, logscale=False, offset=0.1)[source] Plot a pattern. Parameters: Note operation: operation (python function) – Operation to apply to selected patterns (default numpy.sum). logscale (bool) – Whether to plot the intensity on a logarithmic scale (z-axis) (default False). offset (float) – Offset to apply if logarithmic scaling is on. Operation must accept a 3D numpy.array as first input argument and the “axis” keyword-argument. Operation must return a 2D numpy.array. Axis will always be chosen as axis=0. numpy.mean, numpy.std, numpy.sum plotRadialProjection(operation=None, logscale=False)[source] Plot the radial projection of a pattern. Parameters: Note operation: operation (python function) – Operation to apply to selected patterns (default numpy.sum). logscale (bool) – Whether to plot the intensity on a logarithmic scale (z-axis) (default False). Operation must accept a 3D numpy.array as first input argument and the “axis” keyword-argument. Operation must return a 2D numpy.array. Axis will always be chosen as axis=0. numpy.mean, numpy.std, numpy.sum poissonize Query whether to read data with (True) or without (False) Poisson noise. statistics()[source] Get statistics of photon numbers per pattern (mean and rms) over selected patterns and plot a historgram. SimEx.Analysis.DiffractionAnalysis.diffractionParameters(path)[source] Extract beam parameters and geometry from given file or directory. Parameters: path (str) – Path to file that holds the parameters to extract. SimEx.Analysis.DiffractionAnalysis.photonStatistics(stack)[source] SimEx.Analysis.DiffractionAnalysis.plotImage(pattern, logscale=False, offset=0.1)[source] Workhorse function to plot an image Parameters: logscale (bool) – Whether to show the data on logarithmic scale (z axis) (default False). offset (float) – Offset to apply if logarithmic scaling is on. SimEx.Analysis.DiffractionAnalysis.plotRadialProjection(pattern, parameters, logscale=True, offset=1e-05)[source] Perform integration over azimuthal angle and plot as function of radius. SimEx.Analysis.DiffractionAnalysis.plotResolutionRings(parameters)[source] Show resolution rings on current plot. Parameters: parameters (dict) – Parameters needed to construct the resolution rings. module XFELPhotonAnalysis: Module that hosts the XFELPhotonAnalysis class. class SimEx.Analysis.XFELPhotonAnalysis.XFELPhotonAnalysis(input_path=None)[source] Bases: SimEx.Analysis.AbstractAnalysis.AbstractAnalysis Class XFELPhotonAnalysis: Class that implements common data analysis tasks for wavefront (radiation field) data. Parameters:input_path (str) – Name of file or directory that contains data to analyse. animate(qspace=False, logscale=False)[source] Generate an animated gif from the wavefront data. intensity Query for the intensity. plotIntensityMap(qspace=False, logscale=False)[source] Plot the integrated intensity as function of x,y or qx, qy on a colormap. Parameters: qspace (bool) – Whether to plot the reciprocal space intensity map (default False). logscale (bool) – Whether to plot the intensity on a logarithmic scale (z-axis) (default False). plotOnAxisPowerDensity(spectrum=False)[source] Method to plot the on-axis power density. Parameters: spectrum (bool) – Whether to plot the power density in energy domain (True) or time domain (False, default). plotTotalPower(spectrum=False)[source] Method to plot the total power. Parameters: spectrum (bool) – Whether to plot the power density in energy domain (True) or time domain (False, default). wavefront Query for the wavefront. SimEx.Analysis.XFELPhotonAnalysis.mask_nans(a, replacement=0.0)[source] Find nans in an array and replace. :param a: Array to mask. :type a: numpy.array Parameters: replacement (numeric) – The value to replace nans. The array of booleans indicating which values of a are nan, numpy.isnan(a) numpy.array(dtype=bool) module XMDYNPhotonMatterAnalysis: Hosting utilities to analyse and visualize photon-matter trajectories generated by XMDYN. class SimEx.Analysis.XMDYNPhotonMatterAnalysis.XMDYNPhotonMatterAnalysis(input_path=None, snapshot_indices=None, elements=None, sample_path=None)[source] Bases: SimEx.Analysis.AbstractAnalysis.AbstractAnalysis Class XMDYNPhotonMatterAnalysis: Class to encapsulate diagnostics of photon matter interaction trajectories. Parameters: • input_path (str) – Path to the data to analyze. • snapshot_indices (list) – Snapshot (indices or IDs) to analyze (Default: All). • elements (list) – Which elements to include in the analysis (Default: All). animate()[source] Generate an animation of atom trajectories and their ionization. elements Query the elements to include. input_path Query the input path. load_snapshot(snapshot_index)[source] Load snapshot data from hdf5 file into memory. load_trajectory()[source] Load the selected snapshots and extract data to analyze. number_of_snapshots()[source] Get number of valid snapshots. plot_charge()[source] Plot the average number of electrons per atom per atomic species as function of time. plot_displacement()[source] Plot the average displacement per atomic species as function of time. plot_energies()[source] Plot the evolution of MD energies over the simulation time. sample_path Query the sample path. snapshot_indices Query the snapshot indices. SimEx.Analysis.XMDYNPhotonMatterAnalysis.calculate_displacement(snapshot, r0, sample)[source] Calculate the average displacement per atomic species in a snapshot. Parameters: snapshot (dict) – The snapshot to analyze r0 (numpy.array (shape=(Natoms, 3))) – Unperturbed positions of the sample atoms. ### CHECKME: Can’t we read r0 from the sample dict? Parameters: sample (dict) – Sample data SimEx.Analysis.XMDYNPhotonMatterAnalysis.calculate_ion_charge(snapshot, sample)[source] Calculate the remaining electric charge per atomic species of a given snapshot. Parameters: snapshot (dict) – The snapshot to analyze sample (dict) – The sample data. SimEx.Analysis.XMDYNPhotonMatterAnalysis.load_sample(sample_path)[source] Load a sample file into memory. SimEx.Analysis.XMDYNPhotonMatterAnalysis.read_h5_dataset(path, dataset)[source] Read a dataset from hdf5 file. module AbstractBaseCalculator: Hosting the base class of all Calculators. class SimEx.Calculators.AbstractBaseCalculator.AbstractBaseCalculator(parameters=None, input_path=None, output_path=None)[source] Bases: SimEx.AbstractBaseClass.AbstractBaseClass Class AbstractBaseCalculator: Abstract class for all simulation calculators. Parameters: • parameters (dict || AbstractCalculatorParameters) – Parameters of the calculation (not data). • input_path (str) – Path to hdf5 file holding the input data. • output_path (str) – Path to hdf5 file for output. backengine()[source] Method to call the backengine for the calculator. To be implemented on the derived classes. classmethod dumpLoader(fname)[source] Creates calculator object from a dump file Parameters: fname – path to the dump file. Created calculator object. RuntimeError – if cannot create object. dumpToFile(fname)[source] dump class instance to file. Parameters: fname – Path to file to dump. expectedData()[source] Query for the data fields expected by this calculator. input_path Query for the input file path(s). output_path Query for the output file path(s). parameters Query for the control parameters of the calculator. providedData()[source] Query for the data fields provided by this calculator. classmethod runFromCLI()[source] Method to start calculator computations from command line. Returns: exit with status code SimEx.Calculators.AbstractBaseCalculator.checkAndSetBaseCalculator(var=None, default=None)[source] Check if passed object is an AbstractBaseCalculator instance. If non is given, set to given default. Parameters: var – The object to check. default – The default to use. Te checked photon source object. RuntimeError – if no valid BaseCalculator was given. SimEx.Calculators.AbstractBaseCalculator.checkAndSetIO(io)[source] Check the passed io path/filenames and set appropriately. SimEx.Calculators.AbstractBaseCalculator.checkAndSetParameters(parameters)[source] Utility to check if the ‘parameters’ argument is valid input. Parameters: parameters (dict or AbstractCalculatorParameters) – The parameters object to check. The checked parameters object. module AbstractPhotonAnalyzer: Module for AbstractPhotonAnalyzer class SimEx.Calculators.AbstractPhotonAnalyzer.AbstractPhotonAnalyzer(parameters=None, input_path=None, output_path=None)[source] Class AbstractPhotonAnalyzer: Abstract base class for all PhotonAnalyzers. Parameters: • parameters (dict || AbstractCalculatorParameters) – Parameters of the calculation (not data). • input_path (str) – Path to hdf5 file holding the input data. • output_path (str) – Path to hdf5 file for output. SimEx.Calculators.AbstractPhotonAnalyzer.checkAndSetPhotonAnalyzer(var=None, default=None)[source] Check if passed object is an AbstractPhotonAnalyzer instance. If non is given, set to given default. Parameters: var – The object to check. default – The default to use. The checked photon source object. RuntimeError – if no valid PhotonAnalyzer was given. module AbstractPhotonDetector: Hosts the base class for all PhotonDetectors. class SimEx.Calculators.AbstractPhotonDetector.AbstractPhotonDetector(parameters=None, input_path=None, output_path=None)[source] Class AbstractPhotonDetector: Abstract base class for all PhotonDetectors. SimEx.Calculators.AbstractPhotonDetector.checkAndSetPhotonDetector(var=None, default=None)[source] Check if passed object is an AbstractPhotonDetector instance. If non is given, set to given default. Parameters: var – The object to check. default – The default to use. The checked photon source object. RuntimeError – if no valid PhotonDetector was given. module AbstractPhotonDiffractor: Hosts the base class for all Diffractors. class SimEx.Calculators.AbstractPhotonDiffractor.AbstractPhotonDiffractor(parameters=None, input_path=None, output_path=None)[source] Abstract base class for all PhotonDiffractors. Parameters: parameters (dict || AbstractCalculatorParameters) – Parameters of the calculation (not data). input_path (str) – Path to hdf5 file holding the input data. output_path (str) – Path to hdf5 file for output. SimEx.Calculators.AbstractPhotonDiffractor.checkAndSetPhotonDiffractor(var=None, default=None)[source] Check if passed object is an AbstractPhotonDiffractor instance. If non is given, set to given default. @param var : The object to check. @param default : The default to use. @return : The checked photon source object. @throw : RuntimeError if no valid PhotonDiffractor was given. module AbstractPhotonInteractor: Hosts the base class for all PhotonInteractors. class SimEx.Calculators.AbstractPhotonInteractor.AbstractPhotonInteractor(parameters=None, input_path=None, output_path=None, sample_path=None)[source] Class AbstractPhotonInteractor: Abstract base class for all PhotonInteractors. Parameters: • parameters (dict || AbstractCalculatorParameters) – Parameters of the calculation (not data). • input_path (str) – Path to hdf5 file holding the input data. • output_path (str) – Path to hdf5 file for output. • sample_path (str) – Path to file containing the sample atom coordinates (at least atom type and cartesian coordinates). SimEx.Calculators.AbstractPhotonInteractor.checkAndSetPhotonInteractor(var=None, default=None)[source] Check if passed object is an AbstractPhotonInteractor instance. If non is given, set to given default. @param var : The object to check. @param default : The default to use. @return : The checked photon source object. @throw : RuntimeError if no valid PhotonInteractor was given. module AbstractPhotonPropagator: Module holding the AbstractPhotonPropagator abstract class. class SimEx.Calculators.AbstractPhotonPropagator.AbstractPhotonPropagator(parameters=None, input_path=None, output_path=None)[source] Class AbstractPhotonPropagator: Base class for all PhotonPropagators. Parameters: • parameters (dict || AbstractCalculatorParameters) – Parameters of the calculation (not data). • input_path (str) – Path to hdf5 file holding the input data. • output_path (str) – Path to hdf5 file for output. expectedData()[source] Return the list of expected data sets with full paths. Returns: List of strings, e.g. [‘/data/data1’, ‘/params/params1’] providedData()[source] Return the list of provided data sets with full paths. Returns: List of strings, e.g. [/data/data1, /params/params1’] SimEx.Calculators.AbstractPhotonPropagator.checkAndSetPhotonPropagator(var=None, default=None)[source] Check if passed object is an AbstractPhotonPropagator instance. If non is given, set to given default. Parameters: var – The object to check default – The default to use The checked photon source object RuntimeError – if no valid PhotonPropagator was given. module AbstractPhotonSource: Hosting the base class for all PhotonSources. class SimEx.Calculators.AbstractPhotonSource.AbstractPhotonSource(parameters=None, input_path=None, output_path=None)[source] Class AbstractPhotonSource: Abstract base class for all PhotonSources. Parameters: • parameters (dict || AbstractCalculatorParameters) – Parameters of the calculation (not data). • input_path (str) – Path to hdf5 file holding the input data. • output_path (str) – Path to hdf5 file for output. expectedData()[source] Return the list of expected data sets with full paths. Returns: List of strings, e.g. [/data/data1, /params/params1’] providedData()[source] Return the list of provided data sets with full paths. Returns: List of strings, e.g. [/data/data1, /params/params1’] SimEx.Calculators.AbstractPhotonSource.checkAndSetPhotonSource(var=None, default=None)[source] Check if passed object is an AbstractPhotonSource instance. If non is given, set to given default. Parameters: var – The object to check. default – The default to use. The checked photon source object. RuntimeError if no valid PhotonSource was given. module ComptonScatteringCalculator: Hosts the ComptonScatteringCalculator class. class SimEx.Calculators.ComptonScatteringCalculator.ComptonScatteringCalculator(parameters=None, input_path=None, output_path=None)[source] Class ComptonScatteringCalculator: Class representing a Compton scattering calculator. :param parameters : Parameters for the ComptonScatteringCalculator. :type parameters : dict Parameters: input_path (str) – Path to input data for Compton Scattering calculations (Default: ‘xrts_in.h5’). output_path (str) – Path to output data for Compton Scatteroutg calculations (Default: ‘xrts_out.h5’). backengine()[source] This method drives the backengine xrts. data Query for the field data. expectedData()[source] Query for the data expected by the Diffractor. providedData()[source] Query for the data provided by the Diffractor. saveH5()[source] SimEx.Calculators.ComptonScatteringCalculator.checkAndSetParameters(parameters)[source] Utility to check if the parameters dictionary is ok . SimEx.Calculators.ComptonScatteringCalculator.fermihalf(x, sgn)[source] Series approximation to the F_{1/2}(x) or F_{-1/2}(x) Fermi-Dirac integral. Credits: Greg von Winckel http://www.scientificpython.net/pyblog/approximate-fermi-dirac-integrals module CrystFELPhotonDiffractor: Module that holds the CrystFELPhotonDiffractor class. class SimEx.Calculators.CrystFELPhotonDiffractor.CrystFELPhotonDiffractor(parameters=None, input_path=None, output_path=None)[source] Class CrystFELPhotonDiffractor: Represents simulation of photon diffraction by crystals using CrystFEL.oattern_sim. Parameters: • parameters (CrystFELPhotonDiffractorParameters) – Parameters of the calculation (not data). • input_path (str) – Path to hdf5 file holding the input data. • output_path (str) – Path to hdf5 file for output. backengine()[source] This method drives the backengine CrystFEL.pattern_sim. computeNTasks()[source] Calculate the number of MPI tasks as function of available resources and assigned cpus per task. data Query for the field data. expectedData()[source] Query for the data expected by the Diffractor. providedData()[source] Query for the data provided by the Diffractor. saveH5()[source] Method to save the output to a file. Creates links to h5 files that all contain only one pattern. module DMPhasing: Module that holds the DMPhasing class. class SimEx.Calculators.DMPhasing.DMPhasing(parameters=None, input_path=None, output_path=None)[source] Class DMPhasing: Encapsulates photon diffraction analysis for electron density reconstruction from oriented 3D diffraction patterns. Parameters: • parameters (DMPhasingParameters instance) – Phasing parameters. • input_path (str) – Path to input data (file or directory). • output_path (str) – Path to output data (file or directory). backengine()[source] Start the actual calculation. Returns: 0 if the DM run was successful, 1 if not. data Query for the field data. Returns: The stored 3D electron density map. expectedData()[source] Query for the data expected by the Analyzer. Returns: A list of strings telling which datasets are expected to be found in the input file. providedData()[source] Query for the data provided by the Analyzer. Returns: A list of strings indicating which datasets are produced in the output data. saveH5()[source] module EMCOrientation: Module that holds the EMCOrientation class. class SimEx.Calculators.EMCOrientation.EMCOrientation(parameters=None, input_path=None, output_path=None, tmp_files_path=None, run_files_path=None)[source] Class EMCOrientation: Representing photon data analysis for orientation of 2D diffraction patterns to a 3D diffraction volume. Parameters: • parameters (EMCOrientationParameters instance) – Parameters for the EMC orientation calculator. • input_path (str) – Path to directory holding input data for EMC. • output_path (str) – Path to file where output data will be stored. • tmp_files_path (str) – Path to directory where temporary files will be stored. • run_files_path (str) – Path to directory where run data will be stored, in particular the sparse photons file ‘photons.dat’ and ‘detector.dat’. Note: If ‘run_files_path’ is an existing directory that contains data from a previous EMC run, the current run will append to the existing data. A consistency check is performed. backengine()[source] Starts EMC simulations in parallel in a subprocess data Query for the field data. expectedData()[source] Query for the data expected by the Analyzer. providedData()[source] Query for the data provided by the Analyzer. saveH5()[source] module EMCCaseGenerator: Hosting the EMCCaseGenerator class that sets up a EMC run. class SimEx.Calculators.EMCCaseGenerator.EMCCaseGenerator(runLog=None)[source] Bases: object Class EMCCaseGenerator: Encapsulates one EMC case. Parameters:runLog (str, default None (don't save log.)") – Flag that indicates where to save the runtime log. createTestScatteringGeometry()[source] ATTENTION: Untested! Contains recipe to create, diffract and show a low-pass-filtered, random particle contrast. If particle and diffraction parameters are not given, then default ones are used: particleRadius = 5.9 (num. of pixels; good results if number is x.9, where x is an integer), damping = 1.5 (larger damping=larger DeBye-Waller factor), frac = 0.5 (frac. of most intense realspace voxels forced to persist in iterative particle generation), pad = 1.8 (extra voxels to pad on 3D particle density to create support for phasing), radius = numpy.floor(particleRadius) + numpy.floor(pad) (half length of cubic volume that holds particle), size = 2*radius + 1 (length of cubic volume that holds particle). diffractTestCase(inMaxScattAngDeg=45.0, inSigma=6.0, inQminNumShannonPix=1.4302966531242025)[source] ATTENTION: Untested! Requires makeMonster() to first be called, so that particle density is created. Function diffract() needs the maximum scattering angle to the edge of the detector, the sampling rate of Shannon pixels (inSigma=6 means each Shannon pixel is sampled by roughly 6 pixels), and the central missing data region has a radius of inQminNumShannonPix (in units of Shannon pixels). Variables redefined here: z = cotangent of maximum scattering angle, sigma = sampling rate on Shannon pixels, qmax = number of pixels to edge of detector, numPixToEdge = same as qmax, detectorDist = detector-particle distance (units of detector pixels), beamstop = voxel positions of central disk of missing data on detector, detector = pixel position of 2D area detector (projected on Ewald sphere), intensities = 3D Fourier intensities of particle. makeTestParticleAndSupport(inParticleRadius=5.9, inDamping=1.5, inFrac=0.5, inPad=1.8)[source] ATTENTION: Untested! Recipe for creating random, “low-passed-filtered binary” contrast by alternating binary projection and low-pass-filter on an random, 3D array of numbers. Variables defined here: support = sphereical particle support (whose radius is less than particleRadius given), density = 3D particle contrast, supportPositions = voxel position of support used in phasing. placePixel(ii, jj, zL)[source] Gives (qx,qy,qz) position of pixels on Ewald sphere when given as input the (x,y,z)=(ii,jj,zL) position of pixel in the diffraction laboratory. The latter is measured in terms of the size of each realspace pixel. Parameters: ii (int) – Pixel index in x direction jj (int) – Pixel index in y direction zL (float) – Distance of pixel from detector in units of detector size. readGeomFromDetectorFile(fn='detector.dat')[source] Read qx,qy,qz coordinates of detector and beamstop from detector.dat. readGeomFromPhotonData(fn, thisProcess)[source] Extract detector geometry from S2E photon files. Parameters: fn (str) – Path to file to read. showDensity()[source] ATTENTION: Untested! Shows particle density as an array of sequential, equal-sized 2D sections. showDetector()[source] Shows detector pixels as points on scatter plot; could be slow for large detectors. showLogIntensity(inSection=0)[source] ATTENTION: Untested! Show a particular intensities section of Fourier intensities. Sections range from -qmax to qmax. showLogIntensitySlices()[source] ATTENTION: Untested! Shows Fourier intensities as an array of sequential, equal-sized 2D sections. Maximum intensities set to logarithm of maximum intensity in 3D Fourier volume. writeAllOuputToFile(supportFileName='support.dat', densityFileName='density.dat', detectorFileName='detector.dat', intensitiesFileName='intensity.dat')[source] ATTENTION: Untested! Convenience function for writing output Parameters: supportFileName (str, default 'support.dat') – Path to file for support data. densityFileName (str, default 'density.dat') – Path to file for density data. detectorFileName (str, default 'detector.dat') – Path to file for detector data. intensitiesFileName (str, default intensities.dat') – Path to file for intensities data. writeDensityToFile(filename='density.dat')[source] Write electron density to a file. ATTENTION: Untested! :param filename: Path to file. :type filename: str writeDetectorToFile(filename='detector.dat')[source] Writes computed detector and beamstop coordinates to output. Parameters: filename (str) – Path of file where to write the detector data. writeSparsePhotonFile(fileList, outFN, outFNH5Avg, thisProcess, numProcesses)[source] Convert dense S2E file format to sparse EMC photons.dat format. Parameters: fileList (List ot str.) – List of files to convert into one sparse photon file. outFN (str, default 'photons.dat') – Filename of sparse photon file. outFNH5Avg (str) – Filename for averaged photon file. writeSupportToFile(filename='support.dat')[source] Write the support range to a file. ATTENTION: Untested! :param filename: Path to file. :type filename: str module EstherPhotonMatterInteractor: Module that holds the EstherPhotonMatterInteractor class. class SimEx.Calculators.EstherPhotonMatterInteractor.EstherPhotonMatterInteractor(parameters=None, input_path=None, output_path=None)[source] Class EstherPhotonMatterInteractor: Class interfacing the Esther Radiation-Hydrodynamics simulation backengine. Parameters: • parameters (EstherPhotonMatterInteractorParameters) – Parameters for the EstherPhotonMatterInteractor. • input_path (str) – Path to the input data for this calculator. • output_path (str) – Path to write output data generated by this calculator to. backengine()[source] This method drives the esther backengine code. data Query for the field data. expectedData()[source] Query for the data expected by the Diffractor. providedData()[source] Query for the data provided by the Diffractor. saveH5()[source] Method to save the data to a file. module FEFFPhotonMatterInteractor: Holds the FEFFPhotonMatterInteractor class. class SimEx.Calculators.FEFFPhotonMatterInteractor.FEFFPhotonMatterInteractor(parameters=None, input_path=None, output_path=None)[source] Class FEFFPhotonMatterInteractor: Interface class for photon-matter interaction calculations using the FEFF code. Parameters: • parameters (FEFFPhotonMatterInteractorParameters) – Parameters that govern the PMI calculation. • input_path (str) – Location of data needed by the PMI calculation. • output_path (str) – Where to store the data generated by the PMI calculation. backengine()[source] This method drives the backengine code. data Query for the field data. expectedData()[source] Query for the data expected by the Interactor. path_to_executable Query the path to the feff executable. providedData()[source] Query for the data provided by the Interactor. saveH5()[source] working_directory Query the working directory module GenesisPhotonSource: Module that holds the GenesisPhotonSource class. class SimEx.Calculators.GenesisPhotonSource.GenesisPhotonSource(parameters=None, input_path=None, output_path=None)[source] Class GenesisPhotonSource: Representing a x-ray free electron laser photon source using the Genesis backengine. :param parameters : Photon source parameters. :type parameters: dict Parameters: Note input_path: input_path (str) – The path to the input data for the photon source. output_path – The path where to save output data. Accepts a native genesis beam file or openPMD conform hdf5. backengine()[source] Method to call the backengine for the calculator. To be implemented on the derived classes. data Query for the field data. saveH5()[source] module IdealPhotonDetector: Module that holds the IdealPhotonDetector class. class SimEx.Calculators.IdealPhotonDetector.IdealPhotonDetector(parameters=None, input_path=None, output_path=None)[source] Class IdealPhotonDetector: Class representing an ideal photon detector. This is just a dummy calculator that copies input data to output data. Parameters: parameters (dict) – Parameters for the Detector simulation. input_path (str) – Path to input files for the detector simulation. output_path (str) – Path where output is stored. backengine()[source] This method drives the backengine code. data Query for the field data. expectedData()[source] Query for the data expected by the Interactor. providedData()[source] Query for the data provided by the Interactor. saveH5()[source] module PlasmaXRTSCalculator: Module that holds the PlasmaXRTSCalculator class. class SimEx.Calculators.PlasmaXRTSCalculator.PlasmaXRTSCalculator(parameters=None, input_path=None, output_path=None)[source] Class PlasmaXRTSCalculator: Represents a plasma x-ray Thomson scattering calculation. Parameters: • parameters (PlasmaXRTSCalculatorParameters) – Parameters for the PlasmaXRTSCalculator. • input_path (str) – Path to the input data for this calculator. • output_path (str, default 'xrts.h5') – Where to write output data generated by this calculator. backengine()[source] This method drives the backengine xrts. data Query for the field data. expectedData()[source] Query for the data expected by the Diffractor. providedData()[source] Query for the data provided by the Diffractor. saveH5()[source] Method to save the data to a file. static_data Query for the static data. SimEx.Calculators.PlasmaXRTSCalculator.checkAndSetParameters(parameters)[source] Utility to check if the parameters dictionary is ok . Parameters: parameters (AbstractCalculatorParameters) – The parameters to check. SimEx.Calculators.PlasmaXRTSCalculator.extractDate(pattern_string, text)[source] Workhorse function to get a pattern from text using a regular expression. :param pattern_string: The regex pattern to find. :type pattern_string: str (argument to re.compile) Parameters: text (str) – The string from which to extract the date. :return The date. :rtype: float module S2EReconstruction: Module that holds the S2EReconstruction class. class SimEx.Calculators.S2EReconstruction.S2EReconstruction(parameters=None, input_path=None, output_path=None)[source] Class S2EReconstruction: Class representing photon data analysis for electron density reconstruction from 2D diffraction patterns. Wraps the EMC orientation module and the DM phasing module. Parameters: Example parameters: parameters (dict) – The parameters for the reconstruction. input_path (str) – Path for input data. output_path (str) – Path where to write output to. parameters={‘EMC_Parameters’ : EMCOrientationParameters(), ‘DM_Parameters’ : DMPhasingParameters()} # Use default parameters for EMC and DM. backengine()[source] Run the EMC and DM backengine executables. data Query for the field data. expectedData()[source] Query for the data expected by the Analyzer. providedData()[source] Query for the data provided by the Analyzer. saveH5()[source] module SingFELPhotonDiffractor: Module that holds the SingFELPhotonDiffractor class. class SimEx.Calculators.SingFELPhotonDiffractor.SingFELPhotonDiffractor(parameters=None, input_path=None, output_path=None)[source] Class SingFELPhotonDiffractor: Representing scattering from a molecular sample into a detector plane. Parameters: • parameters (dict || SingFELPhotonDiffractorParameters) – Parameters of the calculation (not data). • input_path (str) – Path to hdf5 file holding the input data. • output_path (str) – Path to hdf5 file for output. backengine()[source] This method drives the backengine singFEL. data Query for the field data. expectedData()[source] Query for the data expected by the Diffractor. providedData()[source] Query for the data provided by the Diffractor. saveH5()[source] module XCSITPhotonDetector: Hosts the XCSITPhotonDetector class. class SimEx.Calculators.XCSITPhotonDetector.XCSITPhotonDetector(parameters=None, input_path=None, output_path=None)[source] Class XCSITPhotonDetector: Wraps detector simulations with XCSIT. Parameters:parameters – Parameters of the calulator such as the type of detector :type parameters: XCSITPhotonDetectorParameters Parameters: input_path (str) – Path to the hdf5 file holding the input data. output_path (str) – Path pointing to the path for output backengine()[source] Executes the simulation of the particle and charge simulation. expectedData()[source] Query for the data fields expected by this calculator. input_path Query for the input file path(s). output_path Query for the output file path(s). providedData()[source] Query for the data fields provided by this calculator. saveH5()[source] Save the results in a file module XFELPhotonPropagator: Module that holds the XFELPhotonPropagator class. class SimEx.Calculators.XFELPhotonPropagator.XFELPhotonPropagator(parameters=None, input_path=None, output_path=None)[source] Class XFELPhotonPropagator: Represents coherent wavefront propagation using the WPG wrapper for SWR. Parameters: • parameters (WavePropagatorParameters instance.) – Parameters for the photon propagation. • input_path (str, default 'FELsource/') – Location of input data for photon propagation. • output_path (str, default 'prop/') – Location of propagation output data. backengine()[source] Starts WPG simulations in parallel in a subprocess data Query for the field data. saveH5()[source] module XFELPhotonSource: Module that holds the XFELPhotonSource class. class SimEx.Calculators.XFELPhotonSource.XFELPhotonSource(parameters=None, input_path=None, output_path=None)[source] Class XFELPhotonSource: Class representing a x-ray free electron laser photon source. :param parameters : Photon source parameters. :type parameters: dict Parameters: input_path (str, default FELsource_in.h5) – The path to the input data for the photon source. output_path – The path where to save output data. backengine()[source] Method to call the backengine for the calculator. To be implemented on the derived classes. data Query for the field data. saveH5()[source] module XMDYNDemoPhotonMatterInteractor: Module that holds the XMDYNDemoPhotonMatterInteractor class. class SimEx.Calculators.XMDYNDemoPhotonMatterInteractor.XMDYNDemoPhotonMatterInteractor(parameters=None, input_path=None, output_path=None, sample_path=None)[source] Class XMDYNDemoPhotonMatterInteractor: Interface class for photon-matter interaction calculations using the demo version of the XMDYN code. Parameters: • parameters (dict) – Parameters that govern the PMI calculation. • input_path (str) – Location of data needed by the PMI calculation (Laser source wavefront data). • output_path (str) – Where to store the data generated by the PMI calculation. • sample_path (str) – Location of the sample/target geometry file. Can be either a simS2E sample file or a pdb file. Specifying a pdb will first check if it’s present in a database, if not, it will issue a query for the basename of the file to the RCSB protein data bank. backengine()[source] This method drives the backengine code. data Query for the field data. expectedData()[source] Query for the data expected by the Interactor. providedData()[source] Query for the data provided by the Interactor. saveH5()[source] module XMDYNPhotonMatterInteractor: Module that holds the XMDYNPhotonMatterInteractor class. class SimEx.Calculators.XMDYNPhotonMatterInteractor.XMDYNPhotonMatterInteractor(parameters=None, input_path=None, output_path=None, sample_path=None, seed=1, root_path=None)[source] Class XMDYNPhotonMatterInteractor: Wrapper class for photon-matter interaction calculations using the XMDYN code. Parameters: • parameters (dict) – Parameters that govern the PMI calculation. • input_path (str) – Location of data needed by the PMI calculation (Laser source wavefront data). • output_path (str) – Where to store the data generated by the PMI calculation. • sample_path (str) – Location of the sample/target geometry file. Can be either a simS2E sample file or a pdb file. Specifying a pdb will first check if it’s present in a database, if not, it will issue a query for the basename of the file to the RCSB protein data bank. • root_path (str) – Path to a root directory from which to restart a (previously failed) simulation. backengine()[source] This method drives the backengine code. data Query for the field data. expectedData()[source] Query for the data expected by the Interactor. load_snp_from_dir(path_to_snapshot)[source] Load xmdyn output from an xmdyn directory. Parameters: path (str) – The directory path to xmdyn output. snapshot_index (int) – Which snapshot to load. The snapshot data. dict parameters Query the calculator parameters. Returns: The parameters of this Calculator. providedData()[source] Query for the data provided by the Interactor. root_path Get the path to the restart data. sample_path Get the path to the sample geometry file. saveH5()[source] setup_hierarchy(h5_handle)[source] Create all datagroups in the output hdf5 file. Parameters: h5_handle (h5py.File) – File handle to writable hdf5 file. module CrystFELPhotonDiffractorParameters: Module that holds the CrystFELPhotonDiffractorParameters class. class SimEx.Parameters.CrystFELPhotonDiffractorParameters.CrystFELPhotonDiffractorParameters(sample=None, uniform_rotation=None, number_of_diffraction_patterns=None, powder=None, intensities_file=None, crystal_size_min=None, crystal_size_max=None, poissonize=None, number_of_background_photons=None, suppress_fringes=None, beam_parameters=None, detector_geometry=None, **kwargs)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class CrystFELPhotonDiffractorParameters: Encapsulates parameters for the CrystFELPhotonDiffractor. Parameters: • sample (str) – Location of file that contains the sample definition (pdb or crystfel format) • uniform_rotation (bool, default True) – Whether to perform uniform sampling of rotation space. • powder (bool) – Whether to sum all patterns to generate a simulated powder diffraction pattern. • intensities_file (str) – Location of file that contains intensities and phases at reciprocal lattice points. See CrystFEL documentation for more info. Default: Constant intensities and phases across entire sample. • crystal_size_min (PhysicalQuantity with unit of length (meter)) – Minimum crystal size. • crystal_size_max (PhysicalQuantity with unit of length (meter)) – Maximum crystal size. • poissonize (bool) – Whether to add Poisson noise to pixel values. • number_of_background_photons (int) – Add this number of Poisson distributed photons uniformly over the detector surface (default 0). • number_of_diffraction_patterns (int, default 1) – Number of diffraction patterns to calculate from each trajectory. • suppress_fringes (bool) – Whether to suppress subsidiary maxima beyond first minimum of the shape transform (default False). • beam_parameters (str) – Path of the beam parameter file. • detector_geometry (str) – Path of the beam geometry file. • kwargs – Key-value pairs to pass to the parent class. beam_parameters Query for the ‘beam_parameters’ parameter. crystal_size_max Query the ‘crystal_size_max’ parameter. crystal_size_min Query the ‘crystal_size_min’ parameter. detector_geometry Query for the ‘detector_geometry’ parameter. intensities_file Query the ‘intensities_file’ parameter. number_of_background_photons Query the ‘number_of_background_photons’ parameter. number_of_diffraction_patterns Query for the ‘number_of_diffraction_patterns_file’ parameter. poissonize Query the ‘poissonize’ parameter. powder Query the ‘powder’ parameter. sample Query the ‘sample’ parameter. suppress_fringes Query the ‘suppress_fringes’ parameter. uniform_rotation Query for the ‘uniform_rotation’ parameter. module DMPhasingParameters: Module that holds the DMPhasingParameters class. class SimEx.Parameters.DMPhasingParameters.DMPhasingParameters(number_of_trials=None, number_of_iterations=None, averaging_start=None, leash=None, number_of_shrink_cycles=None, parameters_dictionary=None, **kwargs)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class DMPhasingParameters: Encapsulates parameters for the DMPhasing analyzer. Parameters: • number_of_trials (int>0, default 500) – How many trials to run in each iteration. • number_of_iterations (int>0, default 50) – Maximum number of DM iterations. • averaging_start – Start averaging after this many runs. • leash (float>0, default 0.2) – DM leash parameter. • number_of_shrink_cycles (int>0, default 10) – DM shrink cycles. averaging_start Query for the ‘averaging_start’ parameter. leash Query for the ‘leash’ parameter. number_of_iterations Query for the ‘number_of_iterations’ parameter. number_of_shrink_cycles Query for the ‘number_of_shrink_cycles’ parameter. number_of_trials Query for the ‘number_of_trials’ parameter. module EMCOrientationParameters: Hosts the EMCOrientationParameters class. class SimEx.Parameters.EMCOrientationParameters.EMCOrientationParameters(initial_number_of_quaternions=None, max_number_of_quaternions=None, max_number_of_iterations=None, min_error=None, beamstop=None, detailed_output=None, parameters_dictionary=None, **kwargs)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class EMCOrientationParameters: Class representing parameters for the EMCOrientation analyzer. Parameters: • initial_number_of_quaternions (int (0<n<10), default 1) – Number of quaternions to start the EMC algorithm. • max_number_of_quaternions (int (initial_number_of_quaternions < n <= 10), default initial_number_of_quaternions + 1) – Maximum number of quaternions for the EMC algorithm. • min_error (float (>0), default 1.e-6) – Relative convergence criterion (Go to next quaternion is relative error gets below this value.) • max_number_of_iterations (int (>0), default 100) – Stop the EMC algorithm after this number of iterations. • beamstop (bool, default True) – Whether to apply a “center + strip” beamstop to the pixel map. • detailed_output (bool, default True) – Whether to write detailed info to log. beamstop Query for the ‘beamstop’ parameter. detailed_output Query for the ‘detailed_output’ parameter. initial_number_of_quaternions Query for the ‘initial_number_of_quaternions’ parameter. max_number_of_iterations Query for the ‘max_number_of_iterations’ parameter. max_number_of_quaternions Query for the ‘max_number_of_quaternions’ parameter. min_error Query for the ‘min_error’ parameter. module EstherPhotonMatterInteractorParameters: Hosting the parameter class for the EstherPhotonMatterInteractor. class SimEx.Parameters.EstherPhotonMatterInteractorParameters.EstherPhotonMatterInteractorParameters(number_of_layers=None, ablator=None, ablator_thickness=None, sample=None, sample_thickness=None, layer1=None, layer1_thickness=None, layer2=None, layer2_thickness=None, window=None, window_thickness=None, laser_wavelength=None, laser_pulse=None, laser_pulse_duration=None, laser_intensity=None, run_time=None, delta_time=None, read_from_file=None, force_passage=None, without_therm_conduc=None, rad_transfer=None)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class EstherPhotonMatterInteractorParameters: representing parameters for the Esthe Hydrocode Calculator. Parameters: • ablator (str) – The ablating material ( “Al” | “CH” | “Diamond” | “Kapton” | “Mylar” ) • ablator_thickness – The ablator thickness (micrometers) • sample (str) – The sample material (from list of materials) • sample_thickness (float) – The sample thickness (micrometers) • layer1 (str) – The layer1 material (from list of materials) • layer2 (str) – The layer2 material (from list of materials) • window (str) – The window material (LiF | SiO2 | Diamond) • window_thickness (float) – The window thickness, if using window (micrometers) • laser_pulse (str) – Pulse type (“flat” | “ramp” | “other”) • laser_pulse_duration (float) – Pulse duration of the pump laser (ns) • laser_wavelength (float) – Laser wavelength (nm) • laser_intensity (float) – Laser intensity (TW/cm2) • run_time (float) – Simulation run time (ns) • delta_time (float) – Time steps resolution (ns) • force_passage (boolean) – Expert option to force passage of simulation through minor errors • without_therm_conduc (boolean) – Expert option to use without thermal conductivity options • rad_transfer (boolean) – Expert option to use radiative transfer ablator Query for the ablator type. ablator_thickness Query for the ablator thickness. delta_time Query for simulation time resolution (delta t ns) laser_intensity Query for laser intensity laser_pulse Query for laser pulse type laser_pulse_duration Query for laser pulse duration laser_wavelength Query for the laser wavelength type. layer1 Query for the layer1 type. layer1_thickness Query for the layer1 thickness type. layer2 Query for the layer2 type. layer2_thickness Query for the layer2 thickness type. number_of_layers Query for the number of layers. run_time Query for simulation run time sample Query for the sample type. sample_thickness Query for the sample thickness type. window Query for the window type. window_thickness Query for the window thickness type. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetAblator(ablator)[source] Utility to check if the ablator exists in the EOS database. Parameters: ablator – The ablator material to check. The ablator choice after being checked. ValueError – ablator not in [“CH”, “Al”, “Diamond”, “Mylar”, “Kapton”]. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetAblatorThickness(ablator_thickness)[source] Utility to check that the ablator thickness is > 5 um and < 100 um SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetDeltaTime(delta_time)[source] Utility for checking the simulation delta time (resolution) is valid SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetLaserIntensity(laser_intensity)[source] Utility to check that the laser intensity is valid. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetLaserPulse(laser_pulse)[source] Utility to check that the laser pulse type is correct. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetLaserPulseDuration(laser_pulse_duration)[source] Utility to check that the laser pulse duration is valid. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetLaserWavelength(laser_wavelength)[source] Utility to check that the laser wavelength is correct. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetLayer1(layer1)[source] Utility to check if the layer1 is in the list of known EOS materials SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetLayer1Thickness(layer1_thickness)[source] Utility to check that the layer1 thickness is in permitted range set by Esther. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetLayer2(layer2)[source] Utility to check if the layer2 is in the list of known EOS materials SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetLayer2Thickness(layer2_thickness)[source] Utility to check that the layer2 thickness is in permitted range set by Esther. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetNumberOfLayers(number_of_layers)[source] Utility to check if the number of layers is reasonable. Parameters: number_of_layers – The number of layers to check Checked number of layers ValueError – not (1 < number_of_layers <= 4 ) SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetRunTime(run_time)[source] Utility for checking the simulation run time is valid SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetSample(sample)[source] Utility to check if the sample is in the list of known EOS materials SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetSampleThickness(sample_thickness)[source] Utility to check that the sample thickness is in permitted range set by Esther. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetWindow(window)[source] Utility to check that the window exists in the EOS database. SimEx.Parameters.EstherPhotonMatterInteractorParameters.checkAndSetWindowThickness(window_thickness)[source] Utility to check that the window thickness is > 1 um and < 500 um module: Holds the FEFFPhotonMatterInteractorParameters class. class SimEx.Parameters.FEFFPhotonMatterInteractorParameters.FEFFPhotonMatterInteractorParameters(atoms=None, potentials=None, edge=None, amplitude_reduction_factor=None, effective_path_distance=None)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class FEFFPhotonMatterInteractorParameters: Interface class for photon-matter interaction calculations using the FEFF code. Parameters: • atoms (list || tuple) – The atomic structure (Atom coordinates ([x,y,z] in Angstrom), element symbol, and potential index). If no potential index is given, all atoms of the same species will be assigned the default potential. The scattering atom must have the potential index 0. • potentials (list) – The potentials to use. • edge (str) – The edge to calculate (K, L1, L2, M1, M2, M3, …). Default ‘K’. • amplitude_reduction_factor (float) – The amplitude reduction factor. Default 1.0 • effective_path_distance (float) – The maximum effective (half-path) distance in Angstrom. Translates to rpath parameter in feff.inp. Default 2.2 times nearest neighbor distance. Example atoms: ([[0.0, 0.0, 0.0], ‘Cu’, 0], [[0.0, 1.0, 1.2], ‘O’, 1], …) amplitude_reduction_factor Query method for amplitude_reduction_factor atoms Query method for atoms edge Query method for edge effective_path_distance Query method for effective_path_distance finalize()[source] Finalize the parameters. Check if all parameters are internally consistent. finalized Query the finalization status. potentials Query method for potentials module PhotonBeamParameters: Contains the PhotonBeamParameters class and associated functions. class SimEx.Parameters.PhotonBeamParameters.PhotonBeamParameters(photon_energy, beam_diameter_fwhm, pulse_energy, photon_energy_relative_bandwidth=None, divergence=None, photon_energy_spectrum_type=None, **kwargs)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class PhotonBeamParameters: Encapsulates the parameters of a photon beam. Parameters: • photon_energy (float) – The mean photon energy in units of electronvolts (eV). • photon_energy_relative_bandwidth (float (>0.0)) – The relative energy bandwidth • beam_diameter_fwhm (float) – Beam diameter in units of metre (m). • pulse_energy (float) – Total energy of the pulse in units of Joule (J). • divergence (float (0 < divergence < 2*pi)) – Beam divergence angle in units of radian (rad). • photon_energy_spectrum_type (float) – Type of energy spectrum (“SASE” | “tophat” | “twocolour”, default “SASE”). • kwargs (dict) – Key-value pairs to be passed to the parent class constructor. beam_diameter_fwhm Query the ‘beam_diameter_fwhm’ parameter. divergence Query the ‘divergence’ parameter. photon_energy Query the ‘photon_energy’ parameter. photon_energy_relative_bandwidth Query the ‘photon_energy_relative_bandwidth’ parameter. photon_energy_spectrum_type Query the ‘photon_energy_spectrum_type’ parameter. pulse_energy Query the ‘pulse_energy’ parameter. serialize(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source] Serialize the object (write to a stream) Parameters: stream (str || file) – The stream to write to (default sys.stdout) SimEx.Parameters.PhotonBeamParameters.propToBeamParameters(prop_output_path)[source] Utility to setup a PhotonBeamParameters instance from propagation output. module PhotonMatterInteractorParameters: Module that holds the PhotonMatterInteractorParameter class. class SimEx.Parameters.PhotonMatterInteractorParameters.PhotonMatterInteractorParameters(rotation=None, calculate_Compton=None, number_of_trajectories=None, beam_parameters=None, parameters_dictionary=None, **kwargs)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class PhotonMatterInteractorParameters: Encapsulates parameters for the PhotonMatterInteractor calculator. Parameters: • rotation – Rotation to apply to the sample atoms’ positions (Default: no rotation). • calculate_Compton (bool, default False) – Whether to calculate incoherent (Compton) scattering. • number_of_trajectories (int, default 1) – Number of trajectories to simulate. • beam_parameters (PhotonBeamParameters) – Parameters of the photon beam. • parameters_dictionary (dict) – A legacy parameters dictionary (Default: None). beam_parameters Query for the ‘beam_parameters’ parameter. calculate_Compton Query for the ‘calculate_Compton’ parameter. number_of_trajectories Query for the ‘number_of_trajectories_file’ parameter. rotation Query for the ‘rotation’ parameter. module PlasmaXRTSCalculatorParameters: Module that holds the PlasmaXRTSCalculatorParameters class. class SimEx.Parameters.PlasmaXRTSCalculatorParameters.PlasmaXRTSCalculatorParameters(elements=None, photon_energy=None, scattering_angle=None, electron_temperature=None, electron_density=None, ion_temperature=None, ion_charge=None, mass_density=None, debye_temperature=None, band_gap=None, energy_range=None, model_Sii=None, model_See=None, model_Sbf=None, model_IPL=None, model_Mix=None, lfc=None, Sbf_norm=None, source_spectrum=None, source_spectrum_fwhm=None, **kwargs)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class PlasmaXRTSCalculatorParameters: Encapsulates parameters for the plasma x-ray Thomson scattering calculator. Parameters: • elements (list [[element symbol, stochiometric number, charge], ..], default None) – The chemical elements in the scattering target. • photon_energy (float) – The central energy of incoming x-ray photons. • scattering_angle (float) – The scattering angle. • electron_temperature (float) – The temperature of the electron subsystems (units of eV). • electron_density (float) – The electron number density (units of 1/cm^3) • ion_temperature (float) – The temperature of the ion subsystem (units of eV). • ion_charge (float) – The average ion charge (units of elementary charge e). • mass_density (float) – The mass density of the target (units of g/cm^3). • debye_temperature (float) – The Debye temperature (units of eV). • band_gap (float, default 0) – The band gap of the target (units of eV). • energy_range (dict, default 0) – The energy range over which to calculate the scattering spectrum. • model_Sii (str ('DH' || 'OCP' || 'SOCP' || 'SOCPN') || float, default 'DH') – The model to use for the ion-ion structure factor. • model_See (str ('RPA' || 'BMA' || 'BMA+sLFC'), default 'RPA') – The model of the dynamic (high frequency) part of the electron-electron structure factor. • model_Sbf (str ('IA' || 'FA'), default 'IA') – The model for the bound-free structure factor. • model_IPL (str ('SP' || 'EK') || float, default 'SP') – Model for ionization potential lowering. • model_Mix (str, default None) – The model to use for mixing (of species). • lfc (float, default 0.0) – The local field correction to use. • Sbf_norm (str || float, default None) – How to normalize the bound-free structure factor. • source_spectrum (str, default None) – Path to a file holding the x-ray probe energy spectrum. • source_spectrum_fwhm (float) – The x-ray probe energy spectrum fwhm. Example elements: [[‘B’, 1, 2], [‘N’, 1, 2]] for Boron-Nitride with both B and N two fold ionized (ion average). Example elements: [[‘C’, 1, 4], [‘H’, 1, -1]] for Plastic with both four-fold ionized C and ionization of H calculated so that the given average ion charge comes out correct. Example energy_range: energy_range={‘min’ -100.0, ‘max’ 100, ‘step’ 0.5} to go from -100 eV to 100 eV in steps of 0.5 eV. Example model_Sii: Sii=1.5 to use a fixed value of Sii=1.5 Example model_IPL: model_IPL=100.0 # Set the ionization potential difference (lowering) to 100 eV. Sbf_norm Query for the norm of the bound-free structure factor. band_gap Query for the band gap. debye_temperature Query for the Debye temperature. electron_density Query for the electron density. electron_temperature Query for the electron temperature. elements Query for the field data. energy_range Query for the energy range. ion_charge Query for the ion charge. ion_temperature Query for the ion temperature. lfc Query for the local field factor. mass_density Query for the mass density. model_IPL Query for the ionization potential lowering model. model_Mix Query for the mixing model. model_Sbf Query for the bound-free structure factor model. model_See Query for the electron-electron (high-frequency) structure factor model. model_Sii Query for the ion-ion structure factor model. photon_energy Query for the photon energy. scattering_angle Query for the scattering angle. source_spectrum Query for the source spectrum identifier. source_spectrum_fwhm Query for the source spectrum fwhm identifier. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetBandGap(band_gap)[source] Utility to check if input is a valid bandgap. @param band_gap: The bandgap to check. <br/><b>type</b> : double <br/><b>default</b> 0.0. @return : The checked bandgap. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetDebyeTemperature(debye_temperature)[source] Utility to check if input is a valid Debye temperature. @param debye_temperature : The Debye temperature to check. <br/><b>type</b> : double <br/><b>default</b> : 0.0 @return : The checked Debye temperature. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetDensitiesAndCharge(electron_density, ion_charge, mass_density, elements)[source] Utility to check input and return a set of consistent electron density, average ion charge, and mass density, if two are given as input. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetElectronTemperature(electron_temperature)[source] Utility to check if input is a valid electron temperature. @param electron_temperature : The electron temperature to check. <br/><b>type</b> : double @return : The checked electron temperature. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetElements(elements)[source] Utility to check if input is a valid list of elements. @param elements: The elements to check. <br/><b>type</b> elements: list @return: The checked list of elements. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetEnergyRange(energy_range, electron_density=None)[source] Utility to check if the photon energy range is ok. @param energy_range : The range to check. <br/><b>type</b> dict @return The checked photon energy range. @raise ValueError if not of correct shape. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetIonTemperature(ion_temperature, electron_temperature=None)[source] Utility to check if input is a valid ion temperature. @param ion_temperature : The ion temperature to check. <br/><b>type</b> : double <br/><b>default</b> : Electron temperature. @return : The checked ion temperature. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetLFC(lfc)[source] Utility to check if input is a valid local field correction factor. @param lfc : The lfc to check. <br/><b>type</b> : double @return : The checked lfc. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetModelIPL(model)[source] Utility to check if the model is a valid model for ionization potential lowering. @param model : The model to check. <br/><b>type</b> : str or float @return : The checked model @raise ValueError if not a valid IPL model. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetModelMix(model_Mix)[source] Utility to check if input is a valid mixing model. @param model_Mix : The mixing model to check. <br/><b>type</b> : string @return : The checked mixing model. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetModelSbf(model)[source] Utility to check if the model is a valid model for the bound-free (Compton) scattering feature. @param model : The model to check. <br/><b>type</b> : str @return : The checked model @raise ValueError if not a string or not a valid Sbf model (‘IA’, ‘HWF’) SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetModelSee(model)[source] Utility to check if the model is a valid model for the high frequency (dynamic) feature. @param model : The model to check. <br/><b>type</b> : str @return : The checked model @raise ValueError if not a string or not a valid See0 model (‘RPA’, ‘BMA’, ‘BMA+sLFC’, ‘BMA+dLFC’, ‘LFC’, ‘Landen’) SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetModelSii(model)[source] Utility to check if the model is a valid model for the Rayleigh (quasistatic) scattering feature. @param model : The model to check. <br/><b>type</b> : str @return : The checked model @raise ValueError if not a string or not a valid Sii model (‘RPA’, ‘DH’, SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetPhotonEnergy(energy)[source] Utility to check if the photon energy is correct. @param energy : The energy to check. @return The checked energy. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetSbfNorm(Sbf_norm)[source] Utility to check if input is a valid norm of the bound-free structure factor. @param Sbf_norm : The norm to check. <br/><b>type</b> : string or double. @return : The checked norm. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetScatteringAngle(angle)[source] Utility to check if the scattering angle is in the correct range. @param angle : The angle to check. @return The checked angle. @raise ValueError if not 0 <= angle <= 180 SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetSourceSpectrum(source_spectrum)[source] Utility to check sanity of given input for the source spectrum identifier. @param source_spectrum : The source spectrum identifier to check. <br/><b>type</b> : str @return : The checked identifier. @raise : TypeError or ValueError if input is not valid. SimEx.Parameters.PlasmaXRTSCalculatorParameters.checkAndSetSourceSpectrumFWHM(fwhm)[source] Utility to check sanity of given input for the source spectrum full width at half maximum (fwhm). @param source_spectrum : The value to check. <br/><b>type</b> : float @return : The checked value. @raise : TypeError or ValueError if input is not valid. module SingFELPhotonDiffractorParameters: Module that holds the SingFELPhotonDiffractorParameters class. class SimEx.Parameters.SingFELPhotonDiffractorParameters.SingFELPhotonDiffractorParameters(sample=None, uniform_rotation=None, calculate_Compton=None, slice_interval=None, number_of_slices=None, pmi_start_ID=None, pmi_stop_ID=None, number_of_diffraction_patterns=None, beam_parameters=None, detector_geometry=None, number_of_MPI_processes=None, parameters_dictionary=None, **kwargs)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class SingFELPhotonDiffractorParameters: Class representing parameters for the SingFELPhotonDiffractor calculator. Parameters: • sample (str) – Name of file containing atomic sample geometry (default None). • uniform_rotation (bool, default True) – Whether to perform uniform sampling of rotation space. • calculate_Compton (bool, default False) – Whether to calculate incoherent (Compton) scattering. • slice_interval (int, default 100) – Length of time slice interval to extract from each trajectory. • number_of_slices (int, default 1) – Number of time slices to read from each trajectory. • pmi_start_ID (int, default 1) – Identifier for the first pmi trajectory to read in. • pmi_stop_ID (int, default 1) – Identifier for the last pmi trajectory to read in. • number_of_diffraction_patterns (int, default 1) – Number of diffraction patterns to calculate from each trajectory. • beam_parameters (str) – Path of the beam parameter file. • detector_geometry (str) – Path of the beam geometry file. • number_of_MPI_processes (int, default 1) – Number of MPI processes beam_parameters Query for the ‘beam_parameters’ parameter. calculate_Compton Query for the ‘calculate_Compton’ parameter. detector_geometry Query for the ‘detector_geometry’ parameter. number_of_diffraction_patterns Query for the ‘number_of_diffraction_patterns_file’ parameter. number_of_slices Query for the ‘number_of_slices’ parameter. pmi_start_ID Query for the ‘pmi_start_ID’ parameter. pmi_stop_ID Query for the ‘pmi_stop_ID’ parameter. sample Query for the ‘sample’ parameter. slice_interval Query for the ‘slice_interval’ parameter. uniform_rotation Query for the ‘uniform_rotation’ parameter. module WavePropagatorParameters: Module that holds the WavePropagatorParameters class. class SimEx.Parameters.WavePropagatorParameters.WavePropagatorParameters(use_opmd=None, beamline=None, **kwargs)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class WavePropagatorParameters: Class representing parameters for the WavePropagator. Parameters: • use_opmd (bool, default False) – Whether to use the openPMD output format. • beamline (WPG.Beamline instance.) – The WPG beamline to use in the propagation. beamline Query for the ‘beamline’ parameter. use_opmd Query for the ‘use_opmd’ parameter. module XCSITPhotonDetectorParameters: Hosts the XCSITPhotonDetectorParameters class. class SimEx.Parameters.XCSITPhotonDetectorParameters.XCSITPhotonDetectorParameters(detector_type=None, plasma_search_flag=None, plasma_simulation_flag=None, point_simulation_method=None, patterns=None)[source] Bases: SimEx.Parameters.AbstractCalculatorParameters.AbstractCalculatorParameters Class XCSITPhotonDetectorParameters: Encapsulates all parameters for the XCSITPhotonDetector class. Parameters: • detector_type (str) – The detector type to simulate (“pnCCD” | “LPD” | “AGIPD | “AGIPDSPB”). • plasma_search_flag (str) – Flag for the plasma search method (“BLANK”). • plasma_simulation_flag (str) – Flag for the plasma simulation method (“BLANKPLASMA”). • point_simulation_method (str) – Method for the charge point simulation (“FULL” | “FANO” | “LUT” | “BINNING”). • patterns ((str || int) or iterable over these types.) – Which patterns to feed into the detector simulation. Default: Use all patterns. Example patterns: patterns=0 # use the first pattern. Example patterns: patterns=range(10) # use the first 10 patterns Example patterns: patterns=[‘0000001’,‘0001001’] # user patterns with Ids ‘0000001’ and ‘0001001’. detector_type :return string containing the detector name patterns Returns: The patterns to use in the detector simulation. plasma_search_flag :return string, the plasma search method plasma_simulation_flag :return string, the plasma simulation method point_simulation_method :return string, the charge simulation method module EstherExperiment: Hosts the EstherExperiment workflow class. class SimEx.PhotonExperimentSimulation.EstherExperiment.EstherExperiment(parameters=None, input_path=None, output_path=None, esther_sims_path=None, sim_name=None)[source] Bases: object Class EstherExperiment: Represents creating new and iterative Rad-Hydro simulations. Parameters: • parameters (str) – Esther parameters. • input_path (str) – Location of input parameters from e.g. light source simulation. • output_path (str) – Location where to store final results from the rad-hydro simulations. • tmp_files_path (str) – Where to store temporary files produced by Rad-Hydro code or parameters object. • esther_sims_path (str) – Top level directory where all experiments are stored. • sim_name (str) – Name of this experiment module Utilities: Module holding a loose collection of definitions and utility functions. module IOUtilities: Module for input/output utilities. SimEx.Utilities.IOUtilities.checkAndGetPDB(path)[source] Query a given pdb code from the PDB. Parameters: path (str) – The PDB code of the molecule to query. Path to the checked pdb file. SimEx.Utilities.IOUtilities.genesis_dfl_to_wavefront(genesis_out, genesis_dfl)[source] Based on WPG/wpg/converters/genesis_v2.py SimEx.Utilities.IOUtilities.getTmpFileName()[source] Create a unique filename :return: unique filename for temporary storage :rtype: str SimEx.Utilities.IOUtilities.get_dict_from_lines(reader)[source] Turn a list of [key, ‘ ‘, …, value] elements into a dict. Params reader: An iterable that contains lists of strings in format [key, ‘ ‘, ‘ ‘, …, value] iterable (list, array, generator) SimEx.Utilities.IOUtilities.loadPDB(path=None)[source] Wrapper to convert a given pdb file to a sample dictionary used by e.g. the XMDYNCalculator. Parameters: path (str) – The path to the pdb file to be converted. The dictionary describing the sample molecule. dict SimEx.Utilities.IOUtilities.loadXYZ(path=None)[source] Load atomic structure from a xyz file and setup a dictionary readable by xmdyn calculator. Parameters: path – The path to the xyz file. SimEx.Utilities.IOUtilities.pic2dist(pic_file_name, target='genesis')[source] Utility to extract particle data from openPMD and write into genesis distribution file. Parameters: pic_file_name (str) – Filename of openpmd input data file. target (str) – The targeted file format (genesis || simplex). SimEx.Utilities.IOUtilities.wgetData(url=None, path=None)[source] Download a given url. module ParallelUtilities: Hosts utilities to query HPC runtime parameters. SimEx.Utilities.ParallelUtilities.getCUDAEnvironment()[source] Get the CUDA runtime environment parameters (number of cards etc.). SimEx.Utilities.ParallelUtilities.getParallelResourceInfo()[source] Utility extract information about available parallel resources. @return : The dictionary expected by downstream simex modules. @rtype : resource SimEx.Utilities.ParallelUtilities.prepareMPICommandArguments(ntasks, threads_per_task=0)[source] Utility prepares mpi arguments based on mpi version found in the system. Parameters: ntasks (int) – Number of MPI tasks threads_per_task (int) – Number of threads per task @return : String with mpi command and arguments @rtype : string module RadHydroAnalysis: Collection of utilities to analyse output from (esther) rad-hydro simulations. SimEx.Utilities.RadHydroAnalysis.radHydroAnalysis(filename)[source] Generates four plots to analyse shock compression data. Parameters: filename (str) – Filename of hdf5 file containing rad-hydro data in openPMD format. module RadHydroInputPlots: Hosts utilities to plot target absorption profiles. SimEx.Utilities.RadHydroInputPlots.plotTargetAndTransmission(symbol, edge='K', thickness=0.001, energies=None, ablator_thickness=0.0025)[source] Plots absorption in a given material as function of wavelength. Parameters: symbol (str) – The chemical symbol of the material. edge (str) – The requested absorption edge (K, L1, L2, M1, M2, …) thickness (float) – The material thickness in centimeters.” energies (ndarray) – For which energies to plot the transmission. ablator_thickness (float) – Thickness of ablator SimEx.Utilities.RadHydroInputPlots.plotTransmission(symbol, edge='K', thickness=0.001, energies=None)[source] Plots absorption in a given material as function of wavelength. Parameters: symbol (str) – The chemical symbol of the material. edge (str) – The requested absorption edge (K, L1, L2, M1, M2, …) thickness (float) – The material thickness in centimeters.” energies (ndarray) – For which energies to plot the transmission. module OpenPMDTools: Hosts various utilities to setup openpmd compliant hdf structures. SimEx.Utilities.OpenPMDTools.get_basePath(f, iteration)[source] Get the basePath for a certain iteration f : an h5py.File object The file in which to write the data iteration : an iteration number A string with a in-file path. SimEx.Utilities.OpenPMDTools.setup_base_path(f, iteration, time, time_step)[source] Write the basePath group for iteration f : an h5py.File object The file in which to write the data iteration : int The iteration number for this output SimEx.Utilities.OpenPMDTools.setup_root_attr(f, extension=None)[source] Write the root metadata for this file f : an h5py.File object The file in which to write the data SimEx.Calculators.AbstractPhotonAnalyzer.checkAndSetPhotonAnalyzer(var=None, default=None)[source] Check if passed object is an AbstractPhotonAnalyzer instance. If non is given, set to given default. Parameters: var – The object to check. default – The default to use. The checked photon source object. RuntimeError – if no valid PhotonAnalyzer was given. SimEx.Calculators.AbstractPhotonDetector.checkAndSetPhotonDetector(var=None, default=None)[source] Check if passed object is an AbstractPhotonDetector instance. If non is given, set to given default. Parameters: var – The object to check. default – The default to use. The checked photon source object. RuntimeError – if no valid PhotonDetector was given. SimEx.Calculators.AbstractPhotonDiffractor.checkAndSetPhotonDiffractor(var=None, default=None)[source] Check if passed object is an AbstractPhotonDiffractor instance. If non is given, set to given default. @param var : The object to check. @param default : The default to use. @return : The checked photon source object. @throw : RuntimeError if no valid PhotonDiffractor was given. SimEx.Calculators.AbstractPhotonInteractor.checkAndSetPhotonInteractor(var=None, default=None)[source] Check if passed object is an AbstractPhotonInteractor instance. If non is given, set to given default. @param var : The object to check. @param default : The default to use. @return : The checked photon source object. @throw : RuntimeError if no valid PhotonInteractor was given. SimEx.Calculators.AbstractPhotonPropagator.checkAndSetPhotonPropagator(var=None, default=None)[source] Check if passed object is an AbstractPhotonPropagator instance. If non is given, set to given default. Parameters: var – The object to check default – The default to use The checked photon source object RuntimeError – if no valid PhotonPropagator was given. SimEx.Calculators.AbstractPhotonSource.checkAndSetPhotonSource(var=None, default=None)[source] Check if passed object is an AbstractPhotonSource instance. If non is given, set to given default. Parameters: var – The object to check. default – The default to use. The checked photon source object. RuntimeError if no valid PhotonSource was given. SimEx.Utilities.IntensityCalc.calculateLaserIntensity(laser_energy=None)[source] Converts the laser energy (in J), pulse length (flat top, in nanoseconds) and spot size (diameter in microns) to intensity in TW/cm^2. :param laser_energy: Energy (J) :type laser_energy: Number SimEx.Utilities.hydro_txt_to_opmd.convertTxtToOPMD(esther_dirname=None)[source] Converts the esther .txt output files to opmd conform hdf5. @param esther_dirname: Path (absolute or relative) of the directory containing esther output. @type : str SimEx.Utilities.wpg_to_opmd.convertToOPMD`(input_file)[source] Take native wpg output and rewrite in openPMD conformant way. @param input_file: The hdf5 file to be converted. @type: string @example: input_file = “prop_out.h5” ## Data format documentation¶ ### FEL source calculations (FAST)¶ File format: hdf5 (extension .h5) Data set Description Physical unit /data/arrEhor horizontal electric field component sqrt(W/mm^2) /data/arrEver vertical electric field component sqrt(W/mm^2) /params/Mesh/nSlices number of time slices 1 /params/Mesh/nx number of grid points in horizontal dimension (x) 1 /params/Mesh/ny number of grid points in vertical dimension (y) s /params/Mesh/sliceMax time corresponding to last slice s /params/Mesh/sliceMin time corresponding to first slice s /params/Mesh/xMax x coordinate of last grid point in horizontal dimension m /params/Mesh/xMin x coordinate of first grid point in horizontal dimension m /params/Mesh/yMax y coordinate of last grid point in vertical dimension m /params/Mesh/yMin y coordinate of first grid point in vertical dimension m /params/Mesh/zCoord z coordinate of the wavefront m /params/Rx instantaneous horizontal wavefront radius m /params/Ry instantaneous vertical wavefront radius m /params/dRx error in Rx m /params/dRy error on Ry m /params/nval data type of field values, 2 for complex 1 /params/photonEnergy central photon energy (mean of spectrum) eV /params/wDomain time or frequency domain /params/wEFieldUnit Electric field unit /params/wFloatType field numerical type /params/wSpace direct (r-space) or reciprocal (q-space) m /params/xCentre x coordinate of wavefront center m /params/yCentre y coordinate of wavefront center /history/parent/info/data_description data documentation /history/parent/info/package_version code version /history/parent/misc/FAST2XY.DAT FAST calculation data /history/parent/misc/angular_distribution angular distribution of source pulse 1/rad /history/parent/misc/spot_size fhwm spot size m /history/parent/misc/gain_curve gain curve 1 /history/parent/misc/nzc Undulator length (point on gain curve) /history/parent/misc/temporal_struct Temporal pulse structure (on-axis projection) ### Coherent wavefront propagation (WPG/SRW)¶ File format: hdf5 (extension .h5) Data set Description Physical unit /data/arrEhor horizontal electric field component sqrt(W/mm^2) /data/arrEver vertical electric field component sqrt(W/mm^2) /params/Mesh/nSlices number of time slices 1 /params/Mesh/nx number of grid points in horizontal dimension (x) 1 /params/Mesh/ny number of grid points in vertical dimension (y) s /params/Mesh/sliceMax time corresponding to last slice s /params/Mesh/sliceMin time corresponding to first slice s /params/Mesh/xMax x coordinate of last grid point in horizontal dimension m /params/Mesh/xMin x coordinate of first grid point in horizontal dimension m /params/Mesh/yMax y coordinate of last grid point in vertical dimension m /params/Mesh/yMin y coordinate of first grid point in vertical dimension m /params/Mesh/zCoord z coordinate of the wavefront m /params/Rx instantaneous horizontal wavefront radius m /params/Ry instantaneous vertical wavefront radius m /params/dRx error in Rx m /params/dRy error on Ry m /params/nval data type of field values, 2 for complex 1 /params/photonEnergy central photon energy (mean of spectrum) eV /params/wDomain time or frequency domain /params/wEFieldUnit Electric field unit /params/wFloatType field numerical type /params/wSpace direct (r-space) or reciprocal (q-space) m /params/xCentre x coordinate of wavefront center m /params/yCentre y coordinate of wavefront center /history/parent Previous module simulation data /misc/xFWHM Horizontal full width at half maximum (intensity distribution) m /misc/yFWHM Vertical full width at half maximum (intensity distribution) m ### Photon-Matter interaction (XMDYN)¶ File format: hdf5 (extension .h5) Data set Description Physical unit /data/snp*/ff 2D array of form factors. Rows: Atomic number, Columns: q 1 /data/snp*/halfQ 1D array of half-period resolutions corresponding to column index in form factor arrays 1/A /data/snp*/Nph number of photons in the calculation 1 /data/snp*/r 2D array of atomic position vectors. Rows: Atom index, columns: x,y,z coordinates m /data/snp*/T 1D array of unique ID per atomic number /data/snp*/Z 1D array of atom types per atomic position vector$r\$
/data/snp*/xyz 1D array of indices of ff for each atom in Z
/data/snp*/Sq_halfQ half period resolution q space spanned by Sq_bound, Sq_free 1/A
/data/snp*/Sq_bound 1D array for Compton scattering from bound electrons 1
/data/snp*/Sq_free 1D array for Compton scattering from free electrons 1
/history/parent Parent data
/info/package_version backengine code version
/info/contact Support contact for backengine code
/info/data_description Data documentation
/info/method_description Method documentation
/version hdf5 format version

### Diffraction (singFEL)¶

File format: hdf5 (extension .h5)

Data set Description Physical unit
/data/diffr 2D array. Photon number per pixel
/data/data 2D array. Integrated photon number per pixel, poisson noise added.
/data/angle Euler angles applied to atomic positions
/history/parent Details of parent data
/info/package_version Backengine code version
/info/contact Support contact
/info/data_description Data documentation
/info/method_description Method documentation
/params/geom/detectorDist Detector distance
/params/geom/pixelWidth Pixel width (x)
/params/geom/pixelHeight Pixel height (y)