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

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


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

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Event.Represent">
<title>
Representation of an event
</title>

<para>
<emphasis>G4Event</emphasis> represents an event. An object of this class
contains all inputs and outputs of the simulated event. This class
object is constructed in <emphasis>G4RunManager</emphasis> and sent to
<emphasis>G4EventManager</emphasis>. The event currently being processed can be
obtained via the <literal>getCurrentEvent()</literal> method of
<emphasis>G4RunManager</emphasis>.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Event.Struct">
<title>
Structure of an event
</title>

<para>
A <emphasis>G4Event</emphasis> object has four major types of information. Get
methods for this information are available in <emphasis>G4Event</emphasis>.

<variablelist><title></title>
  <varlistentry>
    <term>Primary vertexes and primary particles</term>
    <listitem><para>
      Details are given in <xref linkend="sect.EventGen" />.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>Trajectories</term>
    <listitem><para>
      Trajectories are stored in G4TrajectoryContainer class objects
      and the pointer to this container is stored in <emphasis>G4Event</emphasis>. 
      The contents of a trajectory are given in 
      <xref linkend="sect.Track.Traj" />.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>Hits collections</term>
    <listitem><para>
      Collections of hits generated by <emphasis>sensitive detectors</emphasis> are
      kept in <emphasis>G4HCofThisEvent</emphasis> class object and the pointer to this
      container class object is stored in <emphasis>G4Event</emphasis>. See 
      <xref linkend="sect.Hits" /> for the details.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>Digits collections</term>
    <listitem><para>
      Collections of digits generated by <emphasis>digitizer modules</emphasis> are
      kept in <emphasis>G4DCofThisEvent</emphasis> class object and the pointer to this
      container class object is stored in <emphasis>G4Event</emphasis>. See 
      <xref linkend="sect.Digi" /> for the details.
    </para></listitem>
  </varlistentry>
</variablelist>
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Event.ManEvtMan">
<title>
Mandates of <emphasis>G4EventManager</emphasis>
</title>

<para>
<emphasis>G4EventManager</emphasis> is the manager class to take care of one
event. It is responsible for:

<itemizedlist spacing="compact">
  <listitem><para>
    converting <emphasis>G4PrimaryVertex</emphasis> and 
    <emphasis>G4PrimaryParticle</emphasis>
    objects associated with the current <emphasis>G4Event</emphasis> object to
    <emphasis>G4Track</emphasis> objects. All of <emphasis>G4Track</emphasis> 
    objects representing the primary particles are sent to 
    <emphasis>G4StackManager</emphasis>.
  </para></listitem>
  <listitem><para>
    Pop one <emphasis>G4Track</emphasis> object from 
    <emphasis>G4StackManager</emphasis> and send it to 
    <emphasis>G4TrackingManager</emphasis>. The current <emphasis>G4Track</emphasis>
    object is deleted by <emphasis>G4EventManager</emphasis> after the track is
    simulated by <emphasis>G4TrackingManager</emphasis>, if the track is marked as
    "killed".
  </para></listitem>
  <listitem><para>
    In case the primary track is "suspended" or "postponed to next
    event" by <emphasis>G4TrackingManager</emphasis>, it is sent back to the
    <emphasis>G4StackManager</emphasis>. Secondary 
    <emphasis>G4Track</emphasis> objects returned by
    <emphasis>G4TrackingManager</emphasis> are also sent to
    <emphasis>G4StackManager</emphasis>.
  </para></listitem>
  <listitem><para>
    When <emphasis>G4StackManager</emphasis> returns  <literal>NULL</literal> 
    for the "pop" request, <emphasis>G4EventManager</emphasis> terminates the 
    current processing event.
  </para></listitem>
  <listitem><para>
    invokes the user-defined methods <literal>beginOfEventAction()</literal>
    and <literal>endOfEventAction()</literal> from the 
    <emphasis>G4UserEventAction</emphasis> class. See 
    <xref linkend="sect.UInfoCls" /> for details.
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Event.Stack">
<title>
Stacking mechanism
</title>

<para>
<emphasis>G4StackManager</emphasis> has three stacks, named 
<emphasis>urgent</emphasis>, <emphasis>waiting</emphasis> and 
<emphasis>postpone-to-next-event</emphasis>, which are objects
of the <emphasis>G4TrackStack</emphasis> class. By default, all <emphasis>G4Track</emphasis>
objects are stored in the <emphasis>urgent</emphasis> stack and handled in a
"last in first out" manner. In this case, the other two stacks are
not used. However, tracks may be routed to the other two stacks by
the user-defined <emphasis>G4UserStackingAction</emphasis> concrete class.
</para>

<para>
If the methods of <emphasis>G4UserStackingAction</emphasis> have been
overridden by the user, the <emphasis>postpone-to-next-event</emphasis> and
<emphasis>waiting</emphasis> stacks may contain tracks. At the beginning of an
event, <emphasis>G4StackManager</emphasis> checks to see if any tracks left over
from the previous event are stored in the <emphasis>postpone-to-next-event
stack</emphasis>. If so, it attemps to move them to the <emphasis>urgent</emphasis>
stack. But first the <literal>PrepareNewEvent()</literal> method of
<emphasis>G4UserStackingAction</emphasis> is called. Here tracks may be
re-classified by the user and sent to the <emphasis>urgent</emphasis> or
<emphasis>waiting</emphasis> stacks, or deferred again to the
<emphasis>postpone-to-next-event</emphasis> stack. As the event is processed
<emphasis>G4StackManager</emphasis> pops tracks from the <emphasis>urgent</emphasis> stack
until it is empty. At this point the <literal>NewStage()</literal> method of
<emphasis>G4UserStackingAction</emphasis> is called. In this method tracks from
the <emphasis>waiting</emphasis> stack may be sent to the <emphasis>urgent</emphasis> stack,
retained in the <emphasis>waiting</emphasis> stack or postponed to the next
event.
</para>

<para>
Details of the user-defined methods of
<emphasis>G4UserStackingAction</emphasis> and how they affect track stack
management are given in <xref linkend="sect.UInfoCls" />.
</para>


</sect2>
</sect1>