Title                  :XMAQNT
Keywords               :quantitative correction, PAP, PROZA, XPP
Computer               :Any with ANSI-C; tested on IBM-PC, Unix (Sun and HP)
Operating System       :Any
Programming Language   :ANSI-C
Hardware Requirements  :None
Author(s)              :Cameron Davidson
Correspondence Address :CSIRO, Division of Manuf. Technol., P.O Box 883
                       :Kenmore, 4069, Australia
                       : fax +61 7 212 4681
                       :email (Internet): cjd@brb.dmt.csiro.au
Compression Method     :ZIP -use 'unzip' or 'pkunzip -d' on MS-DOS, or
                       : 'unzip -a' on Unix.
Description:

    XMAQNT.DOC : V1.0 25-Jun-93

    XMAQNT is a software package for performing quantitative X-ray
    microanalysis. It is written entirely in ANSI C and should be
    compatible with most C compilers with little change.
    It has been built and tested on the following systems:

    Unix - gcc (GNU C Compiler) under SunOS 4.1.2 (Sun sparc)
    Unix (HP-UX) - Hewlett Packard C compiler on a 700-series machine 
    MSDOS - using Microsoft C version 5.1 and
    MSDOS - using the free 32-bit GNU C compiler and dos extender
        (the DJGPP package)

    It provides:
    1. A program to perform PAP, PROZ-A or XPP quantitative corrections on
        X-ray intensity ratios.
    2. a library of basic atomic chemistry and X-ray related utility
        routines.
    3. use of databases for X-ray lines, edges and Mass Absorption
        coefficients, with the possibility of supporting multiple
        such databases.
    4. utility programs for creating, examining and editing these
        databases. 
    5. support for plotting the calculated Phi-Rho-Z curves. (This
        requires the user to obtain the free plotting package
        GNUPLOT - available for many different operating systems.)
                   XMAQNT - readme.1 (V1.0 25-Jun-93)

References:
    Main correction routines:
	1. J-L Pouchou and F Pichoir, pp 31-75, in "Electron Probe Quantitation",
	 Ed Heinrich and Newbury, Plenum:NY 1991
	2. G F Bastin and H J M Heijligers, pp 145-161, ibid.
    Other routines:
	1. S J B Reed, Microbeam Analysis, p 109 (1990)
	Many Others; may be referenced in the routines in which they are used.

Compilation Procedure:
Linking Procedure:
    These will vary slightly depending on which C compiler you have.
    Makefiles for several systems are supplied and are described in some
    detail below.

Test Data:
    Several test datafiles are supplied in the 'examples' directory
    of the zip file containing the source code. Their use is described
    below.

Acknowledgements:
    The main correction routines are derived from fortran routines
written by Mr X. Meng at Cambridge University Dept of Earth Sciences (now
at Dept of Materials Science).
All main algorithms are based on references above.
Not all situations discussed in those papers are coded; for example I
have not made the adjustments necessary for very low overvoltages.
The K/K fluorescence is based on Reed 1990, while other fluorescence
calculations are based on the earlier method of Reed.

    Many of the support functions were developed while I was working with
Link Analytical (now part of Oxford Instruments) and they draw to some extent
on the Fortran code in their AN10000 and eXL ZAF-4 product. I am grateful
to Dr P. Statham for permission to release that code.

    I thank Dr D. Cousens for access to the HP computer at Univ of
Queensland Centre of Micr. and Microanalysis and for data from the
JEOL 8800 probe for testing the code.

Bugs:
    I am certain to have introduced some errors either in transcription or
in writing my own code. Please let me know of any you find. If you try it
and can compare it with other correction programs I would like to know the
outcome, no matter whether the results agree or disagree.

Enhancements:
    If you would like to help improve the program then please get in touch
with me first - I or somebody else may have already done it or be working on
other code which affects your proposed changes.

Restrictions on use:
    This software may be used free of charge whether for commercial or
non-profit use. The source code supplied is in the public domain.

