Operational Instructions
========================
Installation
Quick Tutorials
Key Words and Formats
Parameters
User defined Parameters
Constraining Equation Values
Reserved Parameter Names (Th, Lam, X, Radius)
The Key word [str_hkl_angle... !N h k l]
Special Equations
Equation operators and Functions
Occupancies and Symmetry Operators
Macros and include files
The for xdds and strs Constructs
Space Groups, hkls and Symmetry Operator Generation
hkl Intensity Files
Conventions
Further Explanation of Key words

Installation
============
Make sure that Buffers in config.sys is set to at least 40.
Copy the koalariet files into a directory called c:\koalariet.
To install Koalariet into a path different from c:\Koalariet\, change the occurrence of c:\Koalariet\ in the files temdoc8.cpp and rttem8.cpp to the new_path and copy the files to new_path.
Files that should be in c:\Koalariet\
====================================
XFIT Files
xfit.doc XFIT manual
xfit.exe XFIT executable
temdoc8.cpp
hlp.cpp
Koalariet Files
Koalariet.exe Koalariet executable
sg.exe Modified Sginfo executable
rttem8.cpp
std.inp Standard Macros
atmscat.cpp Atomic scattering details
anomdisp.cpp Anomalous dispersion details
sg.txt List of space groups
Koala.txt This file
Borland Files
cw3220.dll
bids50f.dll
owl50f.dll
Quick Tutorials
===============
Copy examples.zip to the directory c:\Koalariet\examples and unzip the file.
Run c:\Koalariet\xfit.exe
Use the "Assign" option of "File Details"/"Koalariet INP File" to assign c:\Koalariet\examples\CeO2.inp for Rietveld refinement.
Execute the menu command "Koalariet"/"Launch Koalariet".
Execute the menu command "Koalariet"/"Edit INP File".
Key Words and Formats
=====================
Input to the Rietveld program is through an input parameter file that consists of readable key words. The order of some key words are important since this is how parameters are assigned to various key word blocks. Within key word blocks order is not important; this simplifies the setting up of parameter files. For example, the key word "xdd" signifies that all information (pertaining to "xdd") occurring between this key word and the next one of the same type (in this case "xdd") applies to the first "xdd". On termination of the refinement process an output parameter file identical to the input file is created with refined values updated.
The following explains the key word formats shown below.
Text enclosed in square brackets are optional.
Key words ending in ... indicate that multiple key words of that type are allowed.
The character # corresponds to a number.
Key words with the characters R, !N or P after them are parameters. The R character correspond to parameter types that can be named and refined. Named parameters can be used in equations. The !N characters correspond to parameter types that can be named but not refined. Named parameters can be used in equations. It is necessary to place the character ! before the name. The P character correspond to parameter types that must be named as is the case for the param key word.

