Examples for HepMC-Geant4 interface
                -----------------------------------

  This directory contains examples for using HepMC as an interface with 
various Monte Carlo event generators, such as PYTHIA. 

  In the version 1.80 of CLHEP, HepMC is merged into a part of CLHEP.
Toghether with this migration, the generic interfaces with HepMC is 
provied in the G4 main tree from the release of Geant4.5.0.
But there are differences between the original HepMC and the CLHEP version
in terms of the I/O scheme. So, in this directory, a pair of codes for 
each example, one for original HepMC and the other for the CLHEP version 
which is tagged with "-clhep", is prepared.


Requirements for external software packages
-------------------------------------------
HepMC (now, migrated into CLHEP(1.80))
  tested version : 1.21 (latest at 28/May/02)
  URL: http://mdobbs.home.cern.ch/mdobbs/HepMC/

  Note that the original HepMC can be currently compiled only with gcc, 
  so examples were tested only with gcc.

PYTHIA
  tested version 6.205
  URL: http://www.thep.lu.se/~torbjorn/Pythia.html


What is provided
----------------
a) For the original HepMC

class HepMCG4Interface
  This class is derived from G4VPrimaryGenerator, and is a base class 
  for primary generation via HepMC object.

  protected members
  + virtual HepMC::GenEvent* GenerateHepMCEvent()
    Implement this method in his/her own concrete class.
    An empty event will be created in default.

  + void HepMC2G4(const HepMC::GenEvent* hepmcevt, G4Event* g4event)
    service method for conversion from HepMC::GenEvent to G4Event

  + virtual G4bool CheckVertexInsideWorld(const G4ThreeVector& pos) const
    We have to take care for the position of primaries because
    primary vertices outside the world volume give rise to G4Exception.
    If the default implementation is not adequate, an alternative 
    can be implemented in your own class.

  public members
  + virtual void GeneratePrimaryVertex(G4Event* anEvent)
    The default behavior is that a single HepMC event generated by
    GenerateHepMCEvent() will be converted to G4Event through HepMC2G4().

class HepMCG4AsciiReader / HepMCG4AsciiReaderMessenger
  (derived from HepMCG4Interface)
  This derived class is for reading primary information from 
  an Ascii file generated by HepMC.

class HepMCG4PythiaInterface / HepMCG4AsciiReaderMessenger
  (derived from HepMCG4Interface)
  This derived class is for directly calling PYTHIA functions. 
  Users can set parameters, initialize, generate, and terminate
  by command line operation.


b) For the CLHEP version of HepMC

  G4HepMCInterface, G4HepMCAsciiReader and G4HepMCAsciiReaderMessenger,
which have the same functionality as the above respective ones, are located
in the Geant4 "event/" source tree. As an example of interface with PYTHIA, 
the classes of HxxPythiaInterface/HxxPythiaMessenger are provided in each 
example.

Examples
--------
HepMCEx01/HepMCEx01-clhep
  This example is based on ExampleN04. Only part of the primary generator 
  action is replaced with new one.

HepMCEx02/HepMCEx02-clhep
  This is another example having the same generator action as HepMCEx01, 
  but much simpler user control.


Macros in examples
-----------------
hepmc_pygen.in
  process PYTHIA events(H->4mu) generated at every event.

hepmc_ascii.in
  read pregenerated events from HepMC Ascii file (data/example_MyPhyia.dat).

How to compile
--------------
To build these examples, directory names including HepMC and PYTHIA 
library have to be given in GNUmakefile.  Please modify the next two lines 
in GNUmakefile;

  HEPMC_DIR   := xxxxx    # HepMC installed directory
                            (required only for using the original version)
  CERNLIB_DIR := xxxxx    # directory including PYTHIA library

Notes
-----
We attached a sample HepMC Ascii data file, "data/example_MyPhyia.dat",
which contains ten PYTHIA events created by "data/example_MyPythia.cxx(cc)".