Warranty:
    This software comes with NO warranty of any sort, expressed or implied.

Contact:
    I am willing to answer questions (particularly if you find my
instructions confusing and can help improve them) but you should bear in
mind that this is not part of my job and I can only do it in my spare time.
If there are questions regarding compilers and such then I would ask you
to try your local experts first since I have only used the ones described
below.
    I can be contacted by e-mail on the Internet as:
cjd@brb.dmt.csiro.au     (or, failing that try cjd@cat.csiro.au)

-------------- INSTRUCTIONS ----------------

What you should have:
    When the source code is unzipped you will have created a directory tree
starting with one named xmaqnt. Change to that directory.
It should contain the following files:
readme - this file, the same as xmaqnt.doc!
makef.xxx - makefiles for various systems on which I have built the software.
  Each is specific to a version of Make, but they are quite basic and should be
  useable with any half-decent Make. The DOS versions suffer the usual problems
  of command line length limitations and the thousand different ways of
  resolving it. If all else fails just make the response files by hand.
  Each subdirectory will also have makefiles with the same naming scheme.
    makef.c51 - for Microsoft C compiler V5.1 (used P.D. ndmake; if you only
        have MS nmake, I think you need to rename to 'makefile'
        (I've not tried it)
    makeall.bat - MS-DOS batch file to perform the same as "make all" if the
        top-level makefiles do not work for you.
    makef.gcc - GCC for dos (DJGPP), used with GNU make for DOS.
        DMAKE nearly works, if you
        don't run the overall makefile from the top directory, but
        run the individual makefiles in the order specified below.
    makef.sun4 - GCC for Sun SPARC, using standard make
    makef.hp   - HP cc (not sure of exact description/version)
directories: the current directory should also contain 6 subdirectories:
    lib - the library source code
    xmaqnt - the main source code
    utils - a couple of utility programs for checking the data.
    mactbl - for constructing MAC database files.
    xwt - for constructing the X-ray wavelength database file.
    examples - some example standards files, as well as example input and
    	the output you should see from it.


How to set it up:

1. Choose your default data directory:

The xmaqnt programs require a directory tree for necessary data files:
by default the data files are below a root directory:
"/usr/local/lib/xray" for unix systems, or
"C:\XRAY" for MS-DOS systems.
If these are not suitable then you should edit the file xrdata.c in the
lib directory. You can also override the directory name on an individual
basis by setting an environment variable named XRAY_DATA.
The data directory tree structure is as follows (where XDD represents
whatever is defined as the X-ray data file root directory, whether it be
defined using the enviroment variable or the built-in defaults):
XDD/data    - Xray database directory. Contains
         xray2.dat - the binary lines and edges database
         mac_N.dat - a number of MAC database files.
                N = 0 for K alpha lines
                N = 1 for L alpha line, etc.
                N = 3 for K beta lines
XDD/stds    - all the  standards information
XDD/stds/comps    - a directory containing all the standard compositions
        for compound stds; each standard is specified in an individual
        file. The name of the standard used by XMAQNT is the name of
        the file, and so must conform to filename restrictions imposed
        by whatever operating system you use.
XDD/stds/pap0150    - directory containing precalculated stds factors
        for using PaP model at 15.0 kV. Each standard named in comps
        will have a file of the same name here (if used at 15kV with
        PAP). Additionally, factors for pure element stds are stored
        in files named e.g. "pureFe" for iron, "pureK" for potassium.
XDD/stds/pap0200/*  - ditto for PaP at 20 kV, thus you can have datasets
                to nearest 100V.
XDD/stds/xpp0150/*  - precalc. factors for XPP at 15.0 kV.
XDD/stds/prz0150/*  - precalc. factors for PROZ-A at 15.0 kV.
    The pap/xpp/prz stds files and directories are created as required
    by the software (well, mostly).
Before you start you should create the directories:
XDD,
XDD/data,
XDD/stds and
XDD/stds/comps.
On Unix systems they should be given read (and possibly execute) permissions
to the world. Whether any have write permission will depend how you see
system security versus flexibility. There is some provision made in the
code for using group-IDs and/or running setGID, but it has not been tested
much (see xmaqnt/std_io.c if you are interested - or if you are building for
Unix and want to disable it).

2. The xray Lines and Edge database.

The program xmasterb in directory xwt reads Chuck Fiori's ascii EMMPDL
database file LINESMAS.TRS and converts to a binary format. You should obtain
the latest version and put a copy in the xwt directory. The binary datafile
which xmasterb will create is called xray2.dat (the number denotes the
revision number of the format).

3. Building the programs:

If you have a system matching one of those already tested then you
can probably proceed by executing "make all" in the current directory.
This will attempt to:
    1. build the library,
    2. build the xmasterb program in xwt, and then run xmasterb to
       build the actual database file.
    3. build the MAC file utilities
    4. build utility programs viewxray and viewfl,
    5. build the xmaqnt program itself.
Nothing is installed. The MAC database files are not built.

3A. Building the programs the hard way.

If the 'make all' failed, or if you did not want to try it, you should go to
each of the directories in turn, check the makefile (same naming convention
as described above) and possibly modify it for your own system, and try
"make" or "make all". The lib must be built first, but the others can be
built in any order.

4. Install Lines and Edge database

assuming you had the file linesmas.trs and succeeded in creating xray2.dat,
You can install it in (copy it to) your xray data directory, keeping the
name "xray2.dat".

5. MAC database:

In directory mactbl you should have two executables: mactbld and editmac.
MACTBLD builds a MAC database file for one particular X-ray line for every
emitter element, for every absorber element. The
initial database files contain the parameterised values from Heinrich 1986
where the line energy is less than 20keV and Heinrich 1964 where line energy
is greater than 20keV. The file is named "mac_n.dat" where 'n' is 0 for K alpha,
1 for L alpha, through to 5 for M beta.
Answer questions as asked when MACTBLD runs, in order to specify
which xray line to do. Specify -1 to make all data files (on a PC you may get
sick of waiting - on a HP700 it takes a few seconds!each). Then move the data
files to the XDD/data directory to make them accessible to the other
programs.

5A. MAC database extensions:

(you should probably come back to this section later, after you have the
basic system working).
To enter you own MAC values in particular cases run the program EDITMAC
which will ask you questions as you go along. There are several sets of data
files included here which contain input data for EDITMAC.
Those with names matching pap*.mac incorporate the recommended values of
Pouchou and Pichoir (from the Electron Probe Quantitation book);
those matching he_*.mac contain Henke and Ebisu values; while
those matching h_*.mac are Henke, Tanaka, et al.
Thus, file "pap_b_ka.mac" contain selected values for Boron K alpha in various
absorber elements from P and P. Run:
    editmac < pap_b_ka.mac
and repeat for any other data sets you wish to update. Only one value for any
given absorber and emitter is stored. Previous values are overwritten and lost.
NOTE: Editmac works directly on the data files in their official places as
defined by XRAY_DATA, and as used by all other programs. MACTBLD creates
files in the current directory - it does not touch the standard files.
You may specify an alternate MAC file by setting an environment variable
XRAY_MAC_PREFIX. Thus, if you say (on DOS):
set XRAY_MAC_PREFIX=HE
then all software would read/write data files HEMAC_n.DAT. You would need
to create these files youself; start by copying the basic MAC_n.DAT files.
The XRAY_MAC_PREFIX option should only be used for short term experiments, since
it can lead to confusion: precalculated standards data files may end up
with data using the wrong MACS. For long term use of more than one set of
MACs you should create an entire extra directory tree and use the XRAY_DATA
environment variable to select one or the other. you can just copy over
(or on Unix, you can link) the lines and edges database, and standards
compositions files.

6. Install

Decide on a directory in your PATH which will contain all your executable
programs and copy each one there.
Use the program VIEWXRAY to check the lines and edges as well as the MAC
data.

7. Test

    1. Copy the sample stds composition files from examples/comps/* into
    directory XDD/stds/comps.
    2. Calculate stds factors... run
           xmaqnt -s al2o3
           xmaqnt -s quartz
    3. change current directory to examples.
    There is a sample datafile "quantin" and two example output files
    "qout" and "qout.ox" which were obtained by running the program
    as specified below. The input data is arbitrary - resemblence to
    anything sensible is unintentional.
    Run the program with sample input datafile:
       xmaqnt quantin
    Then run it again, this time with Oxygen estimated by stoichiometry...
       xmaqnt -eos quantin


Type "xmaqnt -h"  for a list of options on how to run the program.
run xmaqnt and enter data when prompted to find the input file format.
Note that if you have a number of options which you always invoke then
you can put these into a file called "xmaqnt.opt" in the current directory
and the program will read them after parsing the command line. Thus if you
always wanted to use xpp and always worked at 25kv for a particular data set
your file xmaqnt.opt would contain:
-mxpp
-kv25
If you wish to permanently change defaults for
accelerating voltage, correction model, or detector take-off angle
then edit the file maqinit.c in directory xmaqnt.
Changing correction model involves changing 4 separate global variable
initialisation parameters (on 4 successive lines).

Input data format:

Data can be entered from a file or else from std input (keyboard).
If data is from std input the the user is prompted for data.
The list of all measured elements is entered first:
one element per line. On each line give:
chemical symbol, xray line, standard name 
a blank line terminates the element list.
All data should be SEPARATED BY SPACES AND/OR TABS, use no commas.
If standard name is omitted then a "pure" std is assumed.
If xray line is omitted the a pure std and a default line is assumed (either
Ka, La or Ma depending on atomic number)
Then come the data sets: any number of analyses may be added to the one input
file, but only the one element list is allowed. Lines beginning with "#" may be
included - the "#" is removed and the remainder of the line is used as a label
for printout of the next result.
Succeeding lines give the X-ray intensity ratio (unknown / standard) for the
elements in the same order as the element list, one element per line. Each
line may also have a second number which gives the estimated relative
std deviation of the intensity ratio (as a fraction of the input ratio value).
A blank line or end of file terminates the program.

STANDARDS:
Standards are a bit messy at the moment. Before they can be
used for an analysis you have to:
    1. define the composition (if not pure) (see description below for
        format of stds composition file - use any normal text editor)
    2. precalculate the std correction factors using the command
        xmaqnt [options] -s sio2               (e.g. for a defined std)
        or
        xmaqnt [options] -s pure        (for a pure std. )
The stds factors will now be stored in files (in ASCII format) and useable
for full corrections.


Format of standard composition file:
Look at the examples given in examples/comps
The name of the file is how the standard is referenced in the software.
You should therefore choose an obvious name.
line 1, should begin with '#' and is followed by a verbose name for the
        std - say anything you like (80 chars max) (nothing is done
        with this name at the moment by any programs) but it must
        be present.
line 2, should contain the letters "atomic" if data input is in atomic ratios
        or "oxide" if the data expresses oxide wt percents,
        otherwise the data is interpreted as element weight percent
        You can also add the word "fraction", to express data as
        mass fraction, rather than percent.
line 3 to end of file, should specify an element, an X-ray line, and the
	concentration, in whatever units you specified.

Current problems:
1. The program should be able to calculate standards factors when they
   are required, and not require them to be done in advance.
2. The program should not need to be told an Xray line (this is a fault in
   the simplistic approach which I took to storing stds factors ahead of the
   time they are required).
3. The element valence for oxide calculations is assumed
   to be the default value, unless a modification is given in the command line,
   every time the file is read!
   There should perhaps be a way to specify valence in the input file.
   The use of xmaqnt.opt would be a partial solution.
4. It has not had enough use to find all the other problems.