Pyanpha Wiki

A python program to use multiwavelength anomalous surface diffraction

Brought to you by: pyanpha

Program Source

Authors:

Home - Previous: 3. The Menu System

4. Program source

4.1 Types of files
4.2 Config file
4.3 Atom-file
4.4 Databases

4.1 Types of files

There are nine different types of files, which exists in python¹. An overview is given in table 4.1.

Filetype	Columns	Comment	ending
Datafiles	h k l I_n I_a I_b	The datafiles include your measured intensities and are an input file for the phase calculation. `ctrs_fn`, `sim_fn`, `sim_out_fn`, and `mod_out_fn` have to be set as a datafile.	`.dat`
Phase-files	h k l Re{F_S,n} Im{F_S,a} Re{F_S,a} Im{F_S,a} Re{F_S,b} Im{F_S,b}	The phase-files contains your retrieved surface structure factor amplitudes and phases. But it is saved as real and imaginary part of the complex structure factor. Your `data_fn` and `phase_calc_fn` are phase-files.	`.phs`
Atom-files	Label Element x y z oc DW	There are three atom-files: One for your bulk (`bulk_fn`), for your surface (`surf_fn` in case of simulating data) and your anomalous scatterers (`anom_fn`).	`.atm`
Bulk-files	h k l Re{F_B,n} Im{F_B,a} Re{F_B,a} Im{F_B,a} Re{F_B,b} Im{F_B,b}	Bulk files have the saved values of the bulk sutructure factors. They are saved in the same way as phase-files. `fbulk_fn` and `bulk_out_fn` have to be bulk-files	`.blk`
Errorfiles	h k l s_n s_a s_b	Errorfiles contain the errors assorted to the intensities from your datafile. Only `error_fn` has to be an error-file.	`.err`
Positionfiles	x y z N	Position files contain retrieved atomic positions.	`.pos`
ED-files	binary file	ED files can be loaded in python with `utils.load_zip(filename.zip)` and contain the following keys: `’ed’`: your ED, `’fm’`: the retrieved surface structure factors, `’fc’`: the iterated surface structure factors, `’support’` : the given support, `’meas’` : your diffraction pattern, `’r’` : the upsampling factor. `ed_fn` has to be set to an ED-file.	`.zip`
DCAF-files	binary file	This files can be used as initial model in DCAF, an iterative phase retrieval algorithm.	`.dbm`
Configfiles	ASCII file	The config file will be discussed in section 4.2.	`.cfg`

Table 4.1: A summary of the different filetypes, which are used in pyanpha.

4.2 Config file

The config file sets up all the parameters and files, needed to use the algorithm. It has eight parts, which shall be discussed here. First the input filenames:

[Input_fns] bulk_fn = bulk.atm surf_fn = surf.atm anom_fn = anom.atm ctrs_fn = ctrs.dat error_fn = ctrs.err data_fn = data.phs sim_fn = sim.dat fbulk_fn = bulk.blk

The first three parameters are the atom-files. You do not really need a surf_fn, if you do not plan to make simulations. The other two are required. ctrs_fn specifies your input datafile, where your intensities are saved. The error_fn specifies your error-file. This is only needed, if phs_method is set to either min or com. If you do not have an error-file, you can simply input -1 and the square roots of your intensities will be used as errors. data_fn specifies your phase-file, where your retrieved surface structure files are saved. It is needed to calculate an ED. sim_fn is the file which you can use to replace a part of your intensity datafile in the modify data menu. The fbulk_fn specifies a bulk structure factor file. This is only needed, if you have set bulk_toggle to 1.

Next the unit cell parameters are defined: a, b, and c are the lattice constants of your crystal in Angstroms. alp, bet, and gam are the angles between the unit-cell vectors in degrees.

[UCparams] a = 3.904500 b = 3.904500 c = 3.904500 alp = 90.000000 bet = 90.000000 gam = 90.000000

For your experiment, you need three different energies, which are defined in ergn, erga, and ergb. They have to be given in keV.

[Energies] ergn = 16.000000 erga = 16.110000 ergb = 16.500000

angle is the incidence angle at which you have performed your experiment. This is needed to calculate the damping factor in your bulk structure factors. It only has a minor influence.

[Instrument] angle = 0.500000

