Squaw Use Notes
							JMBishop, 10/17/95

Squaw is now ready for running with the E852 analysis.  See file Squawrun.com
for running instructions for the test program.  See file Squawconv.notes
for extensive notes on the conversion process.  These documentaion files are in 
/gblusr/e852/squaw and /du02/e852/squaw.  Also there for documentation are
a list of Squaw fail codes and the mass name equivalences.

The source files are in /gblusr/e852/squaw/src and libraries are in 
.../squaw/ibm or .../sgi and in /du02/e852/squaw/src.  The libraries are 
compiled with the maximum optimization that works: -O2 on IBM and -O1 on SGI.

Following is a dummy main program, such as was used to be sure everything was 
available.  This has been compiled, linked and started on IBM/AIX.  A test
program squawtest.c that reads analyzer files is also in the above directories;
see Squawrun.com for its use.  See Doran Steinike's notes on the web for use 
of Squaw with his C interface routines, some of which are used by squawtest.

      PROGRAM SQUAWMAIN
C     MAIN PROGRAM FOR SQUAW.
C
      CALL SQUAWIO(list,ihist,ifmv)	! once to set I/O options
C
      CALL SQUAWMV(ifmv,idropg)	! once or each event to set main vertex 
C							fitting options
      CALL RESETCONMIN(newconmin)       ! once per run to reset min conf level
C
C	(from somewhere, load the input data common block)
C
      CALL SQUAW		! for each event
C
      CALL SQUAWEND		! only at end of data or test run
      STOP
      END

In the C code of the routine reading the analyzer tapes, these subroutines
must be called (lower case, with trailing _) and arguments must be passed by
reference.  The call to SquawIO sets flags for whether Squaw does any I/O 
(control card & print) or histogramming: 0 is none, 1 is normal Squaw data
card and print; -1 for ihist assumes the calling program wants Squaw's 
histograms, but control is with the calling program (+2 is special JMB option). 
Argument ifmv controls whether main vertex fits are attempted: 1 = yes, 0 = no.
The normal call for E852 will be (0,0,1); no Squaw print or card or histograms.
If no call is made to SquawIO, normal Squaw print and histogramming and no 
main vertex fits are done.  On the first call, Squaw will initialize its 
commons and I/O.  Summary results are added to the print file and histograms 
printed by the call to Squawend.  Squawend also deletes the temporary file 
fort.2.  SquawMV sets flags to control the main vertex fits.  ifmv is the 
same as for SquawIO.  Argument idropg controls whether an odd gamma is 
treated as a batchelor gamma at the main vertex (0) or (1) dropped as a 
stray gamma in the event; the default is 0: treat as batchelor gamma.  SquawMV 
has been added to avoid breaking existing code using SquawIO.  SquawMV can 
be called each event, if desired.  If you call SquawMV to set the gamma flag, 
you must have ifmv set to do main vertex fits, since this overrides the 
original value of ifmv set in SquawIO.  An alternative routine SQUAWA has 
been created, with a long list of arguments, for compatibility with Amir's 
fitter; it does only single vertex fits, but may get extended for multivertex 
fits.  Calls to SquawIO, SquawMV and Squawend are optional depending on how 
one wants to run the program.  If SquawIO is called to set for no Squaw I/O 
or histograms, the call to Squawend is not needed.  SquawMV is necessary 
only to set the idropg flag.

The routine ResetConmin has been created to reset the minimum confidence level
for an acceptable fit.  The default is 1.e-4.  This should be used with care.
It will be better to let Squaw do more fits and you select them than have
Squaw fail them.  There are some cases where a 1 constraint fit will have
a high Chisq/low confidence level and the multivertex fit will have an
acceptable fit with more constraints.  With the minimum confidence level set
too high, some probably good fits will never get tried.

All routines are incorporated into a library, libsquaw.a, and that is linked
into the calling program, along with the CERN library (Hbook is used for
monitoring results, histogram numbers all under 100).  2 makefiles exist in 
the /src directory, one for each platform for building the library (and the
test program).  Copies of these makefiles exist in the /ibm and /sgi 
directories for building the test program on each platform.  See Squawrun.com
for how to make the libraries.

The normal listing file is Fortran unit 3, initialized as file squawprint.lis 
with no directory specification.  This file will be reused, if it exists, 
when the program starts.  If listing is suppressed, this is written to 
/dev/null.  Histogram output is done to Fortran unit 19, initialized as file
squawhist.lis with no directory specification.  If histogramming is suppressed
or under caller control, this file is not created.  One control card image on
Fortran unit 5, squawcntl.dat, is read when normal listing is done; options 
are set to minimum without reading when listing is suppressed.  Fortran unit 2
is used for temporary storage by Squaw and is deleted at the end by Squawend.
One need not worry about any of these files if no I/O is selected in SquawIO.

The input common block is /fitpar/; see subroutines Makeid.f, Ctracks.f and
Gammas.f or Squawtest.c for these variables.  Output to the calling program 
is available thru common block /fitout/ for photon fits and block /fitoutmv/ 
for main vertex fits.  See subroutine Fitset.f and include file squaw.h for 
a description of the variables.

Track and vertex errors are currently explicitly set in routines Gammas and
Ctracks.  These should be tuned to produce reasonable fits.  When real errors 
are available from the Analyzer, we can either directly tune them or modify
them with the Fudge subroutine, as has been done in previous use of Squaw.
These routines must be edited and recompiled and put into the library to
change the errors.  Gammas and Ctracks must be modified to use any errors
eventually passed to them from the Analyzer.

The fits currently tried are pi0-->gamma+gamma, eta-->gamma+gamma and
etaprime-->gamma+gamma, plus a missing mass-->gamma+gamma fit.
Main vertex fits now work for 0-0-0, 0-2-2, 1-1-1 and 1-3-3 topologies with 
2, 4 or 6 gammas.  Events with 3 or 5 gammas are now tried with the odd gamma 
as a batchelor gamma at the main vertex.  Optional routine SQUAWMV allows 
treating the odd gamma as a stray, and fitting with one less gamma; see above.  
Main vertex fits try all pi0/eta/etaprime combinations that are justified by
the single vertex fits.  Note that the single vertex fits are also done when
main vertex fitting is selected, since they set the conditions for the main
vertex fits.

Additional fits have been added.  For 0-2-2 and 1-3-3 topologies, where there
are at least 2 charged pions at the main vertex, the following 2 vertex fits
are tried: eta -> 3pi, omega -> 3pi, etaprime -> eta pi pi.  If any of these
work and any of the normal multivertex fits work, then full main vertex fits
are tried with which ever of these have worked.  Since an additional vertex
has been added, these have 1 more constraint than the fits without these
intermediate mesons.