source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Fundamentals/eventGenerator.xml @ 1358

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Changed by: Katsuya Amako, 21-Sep-1998                -->
<!--    Changed by: Dennis Wright, 25-Jun-2002                -->
<!--    Proof read by: Joe Chuma,  28-Jun-1999                -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.EventGen">
<title>
Event Generator Interface
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.EventGen.StructPriEvt">
<title>
Structure of a primary event
</title>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.EventGen.StructPriEvt.VtxPart">
<title>
Primary vertex and primary particle
</title>

<para>
The <emphasis>G4Event</emphasis> class object should have a set of primary
particles when it is sent to <emphasis>G4EventManager</emphasis> via
<literal>processOneEvent()</literal> method. It is the mandate of your
<emphasis>G4VUserPrimaryGeneratorAction</emphasis> concrete class to send primary
particles to the <emphasis>G4Event</emphasis> object.
</para>

<para>
The <emphasis>G4PrimaryParticle</emphasis> class represents a primary particle
with which Geant4 starts simulating an event. This class object has
information on particle type and its three momenta. The positional
and time information of primary particle(s) are stored in the
<emphasis>G4PrimaryVertex</emphasis> class object and, thus, this class object
can have one or more <emphasis>G4PrimaryParticle</emphasis> class objects which
share the same vertex. Primary vertexes and primary particles are associated 
with the <emphasis>G4Event</emphasis> object by a form of linked list.
</para>

<para>
A concrete class of <emphasis>G4VPrimaryGenerator</emphasis>, the
<emphasis>G4PrimaryParticle</emphasis> object is constructed with either a
pointer to <emphasis>G4ParticleDefinition</emphasis> or an integer number which
represents P.D.G. particle code. For the case of some artificial
particles, e.g., geantino, optical photon, etc., or exotic nuclear
fragments, which the P.D.G. particle code does not cover, the
<emphasis>G4PrimaryParticle</emphasis> should be constructed by
<emphasis>G4ParticleDefinition</emphasis> pointer. On the other hand, elementary
particles with very short life time, e.g., weak bosons, or
quarks/gluons, can be instantiated as <emphasis>G4PrimaryParticle</emphasis>
objects using the P.D.G. particle code. It should be noted that,
even though primary particles with such a very short life time are
defined, Geant4 will simulate only the particles which are defined
as <emphasis>G4ParticleDefinition</emphasis> class objects. Other primary
particles will be simply ignored by <emphasis>G4EventManager</emphasis>. But it
may still be useful to construct such "intermediate" particles for
recording the origin of the primary event.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.EventGen.StructPriEvt.ForcedDecay">
<title>
Forced decay channel
</title>

<para>
The <emphasis>G4PrimaryParticle</emphasis> class object can have a list of its
daughter particles. If the parent particle is an "intermediate"
particle, which Geant4 does not have a corresponding
<emphasis>G4ParticleDefinition</emphasis>, this parent particle is ignored and
daughters are assumed to start from the vertex with which their
parent is associated. For example, a Z boson is associated with a
vertex and it has positive and negative muons as its daughters,
these muons will start from that vertex.
</para>

<para>
There are some kinds of particles which should fly some
reasonable distances and, thus, should be simulated by Geant4, but
you still want to follow the decay channel generated by an event
generator. A typical case of these particles is B meson. Even for
the case of a primary particle which has a corresponding
<emphasis>G4ParticleDefinition</emphasis>, it can have daughter primary
particles. Geant4 will trace the parent particle until it comes to
decay, obeying multiple scattering, ionization loss, rotation with
the magnetic field, etc. according to its particle type. When the
parent comes to decay, instead of randomly choosing its decay
channel, it follows the "pre-assigned" decay channel. To conserve
the energy and the momentum of the parent, daughters will be
Lorentz transformed according to their parent's frame.
</para>

</sect3>
</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.EventGen.InterPriGen">
<title>
Interface to a primary generator
</title>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.EventGen.InterPriGen.HEPEvt">
<title>
G4HEPEvtInterface
</title>

<para>
Unfortunately, almost all event generators presently in use,
commonly are written in FORTRAN. For Geant4, it was decided to not
link with any FORTRAN program or library, even though the C++
language syntax itself allows such a link. Linking to a FORTRAN
package might be convenient in some cases, but we will lose many
advantages of object-oriented features of C++, such as robustness.
Instead, Geant4 provides an ASCII file interface for such event
generators.
</para>

<para>
<emphasis>G4HEPEvtInterface</emphasis> is one of <emphasis>G4VPrimaryGenerator</emphasis>
concrete class and thus it can be used in your
<emphasis>G4VUserPrimaryGeneratorAction</emphasis> concrete class.
<emphasis>G4HEPEvtInterface</emphasis> reads an ASCII file produced by an event
generator and reproduces <emphasis>G4PrimaryParticle</emphasis> objects
associated with a <emphasis>G4PrimaryVertex</emphasis> object. It reproduces a
full production chain of the event generator, starting with primary
quarks, etc. In other words, <emphasis>G4HEPEvtInterface</emphasis> converts
information stored in the <literal>/HEPEVT/</literal> common block to an
object-oriented data structure. Because the <literal>/HEPEVT/</literal>
common block is commonly used by almost all event generators
written in FORTRAN, <emphasis>G4HEPEvtInterface</emphasis> can interface to
almost all event generators currently used in the HEP community.
The constructor of <emphasis>G4HEPEvtInterface</emphasis> takes the file name.
<xref linkend="programlist_EventGen_1" /> shows an example how to use
<emphasis>G4HEPEvtInterface</emphasis>. Note that an event generator is not
assumed to give a place of the primary particles, the interaction
point must be set before invoking <emphasis>GeneratePrimaryVertex()</emphasis>
method.
</para>

