source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Fundamentals/run.xml @ 904

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


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

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Run.Basic">
<title>
Basic concept of <emphasis>Run</emphasis>
</title>

<para>
In Geant4, <emphasis>Run</emphasis> is the largest unit of simulation. A run
consists of a sequence of events. Within a run, the detector
geometry, the set up of sensitive detectors, and the physics
processes used in the simulation should be kept unchanged. A run is
represented by a <emphasis>G4Run</emphasis> class object. A run starts with
<literal>BeamOn()</literal> method of <emphasis>G4RunManager</emphasis>.
</para>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Run.Basic.Rep">
<title>
Representation of a run
</title>

<para>
<emphasis>G4Run</emphasis> represents a run. It has a run identification
number, which should be set by the user, and the number of events
simulated during the run. Please note that the run identification
number is not used by the Geant4 kernel, and thus can be
arbitrarily assigned at the user's convenience.
</para>

<para>
<emphasis>G4Run</emphasis> has pointers to the tables 
<emphasis>G4VHitsCollection</emphasis>
and <emphasis>G4VDigiCollection</emphasis>. These tables are associated 
in case <emphasis>sensitive detectors</emphasis> and 
<emphasis>digitizer modules</emphasis> are
simulated, respectively. The usage of these tables will be
mentioned in <xref linkend="sect.Hits" /> and <xref linkend="sect.Digi" />.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Run.Basic.Manage">
<title>
Manage the run procedures
</title>

<para>
<emphasis>G4RunManager</emphasis> manages the procedures of a run. In the
constructor of <emphasis>G4RunManager</emphasis>, all of the manager classes in
Geant4 kernel, except for some static managers, are constructed.
These managers are deleted in the destructor of
<emphasis>G4RunManager</emphasis>. <emphasis>G4RunManager</emphasis> 
must be a singleton, and
the pointer to this singleton object can be obtained by the
<literal>getRunManager()</literal> static method.
</para>

<para>
As already mentioned in <xref linkend="sect.HowToDefMain" />, all of the
<emphasis>user initialization</emphasis> classes and 
<emphasis>user action</emphasis> classes
defined by the user should be assigned to <emphasis>G4RunManager</emphasis>
before starting initialization of the Geant4 kernel. The
assignments of these user classes are done by
<literal>SetUserInitialization()</literal> and <literal>SetUserAction()</literal>
methods. All user classes defined by the Geant4 kernel will be
summarized in <xref linkend="chap.UserActions" />.
</para>

<para>
<emphasis>G4RunManager</emphasis> has several public methods, which are listed
below.

