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

This directory contains examples for using HepMC as an interface with 
various Monte Carlo event generators, such as PYTHIA.
It also include an example for demonstrating MC truth handling with HepMC.

Requirements for external software packages
-------------------------------------------
HepMC:
  tested version : 1.27.02
  http://lcgapp.cern.ch/project/spi/extsoft/packages.php?pkg=HepMC
  http://cern.ch/mdobbs/HepMC/

  Note: examples were tested only on Linux with gcc.

PYTHIA
  Tested version 6.205 (CERNLIB 2005)
  URL: http://www.thep.lu.se/~torbjorn/Pythia.html


Examples HepMCEx01 and HepMCEx02
================================

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.

  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 HepMCEx01 and HepMCEx02 examples, the directory path where the
  HepMC package is installed must be provided through the variable HEPMC_DIR.
  PYTHIA 6.205 must be installed through CERNLIB 2005 and the bin path
  correctly added in PATH.

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

Example MCTruth
===============

Application demonstrating handling of Monte-Carlo truth information through
the HepMC package.