1. Lecture 2-3 TOPAS Launch Mode

2. TOPAS: Macro language and algebra system
Arnt Kern
Title picture can be exchanged in the masterslide.

3. TOPAS: Macro Language and Algebra System
Contents
TOPAS: Macro language and algebra system - Overview
Structure Determination in GUI Mode
Brute force Monte Carlo
Simulated Annealing
Charge Flipping
3D Fourier Analysis
TOPAS: Macro Language and Algebra System

4. TOPAS: Macro language and algebra system - Overview

5. TOPAS TOtal Pattern Analysis Solutions
TOPAS supports two modes of operation:
"GUI mode" = Graphical User Interface
"Launch mode" = Direct editing of an input file in a text editor
GUI Mode - Parameters Window
Launch Mode - Text Editor
TOPAS: Macro Language and Algebra System

6. TOPAS TOtal Pattern Analysis Solutions
Flexible macro language
Computer algebra system for function minimization and for the application of linear and non-linear restraints
Support of user-defined refinement parameters / refinement models
Probably the most significant aspect of TOPAS is that it supports user-defined equations in an entirely general way such that highly sophisticated/specialized refinement models can be introduced without access to the source code
TOPAS: Macro Language and Algebra System

7. TOPAS GUI Mode - Launch Mode
Parameters Window
GUI Mode
Input File
Launch Mode
Kernel
Stand-alone, automated operation possible (TC.exe)
TOPAS: Macro Language and Algebra System

8. TOPAS GUI Mode - Launch Mode
TOPAS supports two modes of operation:
"GUI mode" = Graphical User Interface
Refinements require input to the "Parameters Window"
Functionality limited to most frequently used refinement models
Ideal for most single line fitting and quantitative Rietveld analyses
"Launch mode" = Direct editing of an input file in a text editor
Refinements are controlled by the TOPAS script language
Offers the full functionality / flexibility of TOPAS
Mandatory for structure determination and user-defined refinement models
TOPAS: Macro Language and Algebra System

9. TOPAS GUI Mode - Launch Mode
TOPAS supports two modes of operation:
"GUI mode" = Graphical User Interface
Writes / reads PRO files by default
Can export INP files for Launch Mode operation
Limited import of INP files (must be restricted to features available in GUI mode, otherwise an error message will be thrown)
"Launch mode" = Direct editing of an input file in a text editor
Reads INP files
Writes OUT files (identical format)
Does not read / write PRO files
INP files : Refinement model; data are kept separate (!)
PRO files : Refinement model + data + user interface settings
TOPAS: Macro Language and Algebra System

10. TOPAS Launch Mode - Script Language
Input in Launch Mode is through an input file (*.INP) consisting of readable "keywords" and "macros"
Macros comprise groupings of keywords
Standard macros are defined in TOPAS.INC; this is an important file to view
Keywords and standard macros represent the default TOPAS functionality; for a full list refer to the Technical Reference manual
An input file contains keywords and macros as required to describe all contributions to the powder pattern
TOPAS: Macro Language and Algebra System

11. TOPAS Input File Format
The file format is free text, but case sensitive
Keywords have the important property of "scope"
e.g. the keywords bkg and str have xdd scope and thus can only be placed after an xdd keyword
Optional scope-dependent indentation assists in the readability of input files
Within keyword blocks such as str order is not important
TOPAS: Macro Language and Algebra System

12. TOPAS Input File Example - Step by Step
The simplest of input files
TOPAS: Macro Language and Algebra System

13. TOPAS Parameter Refinement Flags
GUI
A parameter is flagged for independent refinement by giving it an arbitrary name. Alternatively the character can be used; internally the parameter is given a unique name and treated as an independent parameter. Examples:
a lpa , or
a @ In the GUI "Refine" is synonym to
No flag signals a parameter not to be refined. Alternatively the character "!" can be placed in front of a parameter name. Examples:
a ,
a !lpa In the GUI "Fix" is synonym to "no flag"
TOPAS: Macro Language and Algebra System

14. TOPAS Parameter Refinement Flags
GUI
GUI Mode
Refine independently
Fix
Launch Mode
Refine independently
a @ 'Refine b lpb c @
Fix
a 'fix = no flag b !lpb
TOPAS: Macro Language and Algebra System

15. TOPAS Parameter Constraints
GUI
Parameter names can be used in equations providing a mechanism for introducing linear and non-linear constraints
Example: Constraining three lattice parameters to the same value: Parameters with names that are the same must have the same value. Another means of constraining the three lattice parameters to the same value is by using equations.
a lp a lp b lp b = lp; c lp c = lp;
TOPAS: Macro Language and Algebra System