<variablelist><title></title>
  <varlistentry>
    <term><literal>Initialize()</literal></term>
    <listitem>
      All initializations required by the Geant4 kernel are triggered
      by this method. Initializations are:

      <itemizedlist spacing="compact">
        <listitem><para>
          construction of the detector geometry and set up of sensitive
          detectors and/or digitizer modules,
        </para></listitem>
        <listitem><para>
          construction of particles and physics processes,
        </para></listitem>
        <listitem><para>
          calculation of cross-section tables.
        </para></listitem>
      </itemizedlist>

      This method is thus mandatory before proceeding to the first run.
      This method will be invoked automatically for the second and later
      runs in case some of the initialized quantities need to be updated.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>BeamOn(G4int numberOfEvent)</literal></term>
    <listitem>
      This method triggers the actual simulation of a run, that is,
      an event loop. It takes an integer argument which represents the
      number of events to be simulated.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>GetRunManager()</literal></term>
    <listitem>
      This static method returns the pointer to the
      <emphasis>G4RunManager</emphasis> singleton object.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>GetCurrentEvent()</literal></term>
    <listitem>
      This method returns the pointer to the <emphasis>G4Event</emphasis> object
      which is currently being simulated. This method is available only
      when an event is being processed. At this moment, the application
      state of Geant4, which is explained in the following sub-section,
      is <emphasis>"EventProc"</emphasis>. When Geant4 is in a state other than
      <emphasis>"EventProc"</emphasis>, this method returns
      <literal>null</literal>. 
      Please note that the return value of this method is 
      <literal>const G4Event *</literal> and thus you cannot modify the
      contents  of the object.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>SetNumberOfEventsToBeStored(G4int nPrevious)</literal></term>
    <listitem>
      When simulating the "pile up" of more than one event, it is
      essential to access more than one event at the same moment. By
      invoking this method, <emphasis>G4RunManager</emphasis> keeps <literal>nPrevious
      G4Event</literal> objects. This method must be invoked before proceeding
      to <literal>BeamOn()</literal>.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>GetPreviousEvent(G4int i_thPrevious)</literal></term>
    <listitem>
      The pointer to the <literal>i_thPrevious G4Event</literal> object can be
      obtained through this method. A pointer to a <literal>const</literal> object
      is returned. It is inevitable that <literal>i_thPrevious</literal> events
      must have already been simulated in the same run for getting the
      <literal>i_thPrevious</literal> event. Otherwise, this method returns
      <literal>null</literal>.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>AbortRun()</literal></term>
    <listitem>
      This method should be invoked whenever the processing of a run
      must be stopped. It is valid for <emphasis>GeomClosed</emphasis> and
      <emphasis>EventProc</emphasis> states. Run processing will be safely aborted even
      in the midst of processing an event. However, the last event of the
      aborted run will be incomplete and should not be used for further
      analysis.
    </listitem>
  </varlistentry>
</variablelist>
</para>

</sect3>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Run.Basic.UserRunAction">
<title>
<emphasis>G4UserRunAction</emphasis>
</title>

<para>
<emphasis>G4UserRunAction</emphasis> is one of the <emphasis>user action</emphasis> 
classes from which you can derive your own concrete class. This base class
has two virtual methods, as follows:


<variablelist><title></title>
  <varlistentry>
    <term><literal>BeginOfRunAction()</literal></term>
    <listitem>
      This method is invoked at the beginning of the
      <literal>BeamOn()</literal> method but after confirmation of the conditions
      of the Geant4 kernel. Likely uses of this method include:

      <itemizedlist spacing="compact">
        <listitem><para>
          setting a run identification number,
        </para></listitem>
        <listitem><para>
          booking histograms,
        </para></listitem>
        <listitem><para>
          setting run specific conditions of the sensitive detectors
          and/or digitizer modules (e.g., dead channels).
        </para></listitem>
      </itemizedlist>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>EndOfRunAction()</literal></term>
    <listitem>
      This method is invoked at the very end of the <literal>BeamOn()</literal>
      method. Typical use cases of this method are

      <itemizedlist spacing="compact">
        <listitem><para>
          store/print histograms,
        </para></listitem>
        <listitem><para>
          manipulate run summaries.
        </para></listitem>
      </itemizedlist>
    </listitem>
  </varlistentry>
</variablelist>
</para>

</sect3>
</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Run.StateMac">
<title>
Geant4 as a state machine
</title>

<para>
Geant4 is designed as a state machine. Some methods in Geant4 are
available for only a certain state(s). <emphasis>G4RunManager</emphasis> controls
the state changes of the Geant4 application. States of Geant4 are
represented by the enumeration <emphasis>G4ApplicationState</emphasis>. It has
six states through the life cycle of a Geant4 application.


