-------------------------------------------------------------------------------
This README file is Copyright (c) 1994 Christopher W. Churchill
See the COPYRIGHT file which must be in this directory for details.
-------------------------------------------------------------------------------

This directory contains the FORTRAN 77 source code for HAMSCATT.  

-------------------------------------------------------------------------------

The software is designed so that only the file 'hamscatt.par' will ever require
modification.  This file contains the integer parameters with defaults given:

maxcols   = 2048 ; maximum number of columns in image (cross dispersion)
maxrows   = 1600 ; maximum number of row in image (dispersion)
maxorders =  100 ; maximum number of orders in format
nvec      = maxcols*maxorders ; maximum length of the merit function ***
stdout    =    6 ; standard output unit 
stdin     =    5 ; standard input unit

*** DO NOT MODIFY nvec expression under any circumstances

The above parameters declare the maximum limits within which HAMSCATT, once 
compiled, can operate.  If your images are larger, these parameters will need 
to be updated in the 'hamscatt.par' file and HAMSCATT will need to be recom-
piled.  Your computer may not have enough memory to run larger images.  If
your images are smaller, you will free up considerable memory by reducing 
these parameters to the known values for the images. 

-------------------------------------------------------------------------------

HAMSCATT operates upon images for which an Apextract database exists with 
aperture centers and tracings.  Input files required by HAMSCATT are created 
by the user.  HAMSCATT outputs an IRAF background image file, a pixel mask file
named with the root name of the background image and the suffix '.dqf' (data 
quality file), and a fit file named with the root name of the background image 
and the suffix '.fit'.  The former contains the sigma rejected pixels, and the 
latter contains fitting statistics and the resulting fitting parameters.  

See the examples/ directory for details on these files.

-------------------------------------------------------------------------------

HAMSCATT algorithm specifics are documented in the source code.  If you want 
to know how HAMSCATT is posing the input to the least squares solver, you can
read the subroutine comments, in the routine headers and amongst the code.  
In particular view the 'gridim.f' and 'mask.f' files.

-------------------------------------------------------------------------------

During the first iteration, warnings may be issued from the SLATEC library.  
The most common warning is a complaint that a Jacobian element is "too close 
to zero".  The warning is insignificant; we have chosen not to supress it.  
However, if such warnings arise during later iterations, view HAMSCATT results
with extra scrutiny.  

-------------------------------------------------------------------------------

All file and standard I/O is contained in the routines io.f, hamscatt.f, and 
iraf.f.  This convention is desired to isolate numerical routines from device 
dependency.  File I/O is limited to the io.f routines.

When errors occur in numerical routines, they are flagged and passed back to 
hamscatt.f, where they are written to standard output.  This treatment could 
be treated more elegantly.  

When errors occur in iraf.f, they are IMFORT related I/O errors.  These are 
written to standard output in the routine 'alarm' (in iraf.f).  

-------------------------------------------------------------------------------


HAMSCATT written at the University of California, Santa Cruz under the
auspices of the Board of Astronomy and Astrophysics while Churchill
was a graduate student.

Contact Information:
Chris Churchill
Department of Astronomy
New Mexico State University
email: cwc[at]nmsu[dot]edu
-------------------------------------------------------------------------------