16. TOPAS Parameter Constraints
GUI
Example: 1) Refinement of site occupancies in C4AF:
site Fe1 x 0 y 0 z 0 occ Fe+3 occfe 1 site Fe2 x 0 y 0 z 0 occ Al+3 = 1-occfe;
2) The "min" and "max" keywords limit parameter values:
site Fe1 x 0 y 0 z 0 occ Fe+3 occfe 1 min=0; max=1; site Fe2 x 0 y 0 z 0 occ Al+3 = 1-occfe;
Occupancies cannot get <0 and >1
TOPAS: Macro Language and Algebra System

17. TOPAS Parameter Constraints
GUI
Site Occupancies, e.g. Forsterite:
Values:
Mg1 : ~0.90
Fe1 : ~0.10
Codes:
Mg1
= 1 - Fe1;
TOPAS: Macro Language and Algebra System

18. TOPAS Parameter Constraints
GUI
Min / max values for site occupancies, Forsterite ctd.:
TOPAS: Macro Language and Algebra System

19. TOPAS Parameter Constraints
GUI
Constrain site occupancies with lattice parameters:
The simplest mathematical expression for Vegard’s law for a binary solid solution A-B is:
a = a0A (1−X) + a0B(X)
where a is the lattice parameter, X is the mole fraction of component B and a0A and a0B are the lattice parameters of pure components A and B respectively.
A Composition B
Lattice parameter
a0A
a0B
TOPAS: Macro Language and Algebra System

20. TOPAS Parameter Constraints
Constrain site occupancies with lattice parameters, e.g. Goethite:
GUI
Codes:
= 1 - ( * b_goethite) /100
= ( * b_goethite) /100
Schulze (1984)
TOPAS: Macro Language and Algebra System

21. TOPAS Parameter Constraints
GUI
Special positions, e.g.
x=y=z
x, y=-x
x, y=2x
, ,
...
Why bother?
E.g. use of 3rd party structure data from structure databases such as ICSD and many others
TOPAS: Macro Language and Algebra System

22. TOPAS Parameter Constraints
GUI
Special position: x = y = z
Codes:
x = !O1_x;
y = O1_x;
z = O1_x;
TOPAS: Macro Language and Algebra System

23. TOPAS Parameter Constraints
GUI
Special position: x = -y
Codes:
x = !O2_x;
y = -O2_x;
TOPAS: Macro Language and Algebra System

24. TOPAS Parameter Constraints
GUI
Special positions: /
Often, Wykhoff positions are not given in structure data, therefore this decision can't be automated
Codes:
x = 1/3;
y = 2/3;
TOPAS: Macro Language and Algebra System

25. TOPAS Parameter Constraints
GUI
It is mandatory to enter a fractional coordinate for a special position in the form of an equation such as = 1/3, =1/6, etc. in the Codes page, instead of entering a value with re-occuring digits such as , , etc. in the Values page. The correct parameter value will be calculated automatically from the equation and displayed in blue color. Not adhering to this convention may lead to severely wrong refinement results!
TOPAS: Macro Language and Algebra System

26. TOPAS: Macro Language and Algebra System
TOPAS Macros
Macros comprise groupings of keywords
Simplify reading of INP files
Allow easy reuse of code
Simple:
macro cubic {
a lp
b = lp;
c = lp; }
More flexible:
macro cubic(cv) {
a cv
b = Get(a);
c = Get(b); }
TOPAS: Macro Language and Algebra System

27. TOPAS Macros Macros can be placed in any INP file.
Default macros in TOPAS.INC are included into INP files by default; they can be freely redefined. If possible keep the original macro and only work on a copy. Use a user-defined macro name. E.g: "Cubic"  "MyCubic"
Make sure to backup any changes!
The GUI uses many macros defined in TOPAS.INC
The file LOCAL.INC is loaded by default and can be used for user-defined macros
Different files can be included by using the "#include filename" directive
TOPAS: Macro Language and Algebra System

28. TOPAS User-Defined Parameters
The "prm" keyword defines a new parameter
prm b ' b1 is the name given to this parameter ' 0.2 is the initial value
The "min" and "max" keywords limit parameter values
prm b min=0; max=10;
TOPAS: Macro Language and Algebra System

29. TOPAS User-Defined Parameters
Example: Isotropic thermal parameters
B versus U notation: B = U * 8 * Pi2
Derive U from B:
site Pb x 0 y 0 z 0 occ Pb 1 beq Biso 1.5
prm Uiso = Biso/(8 Pi^2); :0
Refine U directly:
prm Uiso 0
site Pb x 0 y 0 z 0 occ Pb 1 beq = Uiso(8 Pi^2); :0
TOPAS: Macro Language and Algebra System

