    This  is  the  documentation  for  the  release of  the  Black  Hole
    generator.  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:

    charybdis1002.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.

    charybdis1002.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 main code, i.e. charybdis.F, you must specify:

    IDBMUP(1),IDBMUP(2) PDG  codes for the beam  particles (only protons
    and antiprotons allowed.)

    EBMUP(1),EBMUP(2) energies of the beam particles.

    MPLNCK the Planck Mass.

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

    D      the number of dimensions.

    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.) 

    MINMSS the minimum mass of the black holes to be produced.
 
    MAXMSS the maximum mass of the black holes to be produced.

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

    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.

    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.

    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.

    IPRINT print out option 0= no  printout, 1= errors only, 2= errors +
           info.

    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  you extract  the code to  run it separately  then the  following 
    should be taken into account.

    charybdis1002.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.  

Changes:

19/08/2003 changes of D to TOTDIM in subroutine CHUBHS.
28/07/2006 change to fix problem setting antiquark PDFs when using PYTHIA
           internal PDFs
