DECAY - Performs MSU-Gemini secondary decay

 Primary author: Wanpeng Tan (tan@nscl.msu.edu)
 Porting to Linux: Harold Hunt (hunt@nscl.msu.edu)
 This documentation: Harold Hunt (hunt@nscl.msu.edu)
 Primary contact: Betty Tsang (tsang@nscl.msu.edu)

Features:
1) Rebuild MSU's secondary decay with larger tables
2) Output fragment multiplicities and 7 average velocity moments
3) Apply Gemini decay for fragments outside the table (Z > 15)
4) Built-in 6 options for primary inputs:
	Standard, SMM_MSU, McGill, Colonnga, AMD, and Botvina.

 -- July, 2001 by Wanpeng Tan, tan@nscl.msu.edu


1) Installing DECAY in a Personal Directory
===========================================
	DECAY requires the DECAY executable and about ten input files,
some of which are plain text and others that are packed binary
numbers.  Files that contain packed binary floating-point numbers
require processor-specific (and possibly compiler-specific and/or
operating system-specific) versions of these input files.  As of
2002-10-03, we have the packed binary files available for Tru64-UNIX
Alpha machines (using the Compaq Fortran Compiler) and for Linux
Intel-compatible machines (using the Intel Fortran Compiler).

	These files total about 11 MB in size, so it would quickly
become a waste of space if you copied these files, which can be shared
among all users, to your own directory or to multiple subdirectories
in your own directory.  Therefore, we have created a bash script file,
``createlinks.sh'', that automatically creates links to the
platform-specific DECAY executable, the plain text files, and the
platform-specific packed binary input files.  The script file, as of
2002-10-03, points these links to ``/user/hira/decay/exec/'' for the
input files and to either ``/user/hira/decay/exec/linux/decay'' for
the Linux excutable or to ``/user/hira/decay/exec/tru64/decay'' for
the Tru64 executable.

	Simply follow the example steps below to setup your own
directory for running the DECAY program:

  mkdir decay-linux 	[or decay-tru64, depending on your platform]

  cd decay-tru64	[or decay-tru64]

  cp /user/hira/decay/exec/createlinks.sh .

  [If you are not already running the bash shell, run: bash]

  ./createlinks.sh

	You should now have a complete set of links to your
platform-specific DECAY executable and to the plain text and packed
binary input files.

	You can repeat the steps above to create links for the other
platform (Tru64-UNIX Alpha or Linux Intel-compatible) so that you can
run DECAY on both Tru64-UNIX and Linux.  However, be careful to make
sure that you run the createlinks.sh script on the platform that you
wish to create links for.  For example, to create links for the Linux
platform, be sure to run createlinks.sh from a Linux machine.


2) Running DECAY
================
	In order to run DECAY you must create links to the input files
as was done in Section 2.  You must also have a Primary Distribution
File and you must know the type of Primary Distribution File that you
have (SMM_MSU, McGill, Colonna, AMD, Botvina, or SMM_DELUXE, as of
2002-10-03).

	Everytime that you run DECAY you must specify a prefix to be
used for the output files that are generated.  This prefix is used so
that you can run multiple instances of DECAY, on different machines
from the same directory, or up to one process per processor on any
single machine.  This allows you to have a single DECAY directory,
rather than having to create a new DECAY directory for each instance
of DECAY that you want to run concurrently.  In addition, using a
prefix for the output files prevents you from accidentally deleting
your output files when you run DECAY again.

	I recommend using an output file prefix that incorporates your
primary file name, the word ``out'', and at least a two digit sequence
number to indicate which run of that primary file those output files
correspond to.  For example, for primary distribution file
``mcgill_168.pri'', a good set of prefixes would be
``mcgill_168_out-01'', ``mcgill_168_out-02'',
... ``mcgill_168_out-10'', ...  I recommend using zeros in your
sequence number to make all of your sequence numbers the same length;
for example, always use ``01'' instead of ``1''.  Using such padding
with zeros keeps your output files properly sorted according to their
sequence number, and it allows you to delete all output files by
specifying the prefix followed by a ``*''; for example, ``rm
mcgill_168_out-01*''.  You risk accidentally deleting your data if you
do not pad your sequence numbers with zeros since to delete sequence
number ``1'' you may type ``rm mcgill_168_out-1*'', but this command
would also delete the output files for sequence numbers ``10'' and
``100''.

	Running DECAY with more than ``10'' Monte Carlo experiments
can take a long, long time; that is, it can take hours or days to
complete.  Therefore, it is always wise to run ``1'' Monte Carlo
experiment to gauge how long it will take to run ``10'', ``100'', or
even ``1000'' Monte Carlo experiments.  The runtime scales almost
perfectly linearly with the number of Monte Carlo experiments, so you
can estimate the running time of ``X'' Monte Carlo experiments by
multiplying the ``Decay running time'' from a DECAY run with ``1''
Monte Carlo experiment by ``X''.  Note that the ``MSU running time'',
reported by DECAY at the end of a run, does not depend upon the number
of Monte Carlo experiments.  Thus, be sure to multiply only the
``Decay running time'' by ``X'' or else your extrapolation for the
running time of ``X'' Monte Carlo experiments will be greatly off
since the ``MSU running time'' takes a disproportionate amount of time
compared to the ``Decay running time'' when running ``1'' Monte Carlo
experiment.

	To run DECAY, simple type the following at a shell running on
either your Linux or Tru64-UNIX host:

  cd decay-linux		[or decay-tru64]
  ./decay


	You should see a welcome screen similar to the following:

==============================================================================
<dill:test >./decay
 Welcome to the MSU DECAY program.
 Primary author: Wanpeng Tan (tan@nscl.msu.edu)
 Porting to Linux: Harold Hunt (hunt@nscl.msu.edu)
 Primary contact: Betty Tsang (tsang@nscl.msu.edu)
 
 You will be asked for a decay option (primary distribution 
 type), a prefix to use for all output files, a primary 
 distribution filename, and the number of Monte Carlo 
 experiments that you wish to perform.
 
 
 NOTE: Enter the option as a negative number if you do 
 not want to record velocity moments in the final files.
 
 Decay option: 1(SMM_MSU)/2(McGill)/3(Colonna)/4(AMD)/5(Botvina)/6(SMM_DELUXE)
 /0(standard format: Event#; A,Z,gspin,E*,Vx,Vy,Vz)

==============================================================================

	You may now specify the ``Decay option'', the prefix to use
for output file names, the name of the primary distribution file, and
the number of Monte Carlo experiments to perform.

	Of particular interest to you may be the ``%prefix%.log'' file
that is created, where %prefix% is the output file name prefix that
you specified.  This file will contain the clock time when DECAY
started, the clock time when DECAY stopped, and some other diagnostic
information such as the name of the primary input file, the number of
Monte Carlo experiments to perform, etc.

	You now know all there is to know about running DECAY.


3) Building DECAY
=================
	DECAY uses the GNU Autotools (Autoconf and Automake) to
configure the source code and build scripts for compiling on multiple
UNIX-like platforms.  As of 2002-08-29, the only supported platforms
are Compaq Tru64 UNIX using the Compaq Fortran Compiler (V5.0) and
Linux using the free Intel Fortran Compiler for Linux (V6.0).

	There are three steps to compiling DECAY: unpacking the source
code, configuring the source code, and building the source code.


3) a) Unpacking the Source Code
===============================
	It is recommended that you do not configure or build in the
directory that you unpack the source code in; building in your source
code directory requires that you have many directories of source code
for each platform that you build on and it generally leads to bug
fixes being lost in one of those directories.  First, you need to find
the DECAY source code file, which will have a name similar to, for
example, decay-1.1.0.tar.gz.  To unpack your source code, open a UNIX
shell (e.g., bash) and change to the directory where you have the
DECAY source code file:

  cd ~/decay
  
	Now you need to ungzip and untar the DECAY source code file,
which can be done in a single step by running:

  tar xzf decay-1.1.0.tar.gz

This command unpacks the source code into a directory called, for
example, decay-1.1.0/.


3) b) Configuring the Source Code
=================================
	Configuring the source code requires that you create a
directory structure to hold your builds.  Each build directory can
have a different configuration; for example, ~/decay/build/linux-debug
could be a Linux debug build and ~/decay/build/linux could be a Linux
optimized build while ~/decay/build/tru64 could be a Tru64 optimized
build.  Start by creating your directory structure; we will use Linux
as an example:

  cd ~/decay
  mkdir build
  cd build
  mkdir linux-debug
  mkdir linux

	When you run the ``configure'' script, in the following
sections, it may run for several minutes and it will generate lots of
confusing output that you do not need to be too concerned about.
Notice that both builds below are compiling the same source code
files; the only difference is that the optimized build passes a
configuration option to ``configure''.

3) b) i) Configuring the Source Code for a Debug Build
======================================================
	To create a debug build, which is the default option, we
simply need to run the ``configure'' script that resides in the source
code directory:

  cd ~/decay/build/linux-debug
  ../../decay-1.1.0/configure

3) b) ii) Configuring the Souce Code for an Optimized Build
===========================================================
	To create an optimized build, which is used when running DECAY
on actual data, we simply need to run the ``configure'' script and
pass it the -O2 (read: ``dash oh two'') configuration option:

  cd ~/decay/build/linux
  ../../decay-1.1.0/configure FFLAGS="-O2"

3) c) Building the Source Code
==============================
	Building the source code, once it has been configured as
above, only requires that you run the ``make'' command in the desired
build directory.
	For a debug build, run:

  cd ~/decay/build/linux-debug
  make

	For an optimized build, run:

  cd ~/decay/build/linux
  make

3) d) Results of a Build
========================
	After building the source code you should have the single
executable named ``decay'' in the build directory, along with lots of
unimportant intermediate build files, such as object files and module
files.  You cannot run the ``decay'' executable from the build
directory because you need to have symlinks to several input files
that would clutter the build directory; rather, it is recommended that
you copy the ``decay'' executable to an execution directory (e.g.,
~/decay/exec/linux or ~/decay/exec/linux-debug) and run it from there.

3) e) Modifying the Autoconf or Automake files
==============================================
	Modifications to ``configure.ac'' require that ``autoconf'' be
rerun.  Autoconf version 2.53a is required for this project (see
below).

	Modifications to ``Makefile.am'' require that ``automake'' be
rerun.  Automake version 1.6.2 is required for this project (see
below).

	The recommended way to obtain and use the latest releases of
Autoconf and Automake is to install Cygwin on your Windows machine,
taking care to select the Autoconf and Automake packages.  Then create
a Windows Mapped Network Drive that points to the user directory on
our file servers where the source code is located (e.g., map
\\samba.nscl.msu.edu\user\hira to drive ``q:'' for source code in
/user/hira/decay/src/).  Next, launch a Cygwin shell and change
directories to the mapped drive where the source code is contained:

  cd /cygdrive/q/decay/src

	Finally, run ``automake'' and ``autoconf'' as necessary.

4) Closing
==========
	At this point you should know enough to use and port DECAY to
other processors and operating systems that might be developed in the
next 20 year.  ;)

	Enjoy DECAY!