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

Last change on this file since 1211 was 1208, checked in by garnier, 15 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.