xnd 1.2 input file

`xnd 1.21`: input file

xnd top	Next file	Previous file

Generalities

In this section, the input data file to the program is described in detail. The coordinate file is often used with a .k extension, this is not mandatory but allows the use of cycling procedures. In this document the input file will be refered as xnd.k.
The easiest way to start a new study with xnd is to select an existing file, from examples or demos, and to modify it. This goes really quicker than writing it with the help of this document.

The xnd.k file is not automatically checked for physical consistency of input data and these short guides to the preparation of this file can not replace the necessary knowledges in crystallography. All the others file names are specified in it.

When the xnd.k file seems to be filled, you can try to run the program by typing xnd, you will be asked for the input file or if you prefer you can type directly xnd xnd.k or xnd xnd to run the same xnd.k input file.

In the xnd.k coordinate file, the cristallographic parameters are grouped into blocks. Each block has a specific function and several blocks are necessary to have a complete coordinate files. The blocks may be grouped as follows

headers (compulsory)
symmetry tables
anomalous scattering tables
diffusion tables
experience description headers (compulsory)
- wavelenghts (compulsory);
- background definition;
- instrumental and geometrical corrections (compulsory);
- instrumental profile (compulsory);
phase description headers (compulsory)
- overall scale factors (compulsory);
- lattice parameters (compulsory);
- structural parameters (compulsory).

In the coordinate file, there are also some alphanumeric fields as file names, symmetry identifiers, atoms identifiers. The following restrictions apply:

no title longer than 60 characters; the title may contain blanks and ends whith a linefeed;
identifiers should not be longer than 6 characters;
the mixing of uppercase and lowercase characters in file names should comply to the operating system conventions;

The whole structure on the input file is described in the following tables. Each parameter is detailled, it is fisrt following by a code which is used to indentify its nature. Then typical value are precised and the input is commented. Two special codes are used to identify the nature of the variables block '%' and the variable parameters '$'. Their use is described in the part encoding the variables in standard block after the header part in which there is no variable parameters.

It is possible to insert a block of comments between each block of the program; each line of comment must began with a character '#'. If not explicitly stated, comments are forbidden inside the programs blocks. The comments are faithfully reproduced in the xnd.new file.

Here the block structure of the coordinate file is detailed, giving the meaning of each parameter. In the first column, an identifier defines the nature of the variable.

c character
c[n] n characters max without space
d decimal
f float
s string, up to the end of the line (see key case below)
% kind of block
$ variable in block

The key structure

This structure has been introduced in the 1.2 release to allow new and optional parameters to be specified without change in the coordinates file structure. It also allows to use default values for common parameters. Inside keys, the string structure is slightly different: the string is read up to the end of the line expcept if the first character is a quote ', in this case if a quote is encountered before the end of the line, the string ends.
In the input file, the program search for a key beginnig by a '@'. They are followed by various token with their value. If a token is not encountered, the associated variable takes its default value. The order of the token is free but they are uppercase. The keys and their token are listed below together with their default values.
A special request can be issued to list all the token associated with a key and their default values at run time, just rename the @KEY in @?KEY.

Coordinates file header

The header from the previous 1.1 release are still recognised. In the 1.2 release the header uses keys. If the @XND key is not found after the title a 1.1 header is assumed.

The file will contain the following parameters which are listed in the tables.

Title and output info

Title	s		title of the refinement	up to the end of the line

@XND key, general parameters

The token in the following tables, describe the refinement procedure and the structure of the file. It is possible to introduce comments before or after this table with lines begining with a '#'.

@XND			key identifier
CYCLE	d	10	number of cycles to perform
EXPER	d	1	number of experiments
PHASE	d	1	number of phases
SYM	d	0	number of symmetry tables to be read in `xnd.k`
ANO	d	0	number of tables of anomalous scattering factors to be read
DIF	d	0	number of the scattering tables to be read in `xnd.k`
LST	c	`xnd.lst`	listing name
NEW	c	`xnd.new`	new file name
HKL	c	`xnd.hkl`	hkl file name
PLG	c	`xnd.plg`	plg file name

Basic and refinement info

The values, in the following tables, describe the refinement procedure and the structure of the file. It is possible to introduce comments in this table. Such comments always begin with '#' and continue up to the end of the line.

@MODES				key identifier
LSQ	d	0	0	full-matrix least square refinement
			+1	linear minimisation is used after each least square refinement
			+2	weight taken on calculated rather than from observed profile
			+4	(reserved to take care of local correlations)
			+8	(reserved for ponderation ascheme calculating weights on the intensity exceeding bakground level). number of cycles to perform
BGROUND	d	0	0	linear interpolation of the background
			1	spline interpolation of the background
			2	polynomial expension in tth
3	expension in q starting with q-2, q-1, q0, q+1 ...
PROFILE	d	0	0	pseudo-Voigt approximation of Voigt
PROFILE	d	0	1	Voigt (to avoid with asymmetry convolution)
ORDER	d	0		maximum number of terms in the polynome (`Temp`) expansion
ASYM	d	2	<0	instrumental (H+S)/L and \|H-S\|/L convolution and assymetry expansion on odd derivatives of gaussian for phases and experiment
			>0	same expansion without instrumental convolution
			=0	instrumental uses only (H+S)/L and \|H-S\|/L convolution and expansion only for phases
