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

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


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.HowToExec">
<title>
How to Execute a Program
</title>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToExec.Intro">
<title>
Introduction
</title>

<para>
A Geant4 application can be run either in

<itemizedlist spacing="compact">
  <listitem><para>
  `purely hard-coded` batch mode
  </para></listitem>
  <listitem><para>
  batch mode, but reading a macro of commands
  </para></listitem>
  <listitem><para>
  interactive mode, driven by command lines
  </para></listitem>
  <listitem><para>
  interactive mode via a Graphical User Interface
  </para></listitem>
</itemizedlist>

The last mode will be covered in <xref linkend="sect.HowToSetUpInter" />.
The first three modes are explained here.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToExec.HardCodedBatch">
<title>
'Hard-coded' Batch Mode
</title>

<para>
Below is an example of the main program for an application which
will run in batch mode.

<example id="programlist_HowToExec_1">
<title>
An example of the <literal>main()</literal> routine 
for an application which will run in batch mode.
</title>
<programlisting>
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();

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

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

<para>
Even the number of events in the run is `frozen`. To change this
number you must at least recompile <literal>main()</literal>.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToExec.BatchMacro">
<title>
Batch Mode with Macro File
</title>

<para>
Below is an example of the main program for an application which
will run in batch mode, but reading a file of commands.

<example id="programlist_HowToExec_2">
<title>
An example of the <literal>main()</literal> routine 
for an application which will run in batch mode, but reading a file of commands.
</title>
<programlisting>
int main(int argc,char** argv) {

   // Construct the default run manager
  G4RunManager * runManager = new G4RunManager;
  
  // set mandatory initialization classes
  runManager-&gt;SetUserInitialization(new MyDetectorConstruction);
  runManager-&gt;SetUserInitialization(new MyPhysicsList);
  
  // set mandatory user action class
  runManager-&gt;SetUserAction(new MyPrimaryGeneratorAction);
  
  // Initialize G4 kernel
  runManager-&gt;Initialize();

  //read a macro file of commands
  G4UImanager * UI = G4UImanager::getUIpointer();
  G4String command = "/control/execute ";
  G4String fileName = argv[1];
  UI-&gt;applyCommand(command+fileName); 

  delete runManager;
  return 0;
}
</programlisting>
</example>
</para>

<para>
This example will be executed with the command:

<informalexample>
<programlisting>
    &gt; myProgram  run1.mac
</programlisting>
</informalexample>

where <literal>myProgram</literal> is the name of your executable and
<literal>run1.mac</literal> is a macro of commands located in the current
directory, which could look like:

<example id="programlist_HowToExec_3">
<title>
A typical command macro.
</title>
<programlisting>
#
# Macro file for "myProgram.cc"
#
# set verbose level for this run
#
/run/verbose      2
/event/verbose    0
/tracking/verbose 1
#
# Set the initial kinematic and run 100 events
# electron 1 GeV to the direction (1.,0.,0.)
#
/gun/particle e-
/gun/energy 1 GeV
/run/beamOn 100
</programlisting>
</example>
</para>

<para>
Indeed, you can re-execute your program with different run
conditions without recompiling anything.
</para>

<para>
<emphasis>Digression:</emphasis> 
many G4 category of classes have a verbose flag which controls
the level of 'verbosity'.
</para>

<para>
Usually <literal>verbose=0</literal> means silent. For instance

<itemizedlist spacing="compact">
  <listitem><para>
  <literal>/run/verbose</literal> is for the <literal>RunManager</literal>
  </para></listitem>
  <listitem><para>
  <literal>/event/verbose</literal> is for the <literal>EventManager</literal>
  </para></listitem>
  <listitem><para>
  <literal>/tracking/verbose</literal> is for the <literal>TrackingManager</literal>
  </para></listitem>
  <listitem><para>
  ...etc...
  </para></listitem>
</itemizedlist>
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToExec.InteractiveMode">
<title>
Interactive Mode Driven by Command Lines
</title>

<para>
Below is an example of the main program for an application which
will run interactively, waiting for command lines entered from the
keyboard.

