source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/UserActions/optionalActions.xml @ 1222

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Changed by: Katsuya Amako,  9-Jul-1998                -->
<!--    Changed by: Katsuya Amako,  4-Aug-1998                -->
<!--    Changed by: John Allison,   4-Aug-1998                -->
<!--    Changed by: Katsuya Amako, 30-Nov-1998                -->
<!--    Changed by: Dennis Wright, 27-Nov-2001                -->
<!--    Proof read by: Joe Chuma,   2-Jul-1999                -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.OptUAct">
<title>
Optional User Actions
</title>

<para>
There are five virtual classes whose methods the user may override
in order to gain control of the simulation at various stages. Each
method of each action class has an empty default implementation,
allowing the user to inherit and implement desired classes and
methods. Objects of user action classes must be registered with
<literal>G4RunManager</literal>.
</para>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.OptUAct.Usage">
<title>
Usage of User Actions
</title>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
<literal>G4UserRunAction</literal>
</bridgehead>

<para>
This class has three virtual methods which are invoked by
<literal>G4RunManager</literal> for each run:

<variablelist><title></title>
  <varlistentry>
    <term>
      <literal>GenerateRun()</literal>
    </term>
    <listitem><para>
      This method is invoked at the beginning of <literal>BeamOn</literal>.
      Because the user can inherit the class <literal>G4Run</literal> and create
      his/her own concrete class to store some information about the run,
      the <literal>GenerateRun()</literal> method is the place to instantiate such
      an object. It is also the ideal place to set variables which affect
      the physics table (such as production thresholds) for a particular
      run, because <literal>GenerateRun()</literal> is invoked before the
      calculation of the physics table.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <literal>BeginOfRunAction()</literal>
    </term>
    <listitem><para>
      This method is invoked before entering the event loop. A
      typical use of this method would be to initialize and/or book
      histograms for a particular run. This method is invoked after the
      calculation of the physics tables.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <literal>EndOfRunAction()</literal>
    </term>
    <listitem><para>
      This method is invoked at the very end of the run processing.
      It is typically used for a simple analysis of the processed run.
    </para></listitem>
  </varlistentry>
</variablelist>
</para>

<para>
<example id="programlist_OptUAct_1">
<title>
<literal>G4UserRunAction</literal>
</title>
<programlisting>
     class G4UserRunAction
     {
       public:
         G4UserRunAction();
         virtual ~G4UserRunAction();

       public:
         virtual G4Run* GenerateRun();
         virtual void BeginOfRunAction(const G4Run*);
         virtual void EndOfRunAction(const G4Run*);
     };
</programlisting>
</example>
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
<literal>G4UserEventAction</literal>
</bridgehead>

<para>
This class has two virtual methods which are invoked by
<literal>G4EventManager</literal> for each event:

<variablelist><title></title>
  <varlistentry>
    <term>
      <literal>beginOfEventAction()</literal>
    </term>
    <listitem><para>
      This method is invoked before converting the primary particles
      to <literal>G4Track</literal> objects. A typical use of this method 
      would be to initialize and/or book histograms for a particular event.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <literal>endOfEventAction()</literal>
    </term>
    <listitem><para>
      This method is invoked at the very end of event processing. It
      is typically used for a simple analysis of the processed event.
      If the user wants to keep the currently processing event until the
      end of the current run, the user can invoke
      <literal>fpEventManager->KeepTheCurrentEvent();</literal>
      so that it is kept in <emphasis>G4Run</emphasis> object. This should 
      be quite useful if you simulate quite many events and want to 
      visualize only the most interest ones after the long execution.
      Given the memory size of an event and its contents may be large, 
      it is the user's responsibility not to keep unnecessary events.
    </para></listitem>
  </varlistentry>
</variablelist>
</para>

<para>
<example id="programlist_OptUAct_2">
<title>
<literal>G4UserEventAction</literal>
</title>

