Physics Study Libraries



The package contains various MC event generators:
	higgs	: zh, ...
	susy	: sfsf, xcxc, ...
	top 	: eett, nntt, tth, tt, ttz, ...
	twoph	: eeff (f=e,mu,tau,q)
	wz	    : eeww, eez, enw, nnww, nnz, ww, wwz, zz, ...
which are all based on BASES/SPRING. The amplitudes squared used in the integration are calculated with HELAS and include full helicity amplitudes: all the angular correations are included and beam polarization can be specified. You can also switch on and off the beam effects: beam energy spread and beamstrahlung. The package also contains some analysis tools, Anlib, prepared as a C++ library: you can find jet finders, event shape routines, a rather primitive vertex tagger, ..., etc. You can find some examples showing its usage in the directory
and its subdirectories.


How to Install the Libraries

In order to use physsim, you have to have cernlib installed. Then you should be able to install "lcbase", "leda", "lclib", and "jsf" following the instructions given in the jsf and lclib home pages. You can get the latest versions of these libraries from the JLCCVS server.

Then you can install "physsim":

$ tar -zxvf physsim-2005a-2.tar.gz -C <somewhere>

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

$ cd <somewhere>
$ export KFLIBROOT=`pwd`
$ vi ~/.rootrc
Unix.*.Root.DynamicPath: .:$(ROOTSYS)/lib:$(JSFROOT)/lib:$(KFLIBROOT)/lib
Unix.*.Root.MacroPath: .:$(ROOTSYS)/macros:$(JSFROOT)/example/guiexam1

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

$ make

How to Build Individual Generators

The above step will create libraries necessary to build various MC event generators based on BASES/SPRING stored in
	higgs   : zh, ...
	susy    : sfsf, xcxc, xn1xn2, xn2xn2, ...
	xd      : hh, ...
	top     : eett, nntt, tth, tt, ttz, ...
	twoph   : eeff (f=e,mu,tau,q)
	wz      : eeww, eezz, eez, enw, nnww, nnzz, nnz, ww, wwz, zz, ...
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

How to Use Individual Generators

The previous step will create a shared object : prod/<PROCESS> 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"
As a rule of thumb, you are strongly recommended to check "bs.out" if integration successfully converges: if there exists any iteration that gives a temporary estimate that fluctuates by 5% or more from the other iterations, you should suspect some convergence problem. This will also allow you to get the cross section of the process given usually in (pb).

Optionally, you can examine a TOPDRAW file (bases.tdr) by

$ tdr -v X bases.tdr
if "tdr" command is available.

The integration conditions can be controlled by editing "jsf.conf" which allows you to change job parameters such as "m_t", "m_H", "E_cm", "Pol_e", "Delta E_beam", ..., etc. You can also switch on and off ISR and beam effects (beam energy spread and beamstrahlung) by setting

where n=(1,2,3)=(ISR:off and BM:off, ISR:on and BM:off, ISR:on and BM:on).
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 SPRNG step ended with no error.
You can change the input BASES file (bases.root) or the number of events to generate 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>" 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>" will be selectable from the GUI in a future release, I hope. Default UserAnalysis macros are meant to be a template and NOT very realistic yet, except for that of SFSFStudy. When more useful ones become available I will include them. Your contributions are very much welcome.

Known Problems

There is a pitfall known to exist in the current version using C++ wrappers called function name confusion. If multiple <PROCESS>'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.
Back to JLC Offline Group Home Page May. 28, 1999