============ INTRODUCTION ============ Debyer is software for calculation of diffraction patterns and PDFs from a set of atomic positions. Typically, the atomic positions are: - the result of molecular dynamics or other simulations, - or simply a geometrical model of investigated structure (i.e. just positions are generated, no interactions or time evolution -- such modeling is sometimes used in analysis of experimental diffraction data). Even tens of millions of atoms can be handled. The diffraction patterns are calculated using Debye's scattering formula: I(k) = \sum_{i,j} f_i f_j sinc(k r_ij) The parallel version of the program uses MPI library. By default, the serial version is built. The program can be also used as a converter of file formats with atomistic configurations. See the USAGE section for details. ============================ COMPILATION AND INSTALLATION ============================ See INSTALL file for generic instruction. In short, you need to type: $ ./configure [and options here] $ make # make install A few other programs with prefixes sic_ and dbr_ are also built. They are not documented, and probably will not be useful for you. The program can be safely compiled with -ffast-math option for GCC. If your processor supports SSE, use scalar floating point instructions present in the SSE instruction set. Eg. if you compiler of choice is GCC 4.x, and your processor is Pentium 4, type: ./configure CFLAGS="-O3 -march=pentium4 -msse2 -mfpmath=sse -ffast-math" If you want to make a parallel version, use the option --enable-mpi. ===== USAGE ===== Invoking the program with the option -h will show you the following usage instruction: Usage: debyer [OPTIONS]... [FILE]... -h, --help Print help and exit -V, --version Print version and exit -q, --quiet silent mode -v, --verbose verbose mode calculation of input ID (internal RDF): -r, --cutoff=FLOAT cut-off distance for ID calculation --quanta=FLOAT interatomic distance discretization quanta (default=`0.001') -a, --pbc-a=FLOAT PBC box length in x direction -b, --pbc-b=FLOAT PBC box length in y direction -c, --pbc-c=FLOAT PBC box length in z direction --sample=INT calculate ID by random sampling n atoms -d, --id-file[=FILENAME] file in which input ID is to be stored, if any file format conversion; write atom positions to...: (if FILENAME is not given, it will be generated based on the input filename) --write-xyz[=FILENAME] XMOL .xyz file --write-cfg[=FILENAME] AtomEye extended .cfg file --write-dlpoly[=FILENAME] DL_POLY CONFIG file --write-dlpoly-s[=FILENAME] same, but sort atoms using symbols --write-lammps-data[=FILENAME] LAMMPS data file --write-pdb[=FILENAME] PDB file calculation of the final result from ID: Group: output only one of the following options can be selected -x, --xray x-ray powder pattern -n, --neutron neutron powder pattern -S, --sf scattering factor (a.k.a total scattering structure function) -R, --RDF radial distribution function (RDF) -g, --PDF pair distribution function (PDF) -G, --rPDF reduced PDF -f, --from=FLOAT start of calculated pattern -t, --to=FLOAT end of calculated pattern -s, --step=FLOAT step of calculated pattern -l, --lambda=FLOAT wavelength for diffraction pattern. If not given, output in Q --ro=FLOAT numeric density, required for PDF and rPDF calculation -w, --weight=STRING how to weight RDF/PDF - using _x_-ray f(0) or _n_eutron b factor (possible values="x", "n", "1" default=`1') -o, --output=FILENAME output filename. If not given, will be auto-generated. cutting, i.e. calculation only for sub-system: --only-x-gt=FLOAT minimum in x direction --only-x-lt=FLOAT maximum in x direction --only-y-gt=FLOAT minimum in y direction --only-y-lt=FLOAT maximum in y direction --only-z-gt=FLOAT minimum in z direction --only-z-lt=FLOAT maximum in z direction benchmarks: --ben1=ATOM-COUNT calculate ID for SiC pseudo-grain with ATOM-COUNT atoms. The following file formats with atomic coordinates are supported: * XMOL .xyz file (read/write) * AtomEye .cfg format (read/write) * DL_POLY CONFIG format (read/write) * PDB format (write-only) * LAMMPS text format (write-only) * the simplest format, which have in each line atom symbol and three numbers (x,y,z), or first three numbers and than atom symbol (read/write). Options --write-xxx can be used to convert file format. If cut-off=r_c is set, the distances r_ij > r_c are ignored. The cut-off is necessary when dealing with periodic system. If the option "--ro" is given, the cut-off correction is added. This correction is calculated with the assumption that that the atomic structure for r_ij > r_c can be approximated by continuum. This correction is not negligible, so avoid using option "--cutoff" without "--ro". For each pair of atom types the histogram of interatomic distances is calculated. This is called `ID' or `internal-RDF' (I haven't found a better name - MW). The option "--quanta" changes the size of histogram bins. The ID can be stored in file, and then you can quickly calculate another pattern or PDF from the same data -- just give the ID file as an input file. The program supports orthorhombic periodic boundary conditions (PBC). There is also a partial support for parallelpiped PBC. When the input file is large, it may be reasonable to randomly draw n atoms and consider only distances r_ij, where i is one of the drawn atoms. This way you may get a good enough pattern much faster. PDF/RDF can be weighted ("-w") using x-ray f(0) or neutron b factor, so it can be compared to data obtained from diffraction experiments. Here is the formula: RDF(r) = 1/N * \sum_{i!=j} W_ij \delta(r - r_ij) where W_ij is one of: W_ij=1, W_ij = b_i * b_j / ^2 W_ij = f_i(0) * f_j(0) / ^2 At last, remember about the option "-v". Examples: # Calculate diffraction pattern calculation: $ debyer -x -f1 -t20 -s0.01 -l0.1 -o t.dat zns.xyz # Don't calculate anything, convert data from AtomEye format to LAMMPS format $ debyer --write-lammps-data=a.lmps foo.cfg $ debyer --write-lammps-data foo.cfg # the output will be written in foo.lammps ========== BENCHMARKS ========== "./debyer --ben1=20000 " on Celeron-M Dothan 1.4GHz COMPILER OPTIONS TIME [s] GCC 4.1 -O3 -ffast-math 23.4 GCC 4.0 -O3 -ffast-math 24.6 GCC 3.4 -O3 -ffast-math 24.1 GCC 3.3 -O3 -ffast-math 24.0 GCC 4.1 -O3 -ffast-math -march=pentium-m -msse2 -mfpmath=sse 10.7 GCC 4.1 -O3 -ffast-math -march=pentium-m -msse -mfpmath=sse 11.3 GCC 4.1 -O3 -ffast-math -march=pentium-m -msse2 -mfpmath=sse,387 11.4 GCC 4.1 -O3 -ffast-math -march=pentium-m -msse2 -mfpmath=387 18.3 GCC 4.1 -O3 -ffast-math -march=pentium-m 18.7 Compiler flags do matter! ============== ID FILE FORMAT ============== You don't need to read this section to use the program. ID file is a file which stores distances between atoms. Writing the distance table to a file is useful when more then one diffraction pattern or PDF is to be calculated. The ID is also called internal-RDF An example of id file: -8<---------------- debyer-id 1 # by debyer ver. 0.1 system Si 12925 C 12925 step 0.001 bins 10000 atoms Si Si sample 1000 1885 1 1892 1 1896 1 1898 2 ... atoms Si C sample 1000 1469 1 1484 2 1503 1 ... atoms C C 1869 1 ... -8<---------------- id file format: Line with '#' in the first column is a comment. The file must begin with magic string "debyer-id " and version of id file (1). Three lines follow: system ATOM-SYMBOL NUMBER-OF-ATOMS [ATOM-SYMBOL NUMBER-OF-ATOMS]... step REAL-NUMBER bins INTEGER-NUMBER The RDF histogram has cut-off at the distance r_cut = step*bins. Histogram of every pair of atom types is written as header and data. Header format is: atoms ATOM1-SYMBOL ATOM2-SYMBOL [sample INTEGER] If the histogram was made as a sum of RDFs around sampled atoms, the number of sampled atoms is included. Otherwise, if all atoms are included in RDF, "sample" is omitted. Histogram data is given as the list of numbers, two numbers per line, the number n of histogram bin and the number of pairs of atoms, that are in distance r: n*step < r < (n+1)*step. Empty bins can be omitted (usually the great majority of bins is empty).