30. TOPAS User-Defined Refinement Models
Example: Cagliotti Formula (Cagliotti et al., 1958)
prm u 0 prm v 0 prm w 0.01
Original function, as implemented in most software:
gauss_fwhm = Sqrt(u Tan(Th)^2 + v Tan(Th) + w)
There is no provision made to prevent the peak width from going negative: The software will crash frequently while refining ("SQRT of FWHM is negative")
Do it yourself (and better !!):
gauss_fwhm = Sqrt(Sqrt(u Tan(Th)^2 + v Tan(Th) + w)^2)
Squaring the function before taking the square-root keeps the FWHM positive
TOPAS: Macro Language and Algebra System

31. TOPAS Do it Yourself!
Develop new methods / refinement models / ... , or take advantage of work published by others
Sometimes its amazingly simple... !
TOPAS: Macro Language and Algebra System

32. TOPAS: Macro Language and Algebra System
TOPAS Do it Yourself!
Example: Data weighting
Toraya H., 1998, J. Appl. Cryst., 31,
Prefers 1/Yo2 over 1/Yo
In TOPAS:
weighting = 1/Yobs; versus
weighting = 1/Yobs^2;
For structure determination it may be useful to give smaller intensities a higher weight:
weighting = 1/SQRT(Yobs);
 "Structure_Solution_Weighting" macro
TOPAS: Macro Language and Algebra System

33. TOPAS TOtal Pattern Analysis Solutions
At first, much of TOPAS's functionality has never been explicitely coded or even foreseen by its makers, but has been developed and made available by the user's community in the form of macros / example data, e.g.
External standard method for QPA (O'Connor & Raven, 1988; macro courtesy of Schmidt)
Phenomenological model of anisotropic peak broadening in powder diffraction (Stephens, 1999; macros courtesy of Dinnebier)
PONKCS method for QPA (Scarlett & Madsen, 2006)
Dealing with energy dispersive data (e.g. David, 2006; Madsen, 2007)
Parametric refinements (Stinton & Evans, 2007)
Distortion mode refinements (Campbell et al., 2007)
Dealing with preferred orientation in SDPD (Whitfield, 2008)
Robust refinements (David, 2001; macro published by Stone et al., 2009)
WPPM (Scardi & Leoni, 2001; some macros published by David, 2010)
Description of turbostratically disordered layer structures (Ufer et al., 2004; example published by Wang et al., 2011)
Popa model of anisotropic peak broadening in powder diffraction (Popa, 1998; macros developed by Wang, 2015)
...
TOPAS: Macro Language and Algebra System

34. TOPAS TOtal Pattern Analysis Solutions
At first, much of TOPAS's functionality has never been explicitely coded or even foreseen by its makers, but has been developed and made available by the user's community in the form of macros / example data, e.g.
External standard method for QPA (O'Connor & Raven, 1988; macro courtesy of Schmidt)
Phenomenological model of anisotropic peak broadening in powder diffraction (Stephens, 1999; macros courtesy of Dinnebier)
PONKCS method for QPA (Scarlett & Madsen, 2006)
Dealing with energy dispersive data (e.g. David, 2006; Madsen, 2007)
Parametric refinements (Stinton & Evans, 2007)
Distortion mode refinements (Campbell et al., 2007)
Dealing with preferred orientation in SDPD (Whitfield, 2008)
Robust refinements (David, 2001; macro published by Stone et al., 2009)
WPPM (Scardi & Leoni, 2001; some macros published by David, 2010)
Description of turbostratically disordered layer structures (Ufer et al., 2004; example published by Wang et al., 2011)
Popa model of anisotropic peak broadening in powder diffraction (Popa, 1998; macros developed by Wang, 2015)
...
TOPAS: Macro Language and Algebra System

35. TOPAS: Macro Language and Algebra System
TOPAS Wiki
User Forum / FAQ
User macros up-/download area
Tutorials
...
Hosted by:
John Evans Durham University Durham, UK
TOPAS: Macro Language and Algebra System

36. Structure Determination in GUI Mode
TOPAS: Macro Language and Algebra System

37. Structure Determination in GUI Mode
Perform a Pawley / LeBail fit
Fix background, profile, lattice parameters
Perform a "classic" Rietveld refinement with random atom positions
Additionally check
Calculate errors
Continue after convergence
Randomize as a function of errors
Brute force Monte-Carlo approach
Works with small structures
Requires good data quality
No temperature regime
No use of bond length, angle, and torsion constraints
TOPAS: Macro Language and Algebra System

38. Structure Determination in Launch Mode Simulated Annealing
TOPAS: Macro Language and Algebra System

39. TOPAS 1. Step: Pawley Refinement
xdd Pbso4.raw CuKa5(0.001) LP_Factor(26.37) Radius(173) Full_Axial_Model(12, 15, 12, 5.1, 5.1) Divergence(1) Slit_Width(0.2) ) 0.0) hkl_I space_group P_b_n_m ) 0.01)
Fix all parameters after refinement
TOPAS: Macro Language and Algebra System

