source: trunk/documents/UserDoc/UsersGuides/ForApplicationDeveloper/html/Fundamentals/run.html@ 1217

Last change on this file since 1217 was 1208, checked in by garnier, 16 years ago

CVS update
File size: 18.5 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2<HTML>
3<HEAD>
4<TITLE></TITLE>
5<!-- Changed by: Dennis Wright, 29-Nov-2001 -->
6<META NAME="GENERATOR" CONTENT="Mozilla/3.0Gold (X11; I; OSF1 V4.0 alpha) [Netscape]">
7</HEAD>
8<BODY>
9
10<!-- Changed by: Katsuya Amako, 9-Jul-1998 -->
11<!-- Changed by: Katsuya Amako, 30-Nov-1998 -->
12<!-- Proof read by: Joe Chuma, 28-Jun-1999 -->
13
14<TABLE WIDTH="100%" >
15<TR>
16<TD>
17
18</A>
19<A HREF="index.html">
20<IMG SRC="../../../../resources/html/IconsGIF/Contents.gif" ALT="Contents" HEIGHT=16 WIDTH=59></A>
21<A HREF="unitSystem.html">
22<IMG SRC="../../../../resources/html/IconsGIF/Previous.gif" ALT="Previous" HEIGHT=16 WIDTH=59></A>
23<A HREF="event.html">
24<IMG SRC="../../../../resources/html/IconsGIF/Next.gif" ALT="Next" HEIGHT=16 WIDTH=59></A>
25</TD>
26
27<TD ALIGN="Right"><FONT COLOR="#238E23"><FONT SIZE=-1>
28<B>Geant4 User's Guide</B>
29<BR>
30<B>For Application Developers</B> <BR>
31<B>Toolkit Fundamentals</B> </FONT></FONT> </TD>
32</TR>
33</TABLE>
34<P><BR>
35
36<CENTER><P><FONT COLOR="#238E23"><FONT SIZE=+3>
37<B>3.4 Run</B> </FONT></FONT>
38</CENTER>
39<BR><BR>
40
41<HR ALIGN="Center" SIZE="7%">
42<P>
43
44<a name="3.4.1">
45<H2>3.4.1 Basic concept of <i>Run</i></H2></a>
46
47 In Geant4, <i>Run</i> is the largest unit of simulation. A run consists of a sequence
48 of events. Within a run, the detector geometry, the set up of sensitive detectors,
49 and the physics processes used in the simulation should be kept unchanged. A run is
50 represented by a <i>G4Run</i> class object. A run starts with <tt>BeamOn()</tt> method
51 of <i>G4RunManager</i>.
52<p>
53<b>Representation of a run</b>
54<p>
55 <i>G4Run</i> represents a run. It has a run identification number, which should be set
56 by the user, and the number of events simulated during the run. Please note that the
57 run identification number is not used by the Geant4 kernel, and thus can be arbitrarily
58 assigned at the user's convenience.
59 <p>
60 <i>G4Run</i> has pointers to the tables <i>G4VHitsCollection</i> and
61 <i>G4VDigiCollection</i>. These tables are associated in case
62 <i>sensitive detectors</i> and <i>digitizer modules</i> are simulated,
63 respectively. The usage of these tables will be mentioned in Sections
64 <a href="../Detector/hit.html">4.4</a> and
65 <a href="../Detector/digitization.html">4.5</a>.
66<p>
67<b>Manage the run procedures</b>
68<p>
69 <i>G4RunManager</i> manages the procedures of a run. In the
70 constructor of <i>G4RunManager</i>, all of the manager classes
71 in Geant4 kernel, except for some static managers, are constructed.
72 These managers are deleted in the destructor of <i>G4RunManager</i>.
73 <i>G4RunManager</i> must be a singleton, and the pointer to this
74 singleton object can be obtained by the <tt>getRunManager()</tt>
75 static method.
76 <p>
77 As already mentioned in
78 <a href="../GettingStarted/mainProgram.html">Section 2.1</a>,
79 all of the <i>user initialization</i> classes and <i>user action</i> classes
80 defined by the user should be assigned to <i>G4RunManager</i> before starting
81 initialization of the Geant4 kernel. The assignments of these user classes
82 are done by <tt>SetUserInitialization()</tt> and
83 <tt>SetUserAction()</tt> methods. All user classes defined by the Geant4
84 kernel will be summarized in
85 <a href="../UserActions/index.html">Section 6</a>.
86 <p>
87 <i>G4RunManager</i> has several public methods, which are listed below.
88 <dl>
89 <dl>
90 <dt><tt>Initialize()</tt>
91 <dd>All initializations required by the Geant4 kernel are triggered by
92 this method. Initializations are:
93 <ul>
94 <li>construction of the detector geometry and set up of sensitive
95 detectors and/or digitizer modules,
96 <li>construction of particles and physics processes,
97 <li>calculation of cross-section tables.
98 </ul>
99 This method is thus mandatory before proceeding to the first
100 run. This method will be invoked automatically for the
101 second and later runs in case some of the initialized quantities
102 need to be updated.
103 <p>
104 <dt><tt>BeamOn(G4int numberOfEvent)</tt>
105 <dd>This method triggers the actual simulation of a run, that is,
106 an event loop. It takes an integer argument which represents
107 the number of events to be simulated.
108 <p>
109 <dt><tt>GetRunManager()</tt>
110 <dd>This static method returns the pointer to the <i>G4RunManager</i>
111 singleton object.
112 <p>
113 <dt><tt>GetCurrentEvent()</tt>
114 <dd>This method returns the pointer to the <i>G4Event</i> object which is
115 currently being simulated. This method is available only when an event
116 is being processed. At this moment, the application state of Geant4,
117 which is explained in the following sub-section, is <i>"EventProc"</i>.
118 When Geant4 is in a state other than <i>"EventProc"</I>, this
119 method returns <tt>null</tt>. Please note that the return value of
120 this method is <tt>const G4Event *</tt> and thus you cannot modify
121 the contents of the object.
122 <p>
123 <dt><tt>SetNumberOfEventsToBeStored(G4int nPrevious)</tt>
124 <dd>When simulating the "pile up" of more than one event, it is essential
125 to access more than one event at the same moment. By invoking this method,
126 <i>G4RunManager</i> keeps
127 <tt>nPrevious G4Event</tt> objects. This method must be invoked
128 before proceeding to <tt>BeamOn()</tt>.
129 <p>
130 <dt><tt>GetPreviousEvent(G4int i_thPrevious)</tt>
131 <dd>The pointer to the <tt>i_thPrevious G4Event</tt> object can be
132 obtained through this method. A pointer to a <tt>const</tt> object
133 is returned. It is inevitable that <tt>i_thPrevious</tt> events
134 must have already been simulated in the same run for getting
135 the <tt>i_thPrevious</tt> event. Otherwise, this method returns
136 <tt>null</tt>.
137 <p>
138 <dt><tt>AbortRun()</tt>
139 <dd>This method should be invoked whenever the processing of a run
140 must be stopped. It is valid for <i>GeomClosed</i> and <i>EventProc</i>
141 states. Run processing will be safely aborted even in the midst of
142 processing an event. However, the last event of the aborted run will
143 be incomplete and should not be used for further analysis.
144 </dl>
145</dl>
146<p>
147<b><i>G4UserRunAction</i></b>
148<p>
149 <i>G4UserRunAction</i> is one of the <i>user action</i> classes
150 from which you can derive your own concrete class. This base class has
151 two virtual methods, as follows:
152 <dl><dd>
153 <dl>
154 <dt><tt>BeginOfRunAction()</tt>
155 <dd>This method is invoked at the beginning of the <tt>BeamOn()</tt>
156 method but after confirmation of the conditions of the Geant4 kernel.
157 Likely uses of this method include:
158 <ul>
159 <li>setting a run identification number,
160 <li>booking histograms,
161 <li>setting run specific conditions of the sensitive detectors
162 and/or digitizer modules (e.g., dead channels).
163 </ul>
164 <p>
165 <dt><tt>EndOfRunAction()</tt> method
166 <dd>This method is invoked at the very end of the <tt>BeamOn()</tt>
167 method. Typical use cases of this method are
168 <ul>
169 <li>store/print histograms,
170 <li>manipulate run summaries.
171 </ul>
172 </dl></dl>
173 <p>
174
175<HR>
176<a name="3.4.2">
177<H2>3.4.2 Geant4 as a state machine</H2></a>
178
179 Geant4 is designed as a state machine. Some methods in Geant4
180 are available for only a certain state(s). <i>G4RunManager</i>
181 controls the state changes of the Geant4 application. States of Geant4
182 are represented by the enumeration <i>G4ApplicationState</i>.
183 It has six states through the life cycle of a Geant4 application.
184 <dl><dl>
185 <dt><i>G4State_PreInit</i> state
186 <dd>A Geant4 application starts with this state. The application needs
187 to be initialized when it is in this state. The application
188 occasionally comes back to this state if geometry, physics processes,
189 and/or cut-off have been changed after processing a run.
190 <p>
191 <dt><i>G4State_Init</i> state
192 <dd>The application is in this state while the <tt>Initialize()</tt> method
193 of <i>G4RunManager</i> is being invoked. Methods defined in
194 any <i>user initialization</i> classes are invoked during this state.
195 <p>
196 <dt><i>G4State_Idle</i> state
197 <dd>The application is ready for starting a run.
198 <p>
199 <dt><i>G4State_GeomClosed</i> state
200 <dd>When <tt>BeamOn()</tt> is invoked, the application proceeds to
201 this state to process a run. Geometry, physics processes, and
202 cut-off cannot be changed during run processing.
203 <p>
204 <dt><i>G4State_EventProc</i> state
205 <dd>A Geant4 application is in this state when a particular event
206 is being processed. <tt>GetCurrentEvent()</tt> and
207 <tt>GetPreviousEvent()</tt> methods of <i>G4RunManager</i> are
208 available only at this state.
209 <p>
210 <dt><i>G4State_Quit</i> state
211 <dd>When the destructor of <i>G4RunManager</i> is invoked,
212 the application comes to this "dead end" state. Managers of
213 the Geant4 kernel are being deleted and thus the application cannot
214 come back to any other state.
215 <p>
216 <dt><i>G4State_Abort</i> state
217 <dd>When a <i>G4Exception</i> occurs,
218 the application comes to this "dead end" state and causes a core dump.
219 The user still has a hook to do some "safe" opperations, e.g. storing
220 histograms, by implementing a user concrete class of <i>G4VStateDependent</i>.
221 The user also has a choice to suppress the occurence of <i>G4Exception</i>
222 by a UI command <i>/control/suppressAbortion</i>.
223 When abortion is suppressed, you will still get error messages issued by G4Exception,
224 and there is NO guarantee of a correct result after the G4Exception error message.
225 <p>
226 </dl></dl>
227<i>G4StateManager</i> belongs to the <i>intercoms</i> category.
228<p>
229
230
231<HR>
232<a name="3.4.3">
233<H2>3.4.3 User's hook for state change</H2></a>
234
235In case the user wants to do something at the moment of state change
236of Geant4, the user can create a concrete class of the <i>G4VStateDependent</i>
237base class. For example, the user can store histograms when G4Exception
238occurs and Geant4 comes to the <i>Abort</i> state, but before the actual
239core dump.
240<p>
241The following is an example user code which stores histograms when
242Geant4 becomes to the <i>Abort</i> state. This class object should be
243mabe in, for example <i>main()</i>, by the user code. This object will
244be automatically registered to <i>G4StateManager</i> at its construction.
245<p>
246<center>
247<table border=2 cellpadding=10>
248<tr>
249<td>
250<PRE>
251
252#ifndef UserHookForAbortState_H
253#define UserHookForAbortState_H 1
254
255#include "G4VStateDependent.hh"
256
257class UserHookForAbortState : public G4VStateDependent
258{
259 public:
260 UserHookForAbortState(); // constructor
261 ~UserHookForAbortState(); // destructor
262
263 virtual G4bool Notify(G4ApplicationState requiredState);
264};
265
266#endif
267</PRE>
268</td>
269</tr>
270<tr>
271<td align=center>
272 Source listing 3.4.3.1<BR>
273Header file of UserHookForAbortState
274</td>
275</tr>
276</table></center>
277<p>
278<center>
279<table border=2 cellpadding=10>
280<tr>
281<td>
282<PRE>
283
284#include "UserHookForAbortState.hh"
285
286UserHookForAbortState::UserHookForAbortState() {;}
287UserHookForAbortState::~UserHookForAbortState() {;}
288
289G4bool UserHookForAbortState::Notify(G4ApplicationState requiredState)
290{
291 if(requiredState!=Abort) return true;
292
293 // Do book keeping here
294
295 return true;
296}
297</PRE>
298</td>
299</tr>
300<tr>
301<td align=center>
302 Source listing 3.4.3.2<BR>
303Source file of UserHookForAbortState
304</td>
305</tr>
306</table></center>
307<p>
308<p>
309<HR>
310<a name="3.4.4">
311<H2>3.4.4 Customizing the Run Manager</H2></a>
312
313<b>Virtual Methods in the Run Manager</b>
314<p>
315 <tt>G4RunManager</tt> is a concrete class with a complete set of
316 functionalities for managing the Geant4 kernel. It is the only manager
317 class in the Geant4 kernel which must be constructed in the
318 <tt>main()</tt> method of the user's application. Thus, instead of
319 constructing the <tt>G4RunManager</tt> provided by Geant4, you are free
320 to construct your own <tt>RunManager</tt>. It is recommended, however,
321 that your <tt>RunManager</tt> inherit <tt>G4RunManager</tt>. For this
322 purpose, <tt>G4RunManager</tt> has various virtual methods which provide
323 all the functionalities required to handle the Geant4 kernel. Hence,
324 your customized run manager need only override the methods particular to
325 your needs; the remaining methods in <tt>G4RunManager</tt> base class
326 can still be used.
327 A summary of the available methods is presented here:
328
329 <dl><dl>
330 <dt><tt>public: virtual void Initialize();</tt>
331 <dd>main entry point of Geant4 kernel initialization<p>
332 <dt><tt>protected: virtual void InitializeGeometry();</tt>
333 <dd>geometry construction<p>
334 <dt><tt>protected: virtual void InitializePhysics();</tt>
335 <dd>physics processes construction<p>
336 <dt><tt>public: virtual void BeamOn(G4int n_event);</tt>
337 <dd>main entry point of the event loop<p>
338 <dt><tt>protected: virtual G4bool ConfirmBeamOnCondition();</tt>
339 <dd>check the kernel conditions for the event loop<p>
340 <dt><tt>protected: virtual void RunInitialization();</tt>
341 <dd>prepare a run<p>
342 <dt><tt>protected: virtual void DoEventLoop(G4int n_events);</tt>
343 <dd>manage an event loop<p>
344 <dt><tt>protected: virtual G4Event* GenerateEvent(G4int i_event);</tt>
345 <dd>generation of <i>G4Event</i> object<p>
346 <dt><tt>protected: virtual void AnalyzeEvent(G4Event* anEvent);</tt>
347 <dd>storage/analysis of an event<p>
348 <dt><tt>protected: virtual void RunTermination();</tt>
349 <dd>terminate a run<p><p>
350 <dt><tt>public: virtual void DefineWorldVolume(G4VPhysicalVolume * worldVol);</tt>
351 <dd>set the world volume to <i>G4Navigator</i><p>
352 <dt><tt>public: virtual void AbortRun();</tt>
353 <dd>abort the run
354 </dl></dl>
355<p>
356<b>Customizing the Event Loop</b>
357<p>
358 In <tt>G4RunManager</tt> the event loop is handled by the virtual method
359 <tt>DoEventLoop()</tt>. This method is implemented by a <tt>for</tt> loop
360 consisting of the following steps:
361 <ol>
362 <li>construct a <tt>G4Event</tt> object and assign to it primary vertex(es)
363 and primary particles. This is done by the virtual
364 <tt>GeneratePrimaryEvent()</tt> method.
365 <li>send the <tt>G4Event</tt> object to <tt>G4EventManager</tt> for the
366 detector simulation. <i>Hits</i> and <i>trajectories</i> will be
367 associated with the <tt>G4Event</tt> object as a consequence.
368 <li>perform bookkeeping for the current <tt>G4Event</tt> object. This is
369 done by the virtual <tt>AnalyzeEvent()</tt> method.
370 </ol>
371 <p>
372 <tt>DoEventLoop()</tt> performs the entire simulation of an event. However,
373 it is often useful to split the above three steps into isolated
374 application programs. If, for example, you wish to examine the effects of
375 changing discriminator thresholds, ADC gate widths and/or trigger conditions
376 on simulated events, much time can be saved by performing steps 1 and 2 in
377 one program and step 3 in another. The first program need only generate the
378 hit/trajectory information once and store it, perhaps in a database. The
379 second program could then retrieve the stored <tt>G4Event</tt> objects and
380 perform the digitization (analysis) using the above threshold, gate and
381 trigger settings. These settings could then be changed and the digitization
382 program re-run without re-generating the <tt>G4Event</tt>s.
383
384 <p>
385<b>Changing the Detector Geometry</b>
386<p>
387 The detector geometry defined in your <i>G4VUserDetectorConstruction</i>
388 concrete class can be changed during a run break (between two runs).
389 Two different cases are considered.
390 <p>
391 The first is the case in which you want to delete the entire
392 structure of your old geometry and build up a completely new set of
393 volumes. For this case, you need to set the new world physical
394 volume pointer to the <i>RunManager</i>. Thus, you should proceed in
395 the following way.
396<pre>
397 G4RunManager* runManager = G4RunManager::GetRunManager();
398 runManager->DefineWorldVolume( newWorldPhys );
399</pre>
400 Presumably this case is rather rare. The second case is more
401 frequent for the user.
402 <p>
403 The second case is the following. Suppose you want to move
404 and/or rotate a particular piece of your detector component. This
405 case can easily happen for a beam test of your detector. It is
406 obvious for this case that you need not change the world volume.
407 Rather, it should be said that your world volume (experimental
408 hall for your beam test) should be big enough for moving/rotating
409 your test detector. For this case, you can still use all of your detector
410 geometries, and just use a <tt>Set</tt> method of a particular physical
411 volume to update the transformation vector as you want. Thus,
412 you don't need to re-set your world volume pointer to <i>RunManager</i>.
413 <p>
414 If you want to change your geometry for every run, you can
415 implement it in the <tt>BeginOfRunAction()</tt> method of
416 <i>G4UserRunAction</i> class, which will be invoked at the beginning of
417 each run, or, derive the <tt>RunInitialization()</tt> method. Please note that,
418 for both of the above mentioned cases, you need to let <i>RunManager</i>
419 know "the geometry needs to be closed again". Thus, you need to invoke
420<pre>
421 runManager->GeometryHasBeenModified();
422</pre>
423 before proceeding to the next run. An example of changing geometry
424 is given in a Geant4 tutorial in Geant4 Training kit #2.
425<p>
426<b>Switch physics processes</b>
427<p>
428 In the <tt>InitializePhysics()</tt> method,
429 <tt>G4VUserPhysicsList::Construct</tt> is invoked in order to define
430 particles and physics processes in your application.
431 Basically, you can not add nor remove any particles during execution,
432 because particles are static objects in Geant4 (see Sections
433 <a href="../GettingStarted/particleDef.html">2.4</a>
434 and <a href="../TrackingAndPhysics/particle.html">5.3</a> for details).
435 In addition, it is very difficult to add and/or remove physics
436 processes during execution, because registration procedures are
437 very complex, except for experts (see Sections
438 <a href="../GettingStarted/physicsDef.html">2.5</a> and
439 <a href="../TrackingAndPhysics/physicsProcess.html">5.2</a>).
440 This is why the <tt>initializePhysics()</tt> method is assumed to be invoked
441 at once in Geant4 kernel initialization.
442 <p>
443 However, you can switch on/off physics processes defined in your
444 <i>G4VUserPhysicsList</i> concrete class and also change parameters
445 in physics processes during the run break.
446 <p>
447 You can use <tt>ActivateProcess()</tt> and <tt>InActivateProcess()</tt> methods of
448 <i>G4ProcessManager</i> anywhere outside the event loop to switch on/off some
449 process. You should be very careful to switch on/off processes
450 inside the event loop, though it is not prohibited to use these methods
451 even in the <i>EventProc</i> state.
452 <p>
453 It is a likely case to change cut-off values in a run.
454 You can change <tt>defaultCutValue</tt> in <i>G4VUserPhysicsList</i> during
455 the <i>Idle</i> state. In this case, all cross section tables need to be
456 recalculated before the event loop. You should use the <tt>CutOffHasBeenModified()</tt>
457 method when you change cut-off values so that the <tt>SetCuts</tt> method of your
458 <i>PhysicsList</i> concrete class will be invoked.
459
460<BR><BR>
461<HR><A HREF="../../../../Authors/html/subjectsToAuthors.html">
462<I>About the authors</A></I> </P>
463
464</BODY>
465</HTML>
Note: See TracBrowser for help on using the repository browser.