<variablelist><title></title>
  <varlistentry>
    <term><emphasis>G4State_PreInit</emphasis> state</term>
    <listitem>
      A Geant4 application starts with this state. The application
      needs to be initialized when it is in this state. The application
      occasionally comes back to this state if geometry, physics
      processes, and/or cut-off have been changed after processing a
      run.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>G4State_Init</emphasis> state</term>
    <listitem>
      The application is in this state while the
      <literal>Initialize()</literal> method of <emphasis>G4RunManager</emphasis> 
      is being invoked. Methods defined in any 
      <emphasis>user initialization</emphasis> classes 
      are invoked during this state.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>G4State_Idle</emphasis> state</term>
    <listitem>
      The application is ready for starting a run.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>G4State_GeomClosed</emphasis> state</term>
    <listitem>
      When <literal>BeamOn()</literal> is invoked, the application proceeds to
      this state to process a run. Geometry, physics processes, and
      cut-off cannot be changed during run processing.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>G4State_EventProc</emphasis> state</term>
    <listitem>
      A Geant4 application is in this state when a particular event
      is being processed. <literal>GetCurrentEvent()</literal> and
      <literal>GetPreviousEvent()</literal> methods of 
      <emphasis>G4RunManager</emphasis> are
      available only at this state.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>G4State_Quit</emphasis> state</term>
    <listitem>
      When the destructor of <emphasis>G4RunManager</emphasis> is invoked, the
      application comes to this "dead end" state. Managers of the Geant4
      kernel are being deleted and thus the application cannot come back
      to any other state.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>G4State_Abort</emphasis> state</term>
    <listitem>
      When a <emphasis>G4Exception</emphasis> occurs, the application comes to this
      "dead end" state and causes a core dump. The user still has a hook
      to do some "safe" opperations, e.g. storing histograms, by
      implementing a user concrete class of <emphasis>G4VStateDependent</emphasis>. The
      user also has a choice to suppress the occurence of
      <emphasis>G4Exception</emphasis> by a UI command
      <emphasis>/control/suppressAbortion</emphasis>. When abortion is suppressed, you
      will still get error messages issued by G4Exception, and there is
      NO guarantee of a correct result after the G4Exception error
      message.
    </listitem>
  </varlistentry>
</variablelist>

<emphasis>G4StateManager</emphasis> belongs to the <emphasis>intercoms</emphasis> 
category.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Run.UserHook">
<title>
User's hook for state change
</title>

<para>
In case the user wants to do something at the moment of state
change of Geant4, the user can create a concrete class of the
<emphasis>G4VStateDependent</emphasis> base class. For example, the user can
store histograms when G4Exception occurs and Geant4 comes to the
<emphasis>Abort</emphasis> state, but before the actual core dump.
</para>

<para>
The following is an example user code which stores histograms
when Geant4 becomes to the <emphasis>Abort</emphasis> state. This class object
should be mabe in, for example <emphasis>main()</emphasis>, by the user code.
This object will be automatically registered to
<emphasis>G4StateManager</emphasis> at its construction.
</para>

<example id="programlist_Run_1">
<title>
Header file of UserHookForAbortState
</title>
<programlisting>
#ifndef UserHookForAbortState_H
#define UserHookForAbortState_H 1

#include "G4VStateDependent.hh"

class UserHookForAbortState : public G4VStateDependent
{
 public:
  UserHookForAbortState();   // constructor
  ~UserHookForAbortState();  // destructor

  virtual G4bool Notify(G4ApplicationState requiredState);
};
</programlisting>
</example>


<example id="programlist_Run_2">
<title>
Source file of UserHookForAbortState
</title>
<programlisting>
#include "UserHookForAbortState.hh"

UserHookForAbortState::UserHookForAbortState() {;}
UserHookForAbortState::~UserHookForAbortState() {;}

G4bool UserHookForAbortState::Notify(G4ApplicationState requiredState)
{
  if(requiredState!=Abort) return true;
  
  // Do book keeping here

  return true;
}
</programlisting>
</example>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Run.Custom">
<title>
Customizing the Run Manager
</title>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Run.Custom.VirMeth">
<title>
Virtual Methods in the Run Manager
</title>

