MStruct software basic example - How to install and run.

Contents

  1. Installation
    1. Download and Unzip
    2. Setup Text Editor
    3. Plotting Utility - GNUPlot, Matlab, Octave
  2. Example 1: Stress Evaluation in a Thin Film Sample
    1. Introduction
    2. Running program
    3. Input and Output files
    4. Input Parameters file
      1. Job type
      2. Measured Data file
      3. Background
      4. Instrumental function
      5. Crystal structure
      6. Absorption correction
      7. Additional effects
        1. Size broadening
        2. Phenomenological Strain broadening
        3. Refraction correction
        4. Residual stress
      8. Output data file
      9. Refinement Section
      10. Refinement Parameters

Installation

The program has no GUI at present time. It runs in a command line. Text editor and an external plotting utility are required. To install program (under Windows) you may need to:

  1. Download and unzip the program and additional files.
  2. Configure your text editor to display program input parameters file tidily.
    (syntax highlighting of C++ type and an 8 spaced Tab width are recommended)
  3. Find some plotting utility for data in a multiple column text format.

The 1st step - Download and Unzip

Folder with the program should contain at least these files:

The folder can contain some additional files - some scripts and example files, which will be described later.

You can try double-click the mstruct.exe file now. You should see a console running, asking you for a job type.

mstruct program running
The MStruct program running in a console, waiting for your answer.
Write "0" for data-refinement and press "ENTER".

The 2nd step - Setup Text Editor

The program is running in a console window without GUI. It is prompting you questions about calculation options, waiting for your response. After all program's questions are answered, the program executes a calculation. The program usually prompts you for hundreds of questions and its impossible for human being to answer them all. It is a good idea to prepare your answers in a text file and redirect the console input from this text file. You need a simple text editor to edit such a file. It is recommended to use an editor with syntax highlighting to see the input file in a pretty format. There are many suitable text editors for Windows. Free editor called PSPad can be a good choice.

The example file tio2-film-stress1.imp is an input parameter file for the first tutorial showing evaluation of residual stress in a thin TiO2 film from a single 2Theta scan with a constant incidence angle. You can find this file in the downloaded archive together with the program. To display this file in a pretty format it is recommended to set a tab width in your editor to be equivalent to 8 spaces and switch on syntax highlighting settings for *.imp files to be a C++ type. To use the program you of course need known nothing about C++. Enabled syntax highlighting should just make orientation in the input parameters file easier (numbers and comments have different color than normal text).

PSPad - Tab Width PSPad - Highlighters
PSPad - Tab Width Settings PSPad - C++ Highlighter Settings for *.imp files


When you open the tio2-film-stress1.imp input parameter file you should see properly formatted text.

If you see the input parameter file for the first time, you may see many words and numbers making no sense. This is OK. But you should no see randomly scattered words and numbers! Tab width and syntax highlighting setup is not obligatory installation step.

PSPad - tio2-film-stress1.imp
PSPad - Opened tio2-film-stress1.imp input file in formatted text format with syntax highlighting

The 3rd step - Plotting Utility

Powder pattern refinement in the mstruct program produces output data file in a column text format. Typical data output file contains in the 1st column (2Theta) values in degrees; in the 2nd column observed intensity (Iobs), in the 3rd calculated intensity (Icalc) and in the 4th differences (Iobs-Icalc) are printed.

# 2Theta/TOF Iobs Icalc Iobs-Icalc Weight Comp0
15.0250 120.0000 111.3516 8.6484 0.0083 7.6486
15.0750 123.0000 110.8423 12.1577 0.0081 7.6234
15.1250 120.0000 110.3364 9.6636 0.0083 7.5983
15.1750 120.0000 109.8340 10.1660 0.0083 7.5735
15.2250 107.0000 109.3351 -2.3351 0.0093 7.5487
…

You need an utility for plotting data in this format to examine visually result of the fit or simualtion. Various sophisticated programs can be used. You can use such tools as a free GNUPlot system, commercial expensive Matlab or you can make yourself a smart Excel worksheet. Very simple GNUPlot and Matlab/Octave scripts are provided with the program. An example of how to plot data by GNUPlot or in Matlab and Octave is shown here.

Plotting data in GNUPlot