[global_do_errors]
[global_non_marquard]
[global_r_exp #]
[global_r_wp #]
[global_r_p_dash #]
[global_gof #]
[global_relax #] ' default 1
[global_iters #] ' default 10
[param R # [min = Eqn;] [max = Eqn;]]
xdd... yobs_in ycalc_out
[xdd_r_exp #]
[xdd_r_wp #]
[xdd_r_p_dash #]
[xdd_gof #]
[xdd_start_th2 #]
[xdd_finish_th2 #]
[xdd_exclude... # #]
[xdd_bkg R # # #...]
[xdd_convolution_step #]
[xdd_diffractometer_radius !N #]
[xdd_receiving_slit_width R #]
[xdd_divergence_fixed_angle R #]
[xdd_divergence_fixed_length R #]
[xdd_receiving_slit_length R #]
[xdd_sample_length R #]
[xdd_length_of_tube_filament R #]
[xdd_primary_soller_angle R #]
[xdd_secondary_soller_angle R #]
[xdd_specimem_tilt R #]
[xdd_linear_absorption_coefficient R #]
[fit_obj... = Eqn; [min X = Eqn;] [max X = Eqn]]
lam
[use_tan_th]
[no_normalize]
[la !N #
lo !N #
lh !N #
[num_hw... #]]...
[g_min_r #]
[g_max_r #]
[strs_scale_pk_intensity *= Eqn;]
[strs_th2_offset += Eqn;]
str...
[scale R #] ' default 1
[volume !N #]
[weight_percent !N #]
[str_mass !N #]
[str_peak_buffer_step #]
[str_lorentzian_fwhm += Eqn;]
[str_gaussian_fwhm += Eqn;]
[str_scale_pk_intensity *= Eqn;]
[str_hkl_angle... !N h k l]
[use_hkl_intensity_file file_name], or
[
[space_group #]
[hkl_numerically_generate]
[create_hkl_intensity_file file_name]
[a R #]
[b R #]
[c R #]
[al R #] ' default 90
[be R #] ' default 90
[ga R #] ' default 90
site...
name
x R #
y R #
z R #
occ atom_name R #
beq R #
[num_posns #]
[s_min_r #]
[s_max_r #]
]
[for xdds {
[more key words]
[for strs {
[more key words]
}]
}]

Comments
========
All input streams are allowed to have line and block comments. A line comment is indicated by the charecter ' and a block comment by the opening /* and closing */. Text from the line comment character to the end of the line is ignored and text within block comments are ignored. Block comments can be nested. Here are some examples.
/* This is a block comment */
space_group C_2/c ' text to the end of this line is ignored.
Parameters
==========
To refine on a parameter give it a name. The first letter of the name must be a letter. For example
site Zr x 0 y 0 z 0 occ Zr+4 1 beq b1 0.5421
here b1 is a name given to the beq parameter. Parameter names can be of any length. To not refine on the beq parameter place the character ! before b1 or simply remove b1:
site Zr x 0 y 0 z 0 occ Zr+4 1 beq !b1 0.5421
or,
site Zr x 0 y 0 z 0 occ Zr+4 1 beq 0.5421
To give a parameter a unique name then use the character @. For example
site Zr x 0 y 0 z 0 occ Zr+4 1 beq @ 0.5421
or,
site Zr x 0 y 0 z 0 occ Zr+4 1 beq @b1 0.5421
here the beq parameter will be internally given a unique name and treated as an independent parameter. In the case of @b1 the b1 text is ignored.
Parameter names can be used in equations. For example
site Zr x 0 y 0 z 0 occ Zr+4 zr 1 beq 0.5421
occ Ti+4 = 1zr; beq 0.3687
here the name zr is used in the equation "= 1zr;". This particular equation defines the Ti+4 occupancy parameter. Equations start with an equal sign and end in a semicolon.
min and max key words can be used to limit a parameter between two values. For example
site Zr x 0 y 0 z 0
occ Zr+4 zr 1 min = 0; max = 1; beq 0.5421
occ Ti+4 = 1zr; beq 0.3687
here zr will be constrained to within 0 and 1. The min and max key words are equations themselves which means that they can be in terms of other named parameters. Both min and max are optional.
Here are two examples of constraining the lattice parameters a,b,c to the same value as is required for a cubic lattice
a lp 5.4031
b lp 5.4031
c lp 5.4031
Parameter names defined more than once must have the same value. An error is displayed otherwise (i.e. if the "lp" parameter values were not all equal to 5.4031). Stated another way; more than one definition of a parameter is allowed only if the parameter values are the same.
Another means of constraining the three lattice parameters to the same value is by using equations as follows
a lp 5.4031
b = lp;
c = lp;
here the parameter "lp" is defined only once.
User defined Parameters
=======================
The param key word defines a new parameter. For example
param b1 0.2 ' b1 is th name given to this parameter
' 0.2 is the initial value
site Zr x 0 y 0 z 0 occ Zr+4 zr 1 beq = 0.5421 + b1;
occ Ti+4 = 1zr; beq = 0.3687 + b1;
here b1 is a new parameter that will be refined. This particular example shows how to add a constant to a set of beq's. In the following example b1 is used but not refined:
param !b1 0
site Zr x 0 y 0 z 0 occ Zr+4 zr 1 beq = 0.5421 + b1;
occ Ti+4 = 1zr; beq = 0.3687 + b1;
The ! character appearing in equations is ignored. In the following example b1 is still refined:
param b1 0
site Zr x 0 y 0 z 0 occ Zr+4 zr 1 beq = 0.5421 + !b1;
occ Ti+4 = 1zr; beq = 0.3687 + !b1;
User defined parameters can also have the min and max key words placed after them. For example
param crystallite_size 1000 min = 10; max = 20000;
here the parameter crystallite_size is constrained within the range 10 to 20000. Since min and max are equations they can also be functions of other parameters. As before, parameters defined using the param key word can have similar names but their values must be the same. Other than the first occurrence, further definitions, using the param key word, of the same name are ignored. This gives the flexibility of being able to define parameters within macros and to not worry about redefinition's.
Constraining Equation Values
============================
Values returned by an equation can be constrained by using a suitable definition of the equation itself. For example, in the UVW macro
macro UVW(u, v, w, u_val, v_val, w_val)
{
param u u_val min = 1; max = 2;
param v v_val min = 1; max = 1;
param w w_val min = 2; max = 2;
str_gaussian_fwhm += Sqrt(Sqrt((u Tan(Th)^2 + v Tan(Th) + w)^2));
}
the str_gaussian_fwhm equation is constrained to positive values. This definition also ensures the correct evaluation of the u, v, w derivatives.
Reserved Parameter Names (Th, Lam, X, Radius)
=============================================
The four names Th, Lam, X and Radius are reserved parameter names. User defined parameter names must not clash with these.
Th corresponds to the Bragg angle (in radians) of hkl peaks. Lam corresponds to the wavelength (lo) of the emission profile line with the largest la value. X corresponds to the measured xaxis (in degrees). Radius corresponds to the value given in the key word xdd_diffractometer_radius.
Radius and Lam can be used in any equation. Th and X can be used only in the following equations:
fit_obj = must be a function of (X)
strs_scale_pk_intensity = can be a function of (Th)
strs_th2_offset = can be a function of (Th)
str_lorentzian_fwhm = can be a function of (Th)
str_gaussian_fwhm = can be a function of (Th)
str_scale_pk_intensity = can be a function of (Th)
The Key word [str_hkl_angle... !N h k l]
========================================
The key word str_hkl_angle defines a parameter and a vector normal to the plane defined by h, k and l. It returns angles (in radians) between itself and the normal to the planes defined in a structure as hkls.
The parameter name for str_hkl_angle must be distinct from any other parameter; it must also have the character ! placed before it indicating that it is a parameter that cannot be refined. The str_hkl_angle parameter name can only be used in the following equations:
str_lorentzian_fwhm
str_gaussian_fwhm
str_scale_pk_intensity
The preferred orientation macro Preferred_Orientation is a good example of the use of str_hkl_angle.
Special Equations
=================
strs_scale_pk_intensity: xdd dependent. Scales all structure peaks belonging to a particular xdd. Used to apply the Lorentz polarization factor (see LP_Factor macro). Can be used to apply the polarization factor for neutron diffraction. Also useful for calibration of intensity versus Th for position sensitive detectors or for other User defined intensity corrections.
str_scale_pk_intensity: str dependent. Same as strs_scale_pk_intensity except local to a structure.
strs_th2_offset: xdd dependent. Offsets the Bragg 2theta positions. Used for applying the zero error and specimen displacement corrections (see Zero_Error and Specimen_Displacement macros). Can be very useful for 2theta calibration.
str_lorentzian_fwhm: str dependent. Describes the FWHM of a lorentzian which is convoluted into the structure peaks (see the CS macro).
str_gaussian_fwhm: str dependent. Describes the FWHM of a gaussian which is convoluted into the structure peaks (see the STRAIN macro).
Together with str_hkl_angle, the str_gaussian_fwhm and str_lorentzian_fwhm equations are used for anisotropic peak broadening.
The equations
strs_scale_pk_intensity
strs_th2_offset
str_lorentzian_fwhm
str_gaussian_fwhm
str_scale_pk_intensity
can be followed by the operators +=, =, *= and /=. These peform the same operations as in c. For example
a += b > a = a + (b)
a = b > a = a  (b)
a *= b > a = a * (b)
a /= b > a = a / (b)
or,
strs_th2_offset += ze  sd Cos(Th) / Radius;
has the same meaning as
strs_th2_offset = strs_th2_offset + ze  sd Cos(Th);
This last construct in not allowed; the first construct with += must be used instead.
fit_obj: A User defined fit object which can be a function of X. Used to insert User deined peaks and backgroung functions to any part of a diffraction pattern (see One_on_X macro). "min X = ...;" and "max X =..." key words appearing immediately after fit_obj's defines the xaxis range of the fit_obj (see the pseudoVoigt PV macro); if omitted the xaxis range of the diffraction pattern is assumed.
Equation operators and Functions
================================
Equations can be functions of parameter names. They can also contain the following symbols and functions (case sensitive):
() Parentheses
Pi The mathematical constant pi.
+

* The multiply sign is optional. i.e.
x * y = x y
/
^ x^y, Calculates x to the power of y.
Precedence
x^y^z = (x^y)^z
x^y * z = (x^y) * z
x^y / z = (x^y) / z
Sin(x) Returns the sine of x.
Cos(x) Returns the cosine of x.
Tan(x) Returns the tangent of x.
ArcSin(x) Returns the arc sine of x (1 <= x <= 1).
ArcCos(x) Returns the arc cos of x (1 <= x <= 1).
ArcTan(x) Returns the arc tangent of x.
Exp(x) Returns the exponential e to the x.
Ln(x) Returns the natural logarithm of x.
Sqrt(x) Returns the positive square root.
Occupancies and Symmetry Operators
==================================
Only unique positions are generated from symmetry operators. Fully occupied sites should therefore have site occupancy values of 1. This greatly simplifies the input of occupancies and at the same time increases the computation efficiency in the calculation of structure factors.
A comparison of atomic positions is performed in the generation of the unique positions with a tolerance in fractional coordinates of 1e15. It is thus necessary to enter fractions (in the form of equations) when entering fractional atomic coordinates with recurring values such as 0.33333..., 0.666666... etc. For example, use
x = 1/3; y = 1/3; z = 2/3;
instead of
x = 0.33333 y 0.33333 z 0.66667
Macros and Include files
========================
Macros are used for grouping key words. Their use can greatly simplify the construction of input files. Here's an example:
macro Cubic(code_val)
{
a code_val b code_val c code_val
}
Macros can have multiple arguments or none at all; the Cubic example above has one argument. Here are some examples of the use of Cubic:
Cubic(4.50671)
Cubic(a_lp 4.50671)
Cubic(!a_lp 4.50671)
The first instance defines the a, b and c lattice parameters without a parameter name. The second defines the lattice parameters with a name indicating a refinement of the "a_lp" parameter. The third macro defines the lattice parameters with a name preceded by the character !. This indicates that the "a_lp" parameter is not to be refined; it can however be used in equations.
Include files are used to group macros. The file std.inp contains standard macros which is a good place to view examples. The text in include files are inserted at the position of the "include" key word. For example
include "c:\Koalariet\std.inp"
places the text contained in "c:\Koalariet\std.inp" at the position of the "include" key word. Both macros and include files can be nested. Macro arguements can also contain other macros.
The for xdds and strs Constructs
================================
The "for xdds {}" and "for strs {}" constructs simplifies the construction of the input file for multiple diffraction patterns with similar structures. For example, two diffraction patterns of the same structure can be composed as follows:
xdd ... ' first xdd
' place xdd dependent key words that are not
' common to the xdd's here.
xdd_bkg ...
xdd_receiving_slit_width ...
str... ' first str
' place str dependent key words that are not
' common to the strs's here.
scale ...
xdd ... ' second xdd
' place xdd dependent key words that are not
' common to the xdd's.
xdd_bkg ...
str... ' second str
' place str dependent key words that are not
' common to the strs's here.
scale ...
for xdds {
' place xdd dependent key words that are common
' between both patterns here.
xdd_receiving_slit_width ...
CuKa2
for strs 1 to 1 {
' place key words common to the first str here.
space_group p1
site ...
}
for strs 2 to 2 {
' place key words common to the second str here.
...
}
}
An important aspect of the above construct is the "no overwrite if already there" mechanism. For example, the xdd_receiving_slit_width key word defined in the first xdd would not be overwritten by the xdd_receiving_slit_width defined in the for xdds {}. This mechanism provides a surprisingly great deal of flexibility in the construction of lengthy input files. It is not uncommon to have up to ten xdds each with three structures. For obvious reasons, parameters should not be given the @ name within "for" constructs. The effect this would have is to give unique parameter names to the parameters iterated over; the output file would contain the parameter value corresponding to the last iteration.
Space Groups, hkls and Symmetry Operator Generation
===================================================
hkls used for determining Bragg 2theata positions are read from a \Koalariet\*.hkl file with a name similar to the name of the space group. For example if the space group is F_M_3_M then the hkls are obtained from \Koalariet\F_M_3_M.hkl. If this file does not exist or if the range of hkls (found within the file) are insufficient then the hkls are generated and placed into \Koalariet\F_M_3_M.hkl. Thus hkls are generated only once during a refinement session.
Similarly symmetry operators are read from a \Koalariet\*.sg file with a name similar to the name of the space group. If the file does not exist then the symmetry operators are generated and placed into the file \Koalariet\F_M_3_M.sg.
hkl and symmetry operator details for space group names containing the characters "/" or ":" are placed in files with these characters changed to "o" and "q" respectively. The reason for this is that file names containing these characters are invalid in some operating systems (DOS for example).
By default hkls are generated using the program Sginfo by
Ralf W. GrosseKunstleve
http://www.csb.yale.edu/sginfo/
The file sg.txt contains a list of 531 space groups symbols catered for by Sginfo.
hkls for space groups not dealt with by Sginfo (C1 for example) can be numerically generated. This is accomplished by including the structure dependent switch hkl_numerically_generate. For this to operate create the symmetry file \Koalariet\c1.sg, e.g.
>Begin_XYZ
x, y, z
x+1/2, y+1/2, z
>End_XYZ
and give the lattice parameters, that are variables, names indicating that they are to be refined; in the case of "C1" all six lattice parameters should be given a unique name. The numerically generated hkls are placed into the file \Koalariet\c1.hkl.
hkl Intensity Files
===================
The key words use_hkl_intensity_file and create_hkl_intensity_file allows the creation and reuse of files containing hkls and intensities. A hkl intensity file can be very useful when a structure is either unknown or partly known. For example, creating an hkl intensity file consisting of only the structure factors from an existing structure, is as follows
include all structural parameters
lattice parameter and sites
comment out the following key words
(or macros containing these key words)
scale
strs_scale_pk_intensity
str_scale_pk_intensity
include the key word
create_hkl_intensity_file file_name
run the Rietveld program
After the hkl intensity file has been created it can be used as input with use_hkl_intensity_file file_name, instead of using sites for generating structure factors. Even though the structure would have no sites, the weight percent key word "weight_percent" can still be used; it will use whatever value is defined by the str_mass in order to calculate the weight percent.
Conventions
===========
It is useful to know the difference between key words, macros, parameter names and reserved parameter names. The conventions followed so far is as follows:
key words > all lower case
parameter names > all lower case
macro names > First letter in upper case
reserved parameter names > First letter in upper case
Further Explanation of Key words
================================
global_do_errors : A switch; calculates errors for refined parameters.
global_non_marquard : A switch; the Marquardt method of refinement is not used.
global_relax : A global relaxation that is applied to the changes in parameter values at the end of each iteration. Typically used in conjunction with global_non_marquard.
global_iters : The number of refinement cycles. The program can be prematurely terminated by pressing any key. Ctrlc aborts the program without updating the output file.
xdd_start_th2 #, xdd_finish_th2 # : Defines the xaxis refinement range.
xdd_exclude x1 x2 : Excludes the xaxis region between x1 and x2.
xdd_bkg R # # #... : Defines a Chubychev polynomial with the number of coefficients equal to the number of numbers appearing after the key word.
xdd_convolution_step # : An integer that defaults to 1. Corresponds to the number of calculated data points per measurement data point. It is useful when numerical instabilities are introduced. This can happen when a particular convolution has a small effect on the profile shape or when the measurement step is large. Only when the measurement step is greater than 0.025 degrees or when high precision is required is it necessary to increase the xdd_convolution_step.
xdd_diffractometer_radius !N # : The radius of the diffractometer in mm.
xdd_receiving_slit_width R # : The width of the receiving slit in the equitorial plane (in mm).
xdd_divergence_fixed_angle R # : The fixed divergence of the beam in the equitorial plane (in degree).
xdd_divergence_fixed_length R # : The fixed length of the sample in the equitorial plane illuminated by variable divergence slits (in mm).
xdd_receiving_slit_length R # : The length of the receiving slit in the axial plane (in mm).
xdd_sample_length R # : The length of the sample in the axial plane (in mm).
xdd_length_of_tube_filament R # : The length of the source (tube filament) in the axial plane (in mm).
xdd_primary_soller_angle R # : The angle transmitted in the axial plane by the primary Soller slits (in degrees).
xdd_secondary_soller_angle R # : The angle transmitted in the axial plane by the secondary Soller slits (in degrees).
xdd_specimem_tilt R # : The tilt of the specimen in respect to the axial plane (in mm).
xdd_linear_absorption_coefficient R # : The linear absorption coefficient of the sample (in cm1).
g_min_r #, g_max_r # : The global minimum and maximum range used for calculating bond lengths (in Angstroms).
s_min_r #, s_max_r # : Overrides the global equivalents. The site minimum and maximum range used for calculating bond lengths (in Angstroms).
scale R # : The Rietveld scale factor with no normalizing constant applied.
volume !N # : The volume of the unit cell (in Angstroms^3).
weight_percent !N # : The weight percent of the phase.
str_mass !N # : The mass of the phase.
space_group # : The space group of the phase, see sg.txt for space groups.
num_posns # : The number of positions within the unit cell generated from the symmetry operators.