Next are inputs about your recorded diffraction pattern: h_max and k_max should be integers of the highest Miller indices, which you have measured. Be aware that if you have for example only measured the 50L rod, but no other reflection with h = 5 you will have zeros for all the other 5KL rods. l_max is the highest l-value, which you have recorded and should be a float at an anti-Bragg position. l_points is the number of points, which you have from l = 0 to l = l_max.

The two parameters low_l and high_l are used in the modify data menu. If you decide to either cut or replace data then those two parameters are called. Then you need to specify the symmetry of your diffraction pattern, which are given in table 4.2

[DiffPatt] h_max = 4 k_max = 4 l_max = 4.500000 l_points = 226 low_l = 0.000000 high_l = 0.000000 symmetry = 5 rb = 0 noise = 0.000000 I0 = 1.000000

rb is used in the calculation of the ED and specifies, how many data-points left and right of a Bragg peak should be cut. noise can be used in the generation of simulated data. It adds so many percent of random noise on your intensities. Finally I0 is used in the determination of your surface structure factors. It scales your intensities by this factor.

parameter	symmetry	symmetry operations
0	S₁
1	S₂	,
2	S_M	,
3	S₄	, , ,
4	S_2MM	, , ,
5	S_4MM	, , , , , , ,
10	S₂	,

6	S₃	, ,
7	S_3M	, , , , ,
8	S₆	, , , , ,
9	S_6MM	, , , , , , , , , , ,

Table 4.2: Surface symmetries, which are available in pyanpha. The four symmetries below the horizontal line are not yet completely implemented.

Next are several conditions that can be applied, h_con and k_con, if you do not want every CTR to be included in the calculation of your surface structure factors. The condition is that h modulus h_con must be zero and analog for k. peak specifies, if every integer l is a Bragg peak (0) or only every other (1). In the latter case, for both even h and even l no substrate Bragg peaks are present, and the odd h odd l signal are considered as Bragg peaks. This is used, when it removes data-points specified by rb.



[Conditions]

h_con = 1

k_con = 1

peak = 0

iter_step = 0

bulk_toggle = 0

phs_method = cut

steps = 20

select = 1

atom = Sr

mf1f2_ergn = 0.0, 0.0

mf1f2_erga = 0.0, 0.0

mf1f2_ergb = 0.0, 0.0

In order to retrieve the missing structure factors close to Bragg peaks, you can set iter_step to 1. Then it will charge-flip all the negative electron density to positive and do an inverse Fourier transform again and fill these holes with the retrieved structure factors. bulk_toggle is available if you prefer to use your bulk atom-file and calculate the bulk structure factors (0) or if you prefer to use a .blk file where they are already saved. The latter could be used if you would like to have different bulk and surface unit cells. 
phs_method is available if you prefer to have your surface structure factors calculated. There are cut, min, and com, where the latter two use the error function R(z), which is given in equation 4.1:


(4.1)




where z is the surface structure factor to determine, R(z) is a measure for the goodness of fit of every z, F_S,i are the sets of surface structure factors and s_i their associated error.

In an ideal case, the three circles will intersect at exactly one point. Since in reality, 

  they will deviate from this situation, there will be up to six intersecting points.

  cut checks now for the three intersecting points, which are closest to each 

  other and then returns its average value. In case, two circles do not intersect, the

  middle of the closest distance is assumed to be an intersecting point. This method is the 

  fastest, but it might fail in the case of large statistical errors.
min returns the z with the minimal R(z).
com returns the center of mass z of the 20 z with lowest R(z).

The grid for the search of R(z) is limited by the extents of the three circles. Its resolution is given by steps. If you increase steps, your accuracy of the retrieved surface structure factor might be higher, but the calculation time increases as well.







Figure 4.1: The three circles shown in the figure are the possible surface structure factors at the three different energies. They should in principle intersect at one point, in reality they do not. The rainbow colouring represent the values of R(z). The black square is the result for min, the magenta diamond for com, the cyan circle for cut.



