The goals of this example are:

A. (i) Generate gamma p -> pi+ pi- pi+ n events, both with physics amplitudes and without
   (ii) Pass generated events through mock toy_detector
B. Perform a fit to extract the production amplitudes as a function of M(pi+ pi- pi+)
C. View fit results

<><><><><><><> Quick recipe for doing example <><><><><><><><>
cd $HALLD_HOME/src/programs/AmplitudeAnalysis/Examples/threepi
gen_3pi -c ../../../Simulation/gen_3pi/gen_3pi.cfg -o threepi_data_gen.root -l 0.7 -u 2.0 -n 50000
toy_detector threepi_data_gen.root threepi_data.root
gen_3pi -c ../../../Simulation/gen_3pi/gen_3pi.cfg -o threepi_gen.root -f -l 0.7 -u 2.0 -n 200000
toy_detector threepi_gen.root threepi_acc.root
./divideData.pl
cd threepi_fit/bin_10
fit -c bin_10.cfg
cp bin_10.fit ../par_seed.txt
cd ../..
./driveFit.pl
plot_3pi -o threepi_fit.txt
root -l drawWaves.C
<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>

-------------------------------------------------
A. Generate MC events
-------------------------------------------------

1. We first need to create a sample of MC that will act as the
   data.  This sample should be generated with appropriate
   physics angular distributions.  The executable gen_3pi is
   provided for this.  To generate at least 50000 events with 
   3 pi invariant mass from 0.7-2.0 GeV/c^2 run the command:

   gen_3pi -c ../../../Simulation/gen_3pi/gen_3pi.cfg -o threepi_data_gen.root -l 0.7 -u 2.0 -n 50000

   You can examine the gen_3pi.cfg file to see the various generated
   resonances and strengths.  The default file utilizes 100%
   polarize beam, but this can be altered as noted in the file.

   In reality the file would then be passed through HDGeant and also
   some reconstruction program.  To save, time, we will use the
   executable toy_detector, which randomly throws away some events
   based on M(pi+pi-pi+) (examine source for details).  Run:

   toy_detector threepi_data_gen.root threepi_data.root

   The file threepi_data.root is the analog of reconstructed data
   acquired with the detector.  The file threepi_data_gen.root
   has no analog in a real analysis as it would correspond to
   list of the actual four-vectors produced in the pure signal events.

2. Normalization of the probability distribution functions used in
   the fit depends on Monte-Carlo integration of the product of
   the detector acceptance and the model-predicted density of events
   over phase space.  In order to construct these integrals we need
   samples of generated and accepted Monte Carlo which do not have
   any physics amplitudes.  We use the -f flag to gen_3pi to do this.
   (A configuration file is still needed although its contents are not used.)

   gen_3pi -c ../../../Simulation/gen_3pi/gen_3pi.cfg -o threepi_gen.root -f -l 0.7 -u 2.0 -n 200000

   Again we will use the toy_detector application:

   toy_detector threepi_gen.root threepi_acc.root

   These two files represent files that would actually be present in an
   analysis that uses real data (with the exception that toy_detector
   would be replaced by HDGeant + reconstruction).

-------------------------------------------------
B. Perform fit
-------------------------------------------------

1. We are intersted in extracting the production amplitudes as a function
   of M(pi+pi-pi+).  For each of the produced resonances, we expect the
   production amplitudes to trace out Breit-Wigners as a function of M(pi+pi-pi+).
   (This is precisely the behavior we have generated with the configuration
   file gen_3pi.cfg.)  In order to extract the production amplitudes as
   a function of resonance mass, we divide the data into bins of M(pi+pi-pi+)
   and then perform a fit in each bin.  The parameters of this fit are related
   to the production amplitudes for the various resonances.

   A PERL script, which invokes the command line tool split_mass, is provided
   to do this division and organize the fits.  Examine the variables 
   at the top of divideData.pl to ensure they are correct.  Then run

   ./divideData.pl

   This should create a directory called threepi_fit and inside of this
   directory are (by default) 65 subdirectories spanning M(pi+pi-pi+) from
   0.7 to 2.0 GeV/c^2.

   Note:  The behavior of the fit, e.g., amplitudes in the fit, free parameters, 
   input polarization, etc., is controlled by the template file.  For fits
   with full polarization, the relevant file is threepi_pol_TEMPLATE.cfg.
   This file will be utilized by the script to generate configuration files
   in each of the bin directories.  The default template is a good match
   to the generated gen_3pi.cfg file used above.  It is instructive to
   examine and understand the differences in the amplitude structure in
   these two files.

2.  A common practice is to seed the fit of one bin with the best fit values of
    the previous bin.  Since parameters tend to be continusously varying
    this starts the fit off close to minimum.  In order to do this
    we need a seed to start the process.  One can simply go into any
    directory and do a fit and copy the fit output to seed file.
    The example below uses bin 10 for this:

    cd threepi_fit/bin_10
    fit -c bin_10.cfg
    cp bin_10.fit ../par_seed.txt
    cd ../..

    Now it is time to sequentially fit all bins.  Check the variables
    at the top of the driveFit.pl script.  Then run:

    ./driveFit

    This will generate a huge amount of output on the screen.  If a fit fails
    at any point, the script will pause to notify you. Pressing 
    RETURN will continue the fit.

-------------------------------------------------
C. View fit results
-------------------------------------------------

1. The raw fit parameters are not particularly meaningful.  One
   needs both the fit parameters and the integrals of the amplitudes
   over phase space to construct a quantity like the fit-predicted
   number of events for a particular amplitude.  Because of this
   a simple C++ command line tool (plot_3pi.cc), which utilizes 
   the fitting framework, has been provided to generate a text
   file of meaningful numbers that can be passed into ROOT.

   Examine the source code of plot_3pi.cc.  Some important numbers
   and paths are hard-coded at the begining of main{}.  In the body
   of the program note the correspondence between the amplitude 
   names used in the function calls and those in the fit configuration file.  
   (Again, this is hard-coded.  It could for example be derived from a
   configuration file, or a GUI -- this is a simple specialized tool
   for quickly generating some numbers.)  To generate a table of numbers 
   run:

   plot_3pi -o threepi_fit.txt

   You can examine the file threepi_fit.txt -- for each bin of mass
   (left column) is listed the predicted number of generated events
   for each of the amplitudes along with the error on this number.
   The numbers of events listed have been corrected for acceptance
   based on the Monte-Carlo samples.

2.  A ROOT script has been provided to read in this file and
    and make a plot.  Execute the script by running:

    root -l drawWaves.C

    The plot that contains all waves is particularly interesting.
    It could, in principle, be compared to the M(pi+pi-pi+) mass
    distribution in the file threepi_data_gen.root