Pyanpha Wiki

A python program to use multiwavelength anomalous surface diffraction

Brought to you by: pyanpha

The Menu System

3. The Menu system

3.1 Config file menu
3.2 Atoms menu
3.3 Simulating Data
3.4 Modifying Data
3.5 Calculating phases
3.6 Calculating ED
3.7 Grid search
3.8 Plot ED or structure factor
3.9 Extracting atomic positions

While the last chapter only gave a brief introduction to a small fraction of the possibilities pyanpha has to offer, this chapter goes through each menu item by item and explains what they do. After running the program in a shell, the root menu of pyanpha, which is shown below, appears. It offers twelve different options, which shall be described in this chapter.

############################################## PYANPHA ############################################## f: Config file menu t: Atoms menu s: Simulate data m: Modify data c: Calculate phases e: Calculate ED g: Grid search o: Open ED p: Plot ED or structure factors a: Extract atomic positions z: Change working directory x: Exit

Some of the items have their own submenu and will be described in a separate section. The options are f to open the config file menu (cf. Section 3.1), t to open the atoms menu (cf. Section 3.2), s to open the simulate data menu (cf. Section 3.3), m to open the modify data menu (cf. Section 3.4), c for the calculate phases menu (cf. Section 3.5), e to open the calculate ED menu (cf. Section 3.6), g opens the grid search menu (cf. Section 3.7) p opens the plot menu (cf. Section 3.8), and a opens the extract atoms menu (cf. Section 3.9).

Furthermore one can open an ED file with o. In grey, all current ED files in this directory are shown. To begin a project, you should change your directory using z, where you can enter a new directory path. Entering ˜ will go to your pyanpha root directory. It is however not possible to create directories within pyanpha. To exit pyanpha, you can press x, after which you will be asked, if you want to save your config file. Doing this will enable you to continue from your current position at a later date.

3.1 Config file menu

The config file (.cfg) contains the parameters required for simulating or modifying diffraction data and calculating the phases and the ED. The individual parameters are described in section 4.2.

Config file menu

-l: Load config file

 e: Enter config file manually

 s: Show config file

 n: Edit a user defined variable

 v: Save config file

 b: back

You have the choice to load (l), show (s), or save (v) a config file. Entering e offers you the possibility to enter one parameter after the other. If you only want to change some parameters, you can enter n. It will show you first the list of all parameters and their current values. You can enter then the name of a variable and its value to update the desired parameter. An example is shown below:

Enter the name of the variable you wish to edit: support Enter its new value (70) : 60 support : 70 >> 60 are you done [y] ? y

If you do not answer y in the final question you can change another parameter. If you entered the dialog by mistake, you can leave it by entering q.

3.2 Atoms menu

Three different types of atom-files (.atm) exist; the bulk atom-file is needed to calculate the bulk structure factor, the anomalous scatterers atom-file which provides the information for the calculation of the surface structure factor phases, and finally, the surface atom-file which is used to calculate the surface structure factors for simulated data. The menu offers the following choices:

Atoms menu

-s: Show atoms

 e: Edit atoms

 l: Load atoms

 r: Reload atoms

 v: Save atoms to file

 b: back

You have the possibility to load (l), show (s), or save (v) your atoms-files. Of course, you can simply change your atom-file in a text editor. However, it is often more convenient to directly change the atoms within pyanpha. This can be done in the edit atoms submenu (e). The submenu will ask you, which atoms you would like to change: bulk (b), anomalous scatterers (a), or surface (s). It then offers you three choices:

Label Element x y z occ DW

Sr4 Sr2p 0.000 0.000 3.625 1.00 0.00787

Sr5 Sr2p 0.000 0.000 4.675 1.00 0.00787

Sr6 Sr2p 0.000 0.000 5.725 1.00 0.00787

---c: Change atom

   d: Delete atom

   a: Add atom

   q: quit