STOP	d	0.10		the refinement stops if the variation of the refined parameters is lesser than the product of `EpsStop` and their e.s.d.
PROF	c	`0.10`		the reflections are calculated in the region where `(Y_cal(i)-Y_bkg(i)) > EpsProf sigma(Y_obs(min))`
RELAX	c	`0.85`		damping factor

Printing codes

@OUTPUT				key identifier
NEW	d	1	<=0	no actualized copy of the `xnd.k` file
NEW	d	1	>0	creates the `n+1` actualized copy of `xnd.k`
PLG	d	1	<=0	no print of the file displaying the calculated profile
			1	prints the file displaying the calculated profile at the last cycle
			+2	without header
			+4	add end mark
			+8	add semicolumns between values
			+16	scale x using Q
HKL	d	1	<=0	no print of the hkl summary
			1	prints the hkl summary at the last cycle
			+2	additional print of all the neglected reflections in the listing file
			+4	additional print of all the null reflections in the listing file
			+8	don't sort lines by increasing 2theta values
			+128	additional print of all the reflections in the listing file
SYM	d	0	0	symmetry operations not printed in the listing file
			+1	symmetry operations explicitely read in `xnd.k` file are printed in the listing file
			+2	symmetry operations read in `xnd_sym.d` file are printed in the listing file
			+4	coordinates of generated atoms when reading the listing.
DIF	d	0	0	diffusion factors tables not printed in the listing file
			+1	scattering factors tables read in `xnd.k` file are printed in the listing file
			+2	scattering factors tables read in `xnd_dif.d` file are printed in the listing file
			+4	scattering factors tables are always printed in the listing file
COR	d	0	0	correlation matrix not printed in the listing file
			1	the whole correlation matrix is printed at the last cycle
			2-9	correlation matrix elements greater than 20-90% are printed
CIF	d	0	1, 8	attempt to generate some infos for cif file
KEY	c	1

Other files information

Most of the following parameters are no more pertinent, they come from backward compatibility and may disappear in the future.

@OTHERS				key identifier
VALID	d	0	0	used for alternate refinement
VALID	d	0	2-9	used for alternate refinement
DYDP	d	0	0	automatic dimension of the points and of the derivatives matrix
DYDP	d	0	`n`	dimension charged into memory
DATA	d	0	0	data file is saved in a binary temporary file
			1	data file is saved in a binary permanent file
			2	data file is read from a binary file; then the binary file is destroyed
			3	data file is read from a binary permanent file
DNAME	c			name of the binary file containing data information
TMPDEF	d	0	0	standard path to `xnd_dif.d`, `xnd_sym.d` and temporary files
			+1	explicit definition of the path to `xnd_dif.d`, `xnd_sym.d`
			+2	explicit definition of the path to temporary files
PATH	c			path to `xnd_dif.d`, `xnd_sym.d`
TMP	c			path to temporary files

Internal test parameters

Following group allows to carry some tests within xnd or to check the effect of some internal constants.

@TEST				key identifier
PRINT	d	0	0	allows to print matrix...
PRINT	d	0	1	print out ...
AS_RMIN	f	0	0	for assymetry convolution
AS_RMAX	f	0	0	for assymetry convolution
AS_RESOL	f	0	0	for assymetry convolution
AS_WIDTH	f	0	0	for assymetry convolution
BRG_RATIO	f	0.5		ratio between modes in R Bragg calculation

Symmetry tables

If nSym=@XND(SYM) defined in the header is non zero, the nSym symmetry tables are read here. They use the same entries than in the xnd_sym.d file.

Anomalous diffusion tables

If nAno=@XND(ANO) defined in the header is non zero, the nAno diffusion tables are read here.

`ADifName`	c[6]	name of the element identifier
`nLambda`	d	number of wavelenghts for which the correction is defined
the following three values repeated `nLambda` times.
`Lambda`	f	wavelenght at which the correction is defined
`f_prime`	f	correction on the real part of the diffusion table
`f_second`	f	imaginary part of the correction

This module has to be repeated for each table needed in the refinement. The correction (ITC vol C, p 219--222) is applied to the wavelengths differing less than 2e-4 A from the wavelenght defined in the table.

Diffusion tables

If nDif=@XND(DIF) defined in the header is non zero, the nDif diffusion tables are read here. They use the same entries than in the xnd_rdif.d file.

Encoding the variables in xnd

In the experiments and in the phases descriptions there are a lot of variables parameters which can be refined. They all used the same encoding and are group into blocks of parameters having the same behaviour. follows in the xnd.k file.

Experiments and Phases

Description of the nExper=@XND(EXPER) experiments follows in the xnd.k file. One experiment, even dummy, has to be present.
Then the description of the nPhase=@XND(PHASE) phases follows in the file. Like for experiment, there is always at less one phase.

End of the file

After the phases, comments are allowed. Then xnd read if possible a value for the Marquardt parameter and a code to specify how it decrease.

vMarquardt	f		Marquardt parameter (value added to the matrix diagonal)
cMarquardt	d		decreasing coef for `vMarquardt` in 1/20

New comments can be put after these values.

xnd top	Next file	Previous file

$Id: xnd_rd.html,v 1.3 2002/05/02 12:43:14 berar Exp $

c	character
c[n]	n characters max without space
d	decimal
f	float
s	string, up to the end of the line (see key case below)
%	kind of block
$	variable in block

xnd 1.21: input file