<programlisting>
     class G4UserEventAction 
     {
       public:
           G4UserEventAction() {;}
           virtual ~G4UserEventAction() {;}
           virtual void BeginOfEventAction(const G4Event*);
           virtual void EndOfEventAction(const G4Event*);
       protected:
           G4EventManager* fpEventManager;
     };
</programlisting>
</example>
</para>
 
<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
<literal>G4UserStackingAction</literal>
</bridgehead>

<para>
This class has three virtual methods, <literal>ClassifyNewTrack</literal>,
<literal>NewStage</literal> and <literal>PrepareNewEvent</literal> which the 
user may override in order to control the various track stacking mechanisms.
ExampleN04 could be a good example to understand the usage of this class.
</para>

<para>
<literal>ClassifyNewTrack()</literal> is invoked by 
<literal>G4StackManager</literal> whenever a new <literal>G4Track</literal> 
object is "pushed" onto a stack by <literal>G4EventManager</literal>.
<literal>ClassifyNewTrack()</literal> returns an enumerator,
<literal>G4ClassificationOfNewTrack</literal>, whose value indicates to which
stack, if any, the track will be sent. This value should be
determined by the user. <literal>G4ClassificationOfNewTrack</literal> has
four possible values:

<itemizedlist spacing="compact">      
  <listitem><para>
    <literal>fUrgent</literal> - track is placed in the 
    <emphasis>urgent</emphasis> stack
  </para></listitem>
  <listitem><para>
    <literal>fWaiting</literal> - track is placed in the 
    <emphasis>waiting</emphasis> stack, and will not be simulated until
    the <emphasis>urgent</emphasis> stack is empty
  </para></listitem>
  <listitem><para>
    <literal>fPostpone</literal> - track is postponed to the next event
  </para></listitem>
  <listitem><para>
    <literal>fKill</literal> - the track is deleted immediately and not
    stored in any stack.
  </para></listitem>
</itemizedlist>      
</para>

<para>
These assignments may be made based on the origin of the track
which is obtained as follows:

<informalexample>
<programlisting>
  G4int parent_ID = aTrack-&gt;get_parentID();
</programlisting>
</informalexample>

where

<itemizedlist spacing="compact">      
  <listitem><para>
    <literal>parent_ID = 0</literal> indicates a primary particle
  </para></listitem>
  <listitem><para>
    <literal>parent_ID &gt; 0</literal> indicates a secondary particle
  </para></listitem>
  <listitem><para>
    <literal>parent_ID &lt; 0</literal> indicates postponed particle from
    previous event.
  </para></listitem>
</itemizedlist>      
</para>

<para>
<literal>NewStage()</literal> is invoked when the <emphasis>urgent</emphasis> 
stack is empty and the <emphasis>waiting</emphasis> stack contains at least one
<literal>G4Track</literal> object. Here the user may kill or re-assign to
different stacks all the tracks in the <emphasis>waiting</emphasis> stack by
calling the <literal>stackManager-&gt;ReClassify()</literal> method which, in
turn, calls the <literal>ClassifyNewTrack()</literal> method. If no user
action is taken, all tracks in the <emphasis>waiting</emphasis> stack are
transferred to the <emphasis>urgent</emphasis> stack. The user may also decide to
abort the current event even though some tracks may remain in the
<emphasis>waiting</emphasis> stack by calling <literal>stackManager-&gt;clear()</literal>.
This method is valid and safe only if it is called from the
<literal>G4UserStackingAction</literal> class. A global method of event
abortion is

<informalexample>
<programlisting>
  G4UImanager * UImanager = G4UImanager::GetUIpointer();
  UImanager-&gt;ApplyCommand("/event/abort");
</programlisting>
</informalexample>
</para>

<para>
<literal>PrepareNewEvent()</literal> is invoked at the beginning of each
event. At this point no primary particles have been converted to
tracks, so the <emphasis>urgent</emphasis> and <emphasis>waiting</emphasis> 
stacks are empty. However, there may be tracks in the 
<emphasis>postponed-to-next-event</emphasis> stack; 
for each of these the <literal>ClassifyNewTrack()</literal> method is
called and the track is assigned to the appropriate stack.

