source: trunk/Documentation/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch02.html@ 901

Last change on this file since 901 was 901, checked in by garnier, 17 years ago

Add Geant4 Documentation at 8.12.2008

File size: 18.1 KB
Line 
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 2.  Getting Started with Geant4 - Running a Simple Example</title><link rel="stylesheet" href="../xml/XSLCustomizationLayer/G4HTMLStylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="Geant4 User's Guide for Application Developers"><link rel="up" href="index.html" title="Geant4 User's Guide for Application Developers"><link rel="prev" href="ch01s02.html" title="1.2.  How to use this manual"><link rel="next" href="ch02s02.html" title="2.2.  How to Define a Detector Geometry"><script language="JavaScript">
2function remote_win(fName)
3{
4 var url = "AllResources/Detector/geometry.src/" + fName;
5 RemoteWin=window.open(url,"","resizable=no,toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=0,copyhistory=0,width=520,height=520")
6 RemoteWin.creator=self
7}
8</script></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. 
9Getting Started with Geant4 - Running a Simple Example
10</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01s02.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch02s02.html"><img src="AllResources/IconsGIF/next.gif" alt="Next"></a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chap.GettingStarted"></a>Chapter 2. 
11Getting Started with Geant4 - Running a Simple Example
12</h2></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect.HowToDefMain"></a>2.1. 
13How to Define the main() Program
14</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.HowToDefMain.SimpleMainMethod"></a>2.1.1. 
15A Sample <code class="literal">main()</code> Method
16</h3></div></div></div><p>
17The contents of <code class="literal">main()</code> will vary according to the
18needs of a given simulation application and therefore must be supplied
19by the user. The Geant4 toolkit does not provide a <code class="literal">main()</code>
20method, but a sample is provided here as a guide to the beginning
21user. <a href="ch02.html#programlist_HowToDefMain_1" title="Example 2.1. 
22Simplest example of main()
23">Example 2.1</a> is the simplest example of
24<code class="literal">main()</code> required to build a simulation program.
25</p><div class="example"><a name="programlist_HowToDefMain_1"></a><p class="title"><b>Example 2.1. 
26Simplest example of <code class="literal">main()</code>
27</b></p><div class="example-contents"><pre class="programlisting">
28 #include "G4RunManager.hh"
29 #include "G4UImanager.hh"
30
31 #include "ExN01DetectorConstruction.hh"
32 #include "ExN01PhysicsList.hh"
33 #include "ExN01PrimaryGeneratorAction.hh"
34
35 int main()
36 {
37 // construct the default run manager
38 G4RunManager* runManager = new G4RunManager;
39
40 // set mandatory initialization classes
41 runManager-&gt;SetUserInitialization(new ExN01DetectorConstruction);
42 runManager-&gt;SetUserInitialization(new ExN01PhysicsList);
43
44 // set mandatory user action class
45 runManager-&gt;SetUserAction(new ExN01PrimaryGeneratorAction);
46
47 // initialize G4 kernel
48 runManager-&gt;initialize();
49
50 // get the pointer to the UI manager and set verbosities
51 G4UImanager* UI = G4UImanager::GetUIpointer();
52 UI-&gt;ApplyCommand("/run/verbose 1");
53 UI-&gt;ApplyCommand("/event/verbose 1");
54 UI-&gt;ApplyCommand("/tracking/verbose 1");
55
56 // start a run
57 int numberOfEvent = 3;
58 runManager-&gt;BeamOn(numberOfEvent);
59
60 // job termination
61 delete runManager;
62 return 0;
63 }
64</pre></div></div><br class="example-break"><p>
65The <code class="literal">main()</code> method is implemented by two toolkit
66classes, <span class="emphasis"><em>G4RunManager</em></span> and <span class="emphasis"><em>G4UImanager</em></span>,
67and three classes, <span class="emphasis"><em>ExN01DetectorConstruction</em></span>,
68<span class="emphasis"><em>ExN01PhysicsList</em></span> and
69<span class="emphasis"><em>ExN01PrimaryGeneratorAction</em></span>, which are derived from
70toolkit classes. Each of these are explained in the following sections.
71</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.HowToDefMain.G4RunManager"></a>2.1.2. 
72<span class="emphasis"><em>G4RunManager</em></span>
73</h3></div></div></div><p>
74The first thing <code class="literal">main()</code> must do is create an instance of
75the <span class="emphasis"><em>G4RunManager</em></span> class. This is the only manager class in
76the Geant4 kernel which should be explicitly constructed in the
77user's <code class="literal">main()</code>. It controls the flow of the program and
78manages the event loop(s) within a run. When <span class="emphasis"><em>G4RunManager</em></span> is
79created, the other major manager classes are also created. They are
80deleted automatically when <span class="emphasis"><em>G4RunManager</em></span> is deleted. The run
81manager is also responsible for managing initialization procedures,
82including methods in the user initialization classes. Through these
83the run manager must be given all the information necessary to
84build and run the simulation, including
85</p><div class="orderedlist"><ol type="1" compact><li><p>
86 how the detector should be constructed,
87 </p></li><li><p>
88 all the particles and all the physics processes to be
89 simulated,
90 </p></li><li><p>
91 how the primary particle(s) in an event should be produced
92 and
93 </p></li><li><p>
94 any additional requirements of the simulation.</p></li></ol></div><p>
95In the sample <code class="literal">main()</code> the lines
96
97</p><div class="informalexample"><pre class="programlisting">
98 runManager-&gt;SetUserInitialization(new ExN01DetectorConstruction);
99 runManager-&gt;SetUserInitialization(new ExN01PhysicsList);
100</pre></div><p>
101
102create objects which specify the detector geometry and physics
103processes, respectively, and pass their pointers to the run
104manager. <span class="emphasis"><em>ExN01DetectorConstruction</em></span> is an example of a user
105initialization class which is derived from
106<span class="emphasis"><em>G4VUserDetectorConstruction</em></span>. This is where the user
107describes the entire detector setup, including
108</p><div class="itemizedlist"><ul type="disc" compact><li><p>
109 its geometry,
110 </p></li><li><p>
111 the materials used in its construction,
112 </p></li><li><p>
113 a definition of its sensitive regions and
114 </p></li><li><p>
115 the readout schemes of the sensitive regions.
116 </p></li></ul></div><p>
117Similarly <span class="emphasis"><em>ExN01PhysicsList</em></span> is derived from
118<span class="emphasis"><em>G4VUserPhysicsList</em></span> and requires the user to define
119</p><div class="itemizedlist"><ul type="disc" compact><li><p>
120 the particles to be used in the simulation,
121 </p></li><li><p>
122 the range cuts for these particles and
123 </p></li><li><p>
124 all the physics processes to be simulated.
125 </p></li></ul></div><p>
126The next instruction in <code class="literal">main()</code>
127
128</p><div class="informalexample"><pre class="programlisting">
129 runManager-&gt;SetUserAction(new ExN01PrimaryGeneratorAction);
130</pre></div><p>
131
132creates an instance of a particle generator and passes its pointer
133to the run manager. <span class="emphasis"><em>ExN01PrimaryGeneratorAction</em></span> is an
134example of a user action class which is derived from
135<span class="emphasis"><em>G4VUserPrimaryGeneratorAction</em></span>. In this class the user must
136describe the initial state of the primary event. This class has a
137public virtual method named <code class="literal">generatePrimaries()</code> which will
138be invoked at the beginning of each event. Details will be given in
139<a href="ch02s06.html" title="2.6. 
140How to Generate a Primary Event
141">Section 2.6</a>.
142Note that Geant4 does not provide any default behavior for generating a primary event.
143</p><p>
144The next instruction
145
146</p><div class="informalexample"><pre class="programlisting">
147 runManager-&gt;initialize();
148</pre></div><p>
149
150performs the detector construction, creates the physics processes,
151calculates cross sections and otherwise sets up the run. The final
152run manager method in <code class="literal">main()</code>
153
154</p><div class="informalexample"><pre class="programlisting">
155 int numberOfEvent = 3;
156 runManager-&gt;beamOn(numberOfEvent);
157</pre></div><p>
158
159begins a run of three sequentially processed events. The
160<code class="literal">beamOn()</code> method may be invoked any number of times within
161<code class="literal">main()</code> with each invocation representing a separate run.
162Once a run has begun neither the detector setup nor the physics
163processes may be changed. They may be changed between runs,
164however, as described in <a href="ch03s04.html#sect.Run.Custom" title="3.4.4. 
165Customizing the Run Manager
166">Section 3.4.4</a>.
167More information on <span class="emphasis"><em>G4RunManager</em></span> in general is found in
168<a href="ch03s04.html" title="3.4. 
169Run
170">Section 3.4</a>.
171</p><p>
172As mentioned above, other manager classes are created when the
173run manager is created. One of these is the user interface manager,
174<span class="emphasis"><em>G4UImanager</em></span>. In <code class="literal">main()</code> a pointer to
175the interface manager must be obtained
176
177</p><div class="informalexample"><pre class="programlisting">
178 G4UImanager* UI = G4UImanager::getUIpointer();
179</pre></div><p>
180
181in order for the user to issue commands to the program. In the
182present example the <code class="literal">applyCommand()</code> method is called three
183times to direct the program to print out information at the run,
184event and tracking levels of simulation. A wide range of commands
185is available which allows the user detailed control of the
186simulation. A list of these commands can be found in
187<a href="ch07.html#sect.BuiltinCom" title="7.1. 
188Built-in Commands
189">Section 7.1</a>.
190</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.HowToDefMain.UserInitAction"></a>2.1.3. 
191User Initialization and Action Classes
192</h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.HowToDefMain.UserInitAction.MandatoryUserClasses"></a>2.1.3.1. 
193Mandatory User Classes
194</h4></div></div></div><p>
195There are three classes which must be defined by the user. Two
196of them are user initialization classes, and the other is a user
197action class. They must be derived from the abstract base classes
198provided by Geant4: <span class="emphasis"><em>G4VUserDetectorConstruction</em></span>,
199<span class="emphasis"><em>G4VuserPhysicsList</em></span> and
200<span class="emphasis"><em>G4VuserPrimaryGeneratorAction</em></span>.
201Geant4 does not provide default behavior for these classes.
202<span class="emphasis"><em>G4RunManager</em></span> checks for the existence of these mandatory
203classes when the <code class="literal">initialize()</code> and <code class="literal">BeamOn()</code>
204methods are invoked.
205</p><p>
206As mentioned in the previous section,
207<span class="emphasis"><em>G4VUserDetectorConstruction</em></span> requires the user to define the
208detector and <span class="emphasis"><em>G4VUserPhysicsList</em></span> requires the user to define
209the physics. Detector definition will be discussed in Sections
210</p><p>
211<a href="ch02s02.html" title="2.2. 
212How to Define a Detector Geometry
213">Section 2.2</a> and
214<a href="ch02s03.html" title="2.3. 
215How to Specify Materials in the Detector
216">Section 2.3</a>.
217Physics definition will be discussed in Sections
218<a href="ch02s04.html" title="2.4. 
219How to Specify Particles
220">Section 2.4</a>
221and
222<a href="ch02s05.html" title="2.5. 
223How to Specify Physics Processes
224">Section 2.5</a>.
225The user action <span class="emphasis"><em>G4VuserPrimaryGeneratorAction</em></span>
226requires that the initial event state be defined. Primary event generation will
227be discussed in
228<a href="ch02s07.html" title="2.7. 
229How to Make an Executable Program
230">Section 2.7</a>.
231</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.HowToDefMain.UserInitAction.OptionalUserAction"></a>2.1.3.2. 
232Optional User Action Classes
233</h4></div></div></div><p>
234Geant4 provides five user hook classes:
235</p><div class="itemizedlist"><ul type="disc" compact><li><p>
236 <span class="emphasis"><em>G4UserRunAction</em></span>
237 </p></li><li><p>
238 <span class="emphasis"><em>G4UserEventAction</em></span>
239 </p></li><li><p>
240 <span class="emphasis"><em>G4UserStackingAction</em></span>
241 </p></li><li><p>
242 <span class="emphasis"><em>G4UserTrackingAction</em></span>
243 </p></li><li><p>
244 <span class="emphasis"><em>G4UserSteppingAction</em></span>
245 </p></li></ul></div><p>
246There are several virtual methods in each of these classes which
247allow the specification of additional procedures at all levels of
248the simulation application. Details of the user initialization and
249action classes are provided in
250<a href="ch06.html" title="Chapter 6. 
251User Actions
252">Chapter 6</a>.
253</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.HowToDefMain.G4UImanagerUICommand"></a>2.1.4. 
254<span class="emphasis"><em>G4UImanager</em></span> and UI CommandSubmission
255</h3></div></div></div><p>
256Geant4 provides a category named <span class="bold"><strong>intercoms</strong></span>.
257<span class="emphasis"><em>G4UImanager</em></span> is the manager class of this category. Using the
258functionalities of this category, you can invoke
259<span class="bold"><strong>set</strong></span> methods
260of class objects of which you do not know the pointer.
261In <a href="ch02.html#programlist_HowToDefMain_2" title="Example 2.2. 
262An example of main() using interactive
263terminal and visualization. Code modified from the previous
264example are shown in blue.
265">Example 2.2</a>,
266the verbosities of various Geant4 manager classes
267are set. Detailed mechanism description and usage of
268<span class="bold"><strong>intercoms</strong></span> will be given in the next chapter,
269with a list of available commands. Command submission can be done all through the
270application.
271</p><div class="example"><a name="programlist_HowToDefMain_2"></a><p class="title"><b>Example 2.2. 
272An example of <code class="literal">main()</code> using interactive
273terminal and visualization. Code modified from the previous
274example are shown in <span class="color_blue">blue</span>.
275</b></p><div class="example-contents"><pre class="programlisting">
276 #include "G4RunManager.hh"
277 #include "G4UImanager.hh"
278 <span class="color_blue">#include "G4UIterminal.hh"</span>
279 #include "G4VisExecutive.hh"
280
281 #include "N02DetectorConstruction.hh"
282 #include "N02PhysicsList.hh"
283 #include "N02PrimaryGeneratorAction.hh"
284 #include "N02RunAction.hh"
285 #include "N02EventAction.hh"
286 #include "N02SteppingAction.hh"
287
288 #include "g4templates.hh"
289
290 int main(int argc,char** argv)
291 {
292 // construct the default run manager
293 G4RunManager * runManager = new G4RunManager;
294
295 // set mandatory initialization classes
296 N02DetectorConstruction* detector = new N02DetectorConstruction;
297 runManager-&gt;SetUserInitialization(detector);
298 runManager-&gt;SetUserInitialization(new N02PhysicsList);
299
300 // visualization manager
301 G4VisManager* visManager = new G4VisExecutive;
302 visManager-&gt;initialize();
303
304 // set user action classes
305 runManager-&gt;SetUserAction(new N02PrimaryGeneratorAction(detector));
306 runManager-&gt;SetUserAction(new N02RunAction);
307 runManager-&gt;SetUserAction(new N02EventAction);
308 runManager-&gt;SetUserAction(new N02SteppingAction);
309
310 // get the pointer to the User Interface manager
311 G4UImanager* UI = G4UImanager::GetUIpointer();
312
313 <span class="color_blue">
314 if(argc==1)
315 // Define (G)UI terminal for interactive mode
316 {
317 G4UIsession * session = new G4UIterminal;
318 UI-&gt;ApplyCommand("/control/execute prerun.g4mac");
319 session-&gt;sessionStart();
320 delete session;
321 }
322 else
323 // Batch mode
324 {
325 G4String command = "/control/execute ";
326 G4String fileName = argv[1];
327 UI-&gt;ApplyCommand(command+fileName);
328 }
329</span>
330
331 // job termination
332 delete visManager;
333 delete runManager;
334
335 return 0;
336 }
337</pre></div></div><br class="example-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.HowToDefMain.G4coutG4cerr"></a>2.1.5. 
338<span class="emphasis"><em>G4cout</em></span> and <span class="emphasis"><em>G4cerr</em></span>
339</h3></div></div></div><p>
340Although not yet included in the above examples, output streams
341will be needed. <span class="emphasis"><em>G4cout</em></span> and <span class="emphasis"><em>G4cerr</em></span>
342are <span class="bold"><strong>iostream</strong></span>
343objects defined by Geant4. The usage of these objects is exactly
344the same as the ordinary <span class="emphasis"><em>cout</em></span> and
345<span class="emphasis"><em>cerr</em></span>,
346except that the output streams will be handled by
347<span class="emphasis"><em>G4UImanager</em></span>.
348Thus, output strings may be displayed on another window or stored in a
349file. Manipulation of these output streams will be described in
350<a href="ch07s02.html#sect.UIDefNew.HowCont" title="7.2.4. 
351How to control the output of G4cout/G4cerr
352">Section 7.2.4</a>.
353These objects should be used instead of the ordinary
354<span class="emphasis"><em>cout</em></span> and <span class="emphasis"><em>cerr</em></span>.
355</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s02.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch02s02.html"><img src="AllResources/IconsGIF/next.gif" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">1.2. 
356How to use this manual
357 </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="AllResources/IconsGIF/home.gif" alt="Home"></a></td><td width="40%" align="right" valign="top"> 2.2. 
358How to Define a Detector Geometry
359</td></tr></table></div></body></html>
Note: See TracBrowser for help on using the repository browser.