Requirements:

This example requires that version 0.6 or later of AmpTools
(amptools.sourceforge.net).  Compile the main AmpTools library and set
the environment variable AMPTOOLS to point this directory (the directory
that contains (GPUManager, GPUUtils, IUAmpTools, ...) *before* compiling
the GlueX source tree.

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 or the simulated GlueX detector
B. Perform a fit to extract the production amplitudes as a function of M(pi+ pi- pi+)
C. Collect results of multiple fits in a table and display the output

<><><><><><><> Quick recipe for doing example <><><><><><><><>
cd $HALLD_HOME/src/programs/AmplitudeAnalysis/Examples/threepi_binned
cp ../../../Simulation/gen_3pi/gen_3pi.cfg .
gen_3pi -c 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 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 -s ../param_init.cfg
cd ../..
./driveFit.pl
plot_3pi -o threepi_fit.txt
root -l drawWaves.C
<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>

<><><><>Alternate recipe that uses the GlueX Detector <><><><><><>
cd $HALLD_HOME/src/programs/AmplitudeAnalysis/Examples/threepi_binned
cp ../../../Simulation/gen_3pi/gen_3pi.cfg .
gen_3pi -c gen_3pi.cfg -o threepi_data_gen.root -hd threepi_data_gen.hddm -l 0.7 -u 2.0 -n 50000

-> run HDGeant on threepi_data_gen.hddm and anlayze the output and
-> write it to a file called threepi_data.root using the format 
-> encoded in the ROOTDataReader and put it in this directory

gen_3pi -c gen_3pi.cfg -o threepi_gen.root -hd threepi_gen.hddm -f -l 0.7 -u 2.0 -n 200000

-> run HDGeant on threepi_gen.hddm and anlayze the output and
-> write it to a file called threepi_acc.root using the format
-> encoded in the ROOTDataReader and put it in this directory

./divideData.pl
cd threepi_fit/bin_10
fit -c bin_10.cfg -s ../param_init.cfg
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.  You should copy the configuration file
   distributed with gen_3pi to the current working directory.
   
   cp ../../../Simulation/gen_3pi/gen_3pi.cfg .

   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 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%
   polarized 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.
   
1. (Alternate) You can use the -hd flag to write out an HDDM
   version of the generated file.
   
    gen_3pi -c gen_3pi.cfg -o threepi_data_gen.root -hd threepi_data_gen.hddm -l 0.7 -u 2.0 -n 50000

   Instead of using the toy_detector application then take this
   HDDM file and pass it through HDGeant and the analysis framework.
   Write the output of the analysis to a file called threepi_data.root
   and place it in this directory.  It is important that the output
   be formatted properly.  These examples utilize the ROOTDataReader
   in the library AMPTOOLS_DATAIO.  You may have to examine the source
   code of this data reader to understand the expected format of the
   source tree.  Proper order of the particles in the final state
   arrays is important.

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 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).
   
2. (Alternate) Write a copy of the phase space MC to an HDDM file also

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

   As in step 1 above, perform the detector simulation and analysis and
   write the output to a ROOT file in this directory called
   threepi_acc.root

-------------------------------------------------
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 -s ../param_init.cfg
    cd ..

    The -s flag passed to fit tells the fit application to write out a
    "seed file" which is the parameter initialization of the configuration
    file.  The seed file is only written if the fit was successful. This seed 
    file can be included using the include command in the config file for 
    the next fit. 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 fit all bins and log the fit output to files in each directory.

-------------------------------------------------
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