************************************************
GMUSIC

Generic MUSIC Simulation Package

Alfred Tang
Kansas State University
January 2007
atang@phys.ksu.edu

************************************************

Content:
********
1.  makefiles (makefile & makemugen)
2.  muon.f -- main program for muons at the far lab
3.  mugen.f -- main program for generating final muon momentum to be used
    FLUKA and GEANT
4.  muon_flux_dbs.f -- mofidied Gaisser distribution generator
5.  music-sr.f -- MUSIC subroutine
6.  music-cross-sections-sr.dat -- datafile
7.  music-double-diff-rock.dat -- datafile
8.  music-eloss-sr.dat -- datefile
9.  ranum.f -- random number header
10. ebin.c -- binning program
11. nr.h -- modified Numerical Recipes header files
12. nrutil.h -- modified Numerical Recipes header files
13. nrutil.c -- modified Numerical Recipes header files
14. fixdat.c -- utility program to post-process raw mountain profile
    generated by 3DField

Short Description
*****************
There are 2 main FORTRAN programs in this package (muon.f and mugen.f)
that propagate muons from the surface of an arbitrary mountain to an
underground lab using MUSIC.  The first program (muon.f) generates E,
cos(theta) and phi uniformly and is designed to calculate average observables
and various distributions very accurately and efficiently.  The second program
(mugen.f) generates E, cos(theta) and phi according to the modified
Gaisser sealevel distribution.  It is not as accurate and efficient as
muon.f in terms of calculating average observables and distributions but
is ideal for generating final muon momentum as input for FLUKA and GEANT.


Installation and Run
********************
1.  Unpack the tar ball and make sure that all the files are placed in
    the same directory.
2.  Make sure that you have CERNLIB (version 2003 or later) installed on
    your system.
3.  Create an environment value CERNLIB for cernlib.  It is recommended that
    the environment value be placed permanently in the setup files such as
    .bashrc, .bash_profile, .tcshrc, .tcsh+profile or so on.  Suppose that
    cernlib is put in a directory called /cern/lib, then add the line
    export CERNLIB=/cern/lib
    in bash, or
    setenv CERNLIB /cern/lib
    in tcsh in the corresponding setup file so that makefile can find the
    cernlib directory.  Similarly, create another environment variable
    CERNROOT.  In this example, add the line
    export CERNROOT=/cern
    in bash, or
    setenv CERNROOT /cern
    in tcsh in the appropriate setup file.
4.  The files border.dat and labxyz.dat are needed by muon.f and mugen.f
    and are created by fixdat.c.  Make sure that a raw data file called
    rawxyz.dat is generated by 3DField.  A quick start guide of how to use
    3DField is posted at http://www.phys.ksu.edu/personal/atang/3dfield.htm.
5.  Right now the number of simulation events in muon.f is set as
    10000.  It is a good number to use when you are testing the program
    because the run time is typically 2-3 minutes on one processor.  For
    production run, set nthrows=1000000 (or higher) in muon.f.  It takes
    approximately 2 hours to run 10^6 events on one processor.  A similar
    arrangement is made for mugen.f.
6.  muon.f uses uniform generation to simulate raw data to be post-processed
    by another program called ebin.c to calculate various observables and
    distributions.  Type "make" at the command prompt to create an executable
    called "musim".  Then type
    $./musim
    at the prompt to run the program.
7.  mugen.f uses generation according to the distribution and creates
    a list of final muon momentum as input for FLUKA and GEANT.  Select
    an option by modifying a line in the beginning of the program:
      parameter (option=1)
    Choose option=1 if final muons are sampled at the center of the
    detector and option=2 if final muons are sampled on a large hemispherical
    vacuum.  Option 2 is set as default.  Choose the number of events by
    modifying the line
      nthrows=1000000
    accordingly.  The survival probability of muons is about 4%.  If 40000
    muons are desired, 10^6 initial muons are needed and so on.
    To make the program, type:
    $make -f makemugen
    To run the program, type:
    $./mugen
8.  The random seed can be modified by changing the integer on the line:
      iranlux=1
