source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/GettingStarted/mainProgram.xml @ 904

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


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.HowToDefMain">
<title>
How to Define the main() Program
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToDefMain.SimpleMainMethod">
<title>
A Sample <literal>main()</literal> Method
</title>

<para>
The contents of <literal>main()</literal> will vary according to the 
needs of a given simulation application and therefore must be supplied 
by the user. The Geant4 toolkit does not provide a <literal>main()</literal>
method, but a sample is provided here as a guide to the beginning
user. <xref linkend="programlist_HowToDefMain_1" /> is the  simplest example of
<literal>main()</literal> required to build a simulation program.
</para>

<example id="programlist_HowToDefMain_1">
<title>
Simplest example of <literal>main()</literal> 
</title>

<programlisting>
 #include "G4RunManager.hh"
 #include "G4UImanager.hh"

 #include "ExN01DetectorConstruction.hh"
 #include "ExN01PhysicsList.hh"
 #include "ExN01PrimaryGeneratorAction.hh"

 int main()
 {
   // construct the default run manager
   G4RunManager* runManager = new G4RunManager;

   // set mandatory initialization classes
   runManager-&gt;SetUserInitialization(new ExN01DetectorConstruction);
   runManager-&gt;SetUserInitialization(new ExN01PhysicsList);

   // set mandatory user action class
   runManager-&gt;SetUserAction(new ExN01PrimaryGeneratorAction);

   // initialize G4 kernel
   runManager-&gt;Initialize();

   // get the pointer to the UI manager and set verbosities
   G4UImanager* UI = G4UImanager::GetUIpointer();
   UI-&gt;ApplyCommand("/run/verbose 1");
   UI-&gt;ApplyCommand("/event/verbose 1");
   UI-&gt;ApplyCommand("/tracking/verbose 1");

   // start a run
   int numberOfEvent = 3;
   runManager-&gt;BeamOn(numberOfEvent);

   // job termination
   delete runManager;
   return 0;
 }
</programlisting>
</example>

<para>
The <literal>main()</literal> method is implemented by two toolkit
classes, <emphasis>G4RunManager</emphasis> and <emphasis>G4UImanager</emphasis>, 
and three classes, <emphasis>ExN01DetectorConstruction</emphasis>, 
<emphasis>ExN01PhysicsList</emphasis> and 
<emphasis>ExN01PrimaryGeneratorAction</emphasis>, which are derived from
toolkit classes. Each of these are explained in the following sections.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToDefMain.G4RunManager">
<title>
<emphasis>G4RunManager</emphasis>
</title>

<para>
The first thing <literal>main()</literal> must do is create an instance of
the <emphasis>G4RunManager</emphasis> class. This is the only manager class in
the Geant4 kernel which should be explicitly constructed in the
user's <literal>main()</literal>. It controls the flow of the program and
manages the event loop(s) within a run. When <emphasis>G4RunManager</emphasis> is
created, the other major manager classes are also created. They are
deleted automatically when <emphasis>G4RunManager</emphasis> is deleted. The run
manager is also responsible for managing initialization procedures,
including methods in the user initialization classes. Through these
the run manager must be given all the information necessary to
build and run the simulation, including
</para>

<orderedlist spacing="compact">
  <listitem><para>
  how the detector should be constructed,
  </para></listitem>
  <listitem><para>
  all the particles and all the physics processes to be
  simulated,
  </para></listitem>
  <listitem><para>
  how the primary particle(s) in an event should be produced
  and
  </para></listitem>
  <listitem><para>
  any additional requirements of the simulation.</para></listitem>
</orderedlist>

<para>
In the sample <literal>main()</literal> the lines

<informalexample>
<programlisting>
  runManager-&gt;SetUserInitialization(new ExN01DetectorConstruction);
  runManager-&gt;SetUserInitialization(new ExN01PhysicsList);
</programlisting>
</informalexample>

create objects which specify the detector geometry and physics
processes, respectively, and pass their pointers to the run
manager. <emphasis>ExN01DetectorConstruction</emphasis> is an example of a user
initialization class which is derived from
<emphasis>G4VUserDetectorConstruction</emphasis>. This is where the user
describes the entire detector setup, including
</para>

<itemizedlist spacing="compact">
  <listitem><para>
  its geometry,
  </para></listitem>
  <listitem><para>
  the materials used in its construction,
  </para></listitem>
  <listitem><para>
  a definition of its sensitive regions and
  </para></listitem>
  <listitem><para>
  the readout schemes of the sensitive regions.
  </para></listitem>
</itemizedlist>