First you see the loaded atoms from the atom-file you have selected. You can then either change, delete, or add an atom by typing c, d, or a, respectively. You have to enter then the atom’s label and in case of adding or changing the atom, it’s element (including its ionization state, if desired, by adding p/m for plus/minus, i.e., 2p for Sr²⁺), coordinates, occupation, and Debye-Waller factor. However, if you change atoms within this submenu, while the parameters used by pyanpha are changed, the atom-file wont be changed, unless you save it.

The last choice you have is to reload an atom-file (r). This can be necessary, if you have edited an atom-file within the atoms menu and you would like to get the original file back.

3.3 Simulating Data

Before you are planning an experiment you might want to look at the impact of the anomalous scattering on the measured intensities and test the feasibility of an experiment. The data simulation menu allows you to do this.

Simulating data

-l: Load config file

 e: Enter config file manually

 s: Show config file

 n: Edit a user defined variable

 r: Run config file

 c: create bulk structure factors

 p: Plot datafile

 a: Plot the absorption edge

 b: back

The first four choices (l, e, s, and n) have already been mentioned in section 3.1. However, if you want to enter the config file manually, it will only ask you for these parameters, which are required to simulate data. An overview over all the parameters in the config file is given in section 4.2. Entering r will run the simulation with the parameters specified in your config file. It will save the datafile as specified by sim_out_fn in the datafile. At the end of the simulation, you will be asked if you want to have a look at the simulated data. This produces the same output as plot datafile (p), which will be described later. The create bulk structure factors option (c) simulates only the bulk structure factors. The output will be saved in the bulk file (.blk), given by the variable bulk_out_fn in the config file, which consists of the columns h, k, l, Re{F_B,n}, Im{F_B,n}, Re{F_B,a}, Im{F_B,a}, Re{F_B,b}, and Im{F_B,b}. This file can be used instead of specifying the bulk atom-file once it is created. To use it, you have to change the bulk_toggle variable in the config file to 1.

The plot datafile option (p) offers you the possibility to look at your simulated or real data.

Plotting real and simulated data

--s: Change simulated datafilename

  r: Change real data filename

  p: Plot

  q: quit

Figure 3.1: The left graph show simulated data only. The graph’s appearance would look the same for real data. The right graph shows both simulated and real data. In both graphs, all three different energies are displayed.

Your default simulated and real datafile-names, the sim_out_fn and ctrs_fn variables from the config file are used, respectively. They can be changed with s and r. However, changing the filenames here does not affect the filenames given in the config file.

To plot the data, press p. You are asked then to enter the Miller indices h and k of the rod and if you want to look at simulated or real data, or at both.

H : 2 K : 1 Simulated data (s), Real data (r), both (sr) : s

An example output is given in Fig 3.1
Lastly, you can also plot the absorption edge by entering a. This will return a plot of the tabulated f′ and f′′ values of your anomalous scatterer, which is specified in the config file as the atom parameter. You have to specify the plot range:

Enter lower energy limit [keV]: 15.5 Enter higher energy limit [keV]: 17

The result is the plot shown in figure 3.2. In the lower panel, you can also see that measured values for f′ and f′′ can substantially deviate from the tabulated values.

Figure 3.2: The upper panel show f′ and f′′ as a function of energy. The three vertical lines mark your specified energies. The lower panel shows an f′/ f′′ plot. The three specified energies are plotted as red, green, and blue points. If you have entered measured f′ and f′′ values, these will be plotted instead.

3.4 Modifying Data

The modifying data menu offers you several possibilities to change your datafile. Be this by adding different datapoints to your dataset either from another dataset or due to interpolation or by modifying it by cutting or scaling the data.

Modyfing data

-l: load alternative data

 i: interpolate data

 c: cut data

 s: shape data

 h: set (h,k) to precise value

 t: transform h,k,l

 d: scale data

 o: sort data

 r: remove non-integer rods

 p: plot data

 b: back