40. TOPAS 2. Step: Structure Determination
Auto_T(10) xdd Pbso4.raw CuKa5(0.001) LP_Factor(26.37) Radius(173) Full_Axial_Model(12, 15, 12, 5.1, 5.1) Divergence(1) Slit_Width(0.2) bkg One_on_X( , ) ZE( , ) str space_group P_b_n_m a b c site Pb occ Pb+2 1 beq 1 site S occ S 1 beq 1 site O occ O-2 1 beq 1.5 site ... CS_L( , ) Strain_L( , )
Perform simulated annealing
Add structure model
TOPAS: Macro Language and Algebra System

41. TOPAS 3. Step: Structure Refinement
xdd Pbso4.raw CuKa5(0.001) LP_Factor(26.37) Radius(173) Full_Axial_Model(12, 15, 12, 5.1, 5.1) Divergence(1) Slit_Width(0.2) ) ) str space_group P_b_n_m site Pb z occ Pb site S z occ S site O z occ O site ) )
Refine all appropriate parameters
TOPAS: Macro Language and Algebra System

42. TOPAS Structure Determination
Required macro, default:
Auto_T : Initiates simulated annealing
Useful helper macros and keywords, optional but recommended:
Decompose : Uses peak maxima only, speed!
Structure_Solution_Weighting : Low intensities have higher weight
Normalize_FCs : Keep coordinates between -1 and 1
append_fractional : Fractional coordinates listing
append_bond_lengths : Bondlength listing
Out_CIF_STR : Writes CIF file
view_structure : Displays structure
Useful helper keywords, can help to identify special positions:
occ_merge S / occ_merge_radius
TOPAS: Macro Language and Algebra System

43. TOPAS Rigid Body Editor Fractional or Cartesian Coordinates
Example: Octahedron prm r 2 rigid point_for_site Zr point_for_site O1 ux = r; point_for_site O2 ux = -r; point_for_site O3 uy = r; point_for_site O4 uy = -r; point_for_site O5 uz = r; point_for_site O6 uz = -r;
This sequence can be read in English:
Define a distance parameter r with a value of 2
Define a rigid body
Place the Zr atom at 0, 0, 0
Place the O1 atom at r, 0, 0
...
TOPAS: Macro Language and Algebra System

44. TOPAS Rigid Body Editor Z_Matrix Notation
Example: Benzene ring prm r 1.3 rigid z_matrix C1 z_matrix C2 C1 =r; z_matrix C3 C2 =r; C1 120 z_matrix C4 C3 =r; C2 120 C1 0 z_matrix C5 C4 =r; C3 120 C1 0 z_matrix C6 C5 =r; C4 120 C1 0
This Z-matrix can be read in English:
Define a distance parameter r with a value of 1.3
Define a rigid body
Place C1 at 0, 0, 0
Place C2, at a distance of r away from C1
Place C3, at a distance of r away from C2, making an angle of 120 with C1 and C2
Place C4, at a distance of r away from C3, making an angle of 120° with C3 and C2, and making a torsion of 0° with C1, C2 and C3
...
TOPAS: Macro Language and Algebra System

45. TOPAS Rigid Body Editor Torsions
Probably the most straightforward possibility to introduce torsions is using the Rotate_about_points macro
TOPAS: Macro Language and Algebra System

46. TOPAS Structure Determination
Rotation and translation of rigid bodies
‘ rotate all previously defined points: 0)
‘ translate all previously defined points: 0)
TOPAS: Macro Language and Algebra System

47. Structure Determination in Launch Mode Charge Flipping
TOPAS: Macro Language and Algebra System

48. TOPAS: Macro Language and Algebra System
TOPAS Charge Flipping
Example: Mo2P4O15 charge_flipping cf_hkl_file 020pn.hkl space_group Pn a b c be Tangent(.3, 30) load f_atom_type f_atom_quantity { MO = 84; P = 168; O = 630; }
Initiates Charge Flipping
hkl-I intensity file
Optional: Use of Tangent formula
Optional: Identification of atoms
TOPAS: Macro Language and Algebra System

49. Structure Determination in Launch Mode Fourier Analysis
TOPAS: Macro Language and Algebra System

50. TOPAS 3D Fourier Analysis
Example: PbSO4
Difference Fourier analysis to locate missing oxygen positions
Final structure after atom picking
TOPAS: Macro Language and Algebra System

51. TOPAS 3D Fourier Analysis
Example: PbSO4 fourier_map 1 fourier_map_formula = Fobs - Fcalc; load f_atom_type f_atom_quantity { Pb = 0; S = 0; O = 16; }
Initiates Fourier analysis
Fourier map type
Optional: Identification of atoms
TOPAS: Macro Language and Algebra System