<para>
<literal>G4RunManager</literal> is a concrete class with a complete set of
functionalities for managing the Geant4 kernel. It is the only
manager class in the Geant4 kernel which must be constructed in the
<literal>main()</literal> method of the user's application. Thus, instead of
constructing the <literal>G4RunManager</literal> provided by Geant4, you are
free to construct your own <literal>RunManager</literal>. It is recommended,
however, that your <literal>RunManager</literal> inherit
<literal>G4RunManager</literal>. For this purpose, <literal>G4RunManager</literal> has
various virtual methods which provide all the functionalities
required to handle the Geant4 kernel. Hence, your customized run
manager need only override the methods particular to your needs;
the remaining methods in <literal>G4RunManager</literal> base class can still
be used. A summary of the available methods is presented here:


<variablelist><title></title>
  <varlistentry>
    <term><literal>public: virtual void Initialize();</literal></term>
    <listitem>
      main entry point of Geant4 kernel initialization
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>protected: virtual void InitializeGeometry();</literal></term>
    <listitem>
      geometry construction
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>protected: virtual void InitializePhysics();</literal></term>
    <listitem>
      physics processes construction
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>public: virtual void BeamOn(G4int n_event);</literal></term>
    <listitem>
      main entry point of the event loop
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>protected: virtual G4bool ConfirmBeamOnCondition();</literal></term>
    <listitem>
      check the kernel conditions for the event loop
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>protected: virtual void RunInitialization();</literal></term>
    <listitem>
      prepare a run
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>protected: virtual void DoEventLoop(G4int n_events);</literal></term>
    <listitem>
      manage an event loop
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>protected: virtual G4Event* GenerateEvent(G4int i_event);</literal></term>
    <listitem>
      generation of <emphasis>G4Event</emphasis> object
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>protected: virtual void AnalyzeEvent(G4Event* anEvent);</literal></term>
    <listitem>
      storage/analysis of an event
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>protected: virtual void RunTermination();</literal></term>
    <listitem>
      terminate a run
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>public: virtual void DefineWorldVolume(G4VPhysicalVolume * worldVol);</literal></term>
    <listitem>
      set the world volume to <emphasis>G4Navigator</emphasis>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>public: virtual void AbortRun();</literal></term>
    <listitem>
      abort the run
    </listitem>
  </varlistentry>
</variablelist>
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Run.Custom.EventLoop">
<title>
Customizing the Event Loop
</title>

<para>
In <literal>G4RunManager</literal> the event loop is handled by the
virtual method <literal>DoEventLoop()</literal>. This method is implemented
by a <literal>for</literal> loop consisting of the following steps:

<orderedlist spacing="compact">
  <listitem><para>
    construct a <literal>G4Event</literal> object and assign to it primary
    vertex(es) and primary particles. This is done by the virtual
    <literal>GeneratePrimaryEvent()</literal> method.
  </para></listitem>
  <listitem><para>
    send the <literal>G4Event</literal> object to <literal>G4EventManager</literal> 
    for the detector simulation. <emphasis>Hits</emphasis> and 
    <emphasis>trajectories</emphasis> will
    be associated with the <literal>G4Event</literal> object as a
    consequence.
  </para></listitem>
  <listitem><para>
    perform bookkeeping for the current <literal>G4Event</literal> object.
    This is done by the virtual <literal>AnalyzeEvent()</literal> method.
  </para></listitem>
</orderedlist>
</para>

<para>
<literal>DoEventLoop()</literal> performs the entire simulation of an
event. However, it is often useful to split the above three steps
into isolated application programs. If, for example, you wish to
examine the effects of changing discriminator thresholds, ADC gate
widths and/or trigger conditions on simulated events, much time can
be saved by performing steps 1 and 2 in one program and step 3 in
another. The first program need only generate the hit/trajectory
information once and store it, perhaps in a database. The second
program could then retrieve the stored <literal>G4Event</literal> objects and
perform the digitization (analysis) using the above threshold, gate
and trigger settings. These settings could then be changed and the
digitization program re-run without re-generating the
<literal>G4Event</literal>s.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Run.Custom.Geometry">
<title>
Changing the Detector Geometry
</title>