The first item (l) is intended to merge datafiles. For example, the low-l part of a dataset can often be missing. These missing structure factors will lead to a negative shift in the ED and can be overcome by adding simulated data. Therefore, you can specify the new datafile which you want to add to your datafile (given by ctrs_fn in the config file), the range in **l which you want to replace, and the new concatenated datafile-name. This new datafilename is saved in the config file as mod_out_fn. If the replacement was successful, the program will update the ctrs_fn variable in the config file with mod_out_fn. In all the eight other options, you can use all kinds of data (.dat, .blk, and .err files). It will always suggests the file, you have specified as ctrs_fn in your config file as your input file and will suggest mod_out_fn as an output filename. But unlike in the alternative data loading options, it will not replace ctrs_fn in the end with mod_out_fn.

The next option (i) is interpolation. If you have missing data-points and would like to interpolate them, you can do this in this menu. The interpolation is performed only from the lowest to the highest datapoint, i.e., it omits missing low- and high-l data. There are two interpolating functions available, spline and linear. There is also the possibility to “cut” the data, i.e., remove data-points. There is the option, if you want, to cut either a certain range in l (l) or to cut data-points around a Bragg peak (p). In the case of an l-range, you have to specify the lowest and highest l which you want to cut and in the case of the Bragg peaks, the number of points you want to cut. Cutting 1 means you only cut the Bragg peak itself, while 2 means it will cut one data point to the left and one to the right of the Bragg peak. You can further specify if you would like to cut the Bragg peaks in all the rods (0), i.e., all integer l in all CTRs, or with 1, you cut even l integers at an even h, and odd l at
an odd h value.

The shape data option (s) will simply add a −1 at all positions between 0 and l_max, specified in your config file, where there is no data available in the datafile you have specified. This is sometimes necessary, if two datafiles (like your .dat and .blk file) have different shapes.

If your input data has decimal places, which have not been rounded to the next integer value, the algorithm might fail. Therefore there is the possibility (h) to round h and k to the next integer. The program will not affect your l values, however, i.e., they might still deviate in their decimal places from your step-size. If the Miller indices of your data are in a different coordinate system than the one in which you want to perform your analysis, you have the option the transform them (t). This can for example be the case, if your surface unit cell is smaller - or larger - than the unit cell, you specified in your measurement. You have to enter the transformation matrix, which will be multiplied with the Miller indices specified in your data file:

If you perform a coordinate transformation, it might be necessary to rescale your data, which you can do with d. This will automatically scale the scaling factor which you have entered with your intensities or amplitudes. In both h, k, l transformation and scaling data, you can enter simple mathematical formulae, i.e., 1/2 instead of
0.5.

Sometimes, when putting together data-files, the order of the data-points can be corrupted. Therefore there is the option to sort the data (o). This will sort your datafile first by h, then by k, and last by l. Be sure that you first have set h and k to integer values, otherwise, you could get an unwanted output.

If you made for example your surface unit cell smaller by a coordinate transformation, you might now have non-integer rods, or you had them already from your measurement. If they do not show any anomalous signal, the phase can not be calculated. If you want to get rid of them, you can remove them with r. Be aware that if you have not set h and k to precise values, it will not remove those data-points.

Finally, the plot data option (p) is the same as that found in the simulated data menu (section 3.3).

3.5 Calculating phases

This menu utilises the core algorithm, where the phases are retrieved, according to the parameters set in your
config file.

Calculating phases

-l: Load config file

 e: Enter config file manually

 s: Show config file

 n: Edit a user defined variable

 r: Run config file

 b: back

Similar to the load config-file and simulating-data file menu, you have the options of loading a saved config file (l), entering the config file manually (e), showing the current values of the config file (s), and editing a specified variable in the config file (n). It will only request those parameters, which are necessary for the calculation of the phases.

The program offers you the option to define which energy you want to calculate the surface structure factors for, the select parameter in the config file can be set to 1, 2, and 3 for the three specified energies, respectively. You can choose between calculating the bulk structure factors with the given parameters from the config file, or to use a separate file, where the structure factors are given. Furthermore, there are three ways in which the surface structure factor is determined: cut, min, and com. These three methods are described in detail, like all the parameters of the config file, in section 4.2.

To calculate the phases, you have to run the algorithm with r. It will use the intensities in the file specified in ctrs_fn and save them in the file specified by phase_calc_fn.

3.6 Calculating ED

