    This  is  the  documentation  for release 1.003 of  the  Black  Hole
    generator CHARYBDIS.  As the code is  designed  to run  with  either
    HERWIG or PYTHIA there are a few things which need to be set up.

    You should have the following code:

    charybdis1003.F the code for the black hole generator;
    dummy.F         the dummy  routines  needed  if  you are  not  using
                    PDFLIB;

    mainpythia.f example main program for PYTHIA;
    mainherwig.f example main program for HERWIG.

    charybdis1003.inc    include file for the black hole event generator

    In  addition to  this  you  will  also  need  a Les  Houches  accord
    compliant version  of either HERWIG  or PYTHIA with  both  the dummy
    Les  Houches  routines  UPINIT  and  UPEVNT   and the  dummy  PDFLIB
    subroutines  PDFSET and  STRUCTM  deleted.  For  HERWIG  this  means
    version 6.500  and above, for PYTHIA  you will need a  version above
    6.200.

    In the Les Houches routines the beams are specified as follows:

    IDBMUP(1),IDBMUP(2) PDG  codes for the beam  particles (only protons
    and antiprotons allowed) [2212,2212]
    EBMUP(1),EBMUP(2) energies of the beam particles [7000.,7000.]

    Square brackets show the default values. In the HERWIG version, they
    are  overwritten with the values deduced from the  HERWIG parameters
    PART1,PART2 and PBEAM1,PBEAM2.  However in the PYTHIA version they
    must be reset explicitly in COMMON/HEPRUP/ if changed.

    The CHARYBDIS parameters available to the user are as follows.  They
    have the default values  indicated,  all of  which may be changed in
    the main program, as shown in the samples mainpythia and mainherwig. 

    MPLNCK the Planck Mass [1000.]

    MSSDEF whose  definition  of the  Planck  Mass  you are  using - see
           Appendix A of hep-ph/0110127 for a comparison [2]

    TOTDIM the total number of dimensions (i.e. 4+extra) [6]

    GTSCA  sets momentum scale for calling the PDFs (.TRUE. is using the
           inverse Schwarzschild  radius  and .FALSE. is using sqrt(s) -
           see  discussion on p12  of hep-ph/0106219  but note  that the
           cross  sections  in  this  paper  were  NOT  calculated  with
           GTSCA=.TRUE. even though it suggests they were) [F]

    MINMSS the minimum mass of the black holes to be produced [5000.]
 
    MAXMSS the maximum mass of the black holes to be produced [14000.]

    NBODY  the  number  of particles  produced in the decay of the black
           hole remnant [2]
  
    TIMVAR time  variation  of  the  Black  Hole's  Hawking  temperature
           (.TRUE. is on .FALSE. is off) [T]

    MSSDEC the type of particles to  produce in the decay, 1= only light
           SM  particles, 2= light SM  particles + top W/Z and 3= all SM
           particles [3]

    GRYBDY controls the use of the gray body  factors, for  GRYBDY=.TRUE.
           the correct  D-dimensional gray body factors are used whereas
           for GRYBDY=.FALSE. the black body spectrum is used [T]

    KINCUT controls  the  termination  of the  Schwarzschild  phase. For
           KINCUT=.TRUE. the  Schwarzschild  phase  terminates  when  an
           emission is selected with energy  greater than the black hole
           mass  whereas for  KINCUT=.FALSE. the  Schwarzschild phase is
           terminated  when the mass of the  black hole  remnant is less
           than the Planck mass [F]

    YRCSEC controls whether the Yoshino-Rychkov  enhancement factors are
           used in computing the cross section (see Phys.Rev.D71:104028,
           2005 [hep-th/0503171]) [F]

    THWMAX maximum value of the  Hawking temperature (GeV).  If a larger
           value is generated during decay, it is reset to this  [1000.]

    RMBOIL controls whether to use the "boiling remnant" model, in which
           the black hole decay continues  below the Planck scale,  with
           temperature limited by  THWMAX.  (This option is inconsistent
           with the use of KINCUT=.TRUE.) [F]

    RMMINM minimum remnant mass. If the "boiling remnant" model is used,
           this should be less than MPLNCK, otherwise it is set equal to
           MPLNCK if smaller [1000.]

    IBHPRN print out option 0= no  printout, 1= errors only, 2= errors +
           info [1]

    In  the  Makefile  you must  specify  which  general  purpose  event
    generator, i.e.

    GENERATOR = HERWIG  for HERWIG
    GENERATOR = PYTHIA  for PYTHIA

    whether or not you want PDFLIB

    PDFLIB = PDFLIB  for PDFLIB
    PDFLIB =         otherwise.

    You  must also  specify the name of the HERWIG/PYTHIA source and the
    location of the PDFLIB library, if used.

    If  you extract  the code to  run it separately  then the  following 
    should be taken into account.

    charybdis1003.F  will  produce  the HERWIG  version by default  when
    compiled the flag -DPYTHIA  should be added if the PYTHIA version is
    required. 

    dummy.F will by default produce  the version for use  without PDFLIB
    the flag -DPDFLIB should be added if PDFLIB is being used.

    In the HERWIG version the black hole entry in the event  record  has
    been assigned the provisional PDG code IDHEP=40 with name 'BlacHole'
    However this has not been implemented in the PYTHIA version.

    This version has  been checked  for compatibility  with a variety of
    Fortran 77 and Fortran 90 compilers.

    PR & BW 24/08/06