The simplest way how to use the GNUPlot program for plotting data in Windows is to:


  1. Open GNUPlot terminal window (running program wgnuplot.exe - it is located in the gnuplot\bin directory).
  2. Navigate to the mstruct directory, where the output data file is located. Type: 
    > cd 'd:\mstruct'
    where d:\mstruct is your mstruct directory. Note that you should use the 'apostrophe marks'.
  3. To plot data in the output data file tio2-film-stress1.dat you can use either a) the direct GNUPlot command or b) a simple mstruct_view.gp gnuplot script.

    In the case a) type: (in a single line) 
    > plot 'tio2-film-stress1.dat' u 1:2 w p,
 'tio2-film-stress1.dat' u 1:3 w l,
 'tio2-film-stress1.dat' u 1:4 w l
    to plot data using columns 1 and 2 with points, columns 1 and 3 with lines and columns 1 and 4 with lines.

    In the case b) type: 
    > call 'mstruct_view.gp' 'tio2-film-stress1' 'sqrt'
    Note that 1) the file suffix ".dat" is omitted and 2) the name of called script mstruct_view.gp and the part of the output data file name are enclosed in 'apostrophe marks'. The additional word parameter 'sqrt' specifies that a square root intensity scale should be used.

    To replot data saved in the same file after next calculation, you can repeat the previous command or simply type in the GNUPlot terminal:

    > replot

    To zoom in the plot use the right mouse button. To zoom out you must type:

    > set autoscale xy; replot

    If you are plotting data from the GNUPlot terminal, it is useful to start program calculation directly from the terminal. You can use a mstructcommand preceded with an exclamation mark ("!...") as: 
    > !mstruct < tio2-film-stress1.imp >
 tio2-film-stress1.out

    Plotting in GNUPlot
Plotting data in Matlab and Octave