<para>
Similarly <emphasis>ExN01PhysicsList</emphasis> is derived from
<emphasis>G4VUserPhysicsList</emphasis> and requires the user to define
</para>

<itemizedlist spacing="compact">
  <listitem><para>
  the particles to be used in the simulation,
  </para></listitem>
  <listitem><para>
  the range cuts for these particles and
  </para></listitem>
  <listitem><para>
  all the physics processes to be simulated.
  </para></listitem>
</itemizedlist>

<para>
The next instruction in <literal>main()</literal>

<informalexample>
<programlisting>
  runManager-&gt;SetUserAction(new ExN01PrimaryGeneratorAction);
</programlisting>
</informalexample>

creates an instance of a particle generator and passes its pointer
to the run manager. <emphasis>ExN01PrimaryGeneratorAction</emphasis> is an
example of a user action class which is derived from
<emphasis>G4VUserPrimaryGeneratorAction</emphasis>. In this class the user must
describe the initial state of the primary event. This class has a
public virtual method named <literal>generatePrimaries()</literal> which will
be invoked at the beginning of each event. Details will be given in
<xref linkend="sect.HowToGenEvent" />. 
Note that Geant4 does not provide any default behavior for generating a primary event.
</para>

<para>
The next instruction

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

performs the detector construction, creates the physics processes,
calculates cross sections and otherwise sets up the run. The final
run manager method in <literal>main()</literal>

<informalexample>
<programlisting>
  int numberOfEvent = 3;
  runManager-&gt;beamOn(numberOfEvent);
</programlisting>
</informalexample>

begins a run of three sequentially processed events. The
<literal>beamOn()</literal> method may be invoked any number of times within
<literal>main()</literal> with each invocation representing a separate run.
Once a run has begun neither the detector setup nor the physics
processes may be changed. They may be changed between runs,
however, as described in <xref linkend="sect.Run.Custom" />.
More information on <emphasis>G4RunManager</emphasis> in general is found in 
<xref linkend="sect.Run" />.
</para>

<para>
As mentioned above, other manager classes are created when the
run manager is created. One of these is the user interface manager,
<emphasis>G4UImanager</emphasis>. In <literal>main()</literal> a pointer to 
the interface manager must be obtained

<informalexample>
<programlisting>
  G4UImanager* UI = G4UImanager::getUIpointer();
</programlisting>
</informalexample> 

in order for the user to issue commands to the program. In the
present example the <literal>applyCommand()</literal> method is called three
times to direct the program to print out information at the run,
event and tracking levels of simulation. A wide range of commands
is available which allows the user detailed control of the
simulation. A list of these commands can be found in 
<xref linkend="sect.BuiltinCom" />.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToDefMain.UserInitAction">
<title>
User Initialization and Action Classes
</title>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToDefMain.UserInitAction.MandatoryUserClasses">
<title>
Mandatory User Classes
</title>

<para>
There are three classes which must be defined by the user. Two
of them are user initialization classes, and the other is a user
action class. They must be derived from the abstract base classes
provided by Geant4: <emphasis>G4VUserDetectorConstruction</emphasis>,
<emphasis>G4VuserPhysicsList</emphasis> and 
<emphasis>G4VuserPrimaryGeneratorAction</emphasis>.
Geant4 does not provide default behavior for these classes.
<emphasis>G4RunManager</emphasis> checks for the existence of these mandatory
classes when the <literal>Initialize()</literal> and <literal>BeamOn()</literal>
methods are invoked.
</para>

<para>
As mentioned in the previous section,
<emphasis>G4VUserDetectorConstruction</emphasis> requires the user to define the
detector and <emphasis>G4VUserPhysicsList</emphasis> requires the user to define
the physics. Detector definition will be discussed in Sections
</para>

<para>
<xref linkend="sect.HowToDefDetectorGeom" /> and 
<xref linkend="sect.HowToSpecMate" />.
Physics definition will be discussed in Sections 
<xref linkend="sect.HowToSpecParti" /> 
and 
<xref linkend="sect.HowToSpecPhysProc" />.
The user action  <emphasis>G4VuserPrimaryGeneratorAction</emphasis> 
requires that the initial event state be defined. Primary event generation will 
be discussed in 
<xref linkend="sect.HowToMakeExec" />.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToDefMain.UserInitAction.OptionalUserAction">
<title>
Optional User Action Classes
</title>

<para>
Geant4 provides five user hook classes:
</para>