You have the option to load a saved config file (l), enter the config file manually (e), show the current values of the config file (s), and edit a specified variable in the config file (n). It will only ask you for the parameters which are necessary for the calculation of the ED.

Having retrieved the phases you can now directly Fourier transform your data and get an ED, available in this menu by pressing r. The algorithm uses the surface structure factors, specified by data_fn in the config file - this is not necessarily the same variable as the output of the calculated surface structure factor file from the previous section - and saves it in the file specified by ed_fn.

Calculating ED

-l: Load config file

 e: Enter config file manually

 s: Show config file

 n: Edit a user defined variable

 r: Run config file

 b: back

The algorithm applies a Gaussian window - its width is determined by width in the config file - to your surface structure factor, completes your data to fill a full Fourier array from −h_max to h_max, −k_max to k_max, and −l_max to l_max using the symmetry given in your config file. It adds a −1 to the empty positions. Furthermore, you can specify your support, i.e., the range of non-zero electron density (ED), how many data-points close to the Bragg peak should not be included in the calculation of the ED (rb), and if missing data-points should be filled with an iterative step (iter_step>/code>). All parameters will be explained in detail in section 4.2.


 3.7 Grid search 

One way to find the proper parameters to retrieve a proper ED is to change to atom-files in the atoms menu and changing parameters in the config file, and then running the calculate phases, and calculate ED routines. Alternatively you can use the grid search menu:

Grid search ED

Label Element x y z occ DW

  Sr4 Sr2p 0.000 0.000 3.600 1.00 0.00787

  Sr5 Sr2p 0.000 0.000 4.600 1.00 0.00787

  Sr6 Sr2p 0.000 0.000 5.600 1.00 0.00787

Enter atom label and parameter (e.g. Sr4occ) or

z0 for the offset of anomalous scatterers from bulk

c for the c-axis of the surface atoms

I0 for the scaling factor

separated by a space or

connected by a + to be parallel searched.

What parameters should be searched?


The menu initially displays the current anomalous scatterer parameters given specified by anom_fn in the config file and include any additional changes from the atoms menu, if you have made any. It then asks you which parameters you want to have searched. You can enter as many as you like. Parameters available include:

z0: This is the offset from the bulk atoms to your surface atoms. In the above

  expressed setup, z0 is currently 3.6. This shifts all your anomalous scatterers

  by the same amount. If it is set to 0, the anomalous scatterer would lie at the next position 

  a bulk atom would lie if this structure would continue. However, it is recommended to set it

  to a higher value such that you retrieve some of the substrate atoms as a reference.
c: This is the c-axis of your anomalous atoms. Its start value is calculated 

  by taking the first two atoms - the closest to the bulk - in your anomalous scatterers atom-

  file. However, if the have the same z, it uses 1 as default c.
I0: This is the scaling factor applied to the intensities given by your datafile

  (ctrs_fn), before determining the phases. Its default value is the one given in

  the config file by I0.
Atoms: You can refine also atoms parameters. This is done by using an atoms label (e.g.

  Sr4) and a parameter (x, y, z, 

  occ , DW). For example, if you like to refine the z position of 

  the top atom in the above case, the parameter would be called Sr6z.
Combinations: Connecting two parameters by a + will search them together. For 

  example Sr4z+Sr5z+Sr6z is the same search parameter like z0.

  However, you can only combine atoms parameters and not z0, c, or 

  I0.

Next, it will ask you, how many iterations the grid search shall perform. Thereafter, you will be asked about your step-size and how many steps you want to do within an iteration. The steps are done in both positive and negative direction. If you enter more than one iteration, you can also specify a decrease in the step-size. You can leave the grid search at any time by entering q.
Then you will be asked, if you want to search in the “interactive mode”. There are two ways, which value will be assigned to a parameter after a grid search. Using the interactive mode, you can specify, which one of the steps you would like to use. If you are not using the interactive mode you have to specify which criterion the grid search will minimise/maximize:

Would like to search in interactive mode? [y]/n : n

