source: trunk/documents/UserDoc/UsersGuides/ForApplicationDeveloper/html/UserActions/OptionalActions.html

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

CVS update
File size: 10.9 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2<HTML>
3<HEAD>
4<!-- Changed by: Katsuya Amako, 9-Jul-1998 -->
5<!-- Changed by: Katsuya Amako, 4-Aug-1998 -->
6<!-- Changed by: John Allison, 4-Aug-1998 -->
7<!-- Changed by: Katsuya Amako, 30-Nov-1998 -->
8<!-- Changed by: Dennis Wright, 27-Nov-2001 -->
9<!-- Proof read by: Joe Chuma, 2-Jul-1999 -->
10
11<META NAME="GENERATOR" CONTENT="Mozilla/3.0Gold (X11; I; OSF1 V4.0 alpha) [Netscape]">
12</HEAD>
13<BODY>
14<TABLE WIDTH="100%" >
15<TR>
16<TD>
17</A>
18<A HREF="index.html">
19<IMG SRC="../../../../resources/html/IconsGIF/Contents.gif" ALT="Contents" HEIGHT=16 WIDTH=59></A>
20<A HREF="MandatoryActions.html">
21<IMG SRC="../../../../resources/html/IconsGIF/Previous.gif" ALT="Previous" HEIGHT=16 WIDTH=59></A>
22<a href="UserInformationClasses.html">
23<IMG SRC="../../../../resources/html/IconsGIF/Next.gif" ALT="Next" HEIGHT=16 WIDTH=59></a>
24</TD>
25
26<TD ALIGN="Right">
27<FONT COLOR="#238E23"><FONT SIZE=-1>
28<B>Geant4 User's Guide</B> <BR>
29<B>For Application Developers</B> <BR>
30<B>User Actions</B> </FONT></FONT>
31</TD>
32</TR>
33</TABLE>
34<P><BR>
35
36<CENTER><FONT COLOR="#238E23"><FONT SIZE=+3>
37<B>6.2 Optional User Actions</B>
38</FONT></FONT>
39<BR><BR>
40</CENTER>
41
42<HR ALIGN="Center" SIZE="7%">
43
44There are five virtual classes whose methods the user may override in order
45to gain control of the simulation at various stages. Each method of each
46action class has an empty default implementation, allowing the user to
47inherit and implement desired classes and methods. Objects of user action
48classes must be registered with <tt>G4RunManager</tt>.
49<p>
50<b><tt>G4UserRunAction</tt></b>
51</p>
52This class has three virtual methods which are invoked by
53<tt>G4RunManager</tt> for each run:
54 <dl><dl>
55 <dt><tt>GenerateRun()</tt>
56<dd>This method is invoked at the beginning of <tt>BeamOn</tt>. Because the
57user can inherit the class <tt>G4Run</tt> and create his/her own concrete
58class to store some information about the run, the <tt>GenerateRun()</tt>
59method is the place to instantiate such an object. It is also the ideal place
60to set variables which affect the physics table (such as production
61thresholds) for a particular run, because <tt>GenerateRun()</tt> is invoked
62before the calculation of the physics table.
63
64 <dt><tt>BeginOfRunAction()</tt>
65 <dd>This method is invoked before entering the event loop. A typical use of
66this method would be to initialize and/or book histograms for a particular run.
67This method is invoked after the calculation of the physics tables.
68 <dt><tt>EndOfRunAction()</tt>
69 <dd>This method is invoked at the very end of the run processing. It is
70 typically used for a simple analysis of the processed run.
71 </dl></dl>
72<p>
73
74<center>
75<table border=2 cellpadding=10>
76<tr>
77<td>
78 <pre>
79 class G4UserRunAction
80 {
81 public:
82 G4UserRunAction();
83 virtual ~G4UserRunAction();
84
85 public:
86 virtual G4Run* GenerateRun();
87 virtual void BeginOfRunAction(const G4Run*);
88 virtual void EndOfRunAction(const G4Run*);
89 };
90
91 </pre>
92</td>
93</tr>
94<tr>
95<td align=center>
96 Source listing 6.2.1<BR>
97 <tt>G4UserRunAction</tt>
98</td>
99</tr>
100</table></center>
101
102<p>
103<b><tt>G4UserEventAction</tt></b>
104</p>
105This class has two virtual methods which are invoked by <tt>G4EventManager</tt>
106for each event:
107 <dl><dl>
108 <dt><tt>beginOfEventAction()</tt>
109 <dd>This method is invoked before converting the primary particles
110 to <tt>G4Track</tt> objects. A typical use of this method would be to
111 initialize and/or book histograms for a particular event.<p>
112 <dt><tt>endOfEventAction()</tt>
113 <dd>This method is invoked at the very end of event processing. It is
114 typically used for a simple analysis of the processed event.
115 <dd>If the user wants to keep the currently processing event until the
116 end of the current run, the user can invoke
117 <dl><dd><i>fpEventManager->KeepTheCurrentEvent();</i></dl>
118 so that it is kept in <i>G4Run</i> object. This should be quite
119 useful if you simulate quite many events and want to visualize only
120 the most interest ones after the long execution.
121 Given the memory size of
122 an event and its contents may be large, it is the user's responsibility
123 not to keep unnecessary events.
124 </dl></dl>
125<p>
126
127<center>
128<table border=1 cellpadding=10>
129<tr>
130<td>
131 <pre>
132 class G4UserEventAction
133 {
134 public:
135 G4UserEventAction() {;}
136 virtual ~G4UserEventAction() {;}
137 virtual void BeginOfEventAction(const G4Event*);
138 virtual void EndOfEventAction(const G4Event*);
139 protected:
140 G4EventManager* fpEventManager;
141 };
142 </pre>
143</td>
144</tr>
145<tr>
146<td align=center>
147 Source listing 6.2.2<BR>
148 <tt>G4UserEventAction</tt>
149</td>
150</tr>
151</table></center>
152
153<p>
154<b><tt>G4UserStackingAction</tt></b>
155</p>
156
157 This class has three virtual methods, <tt>ClassifyNewTrack</tt>,
158 <tt>NewStage</tt> and <tt>PrepareNewEvent</tt> which the user may
159 override in order to control the various track stacking mechanisms.
160 ExampleN04 could be a good example to understand the usage of this
161 class.
162 <dl><dl>
163 <dt><tt>ClassifyNewTrack()</tt> is invoked by <tt>G4StackManager</tt>
164 whenever a new <tt>G4Track</tt> object is "pushed" onto a stack by
165 <tt>G4EventManager</tt>. <tt>ClassifyNewTrack()</tt> returns an
166 enumerator, <tt>G4ClassificationOfNewTrack</tt>, whose value indicates
167 to which stack, if any, the track will be sent. This value should
168 be determined by the user. <tt>G4ClassificationOfNewTrack</tt> has
169 four possible values:
170 <dd><tt>fUrgent</tt> - track is placed in the <i>urgent</i> stack
171 <dd><tt>fWaiting</tt> - track is placed in the <i>waiting</i> stack,
172 and will not be simulated until the <i>urgent</i> stack is empty
173 <dd><tt>fPostpone</tt> - track is postponed to the next event
174 <dd><tt>fKill</tt> - the track is deleted immediately and not stored
175 in any stack.
176 <dt>These assignments may be made based on the origin of the track
177 which is obtained as follows:
178 <dd><tt>G4int parent_ID = aTrack->get_parentID();</tt>
179 <dd>where
180 <dd><tt>parent_ID = 0</tt> indicates a primary particle
181 <dd><tt>parent_ID > 0</tt> indicates a secondary particle
182 <dd><tt>parent_ID < 0</tt> indicates postponed particle from previous event.
183 <p>
184 &nbsp;
185 <p>
186 <dt><tt>NewStage()</tt> is invoked when the <i>urgent</i> stack is empty and
187 the <i>waiting</i> stack contains at least one <tt>G4Track</tt> object.
188 Here the user may kill or re-assign to different stacks all the tracks
189 in the <i>waiting</i> stack by calling the
190 <tt>stackManager->ReClassify()</tt> method which, in turn, calls the
191 <tt>ClassifyNewTrack()</tt> method. If no user action is taken, all
192 tracks in the <i>waiting</i> stack are transferred to the <i>urgent</i>
193 stack. The user may also decide to abort the current event even though
194 some tracks may remain in the <i>waiting</i> stack by calling
195 <tt>stackManager->clear()</tt>. This method is valid and safe only if
196 it is called from the <tt>G4UserStackingAction</tt> class. A global
197 method of event abortion is
198 <dd><tt>G4UImanager * UImanager = G4UImanager::GetUIpointer();</tt>
199 <dd><tt>UImanager->ApplyCommand("/event/abort");</tt>
200 <p>
201 &nbsp;
202 <p>
203 <dt><tt>PrepareNewEvent()</tt> is invoked at the beginning of each event.
204 At this point no primary particles have been converted to tracks, so the
205 <i>urgent</i> and <i>waiting</i> stacks are empty. However, there may
206 be tracks in the <i>postponed-to-next-event</i> stack; for each of these
207 the <tt>ClassifyNewTrack()</tt> method is called and the track is
208 assigned to the appropriate stack.
209 </dl></dl>
210
211<p>
212<center>
213<table border=2 cellpadding=10>
214<tr>
215<td>
216 <pre>
217 #include "G4ClassificationOfNewTrack.hh"
218
219 class G4UserStackingAction
220 {
221 public:
222 G4UserStackingAction();
223 virtual ~G4UserStackingAction();
224 protected:
225 G4StackManager * stackManager;
226
227 public:
228 //---------------------------------------------------------------
229 // virtual methods to be implemented by user
230 //---------------------------------------------------------------
231 //
232 virtual G4ClassificationOfNewTrack
233 ClassifyNewTrack(const G4Track*);
234 //
235 //---------------------------------------------------------------
236 //
237 virtual void NewStage();
238 //
239 //---------------------------------------------------------------
240 //
241 virtual void PrepareNewEvent();
242 //
243 //---------------------------------------------------------------
244
245 };
246 </pre>
247</td>
248</tr>
249<tr>
250<td align=center>
251 Source listing 6.2.3<BR>
252 <tt>G4UserStackingAction</tt>
253</td>
254</tr>
255</table></center>
256
257<p>
258<b><tt>G4UserTrackingAction</tt></b>
259</p>
260
261<center>
262<table border=2 cellpadding=10>
263<tr>
264<td>
265 <pre>
266 //---------------------------------------------------------------
267 //
268 // G4UserTrackingAction.hh
269 //
270 // Description:
271 // This class represents actions taken place by the user at each
272 // end of stepping.
273 //
274 //---------------------------------------------------------------
275
276 ///////////////////////////
277 class G4UserTrackingAction
278 ///////////////////////////
279 {
280
281 //--------
282 public:
283 //--------
284
285 // Constructor & Destructor
286 G4UserTrackingAction(){};
287 virtual ~G4UserTrackingAction(){}
288
289 // Member functions
290 virtual void PreUserTrackingAction(const G4Track*){}
291 virtual void PostUserTrackingAction(const G4Track*){}
292
293 //-----------
294 protected:
295 //-----------
296
297 // Member data
298 G4TrackingManager* fpTrackingManager;
299
300 };
301 </pre>
302</td>
303</tr>
304<tr>
305<td align=center>
306 Source listing 6.2.4<BR>
307 <tt>G4UserTrackingAction</tt>
308</td>
309</tr>
310</table></center>
311
312<p>
313<b><tt>G4UserSteppingAction</tt></b>
314</p>
315
316<center>
317<table border=2 cellpadding=10>
318<tr>
319<td>
320 <pre>
321 //---------------------------------------------------------------
322 //
323 // G4UserSteppingAction.hh
324 //
325 // Description:
326 // This class represents actions taken place by the user at each
327 // end of stepping.
328 //
329 //---------------------------------------------------------------
330
331 ///////////////////////////
332 class G4UserSteppingAction
333 ///////////////////////////
334 {
335
336 //--------
337 public:
338 //--------
339
340 // Constructor and destructor
341 G4UserSteppingAction(){}
342 virtual ~G4UserSteppingAction(){}
343
344 // Member functions
345 virtual void UserSteppingAction(const G4Step*){}
346
347 //-----------
348 protected:
349 //-----------
350
351 // Member data
352 G4SteppingManager* fpSteppingManager;
353
354 };
355 </pre>
356</td>
357</tr>
358<tr>
359<td align=center>
360 Source listing 6.2.5<BR>
361 <tt>G4UserSteppingAction</tt>
362</td>
363</tr>
364</table></center>
365<p>
366
367<BR><BR>
368<HR><A HREF="../../../../Authors/html/subjectsToAuthors.html">
369<I>About the authors</A></I> </P></CENTER>
370
371</BODY>
372</HTML>
Note: See TracBrowser for help on using the repository browser.