Trace: • manual_part_2
This is an old revision of the document!
Table of Contents
9 Macros and Include Files
INP files are preprocessed. The preprocessor comprises directives beginning with the character # and macros. Macros are used for grouping keywords. The directives are of two types, global directives and directives that are invoked on macro expansion, they are:
Directives with global scope
macro $user_defined_macro_name { … }
#include $user_defined_macro_file_name
#delete_macros { $macros_to_be_deleted }
#define, #undef, #ifdef, #ifndef, #else, #endif
Directives invoked on macro expansion
#m_ifarg, #m_else, #m_endif
#m_code, #m_eqn, #m_code_refine, #m_one_word
#m_argu, #m_first_word, #m_unique_not_refine
9.1 The macro directive
Macros are defined using the macro directive; here's an example:
macro Cubic(cv)
{
a cv
b = Get(a);
c = Get(a);
}
Macros can have multiple arguments or none at all; the Cubic macro above has one argument; here are some examples of the use of Cubic:
Cubic(4.50671)
Cubic(a_lp 4.50671 min 4.49671 max 4.52671)
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 refinement of the a_lp parameter. In the third example, the a_lp parameter is preceded by the character !. This indicates that the a_lp parameter is not to be refined; it can however be used in equations. The definition of macros need not precede its use. For example, in the segment:
xdd…
Emission_Profile ' this is expanded
macro Emission_Profile { CuKa2(0.001) }
Emission_Profile is expanded to “CuKa2(0.001)” even though Emission_Profile has been defined after its use.
Macro names need not be unique; in cases where more than one macro have the same name then the actual macro expanded is determined by the number of arguments. For example, if the macro Slit_Width(.1) is used then the Slit_Width(v) macro is expanded. On the other hand if the macro Slit_Width(sw, .1) is used then the Slit_Width(c, v) macro is expanded.
Macros can also expand to other macro names. For example, the macro Crystallite_Size expands to CS and since CS is a macro then the CS macro will be expanded.
9.1.1 Directives with global scope
#include $user_defined_macro_file_name
Include files are used to group macros. The file TOPAS.INC contains standard macros; a good place to view examples. Text within include files are inserted at the position of the #include directive, thus the following:
#include “my include file.inc”
inserts the text within “my include file.inc” at the position of the #include directive. The standard macro file TOPAS.INC is always included by default.
#delete_macros { $macros_to_be_deleted }
Macros can be deleted using the #delete_macroskeyword, for example,
#delete_macros { LP_Factor SW ZE }
will delete all macros previously defined with the names LP_Factor, SW and ZE including macros of the same name but with different arguments.
#define, #undef, #ifdef, #ifndef, #else, #endif
The #define and #undef directives works similar to the c preprocessor directives of the same name. #define and #undef is typically used with #ifdef, #else, #endif directives to control macro expansion in INP files. For example, the following:
#ifdef STANDARD_MACROS
xdd…
#endif
will expand to contain the xdd keyword if STANDARD_MACROS has been previously defined using a #define directive. The following will also expand to contain the xdd keyword if STANDARD_MACROS has not been defined using a #define directive,
#ifdef !STANDARD_MACROS
#define STANDARD_MACROS
xdd…
#endif
or,
#ifndef STANDARD_MACROS
#define STANDARD_MACROS
xdd…
#endif
Note the use of the ‘!’ character placed before STANDARD_MACROS which means if STANDARD_MACROS is not defined.
9.1.2 Directives invoked on macro expansion
#m_ifarg, #m_else, #m_endif
These are conditional directives that are invoked on macro expansion. #m_ifarg operates on two statements immediately following its use; the first must refer to a macro argument and the second can be any of the following: #m_code, #m_eqn, #m_code_refine, #m_one_word and “some string”. #m_ifarg evaluates to true according to the rules of Table 9‑1.
Table 9‑1 #m_ifarg syntax and meaning.
Evaluates to true if the following is true  
#m_ifarg c #m_code  If the macro argument c has a letter or the character ! as the first character and if it is not an equation. 
#m_ifarg c #m_eqn  If the macro argument c is an equation. 
#m_ifarg c #m_code_refine  If the macro argument c has a letter as the first character and if it is not an equation. 
#m_ifarg c “some_string”  If the macro argument c == “some_string”. 
#m_ifarg v #m_one_word.  If the macro argument v consists of one word. 
#m_argu, #m_first_word, #m_unique_not_refine
These operate on one macro argument with the intention of changing the value of the argument according to the rules of Table 9‑2.
Table 9‑2 Directives that operate and maybe change the value of a macro argument.
Meaning  
#m_argu c  Change the macro argument c to a unique parameter name if it has @ as the first character. 
#m_unique_not_refine c  Change the macro argument c to a unique parameter name that is not to be refined. 
#m_first_word v  Replace the macro argument v with the first word in the macro argument v. 
9.2 Overview
The file TOPAS.INC is included into INP files by default; it contains commonly used standard macros. The meaning of the macro arguments in TOPAS.INC can be readily determined from the following conventions:
Ø Arguments called “c” correspond to a parameter name.
Ø Arguments called “v” correspond to a parameter value.
Ø Arguments called “cv” correspond to a parameter name and/or value.
For example, the macro Cubic(cv) requires a value and/or a parameter name as an argument. Some examples are:
Cubic(a_lp 10.604)
Cubic(10.604)
Cubic(@ 10.604 min 10.59 max 10.61)
Here are some more examples for the Slit_Width macro:
SW(@, .1)
SW(sw, .1 min = Val.02; max = Val+.02;)
SW((ap+bp)/cp, 0) ' where ap, bp anc cp are parameters defined elsewhere
9.2.1 xdd macros
RAW(path_no_ext)
RAW(path_no_ext, range_num)
DAT(path_no_ext)
XDD(path_no_ext)
XY(path_no_ext, calc_step)
XYE(path_ext)
SCR(path_no_ext)
SHELX_HKL4(path_no_ext)
9.2.2 Lattice parameters
Cubic(cv)
Tetragonal(a_cv, c_cv)
Hexagonal(a_cv, c_cv)
Rhombohedral(a_cv, al_cv)
9.2.3 Emission profile macros
No_Th_Dependence CuKa1(yminymax) CuK1sharp(yminymax) CuKa2_analyt(yminymax) CuKa2(yminymax) CuKa4_Holzer(yminymax) CuKa5(yminymax) CuKa5_Berger(yminymax) CoKa3(yminymax) CoKa7_Holzer(yminymax) CrKa7_Holzer(yminymax)  FeKa7_Holzer(yminymax) MnKa7_Holzer(yminymax) NiKa5_Holzer(yminymax) MoKa2(yminymax) CuKb4_Holzer(yminymax) CoKb6_Holzer(yminymax) CrKb5_Holzer(yminymax) FeKb4_Holzer(yminymax) MnKb5_Holzer(yminymax) NiKb4_Holzer(yminymax) 
9.2.4 Instrument and instrument convolutions
Radius(rp, rs)
Primary and secondary instrument radii in [mm]. For most diffractometers rp equals rs.
Specimen_Tilt(c, v)
Specimen tilt in mm.
Slit_Width(c, v) or SW(c, v)
Aperture of the receiving slit in the equitorial plane in mm.
Sample_Thickness(dc, dv)
Sample thickness in mm in the direction of the scattering vector.
Divergence(c, v)
Horizontal divergence of the beam in degrees in the equitorial plane.
Variable_Divergence(c, v)
Variable_Divergence_Shape(c, v)
Variable_Divergence_Intensity
Constant illuminated sample length in mm for variable slits (i.e. variable beam divergence). This Variable_Divergence macro applies both a shape and intensity correction.
Simple_Axial_Model(c, v)
Receiving slit length mm for describing peak asymmetry due to axial divergence.
Full_Axial_Model(filament_cv, sample_cv, detector_cv, psol_cv, ssol_cv)
Accurate model for describing peak asymmetry due to axial divergence of the beam.
[filament_cv]: Tube filament length in [mm].
[sample_cv]: Sample length in axial direction in [mm].
[detector_cv]: Length of the detector (= receiving) slit in [mm].
[psol_cv, ssol_cv]: Aperture of the primary and secondary Soller slit in [°].
Finger_et_al(s2, h2)
Finger et al., 1994. model for describing peak asymmetry due to axial divergence.
[s2, h2]: Sample length, receiving slit length.
Tube_Tails(source_width_c, source_width_v, z1_c, z1_v, z2_c, z2_v, z1_z2_h_c, z1_z2_h_v)
Model for description of tube tails (Bergmann, 2000).
[source_width_c, source_width_v]: Tube filament width in [mm].
[z1_c, z1_v]: Effective width of tube tails in the equatorial plane perpendicular to the Xray beam  negative zdirection [mm].
[z2_c, z2_v]: Effective width of tube tails in the equatorial plane perpendicular to the Xray beam  positive zdirection [mm].
[z1_z2_h_c, z1_z2_h_v]: Fractional height of the tube tails relative to the main beam.
UVW(u, uv, v, vv, w, wv)
Cagliotti relation (Cagliotti et al., 1958).
[u, v, w]: Parameter names.
[uv, vv, wv]: Halfwidth value.
9.2.5 Phase peak_type's
PV_Peak_Type(ha, hav, hb, hbv, hc, hcv, lora, lorav, lorb, lorbv, lorc, lorcv)
TCHZ_Peak_Type(u, uv, v, vv, w, wv, x, xv, y, yv, z, zv)
PVII_Peak_Type(ha, hav, hb, hbv, hc, hcv, ma, mav, mb, mbv, mc, mcv)
PseudoVoigt, TCHZ pseudoVoigt and PearsonVII functions.
For the definition of the functions and function parameters refer to section 0.
9.2.6 Quantitative Analysis
Apply_Brindley_Spherical_R_PD( R, PD)
Applies the Brindley correction for quantitative analysis (Brindley, 1945).
MVW(m_v, v_v, w_v)
Returns cell mass, cell volume and weight percent.
9.2.7 2q Corrections
Zero_Error or ZE(c, v)
Zero point error.
Specimen_Displacement(c, v) or SD(c, v)
Specimen displacement error.
9.2.8 Intensity Corrections
LP_Factor(c, v)
Lorentz and LorentzPolarisation factor.
[c, v]: Monochromator angle in [°2q]
For unpolarized radiation v is 90 (e.g. Xray diffractometers without any monochromator), for fully polarized radiation v is 0 (e.g. synchrotron radiation).
Values for most common monochromators (Cu radiation) are:
Ge : 27.3
Graphite : 26.4
Quartz : 26.6
Lorentz_Factor
Lorentz_Factor for fixed wavelength neutron data.
Surface_Roughness_Pitschke_et_al(a1c, a1v, a2c, a2v)
Surface_Roughness_Suortti(a1c, a1v, a2c, a2v)
Suortti and Pitschke_et_al intensity corrections each with two parameters a1 and a2.
Preferred_Orientation(c, v, ang, hkl) or PO(c, v, ang, hkl)
Preferred orientation correction based on March (1932).
[c, v]: March parameter value.
[ang, hkl]: Lattice direction.
PO_Two_Directions(c1, v1, ang1, hkl1, c2, v2, ang2, hkl2, w1c, w1v)
Preferred orientation correction based on March (1932) considering two preferred orientation directions.
[c1, v1]: March parameter value for the first preferred orientation direction.
[ang1, hkl1]: Parameter name and lattice plane for the first preferred orientation direction.
[c2, v2]: March parameter value for the second preferred orientation direction.
[ang2, hkl2]: Lattice direction for the second preferred orientation direction.
[w1c, w1v]: Fraction of crystals oriented into first preferred orientation direction.
PO_Spherical_Harmonics(sh, order)
Preferred orientation correction based on spherical harmonics according to Järvinen (1993).
[(sh, order)]: Parameter name, spherical harmonics order.
9.2.9 Bondlength penalty functions
Anti_Bump(ton, s1, s2, ro, wby)
AI_Anti_Bump(s1, s2, ro, wby, num_cycle_iters), AI_Anti_Bump(s1, s2, ro, wby)
Applies a penalty function as a function of the distance between atoms. The closer the atoms are the higher the penalty is.
[ton]: Sets to_N of the box_interaction keyword.
[s1, s2]: Sites.
[ro]: Distance.
[wby]: Relative weighting given to the penalty function.
For more details refer to box_interaction and ai_anti_bump..
Parabola_N(n1, n2, s1, s2, ro, wby)
Applies a penalty function as a function of the distance between atoms. The closer the atoms are the higher the penalty is.
[n1]: The closest n1 number of atoms of type s2 is soft constrained to a distance ro away from s1 .
[n2]: The closest n2 number of atoms of type s2 (excluding the closest n1 number of atoms of type s2) is repelled from s1, if the distance between s1 and s2 is less than ro .
[s1, s2]: Sites.
[ro]: Distance.
[wby]: Relative weighting given to the penalty function.
Grs_Interaction(s1, s2, wqi, wqj, c, ro, n)
Penalty function applying the GRS series according to Coelho & Cheary (1997).
[s1, s2]: Sites.
[wqi, wqj]: Valence charge of the atoms.
[c]: Name of the GRS.
[ro]: Distance.
[n]: The exponent of the repulsion part of the LennardJones potential.
For more details refer to grs_interaction.
Grs_No_Repulsion(s1, s2, wqi, wqj, c)
Used for calculating the Madelung constants.
[s1, s2]: Sites.
[wqi, wqj]: Valence charge of the atoms.
[c]: Name of the GRS.
Grs_BornMayer(s1, s2, wqi, wqj, c, ro, b)
Uses the GRS series with a BornMayer equation for the repulsion term.
[s1, s2]: Sites.
[wqi, wqj]: Valence charge of the atoms.
[c]: Name of the GRS.
[ro]: Mean distance.
[b]: bconstant for the repulsion part of the BornMayer potential.
Distance_Restrain(sites, t, t_calc, tol, wscale)
Angle_Restrain(sites, t, t_calc, tol, wscale)
Flatten(sites, t_calc, tol, wscale)
Distance_Restrain_Keep_Within(sites, r, wby, num_cycle_iters)
Distance_Restrain_Keep_Out(sites, r, wby, num_cycle_iters)
Applies penalties restraining distances and angles between sites. .
'sites' must comprise two sites for the distance restraints and three for the angle restraints.. For Flatten 'sites' must contain more than three sites. wby is a scaling constant applied to the penalty.
Keep_Atom_Within_Box(size)  this is a constraint macro.
Applies constraints such that the present site cannot more outside of a box with a length of 2*size.
9.2.10 Reporting macros
Create_2Th_Ip_file(file)
Creates a file with positions (2) and intensities.
Create_d_Ip_file(file)
Creates a file with positions (d) and intensities.
Create_hklm_d_Th2_Ip_file(file)
Creates a file with the following information for each peak: h, k, l, multiplicity, positions d and 2q and intensities.
Out_Yobs_Ycalc_and_Difference(file)
Outputs the xaxis, Yobs, Ycalc and difference.
Out_X_Yobs(file), Out_X_Ycalc(file), Out_X_Difference(file)
Outputs the xaxis, Yobs, Ycalc and Difference.to files.
Out_F2_Details(file), Out_A01_A11_B01_B11(file)
Outputs structure factor details, see section 7.3.2.
Out_FCF(file)
Outputs a CIF file representation of structure factor details suitable for generating Fourier maps using ShelX..
Out_CIF_STR(file)
Outputs structure details in CIF format.
9.2.11 Rigid body macros
Set_Length(s0, s1, r, xc, yc, zc, cva, cvb)
Fixes the distance between two sites.
[s0, s1]: Site names.
[r]: Distance in Angstroms.
[xc, yc, zc]: The parameter names for the coordinates of s0.
[cva, cvb]: Parameter names and values for rotations about the x and y axes
Set_Lengths(s0, s1, s2, r, xc, yc, zc, cva1, cvb1, cva2, cvb2)
Set_Lengths(s0, s1, s2, s3, r, xcv, ycv, zcv, cva1, cvb1, cva2, cvb2, cva3, cvb3)
Fixes the distance between two and three sites, respectively.
Set_Lengths(s0, s1, s2, r, xc, yc, zc, cva1, cvb1, cva2, cvb2) is defined as
macro Set_Lengths(s0, s1, s2, r, xc, yc, zc,cva1, cvb1, cva2, cvb2)
{
Set_Length(s0, s1, r, xc, yc, zc, cva1, cvb1)
Set_Length(s0, s2, r, xc, yc, zc, cva2, cvb2)
}
and so on.
Triangle(s1, s2, s3, r)
Triangle(s0, s1, s2, s3, r)
Triangle(s0, s1, s2, s3, r, xc, yc, zc, cva, cvb, cvc)
Defines a regular triangle without and with a central atom (s0).
[s0, s1, s2, s3]: Site names. s0 is the central atom of the triangle.
[r]: Distance in Angstroms.
[xc, yc, zc]: Parameter names for the fractional coordinates of the geometric center of the triangle.
[cva, cvb, cvc]: Parameter names and values for rotations about the x, y and z axes.
Tetrahedra(s0, s1, s2, s3, s4, r, xc, yc, zc, cva, cvb, cvc)
Defines a tetrahedra with a central atom.
[s0, s1, s2, s3, s4]: Site names. s0 is the central atom of the tetrahedra.
[r]: Distance in Angstroms.
[xc, yc, zc]: Parameter names for the fractional coordinates of the geometric center of the tetrahedra.
[cva, cvb, cvc]: Parameter names and values for rotations about the x, y and z axes.
Octahedra(s0, s1, s2, s3, s4, s5, s6, r)
Octahedra(s0, s1, s2, s3, s4, s5, s6, r, xc, yc, zc, cva, cvb, cvc)
Defines an octahedra with a central atom.
[s0, s1, s2, s3, s4, s5, s6]: Site names. s0 is the central atom of the octahedra.
[r]: Distance in Angstroms.
[xc, yc, zc]: Parameter names for the fractional coordinates of the geometric center of the octahedra.
[cva, cvb, cvc]: Parameter names and values for rotations about the x, y and z axes.
Hexagon_sitting_on_point_in_xy_plane(s1, s2, s3, s4, s5, s6, a)
Hexagon_sitting_on_side_in_xy_plane(s1, s2, s3, s4, s5, s6, a)
Defines a regular hexagon, where the hexagon is sitting on a point or on a side in the xy plane, respectively.
[s1, s2, s3, s4, s5, s6]: Site names.
[a]: Distance in Angstroms.
Translate(acv, bcv, ccv)
Translate(acv, bcv, ccv, ops)
Performs a translation of the rigid body.
[acv, bcv, ccv]: Amount of the translation in fractional coordinates.
[ops]: Operates on previously defined sites in “ops”.
Translate_with_site_start_values(s0, xc, yc, zc)
Performs a translation using the coordinates of s0 as start values.
[s0]: Site name.
[xc, yc, zc]: Parameter names for the coordinates of s0.
Rotate_about_points(cv, a, b)
Rotate_about_points(cv, a, b, pts)
Performs a rotation about a rotation vector specified by two sites.
[cv]: Amount the rigid body is rotated about the specified rotation vector in degrees.
[a, b]: Rotation vector defined by the sites a and b.
[pts]: Operates on previously defined point_for_site(s).
Note: Do not include points rotated about in the “operate on points” list of the
Rotate_about_points macro. For example, in
Rotate_about_points(@ 1 0, C1, C2, “ C3 C4 C5 C6 ”)
the points C1 and C2 are not included in the “points operated on” list. Note also that Rotate_about_points without a “points operated on” list will operate on all previously defined point_for_site(s). Therefore, when an “operate on points” list is not defined then it is necessary to place the “points rotated about” after the Rotate_about_points macro. It is best to specify an “operate on points” list when in doubt.
Rotate_about_these_points(cv, a, b, ops)
Performs a rotation about a rotation vector specified by two sites.
[cv]: Amount the rigid body is rotated about the specified rotation vector in degrees.
[a, b]: Rotation vector defined by the sites a and b.
[ops]: Operates on previously defined point_for_site(s).
Rotate_about_axies(cva, cvb)
Rotate_about_axies(cva, cvb, cvc)
Performs a rotation about the axis of the rigid body.
[cva, cvb, cvc]: Parameter names and values for rotations about the x, y and z axes.
Rotation_vector_from_points(a, b)
Determines a rotation vector form two points.
[a, b]: Rotation vector defined by the sites a and b.
9.2.12 Background functions using fit_objects
One_on_X(c, v)
1/X background function ideal to describe background intensity at low angles due to air scattering
Bkg_Diffuse(b, bv, bb, bbv)
Defines a function to describe short range order effects.
[b, bv]: Parameter name, refineable weight.
[bb, bbv]: Parameter name, correlation shell radii.
PV(a, xo, fwhm, g)
PV(a, xo, fwhm, g, av, xov, fwhmv, gv)
Defines a pseudoVoigt function.
[a, av]: Parameter name, area.
[xo, xov]: Parameter name, Position in [° 2q].
[fwhm, fwhmv]: Parameter name, full width at half maximum in [° 2q].
[g, gv]: Parameter name, pseudoVoigt mixing parameter.
PV_Left_Right(a, xo, fwhm1, fwhm2, g)
PV_Left_Right(a, xo, fwhm1, fwhm2, g, av, xov, fwhm1v, fwhm2v, gv)
Defines a splitpseudoVoigt function.
[a, av]: Parameter name, area.
[xo, xov]: Parameter name, Position in [° 2q].
[fwhm1, fwhm1v]: Full width at half maximum in [° 2q] for the left composite function.
[fwhm2, fwhm2v]: Full width at half maximum in [° 2q] for the right composite function.
[g, gv]: PseudoVoigt mixing parameter.
9.2.13 Sample convolutions
Absorption(c, v), AB(c, v)
Linear absorption coefficient in t in cm1 used for adjusting the peak shape due to sample transparency.
Absorption_With_Sample_Thickness_mm_Shape(u, uv, d, dv)
Corrects the peak shape for absorption effects.
[u, uv]: Parameter name, linear absorption coefficient in cm1.
[d, dv]: Parameter name, sample thickness in [mm].
Absorption_With_Sample_Thickness_mm_Shape_Intensity(u, uv, d, dv)
Corrects the peak intensity for absorption effects.
[u, uv]: Parameter name, absorption coefficient in cm1.
[d, dv]: Parameter name, sample thickness in [mm].
CS_L(c,v) or Crystallite_Size(c, v) or CS(c, v)
Applies a Lorentzian convolution with a FWHM that varies according to the relation lor_fwhm = c / Cos(Th).
[c, v]: Parameter name, crystallite size in [nm].
CS_G(c, v)
Applies a Gaussian convolution with a FWHM that varies according to the relation gauss_fwhm = c / Cos(Th).
[c, v]: Parameter name, crystallite size in [nm].
Strain_L(c, v) or Microstrain(c, v) or MS(c, v)
Applies a Lorentzian convolution with a FWHM that varies according to the relation lor_fwhm = c Tan(Th).
Strain_G(c, v)
Applies a Gaussian convolution with a FWHM that varies according to the relation gauss_fwhm = c Tan(Th).
LVol_FWHM_CS_G_L(k, lvol, kf, lvolf, csgc, csgv, cslc, cslv)
Calculates FWHM and IB (integral breadth) based volumeweighted column heights (LVol). For details refer to section 7.2.
[k, lvol]: shape factor (fixed to 1), integral breadth based LVol.
[kf, lvolf]: shape factor (defaults to 0.89), FWHM based LVol.
[csgc, csgv]: Parameter name, Gaussian component.
[cslc, cslv]: Parameter name, Lorentzian component.
9.2.14 Neutron TOF
TOF_XYE(path, calc_step), TOF_GSAS(path, calc_step)
Includes the neutron_data keyword and the calculation step size.
TOF_LAM(w_ymin_on_ymax)
Defines a simple emission profile suitable for TOF data
TOF_x_axis_calibration(t0, t0v, t1, t1v, t2, t2v)
Writes the pk_xo equation in terms of the three calibration constants t0, t1, t2 converting dspacing to xaxis space.
TOF_Exponential(a0, a0v, a1, a1v, wexp, t1, lr)
An exponential convolution applied to the TOF peaks  see example TOF_BANK2_1.INP.
TOF_CS_L(c, v, t1), TOF_CS_G(c, v, t1)
Lorentzian and Gaussian components for crystallite size. t1 is the calibration constant appearing in the argument of the macro TOF_x_axis_calibration.
TOF_PV(fwhm, fwhmv, lor, lorv, t1)
A pseudoVoigt used to describe the instrumental broadening t1 is the calibration constant appearing in the argument of the macro TOF_x_axis_calibration, see examples tof_balzar_br1.inp and tof_balzar_sh1.inp.
9.2.15 Miscalleneous
Temperature_Regime
Defines a temperature regime. See the temperature keyword.
STR(sg)
Signals the start of structure information with a space group of sg.
Exclude
Defines excluded regions. See the exclude keyword.
Decompose(diff_toll)
Decompose a diffraction pattern into data points at peak positions only. Data points closer than diff_toll to another data point is not included. Decompose also sets x_calculation_step to the value of diff_toll.
ADPs_Keep_PD
Mixture_LAC_1_on_cm(mlac)
Phase_Density_g_on_cm3(pd)
Phase_LAC_1_on_cm(u)
Gauss(xo, fwhm), Lorentzian(xo, fwhm)
An equation defines a unit area Gaussian or Lorentzian with a position of xo and a FWHM of fwhm
10 File types and formats
Table 10‑1 File types.  
File Type  Comments 
*.PRO  Project files. 
*.INP  INP format Input file. 
*.OUT  Output file created on termination of refinement. Same format as *.INP. 
*.STR  Structure data. Same format as *.INP. 
*.LAM  Source emission profile data. Same format as *.INP. 
*.DEF  Program defaults. Same format as *.INP. 
*.LOG  TOPAS.log and Tc.log. Useful for tracking input errors. 
Measurement Data  
*.RAW  Bruker AXS binaries (DIFFRAC AT and DIFFRAC^{plus}) 
*.DAT *.XDD / *.CAL *.XY, *XYE  ASCII file formats, see Table 10‑2 
*.SCR  ASCII file format comprising lines of h, k, l, m, d, 2q, and Fo. 
*.HKL  ShelX HKL4 format. 
Structure and structure factor data  
*.CIF  Crystallographic Information File; International Union for Crystallography (IUCr). 
*.FCF  CIF file representation of structure factor details suitable for generating Fourier maps using ShelX. 
Table 10‑2 ASCII input data file formats. *.XY, *.XYE, *.XDD and *.CAL are delimited by white space characters and can contain line and block comments.  
File Type  Format  Explanation 
*.DAT, LHPM/RIET7/CSRIET  
Line 14  Comments  
Line 5  Start angle, step width, finish angle  
Line 6 onwards  Observed XRD data points (any number of rows)  
GSAS (“std  const”, “alt  ralf”), use keyword gsas_format  
Line 1  Legend  
Line 2  Item 3: Number of data points  
Line 3 onwards  Depending of item10 and item5  
For item10 = “STD” and item5 = “CONST” xmin = item6/div step =item7/div read(10(i2,F6.0) iww(i),y(i) i=1, npts sigma(i)=sqr(y(i)/iww(i)) i=1, npts For item10 = “ALT” and item5 = “RALF” xmin = item6/32 step = item7/32 read(4(F8.0,F7.4,F5.4) x(i), y(i), sigma(i) i=1, npts x(i) = x(i)/32 i=1, npts do i = 1, npts1 div = x(i+1)x(i) y(i) =1000 * y(i)/div sigma(i) = 1000 * sigma(i)/div end do rk (constant wavelength data): div = 100 rk (time of flight data): div = 1  
FullProf (INSTRM = 0: free format file), use keyword fullprof_format  
Line 1  Start angle, step width, finish angle, comments  
Line 2 onwards  Observed XRD data points (any number of rows)  
*.XDD / *.CAL  Line 1  Optional line for comments 
Number 2  Start angle  
Number 3  Step width  
Number 4  Finish angle  
Number 5  Counting time  
Number 6  Unused  
Number 7  Unused  
Number 8 onwards  Observed XRD data points  
*.XY  2q and intensity data values  
*.XYE  2q, intensity and intensity error values. 
11 Chargeflipping
The chargeflipping method of Oszlányi & Süto (2004) has been implemented using the keywords shown in Table 11‑2. Also included is the use of the tangent formula (Hauptman & Karle, 1956) within the iterative chargeflipping process. Equations appearing in chargeflipping keywords can be functions of the items shown in Table 11‑1. At the end of a charge flipping process a file with the same name as that given by cf_hkl_file is created but with a *.FC extension. Almost all of the chargeflipping keywords can be equations allowing for great flexibility in regards to changing resolution etc… on the fly. Table 11‑3 lists chargeflipping examples found in the CF directory.
Table 11‑1. Items that can be used in chargeflipping equations  
Get(Aij) Get(alpha_sum) Get(density) Get(cycles_since_last_best) Get(d_squared_inverse) Get(initial_phase) Get(iters_since_last_best) Get(F000) Get(max_density) Get(max_density_at_cycle_iter_0) Get(num_reflections_above_d_min) Get(phase_difference) Get(r_factor_1), Get(r_factor_2) Get(threshold)  These are updated internally each chargeflipping iteration or cycle or when needed. 
Reserved parameter names Cycle_Iter, Cycle, Iter, D_spacing  
Macros  
Ramp, Ramp_Clamp, Cycle_Ramp,Tangent, Restart_CF, Pick, Pick_Best  See TOPAS.INC for details. 
Out_for_cf(file) : Outputs the A matrix from a Pawley refinement for use in charge flipping; uses cf_in_A_matrix. See example CFCIMEPAWLEY.INP. 

Table 11‑2. Keywords that can be used in chargeflipping. 
11.1 Chargeflipping usage
CF works particularlly well on data at good resolution (<1Å resolution). For data at poor resolution or for difficult structures then inclusion of the tangent formula can facilitate solution and sharpen electron densities, see example CF1A7Y.INP. Powder diffraction data usually fall under the poor resolution/data quality category and as such additional symmetry restraints using symmetry_obey_0_to_1 can sharpen electron densities. Example CFALVO4.INP demonstrates the use of the tangent formula on powder data.
The choice and amount of perturbation necessary for finding a solution are important considerations. Not enough perturbation leads to the system being trapped within a local parameter space; too much perturbation may lead to a solution not being found and in addition contrast in Rfactors prior to and at convergence are diminished leading to difficult to identify solutions. Many of the examples in the CF directory uses the Ramp macro to gradually vary control parameters, here are some examples:
fraction_density_to_flip = Ramp(0.85, 0.8, 100);
fraction_reflections_weak = Ramp(0.5, 0, 100);
flip_regime_2 = Ramp(1, 0, 200);
flip_regime_3 = Ramp(0.25, 0.5, 200);
symmetry_obey_0_to_1 = Ramp(0.5, 1, 100);
tangent_scale_difference_by = Ramp(0, 1, 100);
Choosing control parameters in this manner gradually decreases perturbation allowing for solutions to be found and identified. This is similar to a simulated annealing process where temperatures start at high values and then progressively lowered.
11.1.1 Perturbations
Perturbations can be categorized as being of either phase, structure factor intensity or electron density perturbations as shown in Table 11‑2. There are two built in flipping regimes, flip_regime_2 and flip_regime_3, and one user defined regime flip_equation. Only one can be used and they all modify the electron density. In the absence of a flipping regime the following is used:
_{}  (11‑1) 
where d corresponds to the electron density threshold.
Using the tangent formula on either difficult structures or on data at poor resolution often leads to uranium atom solutions. Uranium atom solutions can be avoided by modifying the electron density using a flipping regime that dampens high electron densities or by using pick_atoms.
Using a large number of triplets per E_{h} value (a value for tangent_max_triplets_per_h greater than 100) reduces perturbation, increases occurrences of uranium atom solutions and increases the chances of finding a solution after an initial phase randomization. A large number of triplets would typically be used for poor resolution data; correspondingly a flipping regime that avoids uranium atom solutions should be chosen.
Perturbations mostly increase randomness in the system with the exceptions of the tangent formula, scale_density_below_threshold and histogram_match_scale_fwhm.
11.1.2 The Ewald sphere, weak reflections and CF termination
By default CF uses the minimum observed d spacing to define the Ewald sphere; alternatively min_d can be used. The Ewald sphere can be increased using extend_calculated_sphere_to; this inserts missing reflections and gives them the status of “weak” reflections. Weak reflections are also inserted for missing reflections within the Ewald sphere. Weak reflection phases and structure factors can be modified using scale_weak_reflections and add_to_phases_of_weak_reflections.
Reflections that have zero intensities according to the space group are not included in CF; correspondingly the number of observed reflections removed are reported. Structure factor intensities within a family of reflections are determined by averaging the observed structure factors intensities. This averaging is also performed on calculated intensities each CF iteration for weak reflections.
Changing the space group is possible; changing the space group to a higher symmetry from that as implied in the input hkl file often makes sense. Changing the space group to a lower symmetry implies less symmetry and is useful for checking whether a significantly better Rfactor is realized.
Typically a fraction of observed reflections are given the status of “weak” using fraction_reflections_weak. When a solution is found and CF terminates a *.FC file is saved; this file comprises structures factors that produced the best Rfactor. A new CF process can be initiated with phase information saved in the *.FC file using the Restart_CF macro. To further complete the structure the new CF process may for example reduce perturbations in order to sharpen the electron density.
11.1.3 Powder data considerations
For powder data it is usually best to maximize the number of constraints due to poor data quality; it is also best to use *.A files as generated by a Pawley refinement and to then use cf_in_A_matrix. No weak observed reflections within the observed Ewald sphere should be assigned by setting fraction_reflections_weak to zero. Instead weak reflections can be included by extending the Ewald sphere with something like:
extend_calculated_sphere_to 1
add_to_phases_of_weak_reflections = 90 Ramp(1, 0, 100);
If the Ewald sphere is extended such that the weak reflections are many then some of these weak reflections could well be of high intensity. Subsequently offsetting high intensity weak reflections by a constant could lead to too much perturbation and thus the following may be preferential:
extend_calculated_sphere_to 1
add_to_phases_of_weak_reflections = Rand(180,180) Ramp(1, 0, 100);
In a Pawley refinement the calculated intensities at the low dspcaing edge of are often in error to a large extent; it is therefore best to remove these reflections using delete_observed_reflections, for example example:
delete_observed_reflections = D_spacing < 1.134;
A typical first try INP file template for powders is as follows:
macro Nr { 100 }
charge_flipping
cf_in_A_matrix PAWLEY_FILE.A
space_group $
a # b # c al # be # ga #
delete_observed_reflections = D_spacing < #;
extend_calculated_sphere_to #
add_to_phases_of_weak_reflections = 90 Ramp(1, 0, Nr);
flip_regime_2 = Ramp(1, 0, Nr);
symmetry_obey_0_to_1 = Ramp(0.5, 1, Nr);
Tangent(.3, 30)
min_grid_spacing .3
load f_atom_type f_atom_quantity { … }
11.1.4 The algorithm of Oszlányi & Süto (2005) and F000
Normalized structure factors enhances the chances of finding a solution (Oszlányi & Süto, 2006) and are realized by inclusion of f_atom_type’s and when correct_for_temperature_effects is nonzero. Example CF1A7YGABOR.INP implements the algorithm of Oszlányi & Süto (2005) with normalized structure factors. In the original algorithm the amount of charge flipped is a function of the maximum electron density; this can be realized using:
user_threshold = 0.2 Get(max_density_at_cycle_iter_0);
Get(max_density_at_cycle_iter_0) is a different value at the start of each CF process as phases are chosen randomly. An alternative means of defining the threshold is:
fraction_density_to_flip 0.83
The CF process is sensitive to the threshold value. A value of 0.83 for fraction_density_to_flip is optimum for 1a7y and produces a solution in ~1000 iterations. A solution is not found however at 0.75 or 0.85. To overcome this sensitivity the fraction_density_to_flip parameter could be ramped as a function of iteration from a high value to a low value, or,
fraction_density_to_flip = Ramp(0.85, 0.8, 100);
Implementation of such a ramp solves 1a7y in ~2000 iterations.
F000 is allowed to float when scale_F000 is set to 1. In the Oszlányi & Süto (2005) algorithm a floating F000 produces the best results for some structures but not for others (see section 11.2.3).
When the electron density is perturbed then a floating F000 often produces unfavourable oscillations in Rfactors. In general the electron density is best left unperturbed when scale_F000 is nonzero.
Example CF1A7YGABOR.INP does not seem to solve at a lower resolution, try for example:
delete_observed_reflections = D_spacing < 1.1;
On the other hand when scale_F000 is zero then electron density perturbations are possible; CF_1A7Y.INP solves 1a7y at 1.1 Angstrom (ie. include “delete_observed_reflections = D_spacing < 1.1”); CF_1A7Y.INP uses flip_regime_2 and the tangent formula.
11.2 Chargeflipping Investigations / Tutorials
The effects of CF keywords can be investigated by inclusion/exclusion of keywords or by changing equations. This section lists some investigative examples and highlights the use of keywords necessary to solve particular examples found in the CF directory.
11.2.1 Preventing uranium atom solutions using pick_atoms
Example CF1A7YOMIT.INP uses pick_atoms to modify the peaks of the highest intensity atoms as follows:
pick_atoms *
choose_to 5
omit = Rand(1, 1.1);
This example additionally uses the tangent formula and 1a7y solves in ~100 iterations and with a large contrast in Rfactors before and at converegnce. Another means to modify the peaks are:
pick_atoms *
choose_to 5
insert = Rand(.1, 1);
The insert case is slightly slower than the omit case as the 5 atoms are first omitted before insertion. Each case however solves 1a7y in a similar number of iterations.
Example CF1A7YNOTANGENT.INP is similar but without the tangent formula, 1a7y in this case solves in ~1000 iterations.
11.2.2 The tangent formula on powder data
In CFALVO4.INP comment out the Tangent line as follows:
‘ Tangent(.5, 50)
Run CFALVO4.INP and turn on Octahedra viewing in the OpenGL window. Visual inspection of picked atoms should show electron densities that are not recognizable as correct solutions.
Include the Tangent line and rerun; after a minute or two and at the bottom of the Ramps visual inspection of picked atoms should show a well defined solution.
Thus use of the tangent formula assists in solving CFALVO4.INP.
11.2.3 Pseudo symmetry – 441 atom oxide
CF works particularly well on pseudo symmetric structures (Oszlányi et el., 2006). Example CFPN02.INP is an oxide structure that contains 441 atom in the asymmetric unit (Lister et el., 2004); run CF to convergence. Pick atoms and turn on Octahedra viewing; all polyhedra should be well formed. Thus CF works extremely fast and trivializes the solving of such structures. The contents of the INP file is as follows:
charge_flipping
cf_hkl_file 020pn.hkl
space_group Pn
a 24.1332
b 19.5793
c 25.1091
be 99.962
fraction_reflections_weak 0.4
symmetry_obey_0_to_1 .3
Tangent(.25, 30)
load f_atom_type f_atom_quantity
{
MO = 42 2;
P = (126  42) 2;
O = (441  126) 2;
}
The tangent formula is used to assist symmetry_obey_0_to_1 and to assist in finding the solution faster; it is not necessary for this example however. The Oszlányi & Süto (2005) algorithm can be used by replaceing symmetry_obey_0_to_1 and the Tangent line with the following:
scale_F000 1
fraction_reflections_weak .4
add_to_phases_of_weak_reflections 90
user_threshold = 0.15 Get(max_density_at_cycle_iter_0);
Slow convergence is then observed and the reason is the use of F000. This is opposite to the case of 1a7y in CF1A7YGABOR.INP where F000 is necessary. Setting scale_F000 to zero greatly increases the rate of convergence.
11.2.4 Origin finding and symmetry_obey_0_to_1
When symmetry_obey_0_to_1 is defined origin finding is performed each iteration of charge flipping. Symmetry elements of the space group are used in finding an origin. On finding an origin the electron density is shifted to a position that best matches the symmetry of the space group. Additionally a restraint is placed on the electron density pixels forcing symmetry to be obeyed.
Run CFAE14.INP to convergence; notice the P1 symmetry. Remove symmetry_obey_0_to_1 and run to convergence; the origin should now be arbitrary.
11.2.5 symmetry_obey_0_to_1 on poor resolution data
Run CFAE5.INP until a solution is found; terminate CF, this saves the phase information to the file AE5.FC.
Copy AE5.FC to AE5SAVE.FC.
Place the following lines into the file CFAE5POOR.INP
set_initial_phases_to ae5save.fc
randomize_initial_phases_by 0
This simply starts CF with optimum phase values. Also include the following line:
symmetry_obey_0_to_1 .75
Run CFAE5POOR.INP; the atom positions after picking should visually produce the correct result. Comment out symmetry_obey_0_to_1 and rerun CFAE5POOR.INP. Rfactors should diverge and picked atoms should show a nonsolution. Thus symmetry_obey_0_to_1 assists in solving CFAE5POOR.INP.
Include symmetry_obey_0_to_1 and remove set_initial_phases_to and randomize_initial_phases_by and then rerun CFAE5POOR.INP. A solution should be obtained in a few minutes. Note that in this example the default flipping regime leads to regular occurrences of uranium atom solutions; this can be trivially ascertained by viewing the electron density. To reduce the occurrences of uranium atom solutions the following flipping regime is used:
flip_regime_3 0.5
11.2.6 Sharpening clouds  extend_calculated_sphere_to
Example CFAE9POOR.INP demonstrates the limit to which the present CF implementation can operate. Single crystal data is purposely chosen to isolate resolution effects and not intensity errors. The tangent formula is critical where without it the CF process is extremely perturbed and unstable. “flip_regime_3 .5” is used due to occurrences of uranium atom solutions.
There are no ramps, instead the CF process is restarted when the Rfactor fails to decrease for 100 consecutive iterations, or,
break_cycle_if_true = Get(iters_since_last_best) > 100;
randomize_phases_on_new_cycle_by = Rand(180, 180);
Half of the observed reflections are considered weak and additionally missing reflections up to 1 Angstrom are included and considered weak using:
fraction_reflections_weak 0.5
extend_calculated_sphere_to 1
The intensities of weak reflections are left untouched and instead a Pi/2 phase shift is randomly applied to ~30% of weak reflections as follows:
add_to_phases_of_weak_reflections = If(Rand(0, 1) < .3, 90, 0);
A symmetry_obey_0_to_1 of 0.7 is used not merely to find an origin but rather to prevent the electron density from straying.
Run CFAE9POOR.INP and a solution should be clearly recognizable after a few minutes. Change/remove keywords and rerun to view effects. Examples CFCIMEPOOR.INP and CFAE5POOR.INP are similar.
11.2.7 A difficult powder, CFSUCROSE.INP
CFSUCROSE.INP without scale_density_below_threshold=0 exhibits large oscillations in Rfactors resulting in difficult to identify solutions; this can be prevented by increasing the amount of charge flipped and including scale_density_below_threshold=0, for example
fraction_density_to_flip 0.83
scale_density_below_threshold 0
When scale_density_below_threshold=0 is used the percentage of charge that is less than the threshold before the application of scale_density_below_threshold is reported; the difference between this reported value and (1fraction_density_to_flip) gives the amount of flipped pixels that survived scale_density_below_threshold. At fraction_density_to_flip of 0.83 approximately 23% of pixels survives scale_density_below_threshold=0 which in effect means that only 23% of pixels are actually flipped out of the original 83%.
picked_atoms is used as a perturbation where 30% of atoms are omitted using:
pick_atoms *
activate = Cycle_Iter == 0;
insert = If(Rand(0, 1) > 0.3, 10, 0);
Note that atoms are inserted at an intensity that is 10 times the average intensity. This increases the weight of inserted atoms relative to electron density noise. It also initially gives more weight to weak reflections.
Use of scale_density_below_threshold often results in CF requiring more interations to solution; a solution however is preferable to no solution.
11.2.8 Increasing contrast in Rfactors
The act of flipping introduces an appreciable amount of unwanted high frequencies in the structure factors. This effect can be reduced by dampening high frequencies using apply_exp_scale which is ON by default. apply_exp_scale changes Rfactors and not phases, directions taken by CF are unchanged.
Run CF1A7Y.INP until convergence. The difference in Rfactors before and at convergence should be ~0.39 (ie. 0.81 and 0.42). Turn OFF apply_exp_scale by including the following line:
apply_exp_scale 0
Rerun CF1A7Y.INP until convergence. The difference in Rfactors before and at convergence should now be ~0.29 (ie. 0.81 and 0.52). Thus apply_exp_scale increases contrast in Rfactors. Note that most of the increase seems to be realized from dspacings less than 1 Angstrom.
11.3 Chargeflipping Examples
Table 11‑3. Examples found in the CF directory, Number of atoms corresponds to the number of nonhydrogen atoms within the asymmetric unit.  
Single crystal data  Number of atoms in asymmetric unit  Space group 
cf1a7y.inp cf1a7ygabor.inp cf1a7yomit.inp cf1a7ynotangent.inp  314  P1 
cfae14.inp  43  P1 
cfae5.inp cfae5poor.inp  23  C2/c 
cfae9.inp cfae9poor.inp  53  P1 
cfgebaa.inp  17  P4_{1}2_{1}2 
cfpn02.inp  441  Pn 
cfylidm.inp  17  P2_{1}2_{1}2_{1} 
Powder data  
cfalvo4.inp, cfalvo4pawley.inp  18  P1 
cfcimepawley.inp cfcime.inp, cfcimehisto.inp cfcimepoor.inp, cfcimepoorhisto.inp  17  P2_{1}/a 
cfsucrose.inp, cfsucrosepawley.inp  23  P2_{1} 
11.4 Keywords in detail
[add_to_cloud_N !E]
[add_to_cloud_when !E]
The current cloud is added to the GUI cloud creating a running average cloud for display purposes. add_to_cloud_N corresponds to the number of most recent clouds to include in the running average. add_to_cloud_when determines when the current cloud is to be included in the running average; here’s an example:
add_to_cloud_N 10
add_to_cloud_when = Mod(Cycle_Iter, 2);
Averaged clouds eliminate noise and is effective if the cloud remains stationery which is generally the case. Note that add_to_phases_of_weak_reflections can produce translations of the cloud and should not be included when averaging clouds.
[add_to_phases_of_weak_reflections !E]
Allows for modification to phases of weak reflections. For example, to add p/2 to the phases of weak reflections then the following could be used:
add_to_phases_of_weak_reflections 90
When add_to_phases_of_weak_reflections is defined then the intensities of weak reflections are not set to zero; instead they are left untouched meaning that their intensities are set to the values as determined by the inverse Fourier transform. See also scale_weak_reflections.
[apply_exp_scale !E]
Determines a and b each CF iteration such that the following is a minimum:
Rfactor = ∑ a Exp(b / D_spacing^2) Fc – Fo 
where Fc and Fo are the calculated and observed moduli respectively. Use of apply_exp_scale corrects Rfactors in case of an incorrect temperature factor correction as applied when normalizing structure factors. Use of apply_exp_scale typically increases the difference between Rfactors prior to and at convergence. apply_exp_scale is used by default, setting it to zero prevents its use.
[cf_hkl_file $file]
Defines the input hkl file.
[cf_in_A_matrix $file [scale_Aij !E] ]
Data input is from a file created using out_A_matrix from a previous Pawley refinement. The correlations in $file are used to partition intensities during each iteration of chargeflipping. This partitioning is applied to structure factors as used by CF and as used by the tangent formula.
scale_Aij can be used to modify the A matrix offdiagonal coefficients, here are some examples:
scale_Aij = Get(Aij);
scale_Aij = Get(Aij)^2; ‘ the default
scale_Aij = 0; ‘ Equivalent to using a Pawley generated hkl file
CF on powder data can also be initiated using standard hkl files.
[break_cycle_if_true !E]
Interrupts charge flipping to execute randomize_phases_on_new_cycle_by. Cycle_Iter is set to zero and Cycle is incremented.
[correct_for_atomic_scattering_factors !E]
Structure factors are normalized when nonzero and when f_atom_type’s are defined. By default structure factors are normalized.
[correct_for_temperature_effects !E]
Attempts to remove isotropic temperature effects from the structure factors. correct_for_temperature_effects is ON by default, setting it to zero will prevent the correction. Normalized structure factors are realized when correct_for_temperature_effects is ON and the unit cell contents is defined using f_atom_type and f_atom_quantity.
[delete_observed_reflections !E]
Reflections are deleted before entering CF according to delete_observed_reflections; it can be a function of D_spacing, for example:
delete_observed_reflections = D_spacing < 1.1;
Once deleted, observed reflections cannot be reinstated by changing min_d.
[extend_calculated_sphere_to !E]
Used to sharpen electron density clouds by filling in missing reflections; added reflections are given the status of “weak”. extend_calculated_sphere_to can be used in conjunction with scale_weak_reflections and add_to_phases_of_weak_reflections to modify “weak” reflection magnitudes and phases respectively (see section 11.2.6); here’s an example:
extend_calculated_sphere_to 1
add_to_phases_of_weak_reflections = If(Rand(0, 1) < .3, 90, 0);
[f_atom_type $type f_atom_quantity !E]…
Defines atom types and number of atoms within the unit cell; used by the tangent formula in determining E_{h} values and by the OpenGL display for picking atoms. For the tangent formula then realtive quantities are important.
[find_origin !E]
If defined and nonzero then origin finding is turned ON. symmetry_obey_0_to_1 defines find_origin by default. symmetry_obey_0_to_1 can be used without find_origin by defining and setting find_origin to zero.
[flip_equation !E]
Allwows for a user defined flip; here’s an example:
flip_equation =
If(Get(density) < Get(threshold), Get(density), Get(density));
[flip_regime_2 !E]
The elctron density is modified according to Eq. (11‑1) and then further modified using:
_{}flip_regime_2 is typically ramped from 1 to 0.
[flip_regime_3 !E]
The elctron density is modified according to Eq. (11‑1) and then further modified using:
_{}A value of 0.5 for flip_regime_3 introduces little perturbation whilst reducing the occurance of uranium atom solutions. It is recommended that flip_regime_3 be used in cases where flip_regime_2 produces uranium atom solutions. An additional perturbation, such as “add_to_phases_of_weak_reflections=90;” may be necessary.
[fraction_density_to_flip !E]
The amount of charge flipped is fractionally based. A value of 0.6, for example, sets the threshold d such that the sign of the lowest 60% of charge is changed. Get(threshold) can be used to retrieve d.
[fraction_reflections_weak !E]
Defines the fraction of observed reflections to flag as “weak”. When scale_weak_reflections, add_to_phases_of_weak_reflections and extend_calculated_sphere_to are all not defined then intensities of weak reflections are set to zero effectively removing them from the charge flipping process. Otherwise intensities of weak reflections are not set to zero; instead they are left untouched prior to scale_weak_reflections and add_to_phases_of_weak_reflections and space group family averaging.
[histogram_match_scale_fwhm !E]
[hm_size_limit_in_fwhm !E]
[hm_covalent_fwhm !E]
An implementation of Histogram Matching (Baerlocher et al., 2007) where the distribution of pixels within the unit cell is restrained to one that mathes Gaussian atoms with intensities corresponding to the atoms defined by f_atom_type‘s. The Histogram matching operation is performed when histogram_match_scale_fwhm evaluates to a nonzero value. Subsequently the full width at half maximum (FWHM) of the Gaussians (obtained from the file ATOM_RADIUS.DEF) is scaled by histogram_match_scale_fwhm. hm_size_limit_in_fwhm corresponds to the extent to which the Gaussians are calculated in units of FWHM. Covalent radii is used if hm_covalent_fwhm evaluates to a nonzero value otherwise ionic radii is used. An example use is as follows:
histogram_match_scale_fwhm = If(Mod(Cycle_Iter, 3), 0, 1);
hm_size_limit_in_fwhm 1
hm_covalent_fwhm 1
Reported on is the fraction of pixels modified; values of 1 for both histogram_match_scale_fwhm and hm_size_limit_in_fwhm seem optimal where typically ~15 to 20% of pixels are modified. Use of histogram matching should produce Rfactors at convergence that are equal to or than less Rfactors produced when not using histogram matching. Histogram matching sharpens the electron density cloud for data at poor resolution (see examples CFCIMEHISTO.INP and CFCIMEPOORHISTO.INP).
[min_d !E]
Determines in Angstroms the resolution of observed reflections to work with; only observed reflections with a dspacing above min_d are considered. min_d is evaluated each CF iteration. Get(num_observed_reflections_above_d_min) is updated when a change in min_d is detected. See also extend_calculated_sphere_to and delete_observed_reflections.
[min_grid_spacing !E]
If defined then the grid spacing used is set to the smaller of min_d/2 and min_grid_spacing; useful for obtaining many grid points for graphical purposes.
[neutron_data]
Signals that the input data is of neutron type. Used in the picking of atoms and additionally E_{h} values are not corrected from any defined f_atom_type and f_atom_quantity keywords.
[pick_atoms $atoms]…
[activate !E]
[choose_from !E]
[choose_to !E]
[choose_randomly !E]
[omit !E]
[displace !E]
[insert !E]
pick_atoms modifies the electron density based on picked atoms. $atom corresponds to the atom types to be operated on; it can contain the wild card character ‘*’ and the negation character ‘!’, see section 7.6 for details. The operations of pick_atoms are invoked when activate evaluates to a nonzero value; for example,
pick_atoms “O C”
activate = Mod(Cycle_Iter, 20) == 0;
The picking routine will attempts to locate the atom types found in $atom based on the intensities of picked atoms and the scattering power of the atoms defined in f_atom_type. For example,
load f_atom_type f_atom_quantity { Ca 2 O 10 C 12 }
pick_atoms “O C”
Here 2 Ca atoms are first picked and then 10 O atoms and then 12 C atoms. The picked atoms operated on will be the O and C atoms with the Ca atoms ignored.
choose_from and choose_to can be used to limit the number of atoms operated on. Note, that picked atoms within a particular pick_atoms are sorted in decreasing intensity order. For example, to not operate on the first thee O atoms and the last 2 C atoms then the following could be used:
choose_from 4
choose_to 20
choose_randomly further reduces the atoms operated on and is exected after choose_from and choose_to.
omit removes operated on atoms from the electron density. Atoms can be partially removed by setting omit to values less than 1. Values greater than 1 can also be used, the effect is to change the sign of the electron density. omit operating on a few of the highest intensity atoms is an extremely effective means of preventing the occurance of uranium atom solutions, see CF1A7YOMIT.INP; for example:
pick_atoms *
choose_to 5
omit = Rand(1, 1.1);
Omitting atoms randomly is a technique referred to as “random omit maps“ in ShelXD, (Schneider and Sheldrick, 2002).
insert inserts operated on atoms; a value of 1 inserts the atoms with an intensity that is equal to the average of the picked atoms. Values of less than 1 descreases the intensity of the inserted atoms. When insert is defined then omit is internally defined if it does not already exist. Thus, atoms are removed before insertion by default.
displace (in Angstroms) displaces atom positions from their picked positions; it is evaluated before insert. For example, to randomly displace atoms by 0.3 Angstroms then the following could be used:
displace = Rand(0.4, 0.6);
insert 1
There can be more than one occurance of pick_atoms, for example to limit uranium atom solutions then the follow can be used:
pick_atoms *
choose_to 5
insert = Rand(.1, 1);
To further randomly remove ~33% of atoms then the following could additionally be used:
break_cycle_if_true = Get(iters_since_last_best) > 10;
pick_atoms *
activate = Cycle_Iter == 0;
insert = If(Rand(0, 1) > 0.33, 10, 0);
Note that in this example atoms are inserted at ten times the average picked intensity; this simply gives more weight to picked atoms relative to electron density noise. Additionaly weak reflections are also given more weighting.
[pick_atoms_when !E]
Atoms are picked in the OpenGL display when pick_atoms_when evaluates to a nonzero value; here’s an example:
pick_atoms_when = Mod(Cycle_Iter + 1, 10) == 0;
Note that picking can be manually initiated from the Cloud dialog of the OpenGL display. A text description of picked atoms can be obtained by opening the “Temporary output” text window of the OpenGL window.
[randomize_initial_phases_by !E]
Initializes phases. To start a process with already saved phase information then the following could be used:
set_initial_phases_to aleady_saved.fc
randomize_initial_phases_by 0 ' this has a default of Rand(180,180)
[randomize_phases_on_new_cycle_by !E]
randomize_phases_on_new_cycle_by = Rand(180, 180); ‘ an example
[scale_density_below_threshold !E]
Electron density pixels that are less than the threshold value are scaled by scale_density_below_threshold. Values for scale_density_below_threshold thata re less than 1 tends to sharpen the electron density and to reduce large oscillations in Rfactors; the latter occurs for bad data, see example CFSUCROSE.INP. A value of zero for scale_density_below_threshold results in “low density elimination“ simlar to that of Shiono & Woolfson (1992).
[scale_E !E]
Normalized structure factors (E_{h} values) are a function of correct_for_temperature_effects and unit cell contents. scale_E allows for an additional scaling of E_{h} values.
[scale_F !E]
CF works with normalized structure factors by default. scale_F is an additional scaling of structure factors. The defualt scale_F broadens electron density peaks to avoid pixilation effects and is given by:
scale_F = Exp(0.2 Get(d_squared_inverse));
[scale_F000 !E]
Scale should be set to 1 for compliance with the algorithm of Oszlányi & Süto (2004). When scale_F000 is non_zero then modifcations to the electron density produces unfavourable effects.
[scale_weak_reflections !E]
By default weak reflection structure factors are set to zero; however when either scale_weak_reflections or add_to_phases_of_weak_reflections is defined then weak reflections structure factors are instead modified accordingly, for example:
scale_weak_reflections = Rand(0.2, 0.4);
scale_weak_reflections or add_to_phases_of_weak_reflections can be a function of D_spacing.
[set_initial_phases_to $file]
[modify_initial_phases !E]
Sets initial phases to those appearing in $file. Typically $file corresponds to a *.FC file saved in a previous chargeflipping process. modify_initial_phases is executed each iteration of CF; it can be used to restrain the phases of $file. For example,
modify_initial_phases =
Get(initial_phase) + Min(Abs(Get(phase_difference)), 45);
where phase_difference corresponds to the difference between the current phase and the initial phase; it has a value between ±90º. modify_initial_phases can be used to constrain phases to those as determined by HRTEM (Baerlocher et al., 2007).
[space_group $]
If defined then the cf_hkl_file is assumed to comprise merged hkls corresponding to the defined space group; otherwise the cf_hkl_file is assumed to be of space group type P1.
[symmetry_obey_0_to_1 !E]
If a space group is defined then symmetry is adhered to according to symmetry_obey_0_to_1. symmetry_obey_0_to_1 can be through of as a real space electron density restraint; its value should range between 0 and 1. If 1 then symmetry is obeyed 100%. symmetry_obey_0_to_1 is implemented follows:
For a particular set of equivalent grid points as determined by the equivalent positions of the space group an average density r_{avg} is obtained. The electron densities on the grid points are then adjusted as follows:
r_{new} = r (1  symmetry_obey_0_to_1) + symmetry_obey_0_to_1 r_{avg}
The text output 'symmetry error' as displayed when symmetry_obey_0_to_1 is used is defined as follows:
'symmetry error' = _{}
where the summation is over all of the electron density grid points.
symmetry_obey_0_to_1 defines find_origin by default. find_origin is applied before symmetry_obey_0_to_1. find_origin shifts the electron density such that an approximate error in 'symmetry error' is minimized; thus find_origin assists in the symmetry_obey_0_to_1 restraint.
[tangent_num_h_read !E]
[tangent_num_k_read !E]
[tangent_num_h_keep !E]
[tangent_max_triplets_per_h !E]
[tangent_min_triplets_per_h !E]
[tangent_scale_difference_by !E]
tangent_num_h_read and tangent_num_k_read defines the number of highest h and highest k reflections to read in determining triplets.
tangent_num_h_keep defines the number of highest h reflections to include for tangent formula updating.
tangent_max_triplets_per_h and tangent_min_triplets_per_h defines the maximum and minium number of triplets per reflection h. Reflections with less that tangent_min_triplets_per_h are not included for tangent formula updating.
tangent_scale_difference_by corresponds to S in the following:
_{} _{} _{} _{} _{}, _{}  (1) 
[user_threshold !E]
By default Get(threshold) is determined using fraction_density_to_flip. When defined then user_threshold overrides fraction_density_to_flip. Electron density pixels are normalized to have a maximum value of 1, thus typical values for user_threshold range between 0 and 0.1.
[use_Fc]
Sets initial phases to those saved in a previous *.FC file. The FC file used corresponds to the same name as the data file, defined using cf_hkl_file or cf_in_A_matrix, but with a FC extension. use_Fc is similar to set_initial_phases_to except that the file used is implied.
[verbose #]
A value of 1 outputs text in a verbose manner. A value of 0 outputs text only when a Rfactor less that a previous value is encountered within a particular Cyle.
[view_cloud !E]
Informs a detected GUI to display the electron density. Here are some examples:
view_cloud 1 ' Update cloud every chargeflipping iteration
view_cloud = Mod(Cycle_Iter, 10) == 0;