Selection criterion : "sum" : sum(ED)

                      "max" : max(ED)

                      "pos" : sum(ED>0)

                      "neg" : sum(ED<0)

                      "R1"  : sum(fm-fc)/sum(fm)

                      "R2"  : sum((fm-fc)ˆ2)/sum(fmˆ2)

                      "avg" : Average over range


The first six criterion are self explanatory. However, the seventh will return to your initial values of the parameters after the search. But the retrieved ED is calculated as the averaged ED of all the EDs, calculated during the search.
In the case of the iterative mode, you will be asked, which columns of the ED you want to have plotted:

Enter x coordinates (0 ... 8) : 0 4

Enter y coordinates (0 ... 8) : 4 0

This will plot four lineplots of cuts along the z-direction of the ED at (0,4),(0,0),(4,4),and (4,0). The coordinates have to be given in c++ style, i.e., the first column is denoted as 0, the second as 1, etc. The output is shown in figure 3.3. You can enter as many coordinates as you like, it will show all possible combinations of x and y. The legend will always be put in the last subplot.







Figure 3.3: The figure shows four lineplots of cuts along the z-direction of the ED. Each step is shown in a different colour. The legend is always shown in the last subplot, where the step-number and the search parameter value are given. In this example a search of the c-axis is shown with 3 steps in each direction.



When the grid search is finished you will be asked if you want to have a look at the ED. If you answer “yes”, you can enter the coordinates of the columns, which will be plotted. This works the in same way as described previously. After this you can either take the new values, which were found by the grid search, or maintain your initial values.
 3.8 Plot ED or structure factor 

In order to judge, if your enter anomalous scatterers and config parameters were proper, you should have a look at your ED. This can be done in the plot ED menu.

Plot ED or structure factor

-l: lineplot

 s: surfplot

 c: slice

 f: ctr plot

 d: 3D plot of ED

 e: manipulateED

 b: back


The first option is a lineplot (l). You have to enter two coordinates (x and y, y and z, or x and z). This will return a cut along the direction, along which you have not entered a coordinate. An example is shown in the left panel of figure 3.4.
You can also make cuts perpendicular to an axis and monitor a plane. This is done with surfplot (s). Here you have to enter one value of a coordinate, at which height and perpendicular to which you would like to receive a cut. An example is shown in the right panel of figure 3.4. The number of electrons are colour-coded.


Figure 3.4: On the left, a lineplot of a cut along the z-axis through the ED is shown. The coordinates are given in the title of the figure, which is the (4,4), which corresponds to (0.5,0.5) in unit-cell dimensions. You can clearly see three Ga, three Ti,and six 0 atoms. The right shows a surfplot perpendicular to the z-axis. It displays one unit-cell with three atoms, one in the centre, and two at the borders of the unit-cell.



There are two more ways to display your ED, which are more for illustrative purposes. The first one is a slice through the ED (c). Here you have to enter the same input as was made for a surfplot. It differs from surfplot in that the number of electrons are shown by peaks of differing height and colour. In cases of a cut perpendicular to the x or y axis, it shows three unit-cells, in case of a cut perpendicular to the z axis, it plots three-by-three unitcells.

An example is shown on the left panel of figure 3.5. The other plot-option is a 3D isosurface plot (d), where you only have to enter the support, which shall be shown. An example is shown on the right panel of figure 3.5. To interact with both the sliceplot as well as the 3D plot, you can use the following keys or mouse buttons, which are self explanatory:

w,s - wire frame or surface applied to all actors

j - joystick like mouse interactions

t - trackball like mouse interactions

3 - 3D stereo - it isn’t written for this.

r - reset camera view

f - change focal point

e,q - exit application

Button 1 - rotate

Button 2 - pan

Button 3 - zoom

ctrl-Button 1 - spin

shift-Button 1 - move

ctrl-shift-Button 1 - zoom




Figure 3.5: The left panel shows slice perpendicular to the x-axis through the ED. The figure shows nine Nd, nine Sr, and fifteen O atoms. The right panel is a three dimensional isosurface plot of the retrieved ED. Both are shown after upsampling the ED by a factor of 3.



