The UWXAFS Analysis Package Bruce Ravel, ravel@u.washington.edu 28 November, 1995 This document is an introduction to the UWXAFS3 package and a guide to its installation on your personal computer. 1. Introduction to the UWXAFS package Thank you for purchasing the UWXAFS analysis software. This document will introduce you to the contents of this package and explain to you how to install the package on your personal computer. The installation instructions presume that your are running MS-DOS on an Intel based personal computer or that you are able to run your personal computer in a DOS emulation mode. If you wish to install the software on a personal computer that cannot emulate the DOS operating environment, then you need two things: 1. A program that recognizes the zoo compression format. These programs are freely available for all major platforms. (See section 7.) 2. A Fortran compiler. The source code for all of the programs is provided on the diskettes. All of the codes are written with a strict adherence to the ANSI standard for the language and are known to compile and run on a wide variety of operating platforms. The UWXAFS package is updated by its authors occasionally, but these updates are not offered on diskette. Updates are available to all of our licensed clients, including you, over the Internet. Please see section 7 of this document for details on using Internet resources. If you have questions, concerns, comments, or complaints, please contact the principal investigator of the UWXAFS project: UWXAFS Project c/o Prof. Edward A. Stern Department of Physics Box 351560 University of Washington Seattle, WA USA 98195 phone: (206) 543-2023 fax: (206) 543-9523 e-mail: stern@phys.washington.edu or the maintainer of the archive: Bruce Ravel Department of Physics Box 351560 University of Washington Seattle, WA USA 98195 phone: (206) 543-0435 fax: (206) 543-9523 e-mail: ravel@phys.washington.edu URL: http://krazy.phys.washington.edu/~bruce Email communication is much prefered. 2. Installation Instructions 1. Choose a place on you hard drive where you want to store all of the files contained in the UWXAFS package. Typically this would be a subdirectory such as C:UWXAFS. You might make this subdirectory by entering the command: MD C:\UWXAFS 2. Make that directory the current working directory. If C:UWXAFS is the name of the directory that you chose, type CD C:\UWXAFS at the prompt. 3. To install of the files in the UWXAFS package onto your hard drive, type A:\INSTALL If the disk dirve that you are using is drive B, substitute B for A in that command. The installation will take a couple minutes. When the installation is completed, you will find that there are 4 new subdirectories, BINARIES, DOCS, SOURCE, and TOOLS. You will also find that that you have 8 megabytes less free disk space. The BINARIES subdirectory contains the executables of the UWXAFS programs. The DOCS subdirectory contains documentation for the programs. Several of the document files are in PostScript format, thus you will need a PostScript viewer or printer to use them. The SOURCE subdirectory contains the source code for each of the programs. All of the codes conform to the ANSI Fortran 77 standard and may be recompiled by any sufficiently powerful Fortran compiler. The TOOLS subdirectory contains a variety of useful files. Under that subdirectory you will find many example input files for the program atoms, all the files necessary for following the example in Appendix A of the autobk and feffit documents, a presentation of the McMaster tables in PostScript format, and an Emacs major mode for editing UWXAFS input files. You will need to place the subdirectory containing the executable programs in your path or move the executables to a subdirectory that is already in your path. In DOS, your path is set by the PATH directive in your autoexec.bat file. You might append the binaries subdirectory to your path by adding C:\UWXAFS\BINARIES to the PATH line of autoexec.bat. The UWXAFS package is distributed in a compressed archive format called the zoo format. Included with the distribution is a file called zoo210.exe. This is a self extracting archive containing the program for and manipulating zoo files and a document explaining its use. The program zoo.exe which comes out of the self-extracting archive is used to extract the files in the UWXAFS distribution. The extraction of zoo.exe from zoo210.exe is performed by the installation script, as is the extraction of files from the four zoo archives. 3. UWXAFS Diskette Manifest Here is a listing of the contents of the UWXAFS package. Diskette #1 contains the following files: 1. UWXAFS.PS: This document in PostScript format. 2. UWXAFS.TXT: This document in plain ascii format. 3. INSTALL.BAT: Installation batch file. 4. ZOO210.EXE: Self exploding archive containing the zoo archive utility. 5. BINARIES.ZOO: Compressed archive of DOS executables. Diskette #2 contains the following files: 1. SOURCE.ZOO: Compressed archive of Fortran 77 source codes. 2. DOCS.ZOO: Compressed archive of PostScript or ascii documentation. 3. TOOLS.ZOO: Compressed archive of miscellaneous utilities. The ZOO files are uncompressed when the installation script is run. Should you ever need to uncompress a single archive, execute the following command at the DOS prompt: zoo e// filename.zoo The next list is of the names of the programs in the exectuables and source codes archives. BINARIES.ZOO, contains DOS executables compiled with the Watcom Fortran compiler with full optimization enabled and producing an OS/2 flat model executable. SOURCE.ZOO contains the Fortran 77 source code for the first seven programs as plain text files. There are no other programs presently distributed with the UWXAFS3 package. 1. feffit: A program for fitting EXAFS data with theoretical standards from feff. 2. atoms: A program for constructing feff.inp files from crystallographic information. 3. autobk: A program for removing background functions from absorption data. 4. ratio: A program for performing log-ratio analysis of filtered EXAFS data. 5. reform: A program for data file type conversion. 6. listdf: A program for viewing the contents of a UWXAFS binary data file. 7. copydf: A program for transferring contents between UWXAFS binary data files. 8. dos4gw: Extended memory manager used by the distributed DOS executables. 9. pminfo: DOS memory probe. The documentation archive, DOCS.ZOO, contains the following files. Note that a PostScript viewer or printer is required to use the PostScript documentation.: 1. xafs.ps: PostScript journal article from the XAFS VIII conference discussing the UWXAFS package. 2. feffit.ps: PostScript documentation for feffit. 3. atoms.ps: PostScript documentation for atoms. 4. autobk.ps: PostScript documentation for autobk. 5. fileh.ps: PostScript documentation for reform, listdf, copydf and the UWXAFS data file handling algorithms. 6. ratio.doc: Ascii documentation for ratio. The documentation archive, TOOLS.ZOO, contains the following items: 1. McBook: PostScript version of the McMaster tables of x-ray cross sections and associated files. 2. Feffit mode: An Emacs lisp program for editing input files to UWXAFS programs using the Emacs text editor and associated files. 3. Analysis example: Files described in the examples of Appendix A of the autobk and Appendix A of the feffit document. 4. Atoms example: Many example input files for atoms. 5. fd2fi: Awk script and associated files for converting the files.dat file from feff into a feffit.inp file. 4. Restrictions, License, and Copyright Information All of the programs in the UWXAFS 3.0 package are copyrighted software and a license from the University of Washington Office of Technology Transfer must be obtained for their use. This is necessary to protect the interests of users and of the University of Washington. Both academic/non-profit and corporate licenses are available. New users should request the latest version of the package from the authors. The license may be obtained by writing to UWXAFS Project c/o Shari Stern Department of Physics, FM-15 University of Washington Seattle, WA USA 98195 phone: (206) 685-4091 fax: (206) 543-9523 e-mail: sstern@u.washington.edu Government Copyrights (DO NOT DELETE): This work was supported in part by DOE Grant DE-FG06-90ER45425 and by the Royalty Research Fund of the University of Washington. In accordance with the DOE FAR rules part 600.33 "Rights in Technical Data - Modified Short Form" the following clause applies to the UWXAFS programs: (c)(1)The grantee agrees to and does hereby grant to the U.S. Government and to others acting on its behalf: (i) A royalty-free, non-exclusive, irrevocable, world-wide license for Governmental purposes to reproduce, distribute, display, and perform all copyrightable material first produced or composed in the performance of this grant by the grantee, its employees or any individual or concern specifically employed or assigned to originate and prepare such material and to prepare derivative works based thereon, (ii) A license as aforesaid under any and all copyrighted or copyrightable work not first produced or composed by the grantee in the performance of this grant but which is incorporated in the material furnished under the grant, provided that such license shall be only to the extent the grantee now has, or prior to completion or close-out of the grant, may acquire the right to grant such license without becoming liable to pay compensation to others solely because of such grant. (c)(2) The grantee agrees that it will not knowingly include any material copyrighted by others in any written or copyrightable material furnished or delivered under this grant without a license as provided for in paragraph (c)(1)(ii) of this section, or without the consent of the copyright owner, unless it obtains specific written approval of the Contracting Officer for the inclusion of such copyright material. 5. Graphics and Plotting This section is taken verbatim from our World Wide Web site. The URL for this document is: http://krazy.phys.washington.edu/html/graphics.html With the release of the UWXAFS 3.0 package, we have made a deliberate decision to discontinue our support of programs for plotting and displaying XAFS data. Our reason for this is simple: we are experts in the subject of data analysis and encoding analysis algorithms but not in the subject of graphical interfaces. While we consider our programs to be the best XAFS analysis software available, we know of many plotting programs that are better than anything we can write. For many years, the program idp has been associated with programs distributed by the UWXAFS project. idp reads a special binary file format that is generated by previous versions of the UWXAFS programs. The programs in the UWXAFS 3.0 package are also capable of writing this file format, thus are compatible with idp. idp can be found at Illinois Institute of Technology's XAFS Database. The UWXAFS 3.0 programs also read and write data in a simple ASCII format. The data is stored in columns. For details read the File Handling document. This file format is chosen for its great flexibility. Column data stored in an ASCII format is easily transfered among platforms and is understood by virtually all plotting programs. If you have some favorite plotting program that uses the special graphics capabilities of, say, X Windows, Microsoft Windows, or Macintosh, then you should be able to use the column data format. The plotting program most often used by the members of the UWXAFS project is gnuplot. gnuplot is a freely available plotting package that supports a wide variety of platforms. We like it because it is fairly robust and the price just cannot be beat. A nice front-end to gnuplot is fudgit. Look for version 2.41. fudgit is an extensible driver for gnuplot and allows the user to do data manipulation, such as e0 shifts, k-weighting, Fourier transforms, and fitted splines. Versions of this exist for VMS and DOS as well as Unix. fudgit shares with gnuplot the fine feature of being free. See section 7 of this document for information about finding idp, gnuplot, and fudgit. 6. Reporting Bugs and Problems This section is taken verbatim from our World Wide Web site. The URL for this document is: http://krazy.phys.washington.edu/html/bugs.html What should you do if you have a problem using the UWXAFS software or if you find a bug/feature in one of the programs? 1. Reread the documentation. It is possible that you are simply misunderstanding what the code is intended to do. 2. If you are convinced there is a problem, try downloading the most recent version of the program. It is possible that we already know about your bug and have corrected it. We will occasionally post bug-corrected versions of the programs on the WWW/anonymous ftp site. You will, of course, need to use the user authentication code that you were given when you first obtained the software. 3. If your problem is addressed neither in the document nor in the latest version of the code, then you should contact the author of the code. The author's name, mailing address, electronic address, phone, and fax should be in the code documentation. The prefered method of communication is by e-mail. You should provide as much information about the nature of the problem as possible. Specifically you should send: a. The problematic data, if applicable. b. The problematic input file. c. Any output files generated by the program. d. Any run-time messages written to the screen. e. What kind of machine you are working on. f. Which compiler and compiler flags you used to make the executable. 4. If you cannot contact the author of the program, then contact the maintainer of this Web site: Bruce Ravel University of Washington Department of Physics Box 351560 Seattle WA, 98195, USA FAX: (206) 685-0635 PHONE: (206) 543-0435 e-mail: ravel@u.washington.edu URL: http://krazy.phys.washington.edu/~bruce 7. Internet Resources The entire UWXAFS3 package is available on the Internet, either via the World Wide Web or by ftp. This is our prefered method of distribution of our software. It should also be preferable for you, the user, because, in this way, you have access to the most up-to-date versions of all codes and files. Updates to the various files and programs distributed in the package are made at unpredictable intervals. Your diskettes were made with the most up-to-date files available at the time that the diskettes were created. We do not and will not distribute updates on diskettes, but updates are continuously available on our Internet resources. The documentation and all of the files contained in the TOOLS.ZOO archive are freely available. The source codes and executables for DOS and Macintosh computers are protected by user authentication barriers. Since you are a licensed user of the UWXAFS3 package, you are qualified to gain access to the source code and binaries. To obtain a user authentication password and instructions on using it, contact Bruce Ravel by e-mail at ravel@u.washington.edu. Here is a list of World Wide Web URLs for all programs or Internet resources mentioned in this document: 1. The UWXAFS Project Homepage: http://krazy.phys.washington.edu 2. The FEFF Project Homepage: http://krazy.phys.washington.edu/Feff 3. Illinois Institute of Technology XAFS Database: http://xafsdb.iit.edu/database 4. The gnuplot Homepage: ftp://ftp.dartmouth.edu/pub/gnuplot/ 5. The fudgit Homepage: ftp://ftp.physics.mcgill.ca/pub/Fudgit/ 6. To find the zoo archive utility for your platform, use any World Wide Web browser to look at http://www.acs.oakland.edu/oak/oak.html. Choose the link that says Virtual Software Library front desk. Then choose the link that says quick search and search for the word zoo. You will be presented with dozens of links to freely available programs for many different platforms.