<example id="programlist_OptUAct_3">
<title>
<literal>G4UserStackingAction</literal>
</title>

<programlisting>
     #include "G4ClassificationOfNewTrack.hh"

     class G4UserStackingAction 
     {
       public:
           G4UserStackingAction();
           virtual ~G4UserStackingAction();
       protected:
           G4StackManager * stackManager;

       public:
     //---------------------------------------------------------------
     // virtual methods to be implemented by user
     //---------------------------------------------------------------
     //
           virtual G4ClassificationOfNewTrack 
             ClassifyNewTrack(const G4Track*);
     //
     //---------------------------------------------------------------
     //
           virtual void NewStage();
     //
     //---------------------------------------------------------------
     //
           virtual void PrepareNewEvent();
     //
     //---------------------------------------------------------------

     };
</programlisting>
</example>
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
<literal>G4UserTrackingAction</literal>
</bridgehead>

<para>
<example id="programlist_OptUAct_4">
<title>
<literal>G4UserTrackingAction</literal>
</title>

<programlisting>
     //---------------------------------------------------------------
     //
     // G4UserTrackingAction.hh
     //
     // Description:
     //   This class represents actions taken place by the user at each
     //   end of stepping. 
     //
     //---------------------------------------------------------------

     ///////////////////////////
     class G4UserTrackingAction 
     ///////////////////////////
     {
     
     //--------
        public:
     //--------
     
     // Constructor &amp; Destructor
        G4UserTrackingAction(){};
        virtual ~G4UserTrackingAction(){}
     
     // Member functions
        virtual void PreUserTrackingAction(const G4Track*){}
        virtual void PostUserTrackingAction(const G4Track*){}
     
     //----------- 
        protected:
     //----------- 
     
     // Member data
        G4TrackingManager* fpTrackingManager;
     
     };
</programlisting>
</example>
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
<literal>G4UserSteppingAction</literal>
</bridgehead>

<para>
<example id="programlist_OptUAct_5">
<title>
<literal>G4UserSteppingAction</literal>
</title>

<programlisting>
     //---------------------------------------------------------------
     //
     //  G4UserSteppingAction.hh
     //
     //  Description:
     //    This class represents actions taken place by the user at each
     //    end of stepping. 
     //
     //---------------------------------------------------------------
     
     ///////////////////////////
     class G4UserSteppingAction 
     ///////////////////////////
     {
     
     //--------
        public:
     //--------
     
     // Constructor and destructor
        G4UserSteppingAction(){}
        virtual ~G4UserSteppingAction(){}
     
     // Member functions
        virtual void UserSteppingAction(const G4Step*){}
     
     //----------- 
        protected:
     //----------- 
     
     // Member data
        G4SteppingManager* fpSteppingManager;
     
     };
</programlisting>
</example>
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.OptUAct.EngyConsv">
<title>
Killing Tracks in User Actions and Energy Conservation
</title>

<para>
In either of user action classes described in the previous section, 
the user can implement an unnatural/unphysical action. A typical 
example is to kill a track, which is under the simulation, in the 
user stepping action. In this case the user have to be cautious of 
the total energy conservation. The user stepping action itself does 
not take care the energy or any physics quantity associated with 
the killed track. Therefore if the user want to keep the total 
energy of an event in this case, the lost track energy need to be
recorded by the user. 
</para>

<para>
The same is true for user stacking or tracking actions. If the 
user has killed a track in these actions the all physics information
associated with it would be lost and, for example, the total energy 
conservation be broken.  
</para>

<para>
If the user wants the Geant4 kernel to take care the total energy
conservation automatically when he/she has killed artificially
a track, the user has to use a killer process. For example if the 
user uses G4UserLimits and G4UserSpecialCuts process, energy of 
the killed track is added to the total energy deposit.
</para>


</sect2>
</sect1>