------------------------------------------------------------------------
   Physics study libraries				2008/11/30
------------------------------------------------------------------------
 
[1] Version Information

   Version: 2008a
   Release: 1

[2] Version History

    2008/11/30  K.Fujii		2008a-1
    2005/03/26  K.Fujii		2005a-2
    2005/03/02  K.Fujii		2005a-1
    2004/11/23  K.Fujii		2004a-1
    2001/05/25  K.Fujii		2001a-1
    2000/08/29  K.Fujii		2000a-5
    2000/08/24  K.Fujii		2000a-4
    2000/07/13  K.Fujii		2000a-3
    2000/06/26  K.Fujii		2000a-2
    1999/10/08  K.Fujii		99a-1
    1999/05/24  K.Fujii		98a-1

   See CHANGES for update records.

[3] How to Install the Libraries

   Before you install physsim, you have to install
        lcbase
        leda
	lclib
        jsf
   Since we separated configuration files from JSF as lcbase and leda
   from Satellites, now we need lcbase and leda to install physsim.
   For installation of these packages, see the instruction files that
   come with them.

   In order to use this package you should set some additional
   environmental variables:

	$ cd <the directory containing this file>
	$ export KFLIBROOT=`pwd`
	$ export IMAKEINCLUDE="$IMAKEINCLUDE -I$KFLIBROOT"
	$ vi ~/.rootrc

   where the JSF standard environmental variables such as
   ROOTSYS, JSFROOT, LCLIBROOT, CERN_ROOT, .... are assumed
   to be set beforehand (see HowToInstall of JSF for details).
   Once the environment is set up, do:

	$ make

[4] How to Build Individual Generators

   Step [3] will create libraries necessary to build various MC
   event generators based on BASES/SPRING stored in
	dh	: etcetc, etreti, ...
	higgs	: zh, zhh, nnh, ...
	lht	: whwh, zhah, zhzh, ...
	susy	: sfsf, xcxc, xn1xn2, xn2xn2, ...
	top	: eett, nntt, tth, tt, ttz, ...
	twoph	: eeff (f=e,mu,tau,q)
	wz	: eeww, eezz, eez, enw, nnww, nnzz, nnz, ww, wwz, zz, ...
	xd	: kkhh, ax, zx
   These subdirectories contain subsubdirectories named
   <PROCESSNAME>Study. The top levelMakefile does NOT build 
   individual Monte Carlo event generators: it only creates
    necessary libraries for them.
   You should "cd" to one of these subsubdirectories and do

    	$ xmkmf -a
	$ make


[5] How to Use Individual Generators

   Step [4] will create a shared object : prod/<PROCESSNAME>Spring.so
   which can dynamically be loaded into "jsf".
   Dynamic loading is automatically done by using macro files:
	bases.C	: MC integration (BASES step) ʠnecessary for SPRING step.
	sim.C	: event generation (SPRING step).
 	gui.C	: Miyamoto's GUI for jsf which loads:
			MainMacro.C  : steers through events.
			UserAnalysis : analyzes events (user defined).
   You can use them as:

	$ jsf -b -q bases.C >& bs.out &		# BASES step
	$ tail -f bs.out			# monitor SYSOUT
	.......
	^C					# quit "tail"

   Check "bs.out" if integration successfully converges.
   This will also allow you to get the cross section of the 
   process given usually in (fb).
   Optionally, you can examine the root file (bases.root) by
   starting root:
 	$ jsf bases.root
   and invoke TBrowser by
        Root [1] TBrowser b;
   where you can double-clicking firt "ROOT Files" and then 
   "bases.root" to get histograms generated by BASES:
   	h01BS, ...., h**BS.
   
   The integration conditions can be controlled by editing 
   "jsf.conf" which allows you to change job parameters such as
   "m_t", "m_H", ..., etc. When decay modes for W/Z are slectable,
   the decay mode numbering obays the following convention:

  	 mode	W decay	 comment	 mode	Z decay	 comment
  	-------------------------- 	--------------------------
  	 1	e   nu			 1	nue
  	 2	mu  nu			 2      numu
  	 3	tau nu			 3	nutau
  	 4	d   u			 4	e
  	 5      d   c			 5	mu
  	 6      d   t	forbidden	 6	tau
  	 7      s   u			 7	u
  	 8      s   c			 8	c
  	 9      s   t	forbidden	 9	t	forbidden
  	10      b   u			10	d
  	11      b   c			11	s
  	12	b   t	forbidden	12	b
   	--------------------------	--------------------------
   
   
   
   If everything is OK. you can continue with event generation.

	$ jsf -b -q sim.C >& sm.out &		# SPRING step
	$ tail -f sm.out			# monitor SYSOUT
	.......
	^C					# quit "tail"

   Again, you had better check "sm.out" to confirm that the
   SPRING step ended with no error.
   You can change the input BASES file (bases.root) or the number 
   of events to generate (maxevt) by editing "sim.C". 
   Generated events can be browsed using Miyamoto's GUI:

	$ jsf gui.C

   which navigates you through generated events and allows you 
   to display and analyze them using a user analysis macro 
   called "UserAnalysis". 
   Which "<PROCESS>Spring.so" is loaded and which file is read
   in are controlled by editing "gui.C" and jsf.conf, respectively.
   The input file can also be selected through the GUI's file
   chooser. "<PROCESS>Spring.so" will be selectable from the GUI
   in a future release, I hope.
   Default UserAnalysis macros are meant to be a template and,
   usually, NOT yet very realistic (exceptions include SFSFStudy,
   TTStudy, and WWStudy). 
   You can also find some more examples in Anlib/examples/jsf/.
   When more useful ones become available I will include them.
   Your contributions are very much welcome.


[6] Known Problems

   There is a pitfall known to exist in the current version
   using C++ wrappers called function name confusion.
   If multiple <PROCESS>Spring.so's are loaded into a single
   JSF session, there can be function name confusions.
   A typical example is HELAS/DHELAS confusion which is caused
   by the fact that both single and double precision versions
   have the same function names. To avoid this problem, NEVER
   try to load multiple generator packages. 
   Quit the JSF session before starting analysis of a different
   process.