<example id="programlist_EventGen_1">
<title>
An example code for <emphasis>G4HEPEvtInterface</emphasis>
</title>
<programlisting>
#ifndef ExN04PrimaryGeneratorAction_h
#define ExN04PrimaryGeneratorAction_h 1

#include "G4VUserPrimaryGeneratorAction.hh"
#include "globals.hh"

class G4VPrimaryGenerator;
class G4Event;

class ExN04PrimaryGeneratorAction : public G4VUserPrimaryGeneratorAction
{
  public:
    ExN04PrimaryGeneratorAction();
    ~ExN04PrimaryGeneratorAction();

  public:
    void GeneratePrimaries(G4Event* anEvent);

  private:
    G4VPrimaryGenerator* HEPEvt;
};

#endif


#include "ExN04PrimaryGeneratorAction.hh"

#include "G4Event.hh"
#include "G4HEPEvtInterface.hh"

ExN04PrimaryGeneratorAction::ExN04PrimaryGeneratorAction()
{
  HEPEvt = new G4HEPEvtInterface("pythia_event.data");
}

ExN04PrimaryGeneratorAction::~ExN04PrimaryGeneratorAction()
{
  delete HEPEvt;
}

void ExN04PrimaryGeneratorAction::GeneratePrimaries(G4Event* anEvent)
{
  HEPEvt-&gt;SetParticlePosition(G4ThreeVector(0.*cm,0.*cm,0.*cm));
  HEPEvt-&gt;GeneratePrimaryVertex(anEvent);
}
</programlisting>
</example>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.EventGen.InterPriGen.FormASCII">
<title>
Format of the ASCII file
</title>

<para>
An ASCII file, which will be fed by <emphasis>G4HEPEvtInterface</emphasis>
should have the following format.

<itemizedlist spacing="compact">
  <listitem><para>
    The first line of each primary event should be an integer which
    represents the number of the following lines of primary
    particles.
  </para></listitem>
  <listitem><para>
    Each line in an event corresponds to a particle in the
    <literal>/HEPEVT/</literal> common. Each line has <literal>ISTHEP, IDHEP,
    JDAHEP(1), JDAHEP(2), PHEP(1), PHEP(2), PHEP(3), PHEP(5).</literal>
    Refer to the <literal>/HEPEVT/</literal> manual for the meanings of these
    variables.
  </para></listitem>
</itemizedlist>
</para>

<para>
<xref linkend="programlist_EventGen_2" /> shows an example FORTRAN code to 
generate an ASCII file.
</para>

<example id="programlist_EventGen_2">
<title>
A FORTRAN example using the <literal>/HEPEVT/</literal> common.
</title>
<programlisting>
***********************************************************
      SUBROUTINE HEP2G4
*
* Convert /HEPEVT/ event structure to an ASCII file
* to be fed by G4HEPEvtInterface
*
***********************************************************
      PARAMETER (NMXHEP=2000)
      COMMON/HEPEVT/NEVHEP,NHEP,ISTHEP(NMXHEP),IDHEP(NMXHEP),
     &gt;JMOHEP(2,NMXHEP),JDAHEP(2,NMXHEP),PHEP(5,NMXHEP),VHEP(4,NMXHEP)
      DOUBLE PRECISION PHEP,VHEP
*
      WRITE(6,*) NHEP
      DO IHEP=1,NHEP
       WRITE(6,10) 
     &gt;  ISTHEP(IHEP),IDHEP(IHEP),JDAHEP(1,IHEP),JDAHEP(2,IHEP),
     &gt;  PHEP(1,IHEP),PHEP(2,IHEP),PHEP(3,IHEP),PHEP(5,IHEP)
10     FORMAT(4I10,4(1X,D15.8))
      ENDDO
*
      RETURN
      END
</programlisting>
</example>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.EventGen.InterPriGen.FutureInt">
<title>
Future interface to the new generation generators
</title>

<para>
Several activities have already been started for developing
object-oriented event generators. Such new generators can be easily
linked and used with a Geant4 based simulation. Furthermore, we
need not distinguish a primary generator from the physics processes
used in Geant4. Future generators can be a kind of physics process
plugged-in by inheriting <emphasis>G4VProcess</emphasis>.
</para>

</sect3>
</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.EventGen.EvtOverlap">
<title>
Event overlap using multiple generators
</title>

<para>
Your <emphasis>G4VUserPrimaryGeneratorAction</emphasis> concrete class can have
more than one <emphasis>G4VPrimaryGenerator</emphasis> concrete class. Each
<emphasis>G4VPrimaryGenerator</emphasis> concrete class can be accessed more than
once per event. Using these class objects, one event can have more
than one primary event.
</para>

<para>
One possible use is the following. Within an event, a
<emphasis>G4HEPEvtInterface</emphasis> class object instantiated with a minimum
bias event file is accessed 20 times and another
<emphasis>G4HEPEvtInterface</emphasis> class object instantiated with a signal
event file is accessed once. Thus, this event represents a typical
signal event of LHC overlapping 20 minimum bias events. It should
be noted that a simulation of event overlapping can be done by
merging hits and/or digits associated with several events, and
these events can be simulated independently. Digitization over
multiple events will be mentioned in 
<xref linkend="sect.Digi" />.
</para>


</sect2>
</sect1>