9.  The unit of energy/momentum in MUSIC is always GeV.
10. To optmize efficiency, the parameter lemin in muon_flux_dbs.f and
    mugen.f should be set to the log(Emin) where Emin is the minimum
    energy needed to propagate a muon across the minimum thickness of rock.


Outputs of muon.f
********************
1.  A summary of the results will be printed to the screen and to the
    output file edbs.dat.
2.  The file edist.dat contains a record of all the surviving muons in
    columns corresponding to energy, "flux", theta and phi.  The meaning
    of "flux" can be understood by looking into muon_flux_dbs.f whose role
    to measure the weight of each surviving muon for post-processing
    purpose.
3   The file edist.dat contains the output data in columns of muon energy,
    weight, theta and phi.  This file need to be post-processed by the
    program ebin to generate various kinds of distributions.

Output of mugen.f
********************
1.  A summary of the results will be printed to the screen.
2.  The file pxyz.dat contains rows of the x,y,z-components of the final muon
    momentum in the order of (px,py,pz).


******************************

Instruction for running ebin.c

ebin.c is a program that calculates the
energy and double differential
angular distribution from edist.dat
generated by versions of MUSIC
programs written by the author.

******************************

Installation
************

1.  Go a direcoty where you want ebin.c to run.  The program does not have
    any dependence.  It does not matter where you want to put the program.
2.  Untar and unzip ebin.tar.gz by issuing
      $ tar zxvf ebin.tar.gz
3.  To compile the program, type
      $ gcc -o ebin ebin.c -lm
4.  The executable is ebin.

Run
***

1.  Make sure that you have edist.dat in the same directory.
2.  In general it is a good idea to save edbs.dat and edist.dat to other names
    because it is going to be written over everytime you re-run the MUSIC
    program.
3.  Save the output files for example by typing:
       $ cp edbs.dat edbs_dc.dat
       $ cp edist.dat edist_dc.dat
4.  To run ebin, do the following

       $ ./ebin
       Enter the root name of the input file: _dc
       lower bound of E_mu0: .106
       upper bound of E_mu0: (1) 5000 GeV, (2) 1 TeV.
       2
       nthrows = 10000
       phi offset (degrees) = 14.48
       survival probability =0.502500
       muon energy (GeV) =61.508030
       muon intensity (cm^-2 s^-1) =5.307842e-05
       neutron flux (cm^-3 s^-1) =1.227365e-08
       weighted theta = 2.050304
       weighted phi = 5.412201

5.  The energy distribution is in fdist_dc.dat and the double differential
    angular distribution is in gdist_dc.dat.

   output files:
   1.  fdistx.dat -- energy distribution
   2.  gdistx.dat -- theta-phi distribution
   3.  tdistx.dat -- theta distribution
   4.  pdistx.dat -- phi distribution
   5.  cdistx.dat -- cos(theta) distribution
   6.  ddistx.dat -- cos(theta)-phi distribution
   7.  hdistx.dat -- energy-theta distribution
   8.  qdistx.dat -- energy-phi distribution

6.  Below is a typical summary of run for mugen_dc.f:

[atang@localhost mudc]$ ./mugen
 RANLUX LUXURY LEVEL SET BY RLUXGO : 3     P= 223
 RANLUX INITIALIZED BY RLUXGO FROM SEEDS           1           0           0
 number of overlapped lattice points:  1866
 rmin (cm):   9310.36843
 possible low muon energy threshold (GeV):   45.0959135
 Processing lattice sites ......
 Begin simulation ....................
 PROCESSED  200000 THROWS.
 PROCESSED  400000 THROWS.
 PROCESSED  600000 THROWS.
 PROCESSED  800000 THROWS.
 PROCESSED  1000000 THROWS.
 nph, ncz, iph, jcz:  100 100 40 40
 number of overlapped lattice sites:  1866
 zenth angle cut, ctmin-->deg:   0. --> 89
 omega:   5.54107
 energy range:   1. -->   1.
 nthrows:   1000000
 number of surving muons:  40837
 survival probability:    0.040837
 emaxsim (GeV):   3428.21646
 number of seconds used in processing the lattice:  59
 number of seconds used in simulating muons:  9710
