GloPel.de

Global Analysis of PELDOR/DEER data

User Tools

Site Tools


simpel:manual:index

SimPel Manual

How to use and how not to use SimPel…

An extended version of this manual, including a short description of the algorithms implemented, is available together with the source code of SimPel. This includes an overview of the algorithms implemented for calculating PELDOR/DEER traces.

For convenience, a PDF version of this manual is provided for download.


Introduction

General Description

SimPel (Simulation of PELDOR data) is a Python3-based simulation program for high-performance simulations of PELDOR/DEER traces. SimPel provides a user-friendly GUI based on the PyQt5 GUI framework.

Up to five Gaussian distributions with independent linear coefficients and standard deviations can be used for creating a distance distribution. The user-defined distance distribution is used to calculate the PELDOR/DEER trace. Many simulation options are available. In addition to the pure dipolar evolution signal of the PELDOR/DEER trace, a background function can be added as well as Gaussian (white) noise. Simulations can be saved and automatic figure export is supported (formats: png, tif, pdf, ….).

Configuration settings for simulation and plotting options can be adjusted, allowing the user, e.g. to create figures with own preferences.

SimPel can be used to systematically explore the impact of changes of the distance distribution on the PELDOR/DEER trace. Additionally, SimPel can be used to compare experimental time traces with simulations.

The Bruker BES3T file format (.DTA, .DSC) used by Xepr and Elexsys spectrometers is supported as well as text files for loading experimental data. Furthermore, SimPel can be used to create high quality figures for simulated time traces and distance distributions.

For PELDOR/DEER analysis, we recommend the program GloPel, which is also freely available and can be downloaded from this page.

License

SimPel is made available free of charge and open source. SimPel is distributed under a 2-clause license (“Simplified BSD License” or “FreeBSD License”). The full text of this license can be found in the file LICENSE.txt in the main directory of the SimPel source code.

Requirements

SimPel was developed using Python 3, and whereas there is good chance to get it to run with Python 2.x, this has not been tested and is not guaranteed.

Besides a reasonably recent Python installation, only some standard packages are required that should be either pre-installed on your system or fairly easy to install, namely:

  • NumPy
  • SciPy
  • Matplotlib ≥ 2.0.0
  • PyQt5

Installation Instructions

SimPel is available free of charge and open source (see license). We recommend everybody with a recent Python installation on their computers to download the source code and use it. In this case, no real installation is necessary, and starting SimPel is as simple as typing the following command into a terminal:

python3 SimPel.py

However, SimPel can be downloaded as executable binary for Windows, macOS and several Linux flavors.It was tested on various systems including Windows 7 (32-bit and 64-bit architecture), Windows 10 (32-bit and 64-bit architecture), macOS 10.12.6 (Sierra), and Ubuntu 16.04.

Please note that these versions are much harder to debug if something goes wrong, therefore, they are provided as is without any further support.

Using SimPel

Basic Options

When starting SimPel, the main GUI (Fig. 1) opens. Default settings for all parameters are loaded when starting the program. The main GUI window as well as all additional windows are resizable and can be adjusted by the user.

Figure 1: Main GUI window of SimPel running on a Linux system (Ubuntu 16.04). Simulation of a bimodal distance distribution is shown. A background function (shown in red) was enabled. White noise was added to the simulated time trace.

Parameters such as central distances r0,i, standard deviations σi, or linear coefficients ci for up to five Gaussian functions can be set by the user. Additional simulation options are the time scale (tmax), the PELDOR/DEER step-size and the modulation depth λ. A background function can be added to the PELDOR/DEER trace. The background dimension can be chosen between 1 and 6 in steps of 0.1. The background decay constant can be defined by the user. White noise can be added by enabling the corresponding button. The signal-to-noise ration can be given by the user. The simulation is carried out by pressing the “Start” button.

A user-defined distance can be loaded. From this distance distribution the PELDOR/DEER trace is calculated using a kernel matrix. The distance distribution has to be provided as text file.

Experimental PELDOR/DEER time traces can be loaded and compared to simulations. SimPel accepts either a text-file format or a Bruker BES3T file format (.DTA, .DSC). Example for a comparison between an experimental dataset and a simulation is shown in Fig. 2.

Figure 2: Comparison of a simulation (blue) and an experimental time trace (gray). SimPel can be used to get a first impression about the distance distribution of an experimental time trace. For detailed analysis, we recommend to use the program GloPel.

Integration Settings

The standard integration method of SimPel uses:

points for the discretization of a Gaussian function fi in the interval [r0,i-3σi , r{0,i+3σi]. This is sufficient for most time traces. However, for some cases, especially if broad distance distributions are present in the small distance region, this is not sufficient and simulation noise is observed (Fig. 3).


Figure 3: Comparison of standard integration settings (top, blue) and integration with higher discretization of the Gaussian functions (bottom, purple) used for simulation.

This simulation noise can be avoided by enabling the “Higher discretization” check-box (three times higher discretization rate) or by checking/enabling “Fresnel+very high discretization” button (five times higher discretization rate). These should be sufficient for acquiring noise-free simulations of all possible distance distributions.

Data Output and Figure Export

Once a simulation was carried out, the result can be saved and the figures exported. If the “Save” button is clicked, a file manager opens and the files can be saved at the location defined by the user (Fig. 4). The PELDOR/DEER trace, the distance distribution, and the Fourier transform are saved as text files. Additionally, an information sheet is automatically created, containing all simulation options (see listing below). The information sheet contains all information to reproduce the simulation. Naturally, white noise cannot be reproduced exactly as it is created via a pseudo-random number generator.

Data output and figure export
Figure 4: File manager opens when the Save button is clicked. All output files are saved as text-files.

If not disabled in the configurations (for configuration settings see next section) the figures are automatically saved as Portable Network Graphics (png) and as vectorized Portable Document Format (PDF) files.

infosheet.txt
Infosheet for PELDOR/DEER Simulation. Original Path:
/home/stephan/Python_SimPel/Test_output_1

Simulated with SimPel2018: 1.0.0

Analyzed at: 2018-03-16 11:00:44

*************Simulation Parameter*****************

Distance / nm 	 Coefficient	  sigma / nm
1.8000	         1.0000	          0.2800	         
2.5000	         0.6000	          0.2300	         
2.0000	         0.0000	          0.1000	         
2.0000	         0.0000	          0.1000	         
2.0000	         0.0000	          0.1000	         


PELDOR/DEER step size: 8.0 ns

PELDOR/DEER time scale: 2000.0 ns

PELDOR/DEER modulation depth: 0.2

Gaussian noise enabled: False

Background function enabled: False

Integration method: Fresnel integrals

Configuration Settings

Many standard settings of SimPel can be changed either dynamically directly in the GUI or as default by creating a configuration file.

The current configuration can be opened and changed when running SimPel by pressing the “Config” button. If new configurations are set and the “Accept” button (see Fig. 5) is clicked, the new settings are adapted immediately and a new simulation is carried out.

Configuration settings
Figure 5: Current configurations of SimPel. They can be easily altered and accepted.

Alternatively, user defined configuration setting can be saved in a file called SimPel.conf. This configuration file needs to be located in the folder containing the executable or the source code. An example of a user defined SimPel.conf is shown in the listing below and the corresponding changes on the figures are demonstrated in Fig. 6.

#User defined default configurations 
r_max = 10
r_min = 2
t_min = 0
fontsize = 9.0
Lcolor = green
title_dd = False
title_time_trace = False
yticks_dd = True
ylabel_time_trace = $Form\ \ factor$

Figure 6: Comparison of standard configurations of SimPel (top, blue) and user-defined default configurations as set in the listing shown above. Many settings were changed compared to the standard configuration (the fontsize was increased, the distance range and color were changed, …)

Detaching Figures

If wished, the plots can be detached. This enables additional options to modify or configure the plots. If new simulations are carried out or other things are changed, e.g. noise is added, the figures are updated automatically.

title
Figure 7: Main GUI window of SimPel running on a Linux system (Ubuntu 16.04). Detached figures can be modified separately and saved afterwards.

Full Configuration File (SimPel.conf)

Hereafter, a complete configuration file with the default settings of SimPel is shown. This file has to be located in the same directory as the SimPel source code or executable, respectively.

SimPel.conf
# Simulation Settings
r_max = 8
r_min = 1
sigma_max = 1.1
sigma_min = 0.0
points = 881
t_min = -200
# Figure Settings
fontsize = 9
axeslabelfontsize = 8
xmargin = 0.0
ymargin = 0.1
xsize = 4
ysize = 3
colorL = blue
colorBG = red
ColorUser = grey
linewidth = 1.5
showuserTT = True
yticks_time_trace = True
yticks_dd = False
title_time_trace = True
title_dd = True
# Individual Axes Labels (Latex Math Environment Syntax)
ylabel_time_trace = $Intensity$
xlabel_time_trace = $time\ \mathrm{/ \ ns}$
ylabel_dd = $Normalised\ \ Intensity$
xlabel_dd = $r\ \mathrm{/ \ nm}$
#Save figures
autosave = True
figure_format = png,pdf
simpel/manual/index.txt · Last modified: 2018/03/26 14:24 by till