<para>
The detector geometry defined in your
<emphasis>G4VUserDetectorConstruction</emphasis> concrete class can be changed
during a run break (between two runs). Two different cases are
considered.
</para>

<para>
The first is the case in which you want to delete the entire
structure of your old geometry and build up a completely new set of
volumes. For this case, you need to set the new world physical
volume pointer to the <emphasis>RunManager</emphasis>. Thus, you should proceed
in the following way.

<informalexample>
<programlisting>
  G4RunManager* runManager = G4RunManager::GetRunManager();
  runManager-&gt;DefineWorldVolume( newWorldPhys );
</programlisting>
</informalexample>

Presumably this case is rather rare. The second case is more
frequent for the user.
</para>

<para>
The second case is the following. Suppose you want to move
and/or rotate a particular piece of your detector component. This
case can easily happen for a beam test of your detector. It is
obvious for this case that you need not change the world volume.
Rather, it should be said that your world volume (experimental hall
for your beam test) should be big enough for moving/rotating your
test detector. For this case, you can still use all of your
detector geometries, and just use a <literal>Set</literal> method of a
particular physical volume to update the transformation vector as
you want. Thus, you don't need to re-set your world volume pointer
to <emphasis>RunManager</emphasis>.
</para>

<para>
If you want to change your geometry for every run, you can
implement it in the <literal>BeginOfRunAction()</literal> method of
<emphasis>G4UserRunAction</emphasis> class, which will be invoked at the
beginning of each run, or, derive the <literal>RunInitialization()</literal>
method. Please note that, for both of the above mentioned cases,
you need to let <emphasis>RunManager</emphasis> know "the geometry needs to be
closed again". Thus, you need to invoke

<informalexample>
<programlisting>
  runManager-&gt;GeometryHasBeenModified();
</programlisting>
</informalexample>

before proceeding to the next run. An example of changing geometry
is given in a Geant4 tutorial in Geant4 Training kit #2.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Run.Custom.SwitchPhys">
<title>
Switch physics processes
</title>

<para>
In the <literal>InitializePhysics()</literal> method,
<literal>G4VUserPhysicsList::Construct</literal> is invoked in order to
define particles and physics processes in your application.
Basically, you can not add nor remove any particles during
execution, because particles are static objects in Geant4 (see 
<xref linkend="sect.HowToSpecParti" /> and 
<xref linkend="sect.Parti" /> for details). 
In addition, it is very difficult to add and/or remove physics
processes during execution, because registration procedures are
very complex, except for experts (see <xref linkend="sect.HowToSpecPhysProc" />
and <xref linkend="sect.PhysProc" />). 
This is why the <literal>initializePhysics()</literal> method is assumed 
to be invoked at once in Geant4 kernel initialization.
</para>

<para>
However, you can switch on/off physics processes defined in your
<emphasis>G4VUserPhysicsList</emphasis> concrete class and also change parameters
in physics processes during the run break.
</para>

<para>
You can use <literal>ActivateProcess()</literal> and
<literal>InActivateProcess()</literal> methods of <emphasis>G4ProcessManager</emphasis>
anywhere outside the event loop to switch on/off some process. You
should be very careful to switch on/off processes inside the event
loop, though it is not prohibited to use these methods even in the
<emphasis>EventProc</emphasis> state.
</para>

<para>
It is a likely case to change cut-off values in a run. You can
change <literal>defaultCutValue</literal> in
<emphasis>G4VUserPhysicsList</emphasis> 
during the <emphasis>Idle</emphasis> state. In this case, all cross section 
tables need to be recalculated before the event loop. You should use the
<literal>CutOffHasBeenModified()</literal> method when you change cut-off
values so that the <literal>SetCuts</literal> method of your
<emphasis>PhysicsList</emphasis> concrete class will be invoked.
</para>


</sect3>
</sect2>
</sect1>