source: trunk/documents/UserDoc/UsersGuides/ForApplicationDeveloper/html/GettingStarted/mainProgram.html @ 1358

Last change on this file since 1358 was 1208, checked in by garnier, 15 years ago

CVS update
File size: 12.0 KB
Line 
1<HTML>
2<TITLE>
3</TITLE>
4<!-- Changed by: Katsuya Amako,  4-Aug-1998 -->
5<!-- Changed by: Dennis Wright, 29-Nov-2001 -->
6<!-- Proof read by: Joe Chuma,  14-Jun-1999 -->
7<BODY>
8<TABLE WIDTH="100%"><TR>
9<TD>
10
11
12<A HREF="index.html">
13<IMG SRC="../../../../resources/html/IconsGIF/Contents.gif" ALT="Contents"></A>
14<IMG SRC="../../../../resources/html/IconsGIF/PreviousGR.gif" ALT="Previous">
15<A HREF="geometryDef.html">
16<IMG SRC="../../../../resources/html/IconsGIF/Next.gif" ALT="Next"></A>
17</TD>
18<TD ALIGN="Right">
19<FONT SIZE="-1" COLOR="#238E23">
20<B>Geant4 User's Guide</B>
21<BR>
22<B>For Application Developers</B>
23<BR>
24<B>Getting Started with Geant4</B>
25</FONT>
26</TD>
27</TR></TABLE>
28<BR><BR>
29
30<P ALIGN="Center">
31<FONT SIZE="+3" COLOR="#238E23">
32<B>2.1 How to Define the main() Program</B>
33</FONT>
34<BR><BR>
35
36<HR ALIGN="Center" SIZE="7%">
37<p>
38
39<a name="2.1.1">
40<H2>2.1.1 A Sample <tt>main()</tt> Method</H2></a>
41
42 The contents of <tt>main()</tt> will vary according to the needs
43 of a given simulation application and therefore must be supplied
44 by the user.  The Geant4 toolkit does not provide a <tt>main()</tt> 
45 method, but a sample is provided here as a guide to the beginning
46 user.  Source listing 2.1.1 is the simplest example of <tt>main()</tt> 
47 required to build a simulation program.
48<p>
49<center>
50<table border=2 cellpadding=10>
51<tr>
52<td>
53<PRE>
54#include "G4RunManager.hh"
55#include "G4UImanager.hh"
56
57#include "ExN01DetectorConstruction.hh"
58#include "ExN01PhysicsList.hh"
59#include "ExN01PrimaryGeneratorAction.hh"
60
61int main()
62{
63  // construct the default run manager
64  G4RunManager* runManager = new G4RunManager;
65
66  // set mandatory initialization classes
67  runManager->SetUserInitialization(new ExN01DetectorConstruction);
68  runManager->SetUserInitialization(new ExN01PhysicsList);
69
70  // set mandatory user action class
71  runManager->SetUserAction(new ExN01PrimaryGeneratorAction);
72
73  // initialize G4 kernel
74  runManager->initialize();
75
76  // get the pointer to the UI manager and set verbosities
77  G4UImanager* UI = G4UImanager::GetUIpointer();
78  UI->ApplyCommand("/run/verbose 1");
79  UI->ApplyCommand("/event/verbose 1");
80  UI->ApplyCommand("/tracking/verbose 1");
81
82  // start a run
83  int numberOfEvent = 3;
84  runManager->BeamOn(numberOfEvent);
85
86  // job termination
87  delete runManager;
88  return 0;
89}
90</PRE>
91</td>
92</tr>
93<tr>
94<td align=center>
95 Source listing 2.1.1<BR>
96</td>
97</tr>
98</table></center>
99<p>
100 The <tt>main()</tt> method is implemented by two toolkit classes,
101 <i>G4RunManager</i> and <i>G4UImanager</i>, and three classes,
102 <i>ExN01DetectorConstruction</i>, <i>ExN01PhysicsList</i> and
103 <i>ExN01PrimaryGeneratorAction</i>, which are derived from toolkit
104 classes.  Each of these are explained in the following sections.
105
106<HR>
107<a name="2.1.2">
108<H2>2.1.2 <i>G4RunManager</i></H2></a>
109
110 The first thing <tt>main()</tt> must do is create an instance of
111 the <i>G4RunManager</i> class.  This is the only manager class in the Geant4
112 kernel which should be explicitly constructed in the user's
113 <tt>main()</tt>.  It controls the flow of the program and manages the event
114 loop(s) within a run.  When <i>G4RunManager</i> is created, the other major
115 manager classes are also created.  They are deleted automatically when
116 <i>G4RunManager</i> is deleted.  The run manager is also responsible
117 for managing initialization procedures, including methods in the user
118 initialization classes.  Through these the run manager must be given all
119 the information necessary to build and run the simulation, including
120 <OL>
121  <LI>how the detector should be constructed,
122  <LI>all the particles and all the physics processes to be simulated,
123  <LI>how the primary particle(s) in an event should be produced and
124  <LI>any additional requirements of the simulation.
125 </OL>
126 <p>
127 In the sample <tt>main()</tt> the lines
128 <pre>
129       runManager->SetUserInitialization(new ExN01DetectorConstruction);
130       runManager->SetUserInitialization(new ExN01PhysicsList);
131 </pre>
132 create objects which specify the detector geometry and physics processes,
133 respectively, and pass their pointers to the run manager.
134 <i>ExN01DetectorConstruction</i> is an example of a user initialization
135 class which is derived from <i>G4VUserDetectorConstruction</i>.  This is
136 where the user describes the entire detector setup, including
137 <UL>
138  <LI>its geometry,
139  <LI>the materials used in its construction,
140  <LI>a definition of its sensitive regions and
141  <LI>the readout schemes of the sensitive regions.
142 </UL>
143 
144 Similarly <i>ExN01PhysicsList</i> is derived from <i>G4VUserPhysicsList</i>
145 and requires the user to define
146 <UL>
147  <LI>the particles to be used in the simulation,
148  <LI>the range cuts for these particles and
149  <LI>all the physics processes to be simulated.
150 </UL>
151
152 The next instruction in <tt>main()</tt>
153 <pre>
154       runManager->SetUserAction(new ExN01PrimaryGeneratorAction);
155 </pre>
156 creates an instance of a particle generator and passes its pointer to the
157 run manager. 
158
159 <i>ExN01PrimaryGeneratorAction</i> is an example of a user action class
160 which is derived from <i>G4VUserPrimaryGeneratorAction</i>.  In this class
161 the user must describe the initial state of the primary event.  This class
162 has a public virtual method named <tt>generatePrimaries()</tt> which will
163 be invoked at the beginning of each event.  Details will be given in
164 <a href="eventDef.html">Section 2.6</a>.  Note that Geant4 does not provide
165 any default behavior for generating a primary event.
166 <p>
167 The next instruction
168 <pre>
169       runManager->initialize();
170 </pre>
171 performs the detector construction, creates the physics processes, calculates
172 cross sections and otherwise sets up the run.  The final run manager method
173 in <tt>main()</tt>
174 <pre>
175       int numberOfEvent = 3;
176       runManager->beamOn(numberOfEvent);
177 </pre>
178 begins a run of three sequentially processed events.  The <tt>beamOn()</tt>
179 method may be invoked any number of times within <tt>main()</tt> with each
180 invocation representing a separate run.  Once a run has begun neither the
181 detector setup nor the physics processes may be changed.  They may be
182 changed between runs, however, as described in
183 <a href="../Fundamentals/run.html#3.4.4">Section 3.4.4</a>.  More information
184 on <i>G4RunManager</i> in general is found in
185 <a href="../Fundamentals/run.html">Section 3.4</a>. 
186 <p>
187 As mentioned above, other manager classes are created when the run manager
188 is created.  One of these is the user interface manager, <i>G4UImanager</i>.
189 In <tt>main()</tt> a pointer to the interface manager must be obtained
190 <pre>
191      G4UImanager* UI = G4UImanager::getUIpointer();
192 </pre>
193 in order for the user to issue commands to the program.  In the present
194 example the <tt>applyCommand()</tt> method is called three times to
195 direct the program to print out information at the run, event and tracking
196 levels of simulation.  A wide range of commands is available which allows
197 the user detailed control of the simulation.  A list of these commands can
198 be found in <a href="../Control/commands.html">Section 7.1</a>.
199
200<HR>
201<a name="2.1.3">
202<H2>2.1.3 User Initialization and Action Classes</H2></a>
203
204<B>Mandatory User Classes</B>
205<P>
206 There are three classes which must be defined by the user.  Two of them
207 are user initialization classes, and the other is a user action class.
208 They must be derived from the abstract base classes provided by Geant4:
209 <i>G4VUserDetectorConstruction</i>, <i>G4VuserPhysicsList</i></h4> and
210 <i>G4VuserPrimaryGeneratorAction</i>.  Geant4 does not provide default
211 behavior for these classes.  <i>G4RunManager</i> checks for the existence
212 of these mandatory classes when the <tt>initialize()</tt> and
213 <tt>BeamOn()</tt> methods are invoked.</P> 
214<P>
215 As mentioned in the previous section, <i>G4VUserDetectorConstruction</i>
216 requires the user to define the detector and <i>G4VUserPhysicsList</i>
217 requires the user to define the physics.  Detector definition will be
218 discussed in Sections <a href="geometryDef.html">2.2</a> and
219 <a href="materialDef.html">2.3</a>.  Physics definition will be discussed
220 in Sections <a href="particleDef.html">2.4</a> and
221 <a href="physicsDef.html">2.5</a>.  The user action class
222 <i>G4VuserPrimaryGeneratorAction</i> requires that the initial event
223 state be defined.  Primary event generation will be discussed in
224 <a href="eventDef.html">Section 2.6</a>.
225<p>
226
227<B>Optional User Action Classes</B>
228<p>
229 Geant4 provides five user hook classes:
230<UL>
231 <LI><i>G4UserRunAction</i>
232 <LI><i>G4UserEventAction</i>
233 <LI><i>G4UserStackingAction</i>
234 <LI><i>G4UserTrackingAction</i>
235 <LI><i>G4UserSteppingAction</i>
236</UL>
237<P>
238 There are several virtual methods in each of these classes which allow the
239 specification of additional procedures at all levels of the simulation
240 application.  Details of the user initialization and action classes are
241 provided in <a href="../UserActions/index.html">Section 6</a>.
242
243<HR>
244<a name="2.1.4">
245<H2>2.1.4. <i>G4UImanager</i> and UI Command Submission</H2></a>
246
247 Geant4 provides a category named <b>intercoms</b>. <i>G4UImanager</i> 
248 is the manager class of this category. Using the functionalities of this
249 category, you can invoke <b>set</b> methods of class objects of which you
250 do not know the pointer. In Source listing 2.1.1, the verbosities of various
251 Geant4 manager classes are set. Detailed mechanism description and usage of
252 <b>intercoms</b> will be given in the next chapter, with a list of available
253 commands. Command submission can be done all through the application.
254<p>
255<center>
256<table border=2 cellpadding=10>
257<tr>
258<td>
259<PRE>
260#include "G4RunManager.hh"
261#include "G4UImanager.hh"
262<font color="#0000ff">#include "G4UIterminal.hh"</font>
263#include "G4VisExecutive.hh"
264
265#include "N02DetectorConstruction.hh"
266#include "N02PhysicsList.hh"
267#include "N02PrimaryGeneratorAction.hh"
268#include "N02RunAction.hh"
269#include "N02EventAction.hh"
270#include "N02SteppingAction.hh"
271
272#include "g4templates.hh"
273
274int main(int argc,char** argv)
275{
276  // construct the default run manager
277  G4RunManager * runManager = new G4RunManager;
278
279  // set mandatory initialization classes
280  N02DetectorConstruction* detector = new N02DetectorConstruction;
281  runManager->SetUserInitialization(detector);
282  runManager->SetUserInitialization(new N02PhysicsList);
283 
284  // visualization manager
285  G4VisManager* visManager = new G4VisExecutive;
286  visManager->initialize();
287   
288  // set user action classes
289  runManager->SetUserAction(new N02PrimaryGeneratorAction(detector));
290  runManager->SetUserAction(new N02RunAction);
291  runManager->SetUserAction(new N02EventAction);
292  runManager->SetUserAction(new N02SteppingAction);
293   
294  // get the pointer to the User Interface manager
295  G4UImanager* UI = G4UImanager::GetUIpointer();
296
297<font color="#0000ff">  if(argc==1)
298  // Define (G)UI terminal for interactive mode
299  {
300    G4UIsession * session = new G4UIterminal;
301    UI->ApplyCommand("/control/execute prerun.g4mac");
302    session->sessionStart();
303    delete session;
304  }
305  else
306  // Batch mode
307  {
308    G4String command = "/control/execute ";
309    G4String fileName = argv[1];
310    UI->ApplyCommand(command+fileName);
311  }</font>
312
313  // job termination
314  delete visManager;
315  delete runManager;
316
317  return 0;
318}
319</pre>
320</td>
321</tr>
322<tr>
323<td align=center>
324 Source list 2.1.2<br>
325 An example of <tt>main()</tt> using interactive
326 terminal and visualization. Code modified from 2.1.1. are shown in blue.
327</td>
328</tr>
329</table></center>
330<p>
331
332<HR>
333<a name="2.1.5">
334<H2>2.1.5 <i>G4cout</i> and <i>G4cerr</i></H2></a>
335
336Although not yet included in the above examples, output streams will be
337needed.  <i>G4cout</i> and <i>G4cerr</i> are <b>iostream</b> objects defined
338by Geant4.  The usage of these objects is exactly the same as the ordinary
339<i>cout</i> and <i>cerr</i>, except that the output streams will be handled by
340<i>G4UImanager</i>.  Thus, output strings may be displayed on another window
341or stored in a file.  Manipulation of these output streams will be described
342in <a href="../Control/userInterfaceCommand.html#7.2.4">Section 7.2.4</a>. 
343These objects should be used instead of the ordinary <i>cout</i> and
344<i>cerr</i>.
345<P>
346<HR>
347<A HREF="../../../../Authors/html/subjectsToAuthors.html">
348<I>About the authors</I></A>
349</BODY>
350</HTML>
Note: See TracBrowser for help on using the repository browser.