<example id="programlist_HowToExec_4">
<title>
An example of the <literal>main()</literal> routine for 
an application which will run interactively, waiting for commands from the
keyboard.
</title>
<programlisting>
int main(int argc,char** argv) {

  // Construct the default run manager
  G4RunManager * runManager = new G4RunManager;

  // set mandatory initialization classes
  runManager-&gt;SetUserInitialization(new MyDetectorConstruction);
  runManager-&gt;SetUserInitialization(new MyPhysicsList);
  
  // visualization manager
  G4VisManager* visManager = new G4VisExecutive;
  visManager-&gt;Initialize();
    
  // set user action classes
  runManager-&gt;SetUserAction(new MyPrimaryGeneratorAction);
  runManager-&gt;SetUserAction(new MyRunAction);
  runManager-&gt;SetUserAction(new MyEventAction);
  runManager-&gt;SetUserAction(new MySteppingAction);
  
  // Initialize G4 kernel
  runManager-&gt;Initialize();
  
  // Define UI terminal for interactive mode   
  G4UIsession * session = new G4UIterminal;    
  session-&gt;SessionStart();
  delete session;

  // job termination
  delete visManager;
  delete runManager;

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

<para>
This example will be executed with the command:

<informalexample>
<programlisting>
  &gt; myProgram                  
</programlisting>
</informalexample>

where <literal>myProgram</literal> is the name of your executable.
</para>

<para>
The G4 kernel will prompt:

<informalexample>
<programlisting>
  Idle&gt;
</programlisting>
</informalexample>

and you can start your session. An example session could be:
</para>

<para>
Create an empty scene ("world" is default):

<informalexample>
<programlisting>
  Idle&gt; /vis/scene/create
</programlisting>
</informalexample>

Add a volume to the scene:

<informalexample>
<programlisting>
  Idle&gt; /vis/scene/add/volume
</programlisting>
</informalexample>
</para>

<para>
Create a scene handler for a specific graphics system. Change the
next line to choose another graphic system:

<informalexample>
<programlisting>
  Idle&gt; /vis/sceneHandler/create OGLIX
</programlisting>
</informalexample>

Create a viewer:

<informalexample>
<programlisting>
  Idle&gt; /vis/viewer/create
</programlisting>
</informalexample>

Draw the scene, etc.:

<informalexample>
<programlisting>
  Idle&gt; /vis/scene/notifyHandlers
  Idle&gt; /run/verbose      0
  Idle&gt; /event/verbose    0
  Idle&gt; /tracking/verbose 1
  Idle&gt; /gun/particle mu+
  Idle&gt; /gun/energy 10 GeV
  Idle&gt; /run/beamOn 1
  Idle&gt; /gun/particle proton
  Idle&gt; /gun/energy 100 MeV
  Idle&gt; /run/beamOn 3           
  Idle&gt; exit                  
</programlisting>
</informalexample>
</para>

<para>
For the meaning of the machine state <literal>Idle</literal>, see 
<xref linkend="sect.Run.StateMac" />.
</para>

<para>
This mode is useful for running a few events in debug mode and
visualizing them. Notice that the <emphasis>VisManager</emphasis> is created in
the <literal>main()</literal>, and the visualization system is choosen via
the command:

<informalexample>
<programlisting>
  /vis/sceneHandler/create OGLIX
</programlisting>
</informalexample>
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToExec.GeneralCase">
<title>
General Case
</title>

<para>
Most of the examples in the <literal>$G4INSTALL/examples/</literal> directory
have the following <literal>main()</literal>, which covers cases 2 and 3
above. Thus, the application can be run either in batch or
interactive mode.

<example id="programlist_HowToExec_5">
<title>
The typical <literal>main()</literal> routine from the examples directory.
</title>
<programlisting>
int main(int argc,char** argv) {

  // Construct the default run manager
  G4RunManager * runManager = new G4RunManager;

  // set mandatory initialization classes
  N03DetectorConstruction* detector = new N03DetectorConstruction;
  runManager-&gt;SetUserInitialization(detector);
  runManager-&gt;SetUserInitialization(new N03PhysicsList);
  
#ifdef G4VIS_USE
  // visualization manager
  G4VisManager* visManager = new G4VisExecutive;
  visManager-&gt;Initialize();
#endif
    
  // set user action classes
  runManager-&gt;SetUserAction(new N03PrimaryGeneratorAction(detector));
  runManager-&gt;SetUserAction(new N03RunAction);
  runManager-&gt;SetUserAction(new N03EventAction);
  runManager-&gt;SetUserAction(new N03SteppingAction);
    
  // get the pointer to the User Interface manager 
    G4UImanager* UI = G4UImanager::GetUIpointer();  

  if (argc==1)   // Define UI terminal for interactive mode  
    { 
     G4UIsession * session = new G4UIterminal;
     UI-&gt;ApplyCommand("/control/execute prerunN03.mac");    
     session-&gt;SessionStart();
     delete session;
    }
  else           // Batch mode
    { 
     G4String command = "/control/execute ";
     G4String fileName = argv[1];
     UI-&gt;ApplyCommand(command+fileName);
    }

  // job termination
#ifdef G4VIS_USE
  delete visManager;
#endif
  delete runManager;

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

<para>
Notice that the visualization system is under the control of the
precompiler variable <literal>G4VIS_USE</literal>. Notice also that, in
interactive mode, few intializations have been put in the macro
<literal>prerunN03.mac</literal> which is executed before the session
start.

<example id="programlist_HowToExec_6">
<title>
The <literal>prerunN03.mac</literal> macro.
</title>
<programlisting>
 # Macro file for the initialization phase of "exampleN03.cc"
 #
 # Sets some default verbose flags
 # and initializes the graphics.
 #
 /control/verbose 2
 /control/saveHistory
 /run/verbose 2
 #
 /run/particle/dumpCutValues
 #
 # Create empty scene ("world" is default)
 /vis/scene/create
 #
 # Add volume to scene
 /vis/scene/add/volume
 #
 # Create a scene handler for a specific graphics system
 # Edit the next line(s) to choose another graphic system
 #
 #/vis/sceneHandler/create DAWNFILE
 /vis/sceneHandler/create OGLIX
 #
 # Create a viewer
 /vis/viewer/create
 #
 # Draw scene
 /vis/scene/notifyHandlers
 #
 # for drawing the tracks
 # if too many tracks cause core dump =&gt; storeTrajectory 0
 /tracking/storeTrajectory 1
 #/vis/scene/include/trajectories
</programlisting>
</example>
</para>

<para>
Also, this example demonstrates that you can read and execute a
macro interactively:

<informalexample>
<programlisting>
  Idle&gt; /control/execute  mySubMacro.mac
</programlisting>
</informalexample>
</para>


</sect2>
</sect1>