For plotting data in Matlab or its free alternative - Octave (from version 3.2) - you can use Zdeněk's Matlab scripts. Download and unpack them in the program directory. There are few files:

  • read.m — matlab function to read various diffraction formats.
    (A data files with # symbol at the beginning of the line marking line as a comment and with data in columns can be loaded as 'gnu' or 'gnu1' format.)
  • mstruct_view.m — read and plot mstruct output data (requires the read.m file)

With Matlab follow these steps:


  1. Open Matlab command window
  2. Navigate to the mstruct directory, where the output data file is located. Type: 
    >> cd d:\mstruct
    where d:\mstruct is your mstruct directory.
  3. To plot data file tio2-film-stress1.dat type: 
    >> mstruct_view('tio2-film-stress1')
    Note that the file suffix ".dat" is omitted.

    You can use an additional argument and plot also hkl diffraction indexes of the anatase phase: 
    >> mstruct_view('tio2-film-stress1',
 {'diffData_Anatase'})

    To replot data repeat the plotting command.

If you are plotting data in the Matlab/Octave environment, it is useful to start program calculation directly from Matlab command line. You can use either a mstructcommand preceded with an exclamation mark ("!...") or function system(...) as: (in a single line) 
>> !mstruct < tio2-film-stress1.imp >
 tio2-film-stress1.out
or 
>> system('mstruct < tio2-film-stress1.imp >
 tio2-film-stress1.out')

Plotting in Matlab


Example 1 - Stress evaluation in a thin film sample

This example describes residual stress evaluation in a thin TiO2 film. It illustrates how the program is used. The film is a single phase (anatase), crystallites are large (bigger than 150 nm) and there is only small microstrain in the sample (e ~ 0.2%). The sample is only slightly textured. The most interesting attribute of the sample from the XRD analysis point of view is a possible residual stress in the film. The measurement was done in parallel beam geometry with Cu-Alpha radiation as a 2Theta scan with a constant incidence angle Omega = 0.5 deg. The 2Theta angular resolution for this experiment was about 0.3 deg. For peak position corrections two effects are included:

  1. correction for the refraction effect at the vacuum-film interface,
  2. peak position correction due to simple bi-axial residual stress state in the film.

The program runs in a command line. The program prompts user for questions about calculation details and parameters. The program prints various type of information and the resulted values of fitted parameters at the end of the refinement. It is useful to store the calculation parameters in an input file (tio2-film-stress1.imp) and to catch the program text output into an output text file, which can be later checked. You can run the program from the command line in a program working directory (D:\mstruct here) by a command using input ('<') and output ('>') redirection: 

 mstruct < tio2-film-stress1.imp > tio2-film-stress1.out
or in the GNUPlot and Matlab environment you can directly use the system calling command (exclamation mark - !): 
 ! mstruct < tio2-film-stress1.imp > tio2-film-stress1.out
or in Matlab also: 
 system('mstruct < tio2-film-stress1.imp > tio2-film-stress1.out')

This is an example of the part of the input parameters file (tio2-film-stress1.imp): 

// Job type
0					job type (0-data refinement,1-grid refinement)

// Input Data Filenames and Formats
tio2-film-stress1.xy     0		data filename (2th,obs(,sigma)),data format type (0-xy,1-xysigma)			
0.623     				maximum sin(theta)/lambda

// Background
general		   2			background filename/(general), background type/(number of background components)
invX		   1			background component type (chebyshev,invX,interpolated),X-func.type(0-X,1-sin(Th))
chebyshev	   1			background component type (chebyshev,invX,interpolated),X-func.type(0-X,1-sin(Th))
2					polynomial degree (number of coefficients-1)
-45   33      7				values of coefficients (starting with zero-order)
  0    0      0				coefficients refinement flags (0-refined,1-fixed)
…

This is an example of some parts of the output parametrs file (tio2-film-stress1.out): 

 Beginning program ....
job type (0-data refinement,1-grid refinement)
data filename (2th,obs(,sigma)),data format type (0-xy,1-xysigma)
maximum sin(theta)/lambda
background filename (2th,bkg),background type (0-linear,1-cubic spline)
…
finished cycle #10/10. Rw=0.22525288164616->0.22525644302368
Results after last refinement :(35 non-fixed parameters)
R-factor  : 0.07420510798693
Rw-factor : 0.22525644302368
Chi-Square: 5756.30273437500000
GOF       : 1.46968150138855
Variable information : Initial, last cycle , current values and sigma
Scale_bkgData_InvX                  20.00000000       20.80443192       20.80817223        0.10634584   
Scale_diffData_Anatase               0.00000430        0.00000432        0.00000432        0.00000003   
Background_Coef_0                  -45.00000000      -44.96256256      -44.95737839        0.22215381   
Background_Coef_1                   33.00000000       32.32260513       32.31866455        0.30044675
…

You see in the input and output files some equivalent lines. It is useful to think awhile about how the program works and what it requires. At the beginning the program prompts you a question 'job type (0-data refinement,1-grid refinement)', as you can see on the picture somewhere above. You will answer '0' and than the program asks you 'data filename (2th,obs(,sigma)),data format type (0-xy,1-xysigma)', etc. … You can see these questions in the output file. They are are printed there because the program text output was redirected (by '>') to the file. The input file should theoretically contain only prepared answers. But it contains more! It is because:

  1. Empty lines, tabs and multiple spaces are ignored.
  2. Lines beginning with '//' are comments and are ignored.
  3. You can add a comment to lines with parameters/options (as you can see usually the appropriate program question is rewritten there). This comes as inspiration from old Fortran's programs. The program simply reads all parameters needed (e.g. if it prompts for two numbers, it reads two numbers) and ignores a rest of the line.

Using comments, blank spaces and line-comments you can format the input file in more clear form.

Brief description of input parameters file
Job type
// Job type
0					job type (0-data refinement,1-grid refinement)
Measured Data file
// Input Data Filenames and Formats
tio2-film-stress1.xy     0		data filename (2th,obs(,sigma)),data format type (0-xy,1-xysigma)			
0.623     				maximum sin(theta)/lambda

Two columns data file with experimental data should look like:

     15.0250           120
     15.0750           123
     15.1250           120
     15.1750           120
     …
Background
// Background
general		   2			background filename/(general), background type/(number of background components)
invX		   1			background component type (chebyshev,invX,interpolated),X-func.type(0-X,1-sin(Th))
chebyshev	   1			background component type (chebyshev,invX,interpolated),X-func.type(0-X,1-sin(Th))
2					polynomial degree (number of coefficients-1)
-45   30     10				values of coefficients (starting with zero-order)
  0    0      0				coefficients refinement flags (0-refined,1-fixed)
Instrumental function
// Instrumental Parameters
 0.5					incidence angle (deg)-2Theta scan, negative value-2Theta/Theta scan
// X-pert MRD parallel beam - 0.27 deg
0.06246   0. 0.009211   		instrumental profile params (W,U,V) MPD-Pixcel-variable slits
0.002135     0.147385       		instrumental profile params (Eta0,Eta1)
1.0  0.0  0.0   60.			instrumental profile params (Asym0,Asym1,Asym2,Asym2ThetaMax(deg))
Cu   0.111				wavelength type (Cu,CuA1),linear polarization rate(f), 
//                                      (A=0.8,f=(1-A)/(1+A)=0.111 graphite mon.,f=0. unmonochromatized)
0					number of excluded regions
//20.0   25.0				min2Theta, max2Theta (deg)
Crystal and Diffraction data

Here we become to more crystallographic parts of the problem.

// Crystal Phases
1					number of phases
	
// the 1st phase
diffData_Anatase			phase name (diffDataCrystal)

// the 1st phase - crystal data
structures.xml   Anatase		filename, name (filename-crystal xml file,name-crystal name)

A section for each crystal phase follows with :

Thin film absorption correction
// the 1st phase - thin film absorption correction
300.    0.   470.			absorp corr params:thickness(nm),depth(nm),abs.factor(1/cm) (TiO2,dens=3.75g/cm3)
0					nb of texture phases
1	1				hkl file(0-don't use,1-generate,2-free all,3-read),print HKLIntensities(0-no,1-y)
Micro-structural effects - Size broadening
// the 1st phase - physical line broadening
4					number of additional effects

// the 1st phase - Size broadening - lognormal distribution of crystals diameter (median - M, shape - Sigma)
SizeLn	       sizeProfAnatase		broadening component type (pVoigt(A),SizeLn,dislocSLvB,HKLpVoigtA),effect name
200.0     0.3				M(nm),sigma
Micro-structural effects - Microstrain broadening
// the 1st phase - Strain broadening - simulated with pseudoVoigt function
//                                   - only U-Cagliotu param. (W=V=0.) and shape Eta0 (Eta1=0) params. refined
pVoigtA	       strainProfAnatase	broadening component type (pVoigt(A),SizeLn,dislocSLvB,HKLpVoigtA),effect name
0.0  0.  0.				profile params (W,U,V)
0.0       0.				profile params (Eta0,Eta1)
1.   0.   0.   60.			profile params (Asym0,Asym1,Asym2,Asym2ThetaMax(deg))
Micro-structural effects - Refraction correction
// the 1st phase - Refraction reflection position correction
RefractionCorr   refractionCorrAnatase  effect type,effect name
crystal					chi0 set directly-value,calc from-crystal,calc from chem.-formula
1.					relative density
Micro-structural effects - Residual stress effect
// the 1st phase - Residual stress reflection position correction - simple stress model
StressSimple   stressCorrAnatase  	effect type,effect name
Reuss-Voigt     0.			XECs model, stress (GPa)
// material C11 C12 C13 C33 C44 C66 constants (in GPa) - in the format: C11 value C12 value etc.
C11 320  C12 151  C13 143 		// anatase Cij (GPa)
C33 190  C44  54  C66  60		// ref: M.Iuga,Eur.Phys.J.B(2007)58,127-133 
0.3					model weight (0..Reuss,1..Voigt)

After a wide section including all various physical effects affecting width, shape and position of diffraction maximas there are two sections. One setting output data file and the another one specifying refinement parameters. For most of the refinement procedure the user need to modify especially this last part.

Output file name
// output filename
tio2-film-stress1.dat  			output filename
Refinement parameters
// number of refinement iteractions
15					nb of interactions
// number of parameter which will be set
14					nb of params

This is the first part of the refinement parameters section.
Refinement parameters section
// begin of the parameters section
// *********************************************************************************

Scale_diffData_Anatase   		* param name
1.e-6					scale
4.0  0.01				value, derivative step
0					limited (0,1), min, max
sizeProfAnatase:M			* param name
10.					scale
270.0       2.0              		value, derivative step
1 2. 500.				limited (0,1), min, max

Two parts above show two typical sections of the last part of the input parameter file, where actual values and refinement flags for parameters are finally set.

PARAMETERNAME				* param name
SCALE					scale
VALUE  DERIVSTEP			value, derivative step
LIMITED  MIN  MAX			limited (0,1), min, max

A section for each parameter has 4 lines.
Authors: Z. Matej, J. Vojtisek, M. Dopita, L. Horak, R. Kuzel.
x-ray group, School of Physics, Charles University in Prague
Scientific data, MAX IV Laboratory, Lund University
version 0.1
Friday the 18th of August, 2023