You can retrieve the surface structure factors at all three energies. With select, you select, which one of them you would like to use. 1 returns them for ergn, 2 returns them for erga, and 3 returns them for ergb.
Your anomalous element is specified with atom. It does not matter, if it has the same ionisation, simply enter here the chemical element. Usually, pyanpha uses the tabulated values for f′ and f′′ of your anomalous scatterer. If you prefer to use your measured values, you can specify them in mf1f2_ergn, mf1f2_erga, and mf1f2_ergb for the three energies, respectively.
The next two parameters are determining your Gaussian window width and your support. All your data is multiplied by a Gaussian with width width and variable q, the scattering factor. The support determines, how many voxels in the z-direction should not be zero. If iter_step is not set to 1 then this does not affect your ED at all.

[WinFunc]

width = 0.820000

support = 60

The last functions are your output functions: sim_out_fn is the filename under which your simulated data should be saved. It should be a .dat file. bulk_out_fn is the filename, if you create a bulk-file, where your bulk structure factors are saved. It should be a .blk file. The mod_out_fn specifies the default filename, if you modify your data in the modify data menu. phase_calc_fn sets the filename of the phase-file, which is created by a run of calculate phases. It should be a .phs-file. Last there is your ED-filename, which is specified with ed_fn, which should be a .zip-file.

[Save_fns]

sim_out_fn = ctrs.dat

bulk_out_fn = sim_bulk.blk

mod_out_fn = mod_ctrs.dat

phase_calc_fn = data.phs

ed_fn = ed.zip

 4.3 Atom-file 

The atom-file contains all the information about the atoms within a unit cell. It has seven columns: Label Type x y z Q U. Within one atom file every label has to be unique. The atomic type is first the chemical element and then the ionic configuration: In the example below, you will have Ga³⁺, Nd³⁺, and O²⁻. The appendix of an ion is not required. x, y, and z are the unit-cell coordinates of an atom. Q is the occupation of the atomic site and * U* is the Debye-Waller factor.

#Label atom x y z occ u

GaB Ga3p 0.500 0.500 0.000 1.00 0.00557

NdB Nd3p 0.000 0.000 0.500 1.00 0.00787

OB1  O2m 0.500 0.000 0.000 1.00 0.00927

OB2  O2m 0.500 0.500 0.500 1.00 0.00927

OB3  O2m 0.000 0.500 0.000 1.00 0.00927


4.4 Databases

In the beginning of the file asd.py you can select, which scattering factor databases are used.

#######################################################

#                                                     #

# Which Database should be used for f0?               #

# There are two databases available: IUCR and ACTA,   #

# which have to be assigned to the variable f0_toggle #

#                                                     #

f0_toggle = ’f0_ACTA’                                 #

#f0_toggle = ’f0_IUCR’                                #

#                                                     #

# Which Database should be used for fp?               #

# There are three databases available: IUCR, CXRO,    #

# and Chantler (NIST), which have to be assigned to   #

# the variable fp_toggle                              #

#                                                     #

fp_toggle = ’fp_IUCR’                                 #

#fp_toggle = ’fp_Chantler’                            #

#fp_toggle = ’fp_CXRO’                                #

#                                                     #

#######################################################


The q-dependent part of the atomic form factor is given in either f0_IUCR: International Tables for Crystallography Volume C: Mathematical, Physical and Chemical Tables, 500 (1992). or f0_ACTA: D.Waasmaier and A. Kirfel, Acta Crystallogr. A 51, 416 (1995). The two databases contain the coefficients for each different ion.

f0_IUCR is a nine coefficient approximation for the range 0.0 A \< sinq/l \< 2.0 A, and uses the formula
(4.2)




f0_ACTA is the extension to a eleven coefficient approximation, which is accurate for the range from 0.0 °A \< sinq/l \< 6.0 A. It adds one more Gaussian to the equation and returns:
(4.3)




The energy-dependent part of the atomic form factor is given in either fp_IUCR: S. Brennan and P.L. Cowan, Rev. Sci. Instrum. 63, 850 (1992). , fp_Chantler: C.T. Chantler, Journal of Physical and Chemical Reference Data 24, 71 (1995), or fp_CXRO: B. L. Henke, E. M. Gullikson, and J. C. Davis, Atomic Data and Nuclear Data Tables 54, 2 (1993). The energy range for f′ and f′′* are given in the table below:



Database
E_min
E_max




fp_IUCR
1 keV
25 keV


fp_Chantler
10 eV
433 keV


fp_CXRO
30 eV
30 keV





Table 4.3: Energy-ranges of the databases



Back to top
Home

¹If you do not count python files