1 | <!-- ******************************************************** --> |
---|
2 | <!-- --> |
---|
3 | <!-- [History] --> |
---|
4 | <!-- Changed by: Katsuya Amako, 4-Aug-1998 --> |
---|
5 | <!-- Proof read by: Joe Chuma, 15-Jun-1999 --> |
---|
6 | <!-- Changed by: Hisaya Kurashige, 28-Oct-2001 --> |
---|
7 | <!-- Changed by: Dennis Wright, 29-Nov-2001 --> |
---|
8 | <!-- Converted to DocBook: Katsuya Amako, Aug-2006 --> |
---|
9 | <!-- Changed by: Hisaya Kurashige, 18-Jan-2007 --> |
---|
10 | <!-- Changed by: Hisaya Kurashige, 1-Dec-2007 --> |
---|
11 | <!-- modified 2.4.2 by: Hisaya Kurashige, 23-Nov-2009 --> |
---|
12 | <!-- --> |
---|
13 | <!-- ******************************************************** --> |
---|
14 | |
---|
15 | |
---|
16 | <!-- ******************* Section (Level#1) ****************** --> |
---|
17 | <sect1 id="sect.HowToSpecParti"> |
---|
18 | <title> |
---|
19 | How to Specify Particles |
---|
20 | </title> |
---|
21 | |
---|
22 | <para> |
---|
23 | <literal>G4VuserPhysicsList</literal> is one of the mandatory user base |
---|
24 | classes described in |
---|
25 | <xref linkend="sect.HowToDefMain" />. |
---|
26 | Within this class all particles and physics processes to be used in |
---|
27 | your simulation must be defined. The range cut-off parameter should |
---|
28 | also be defined in this class. |
---|
29 | </para> |
---|
30 | |
---|
31 | <para> |
---|
32 | The user must create a class derived from |
---|
33 | <literal>G4VuserPhysicsList</literal> and implement the following pure |
---|
34 | virtual methods: |
---|
35 | |
---|
36 | <informalexample> |
---|
37 | <programlisting> |
---|
38 | ConstructParticle(); // construction of particles |
---|
39 | ConstructProcess(); // construct processes and register them to particles |
---|
40 | SetCuts(); // setting a range cut value for all particles |
---|
41 | </programlisting> |
---|
42 | </informalexample> |
---|
43 | </para> |
---|
44 | |
---|
45 | <para> |
---|
46 | This section provides some simple examples of the |
---|
47 | <literal>ConstructParticle()</literal> and <literal>SetCuts()</literal> |
---|
48 | methods. |
---|
49 | For information on <literal>ConstructProcess()</literal> methods, please see |
---|
50 | <xref linkend="sect.HowToSpecPhysProc" />. |
---|
51 | |
---|
52 | </para> |
---|
53 | |
---|
54 | |
---|
55 | <!-- ******************* Section (Level#2) ****************** --> |
---|
56 | <sect2 id="sect.HowToSpecParti.PartiDef"> |
---|
57 | <title> |
---|
58 | Particle Definition |
---|
59 | </title> |
---|
60 | |
---|
61 | <para> |
---|
62 | Geant4 provides various types of particles for use in simulations: |
---|
63 | |
---|
64 | <itemizedlist spacing="compact"> |
---|
65 | <listitem><para> |
---|
66 | ordinary particles, such as electrons, protons, and gammas |
---|
67 | </para></listitem> |
---|
68 | <listitem><para> |
---|
69 | resonant particles with very short lifetimes, such as vector |
---|
70 | mesons and delta baryons |
---|
71 | </para></listitem> |
---|
72 | <listitem><para> |
---|
73 | nuclei, such as deuteron, alpha, and heavy ions (including hyper-nuclei) |
---|
74 | </para></listitem> |
---|
75 | <listitem><para> |
---|
76 | quarks, di-quarks, and gluon |
---|
77 | </para></listitem> |
---|
78 | </itemizedlist> |
---|
79 | </para> |
---|
80 | |
---|
81 | <para> |
---|
82 | Each particle is represented by its own class, which is derived |
---|
83 | from <literal>G4ParticleDefinition</literal>. |
---|
84 | (Exception: G4Ions represents all heavy nuclei. Please see |
---|
85 | <xref linkend="sect.Parti" />.) |
---|
86 | Particles are organized into six major categories: |
---|
87 | |
---|
88 | <itemizedlist spacing="compact"> |
---|
89 | <listitem><para> |
---|
90 | lepton, |
---|
91 | </para></listitem> |
---|
92 | <listitem><para> |
---|
93 | meson, |
---|
94 | </para></listitem> |
---|
95 | <listitem><para> |
---|
96 | baryon, |
---|
97 | </para></listitem> |
---|
98 | <listitem><para> |
---|
99 | boson, |
---|
100 | </para></listitem> |
---|
101 | <listitem><para> |
---|
102 | shortlived and |
---|
103 | </para></listitem> |
---|
104 | <listitem><para> |
---|
105 | ion, |
---|
106 | </para></listitem> |
---|
107 | </itemizedlist> |
---|
108 | |
---|
109 | each of which is defined in a corresponding sub-directory under |
---|
110 | <literal>geant4/source/particles</literal>. There is also a corresponding |
---|
111 | granular library for each particle category. |
---|
112 | </para> |
---|
113 | |
---|
114 | |
---|
115 | <!-- ******************* Section (Level#3) ****************** --> |
---|
116 | <sect3 id="sect.HowToSpecParti.PartiDef.G4ParticleDefinition"> |
---|
117 | <title> |
---|
118 | The <literal>G4ParticleDefinition</literal> Class |
---|
119 | </title> |
---|
120 | |
---|
121 | <para> |
---|
122 | <literal>G4ParticleDefinition</literal> has properties which characterize |
---|
123 | individual particles, such as, name, mass, charge, spin, and so on. |
---|
124 | Most of these properties are "read-only" and can not be changed directly. |
---|
125 | <literal>G4ParticlePropertyTable</literal> is used to retrieve (load) |
---|
126 | particle property of <literal>G4ParticleDefinition</literal> |
---|
127 | into (from) <literal>G4ParticlePropertyData</literal>. |
---|
128 | </para> |
---|
129 | |
---|
130 | </sect3> |
---|
131 | |
---|
132 | <!-- ******************* Section (Level#3) ****************** --> |
---|
133 | <sect3 id="sect.HowToSpecParti.PartiDef.HowToAccessParti"> |
---|
134 | <title> |
---|
135 | How to Access a Particle |
---|
136 | </title> |
---|
137 | |
---|
138 | <para> |
---|
139 | Each particle class type represents an individual particle type, |
---|
140 | and each class has a single object. This object can be accessed by |
---|
141 | using the static method of each class. |
---|
142 | There are some exceptions to this rule; please see |
---|
143 | <xref linkend="sect.Parti" /> for details. |
---|
144 | </para> |
---|
145 | |
---|
146 | <para> |
---|
147 | For example, the class <literal>G4Electron</literal> represents the |
---|
148 | electron and the member <literal>G4Electron::theInstance</literal> |
---|
149 | points its only object. |
---|
150 | The pointer to this object is available |
---|
151 | through the static methods |
---|
152 | <literal>G4Electron::ElectronDefinition()</literal>. |
---|
153 | <literal>G4Electron::Definition()</literal>. |
---|
154 | </para> |
---|
155 | |
---|
156 | <para> |
---|
157 | More than 100 types of particles are provided by default, to be |
---|
158 | used in various physics processes. In normal applications, users |
---|
159 | will not need to define their own particles. |
---|
160 | </para> |
---|
161 | |
---|
162 | <para> |
---|
163 | The unique object for each particle class is created when its static |
---|
164 | method to get the pointer is called at the first time. |
---|
165 | Because particles are dynamic objects and should be instantiated before |
---|
166 | initialization of physics processes, |
---|
167 | you must explicitly invoke static methods of all particle classes |
---|
168 | required by your program at the initialization step. |
---|
169 | (NOTE: The particle object was static and created automatically before 8.0 release) |
---|
170 | </para> |
---|
171 | |
---|
172 | </sect3> |
---|
173 | |
---|
174 | <!-- ******************* Section (Level#3) ****************** --> |
---|
175 | <sect3 id="sect.HowToSpecParti.PartiDef.DictOfParti"> |
---|
176 | <title>Dictionary of Particles |
---|
177 | </title> |
---|
178 | |
---|
179 | <para> |
---|
180 | The <literal>G4ParticleTable</literal> class is provided as a dictionary of |
---|
181 | particles. Various utility methods are provided, such as: |
---|
182 | |
---|
183 | <informalexample> |
---|
184 | <programlisting> |
---|
185 | FindParticle(G4String name); // find the particle by name |
---|
186 | FindParticle(G4int PDGencoding) // find the particle by PDG encoding . |
---|
187 | </programlisting> |
---|
188 | </informalexample> |
---|
189 | </para> |
---|
190 | |
---|
191 | <para> |
---|
192 | <literal>G4ParticleTable</literal> is defined as a singleton object, |
---|
193 | and the static method <literal>G4ParticleTable::GetParticleTable()</literal> |
---|
194 | provides its pointer. |
---|
195 | </para> |
---|
196 | |
---|
197 | <para> |
---|
198 | As for heavy ions (including hyper-nuclei), objects are created |
---|
199 | dynamically by requests from users and processes. |
---|
200 | The <literal>G4ParticleTable</literal> class provides |
---|
201 | methods to create ions, such as: |
---|
202 | <informalexample> |
---|
203 | <programlisting> |
---|
204 | G4ParticleDefinition* GetIon( G4int atomicNumber, |
---|
205 | G4int atomicMass, |
---|
206 | G4double excitationEnergy); |
---|
207 | </programlisting> |
---|
208 | </informalexample> |
---|
209 | </para> |
---|
210 | |
---|
211 | <para> |
---|
212 | Particles are registered automatically during construction. The |
---|
213 | user has no control over particle registration. |
---|
214 | </para> |
---|
215 | |
---|
216 | |
---|
217 | </sect3> |
---|
218 | |
---|
219 | <!-- ******************* Section (Level#3) ****************** --> |
---|
220 | <sect3 id="sect.HowToSpecParti.PartiDef.ConstruParti"> |
---|
221 | <title> |
---|
222 | Constructing Particles |
---|
223 | </title> |
---|
224 | |
---|
225 | <para> |
---|
226 | <literal>ConstructParticle()</literal> is a pure virtual method, in which |
---|
227 | the static member functions for all the particles you require should be called. |
---|
228 | This ensures that objects of these particles are created. |
---|
229 | </para> |
---|
230 | |
---|
231 | <para> |
---|
232 | WARNING: You must define "All PARTICLE TYPES" which are used in your |
---|
233 | application, except for heavy ions. |
---|
234 | "All PARTICLE TYPES" means not only primary |
---|
235 | particles, but also all other particles which may appear as secondaries |
---|
236 | generated by physics processes you use. Beginning with Geant4 version 8.0, |
---|
237 | you should keep this rule strictly because all particle definitions are |
---|
238 | revised to "non-static" objects. |
---|
239 | </para> |
---|
240 | |
---|
241 | <para> |
---|
242 | For example, suppose you need a proton and a geantino, which is |
---|
243 | a virtual particle used for simulation and which does not interact |
---|
244 | with materials. The <literal>ConstructParticle()</literal> method is |
---|
245 | implemented as below: |
---|
246 | |
---|
247 | <example id="programlist_HowToSpecParti_1"> |
---|
248 | <title> |
---|
249 | Construct a proton and a geantino. |
---|
250 | </title> |
---|
251 | <programlisting> |
---|
252 | void ExN01PhysicsList::ConstructParticle() |
---|
253 | { |
---|
254 | G4Proton::ProtonDefinition(); |
---|
255 | G4Geantino::GeantinoDefinition(); |
---|
256 | } |
---|
257 | </programlisting> |
---|
258 | </example> |
---|
259 | </para> |
---|
260 | |
---|
261 | <para> |
---|
262 | Due to the large number of pre-defined particles in Geant4, it |
---|
263 | is cumbersome to list all the particles by this method. If you want |
---|
264 | all the particles in a Geant4 particle category, there are six |
---|
265 | utility classes, corresponding to each of the particle categories, |
---|
266 | which perform this function: |
---|
267 | |
---|
268 | <itemizedlist spacing="compact"> |
---|
269 | <listitem><para> |
---|
270 | <literal>G4BosonConstructor</literal> |
---|
271 | </para></listitem> |
---|
272 | <listitem><para> |
---|
273 | <literal>G4LeptonConstructor</literal> |
---|
274 | </para></listitem> |
---|
275 | <listitem><para> |
---|
276 | <literal>G4MesonConstructor</literal> |
---|
277 | </para></listitem> |
---|
278 | <listitem><para> |
---|
279 | <literal>G4BarionConstructor</literal> |
---|
280 | </para></listitem> |
---|
281 | <listitem><para> |
---|
282 | <literal>G4IonConstructor</literal> |
---|
283 | </para></listitem> |
---|
284 | <listitem><para> |
---|
285 | <literal>G4ShortlivedConstructor</literal>. |
---|
286 | </para></listitem> |
---|
287 | </itemizedlist> |
---|
288 | </para> |
---|
289 | |
---|
290 | <para> |
---|
291 | An example of this is shown in <literal>ExN05PhysicsList</literal>, |
---|
292 | listed below. |
---|
293 | |
---|
294 | <example id="programlist_HowToSpecParti_2"> |
---|
295 | <title> |
---|
296 | Construct all leptons. |
---|
297 | </title> |
---|
298 | <programlisting> |
---|
299 | void ExN05PhysicsList::ConstructLeptons() |
---|
300 | { |
---|
301 | // Construct all leptons |
---|
302 | G4LeptonConstructor pConstructor; |
---|
303 | pConstructor.ConstructParticle(); |
---|
304 | } |
---|
305 | </programlisting> |
---|
306 | </example> |
---|
307 | </para> |
---|
308 | |
---|
309 | </sect3> |
---|
310 | </sect2> |
---|
311 | |
---|
312 | <!-- ******************* Section (Level#2) ****************** --> |
---|
313 | <sect2 id="sect.HowToSpecParti.RangeCuts"> |
---|
314 | <title> |
---|
315 | Range Cuts |
---|
316 | </title> |
---|
317 | |
---|
318 | <para> |
---|
319 | To avoid infrared divergence, some electromagnetic processes |
---|
320 | require a threshold below which no secondary will be generated. |
---|
321 | Because of this requirement, gammas, electrons and positrons |
---|
322 | require production thresholds which the user should define. This |
---|
323 | threshold should be defined as a distance, or range cut-off, which |
---|
324 | is internally converted to an energy for individual materials. The |
---|
325 | range threshold should be defined in the initialization phase using |
---|
326 | the <literal>SetCuts()</literal> method of <literal>G4VUserPhysicsList</literal>. |
---|
327 | <xref linkend="sect.CutReg" /> discusses threshold and tracking |
---|
328 | cuts in detail. |
---|
329 | </para> |
---|
330 | |
---|
331 | |
---|
332 | |
---|
333 | <!-- ******************* Section (Level#3) ****************** --> |
---|
334 | <sect3 id="sect.HowToSpecParti.RangeCuts.SetCuts"> |
---|
335 | <title> |
---|
336 | Setting the cuts |
---|
337 | </title> |
---|
338 | |
---|
339 | <para> |
---|
340 | Production threshold values should be defined in <literal>SetCuts()</literal> |
---|
341 | which is a pure virtual method of the <literal>G4VUserPhysicsList</literal> |
---|
342 | class. Construction of particles, materials, and processes should |
---|
343 | precede the invocation of <literal>SetCuts()</literal>. <literal>G4RunManager</literal> |
---|
344 | takes care of this sequence in usual applications. |
---|
345 | </para> |
---|
346 | <para> |
---|
347 | This range cut value is converted threshold energies |
---|
348 | for each material and for each particle type (i.e. electron, |
---|
349 | positron and gamma) |
---|
350 | so that the particle with threshold energy stops (or is absorbed) |
---|
351 | after traveling the range cut distance. |
---|
352 | In addition, from the 9.3 release ,this range cut value is applied |
---|
353 | to the proton as production thresholds of nuclei for hadron |
---|
354 | elastic processes. In this case, the range cut value does not means |
---|
355 | the distance of traveling. Threshold energies are calculated |
---|
356 | by a simple formula from the cut in range. |
---|
357 | </para> |
---|
358 | |
---|
359 | <para> |
---|
360 | Note that the upper limit of the threshold energy is defined as 10 |
---|
361 | GeV. If you want to set higher threshold energy, you can change |
---|
362 | the limit by using "/cuts/setMaxCutEnergy" command before setting |
---|
363 | the range cut. |
---|
364 | </para> |
---|
365 | |
---|
366 | <para> |
---|
367 | The idea of a "unique cut value in range" is one of the |
---|
368 | important features of Geant4 and is used to handle cut values in a |
---|
369 | coherent manner. For most applications, users need to determine |
---|
370 | only one cut value in range, and apply this value to gammas, |
---|
371 | electrons and positrons alike. (and proton too) |
---|
372 | </para> |
---|
373 | |
---|
374 | <para> |
---|
375 | In such case, the <literal>SetCutsWithDefault()</literal> method may be |
---|
376 | used. It is provided by the <literal>G4VuserPhysicsList</literal> base class, |
---|
377 | which has a <literal>defaultCutValue</literal> member as the default range |
---|
378 | cut-off value. <literal>SetCutsWithDefault()</literal> uses this value. |
---|
379 | </para> |
---|
380 | |
---|
381 | <para> |
---|
382 | It is possible to set different range cut values for gammas, |
---|
383 | electrons and positrons, and also to set different range cut values |
---|
384 | for each geometrical region. In such cases however, one must be |
---|
385 | careful with physics outputs because Geant4 processes (especially |
---|
386 | energy loss) are designed to conform to the "unique cut value in |
---|
387 | range" scheme. |
---|
388 | |
---|
389 | <example id="programlist_HowToSpecParti_3"> |
---|
390 | <title> |
---|
391 | Set cut values by using the default cut value. |
---|
392 | </title> |
---|
393 | <programlisting> |
---|
394 | void ExN04PhysicsList::SetCuts() |
---|
395 | { |
---|
396 | // the G4VUserPhysicsList::SetCutsWithDefault() method sets |
---|
397 | // the default cut value for all particle types |
---|
398 | SetCutsWithDefault(); |
---|
399 | } |
---|
400 | </programlisting> |
---|
401 | </example> |
---|
402 | </para> |
---|
403 | |
---|
404 | <para> |
---|
405 | The <literal>defaultCutValue</literal> is set to 1.0 mm by default. Of |
---|
406 | course, you can set the new default cut value in the constructor of |
---|
407 | your physics list class as shown below. |
---|
408 | |
---|
409 | <example id="programlist_HowToSpecParti_4"> |
---|
410 | <title> |
---|
411 | Set the default cut value. |
---|
412 | </title> |
---|
413 | <programlisting> |
---|
414 | ExN04PhysicsList::ExN04PhysicsList(): G4VUserPhysicsList() |
---|
415 | { |
---|
416 | // default cut value (1.0mm) |
---|
417 | defaultCutValue = 1.0*mm; |
---|
418 | } |
---|
419 | </programlisting> |
---|
420 | </example> |
---|
421 | </para> |
---|
422 | |
---|
423 | <para> |
---|
424 | The <literal>SetDefaultCutValue()</literal> method in |
---|
425 | <literal>G4VUserPhysicsList</literal> may also be used, |
---|
426 | and the "/run/setCut" command may be used |
---|
427 | to change the default cut value interactively. |
---|
428 | </para> |
---|
429 | |
---|
430 | <para> |
---|
431 | You can set different cut values in range for different |
---|
432 | particle types. The "/run/setCutForAGivenParticle" command |
---|
433 | may be used interactively. |
---|
434 | </para> |
---|
435 | |
---|
436 | <para> |
---|
437 | WARNING: DO NOT change cut values inside the event loop. Cut |
---|
438 | values may however be changed between runs. |
---|
439 | </para> |
---|
440 | |
---|
441 | <para> |
---|
442 | An example implementation of <literal>SetCuts()</literal> is shown |
---|
443 | below: |
---|
444 | |
---|
445 | <example id="programlist_HowToSpecParti_5"> |
---|
446 | <title> |
---|
447 | Example implementation of the <literal>SetCuts()</literal> method. |
---|
448 | </title> |
---|
449 | <programlisting> |
---|
450 | void ExN03PhysicsList::SetCuts() |
---|
451 | { |
---|
452 | // set cut values for gamma at first and for e- second and next for e+, |
---|
453 | // because some processes for e+/e- need cut values for gamma |
---|
454 | SetCutValue(cutForGamma, "gamma"); |
---|
455 | SetCutValue(cutForElectron, "e-"); |
---|
456 | SetCutValue(cutForElectron, "e+"); |
---|
457 | SetCutValue(cutForProton, "proton"); |
---|
458 | } |
---|
459 | </programlisting> |
---|
460 | </example> |
---|
461 | </para> |
---|
462 | |
---|
463 | <para> |
---|
464 | Beginning with Geant4 version 5.1, it is now possible to set |
---|
465 | production thresholds for each geometrical region. This new |
---|
466 | functionality is described in <xref linkend="sect.CutReg" />. |
---|
467 | </para> |
---|
468 | |
---|
469 | |
---|
470 | </sect3> |
---|
471 | </sect2> |
---|
472 | </sect1> |
---|