You can also have a look at the retrieved amplitudes and phases of the surface structure factor (f). You have to enter the Miller indices h and k, and the output - be it amplitude (a), phase (p), or both (ap) - you would like to be have plotted. It will show you both fmeas and fcalc. The first are the retrieved surface structure factors, while the second sets the ED outside of the support to zero, and, if iter_step is on, charge-flips the negative part of the ED and then performs an inverse Fourier transform. Ideally, the two should coincide. Examples of this output is shown in figure 3.6.



Figure 3.6: All three graphs show the 20L rod’s surface structure factors. On the left are the amplitudes, in the middle, the phases. Both fmeas and fcalc were plotted. On the right, both amplitudes and phases of fcalc are shown.



The “info about ED” option returns some information about the ED which can be accessed by pressing i. First, the dimensions of the ED array, second, three sums: The sum of the whole ED array, the sum of all elements of the ED array - which are positive - and the sum of all elements of the ED array - which are negative. There is also the maximum, minimum, and mean value of the ED, and finally, there are two goodness of fit values - R₁ and R₂. These have in principal nothing to do with the ED, F_m and F_c are not fmeas and fcalc, but the retrieved value for the total amplitude and the measured value. They are calculated as follows:
(3.2)



(3.3)




An example output is shown here:

The ED is a an array of the shape :  (9, 9, 450)

The total sum of the ED is        :  7398.22524016

The positive sum of the ED is     :  7433.50948712

The negative sum of the ED is     :  -35.2842469669

The maximum value of the ED is    :  95.5537574792

The minimum value of the ED is    :  -2.19033700236

The mean value of the ED is       :  0.202969142391

R1 of is                          :  0.000366186577141

R2 of is                          :  0.000200290041566


This information can be helpful, when you optimise your parameters because there should not be any negative ED in principal. Your maximum value should be approximately in the range of the heaviest atom in your structure, and the total sum should be of similar order of magnitude to the number of electrons of which you trying to retrieve.

The last item is the manipulate ED submenu.

Manipulate ED

--e: export ED

  u: upsample ED

  r: reload ED

  p: export DCAF ED

  b: back


The first option is used to export your ED (e), i.e, if you have upsampled your ED and would like to save that to a .zip file. Be warned, If this was the case, it will still check that you are sure, because upsampling causes the files to get rather large. The upsampling is done by the second item (u). This increases your array of surface structure factors by adding zeros. This does not affect your position or the physical meaning of the ED, but it increases the plotting resolution by “smoothing” your ED, as can be seen in figure 3.5.
If you have upsampled your ED but you would like to go back to your normal ED, you can simply reload the ED by pressing r. Alternatively, you could load your ED in the root menu with the open ED option. The last item is the export DCAF ED item. This enables you to export your ED to a dbm-file, which can be read in in DCAF, an iterative phase retrieval algorithm.
 3.9 Extracting atomic positions 

The last menu item (a) is reserved for when you are confident with your ED and would like to know where your atoms sit. Here you can extract the atomic positions.

Extracting atomic positions

-l: load ED

 e: extract positions

 b: back


You can simply load an ED (l) if you want a different ED-file to the last one which you have calculated. Or if you have calculated an ED in your current run and you would like to extract this one then you can press e and it will be used.
The program then asks you about the threshold. This is the percentage of the value of highest peak in your ED, which will be still recognised as an atom. Next you have to enter your support, which usually should be the same as the support you have entered in your config file, and the number of atoms which should be retrieved. Lastly, you can enter a filename for your position-file (.pos).
You will then be asked, if you would like to have a look at the retrieved atoms, which produces a 3D ball-plot. It will plot atoms with the about the same number of electrons in the same colour. Therefore you have to enter a percentage which defines the tolerance between two atoms, differing in ED, to be plotted in the same colour. An example is shown in figure 3.7.


Figure 3.7: The figure shows all the found atoms: In green and red, the Nd atoms, in cyan the Sr atoms, in magenta, the Ga atoms, in yellow the Ti atoms, and in blue the oxygens. So the difference between the lowest Nd atom with the other two was greater than the defined threshold so it was drawn in a different colour.




Back to top