<itemizedlist spacing="compact">
  <listitem><para>
  <emphasis>G4UserRunAction</emphasis>
  </para></listitem>
  <listitem><para>
  <emphasis>G4UserEventAction</emphasis>
  </para></listitem>
  <listitem><para>
  <emphasis>G4UserStackingAction</emphasis>
  </para></listitem>
  <listitem><para>
  <emphasis>G4UserTrackingAction</emphasis>
  </para></listitem>
  <listitem><para>
  <emphasis>G4UserSteppingAction</emphasis>
  </para></listitem>
</itemizedlist>

<para>
There are several virtual methods in each of these classes which
allow the specification of additional procedures at all levels of
the simulation application. Details of the user initialization and
action classes are provided in 
<xref linkend="chap.UserActions" />.
</para>

</sect3>
</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToDefMain.G4UImanagerUICommand">
<title>
<emphasis>G4UImanager</emphasis> and UI CommandSubmission
</title>

<para>
Geant4 provides a category named <emphasis role="bold">intercoms</emphasis>.
<emphasis>G4UImanager</emphasis> is the manager class of this category. Using the
functionalities of this category, you can invoke 
<emphasis role="bold">set</emphasis> methods
of class objects of which you do not know the pointer. 
In <xref linkend="programlist_HowToDefMain_2" />, 
the verbosities of various Geant4 manager classes
are set. Detailed mechanism description and usage of
<emphasis role="bold">intercoms</emphasis> will be given in the next chapter, 
with a list of available commands. Command submission can be done all through the
application.
</para>

<example id="programlist_HowToDefMain_2">
<title>
An example of <literal>main()</literal> using interactive 
terminal and visualization. Code modified from the previous
example are shown in  <emphasis role="color_blue">blue</emphasis>.
</title>
<programlisting>
 #include "G4RunManager.hh"
 #include "G4UImanager.hh"
 <emphasis role="color_blue">#include "G4UIterminal.hh"</emphasis>
 #include "G4VisExecutive.hh"

 #include "N02DetectorConstruction.hh"
 #include "N02PhysicsList.hh"
 #include "N02PrimaryGeneratorAction.hh"
 #include "N02RunAction.hh"
 #include "N02EventAction.hh"
 #include "N02SteppingAction.hh"

 #include "g4templates.hh"

 int main(int argc,char** argv)
 {
   // construct the default run manager
   G4RunManager * runManager = new G4RunManager;

   // set mandatory initialization classes
   N02DetectorConstruction* detector = new N02DetectorConstruction;
   runManager-&gt;SetUserInitialization(detector);
   runManager-&gt;SetUserInitialization(new N02PhysicsList);
  
   // visualization manager
   G4VisManager* visManager = new G4VisExecutive;
   visManager-&gt;Initialize();
    
   // set user action classes
   runManager-&gt;SetUserAction(new N02PrimaryGeneratorAction(detector));
   runManager-&gt;SetUserAction(new N02RunAction);
   runManager-&gt;SetUserAction(new N02EventAction);
   runManager-&gt;SetUserAction(new N02SteppingAction);
    
   // get the pointer to the User Interface manager
   G4UImanager* UI = G4UImanager::GetUIpointer();

 <emphasis role="color_blue">
   if(argc==1)
   // Define (G)UI terminal for interactive mode
   {
     G4UIsession * session = new G4UIterminal;
     UI-&gt;ApplyCommand("/control/execute prerun.g4mac");
     session-&gt;sessionStart();
     delete session;
   }
   else
   // Batch mode
   {
     G4String command = "/control/execute ";
     G4String fileName = argv[1];
     UI-&gt;ApplyCommand(command+fileName);
   }
</emphasis>

   // job termination
   delete visManager;
   delete runManager;

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


</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToDefMain.G4coutG4cerr">
<title>
<emphasis>G4cout</emphasis> and <emphasis>G4cerr</emphasis>
</title>

<para>
Although not yet included in the above examples, output streams
will be needed. <emphasis>G4cout</emphasis> and <emphasis>G4cerr</emphasis> 
are <emphasis role="bold">iostream</emphasis>
objects defined by Geant4. The usage of these objects is exactly
the same as the ordinary <emphasis>cout</emphasis> and
<emphasis>cerr</emphasis>, 
except that the output streams will be handled by
<emphasis>G4UImanager</emphasis>. 
Thus, output strings may be displayed on another window or stored in a
file. Manipulation of these output streams will be described in
<xref linkend="sect.UIDefNew.HowCont" />.
These objects should be used instead of the ordinary
<emphasis>cout</emphasis> and <emphasis>cerr</emphasis>.
</para>


</sect2>
</sect1>