Version:
[ ReleaseNotes ] [ 1.0 ] [ 1.1 ] [ 2.0 ] [ 3.0 ] [ 3.1 ] [ 3.2 ] [ 4.0 ] [ 4.0.p1 ] [ 4.0.p2 ] [ 4.1 ] [ 4.1.p1 ] [ 5.0 ] [ 5.0.p1 ] [ 5.1 ] [ 5.1.p1 ] [ 5.2 ] [ 5.2.p1 ] [ 5.2.p2 ] [ 6.0 ] [ 6.0.p1 ] [ 6.1 ] [ 6.2 ] [ 6.2.p1 ] [ 6.2.p2 ] [ 7.0 ] [ 7.0.p1 ] [ 7.1 ] [ 7.1.p1 ] [ 8.0 ] [ 8.0.p1 ] [ 8.1 ] [ 8.1.p1 ] [ 8.1.p2 ] [ 8.2 ] [ 8.2.p1 ] [ 8.3 ] [ 8.3.p1 ] [ 8.3.p2 ] [ 9.0 ] [ 9.0.p1 ] [ 9.0.p2 ] [ 9.1 ] [ 9.1.p1 ] [ 9.1.p2 ] [ 9.1.p3 ] [ 9.2 ] [ 9.2.p1 ] [ 9.2.p2 ] [ 9.2.p3 ] [ 9.2.p4 ] [ 9.3 ] [ 9.3.p1 ] [ 9.3.p2 ] [ 9.4 ] [ 9.4.p1 ] [ 9.4.p2 ] [ 9.4.p3 ] [ 9.4.p4 ] [ 9.5 ] [ 9.5.p1 ] [ 9.5.p2 ] [ 9.6 ] [ 9.6.p1 ] [ 9.6.p2 ] [ 9.6.p3 ] [ 9.6.p4 ] [ 10.0 ] [ 10.0.p1 ] [ 10.0.p2 ] [ 10.0.p3 ] [ 10.0.p4 ] [ 10.1 ] [ 10.1.p1 ] [ 10.1.p2 ] [ 10.1.p3 ] [ 10.2 ] [ 10.2.p1 ] [ 10.2.p2 ] [ 10.2.p3 ] [ 10.3 ] [ 10.3.p1 ] [ 10.3.p2 ] [ 10.3.p3 ] [ 10.4 ] [ 10.4.p1 ] [ 10.4.p2 ] [ 10.4.p3 ] [ 10.5 ] [ 10.5.p1 ] [ 10.6 ] [ 10.6.p1 ] [ 10.6.p2 ] [ 10.6.p3 ] [ 10.7 ] [ 10.7.p1 ] [ 10.7.p2 ] [ 10.7.p3 ] [ 10.7.p4 ] [ 11.0 ] [ 11.0.p1 ] [ 11.0.p2 ] [ 11.0.p3, ] [ 11.0.p4 ] [ 11.1 ] [ 11.1.1 ] [ 11.1.2 ] [ 11.1.3 ] [ 11.2 ] [ 11.2.1 ] [ 11.2.2 ] [ 11.3.0 ]
1
2 -------------------------------------------------------------------
3
4 =========================================================
5 Geant4 - an Object-Oriented Toolkit for Simulation in HEP
6 =========================================================
7
8 Example ThreadsafeScorers
9 ----------------------------
10
11 This example demonstrates a very simple application where an energy
12 deposit and # of steps is accounted in thread-local (i.e. one instance per
13 thread) hits maps with underlying types of plain-old data (POD) and global
14 (i.e. one instance) hits maps with underlying types of atomics.
15 The example uses a coarse mesh, extensive physics, and step limiters
16 to ensure that there is a higher degree of conflict between threads
17 when updating the scorers to test the robustness of the atomics
18 classes and maximize the compounding of thread-local round-off error.
19 At the end of the simulation, the scorers are printed to
20 "mfd_<DATA_TYPE>_<SCORER_TYPE>.out", where DATA_TYPE is either
21 "tl" (thread-local) or "tg" (thread-global) and SCORER_TYPE is "EnergyDeposit"
22 or "NumberOfSteps". These values are then compared to a thread-global
23 sum of these scorers that were updated via mutex locking. If round-off
24 errors in thread-local EnergyDeposit are present, they can be viewed
25 in "mfd_diff.out" at the end of the simulation
26
27 1- ATOMICS and the ATOMIC SCORERS
28
29 atomics can ONLY handle plain-old data (POD) types, e.g. int, double, etc.
30 The implementation of atomics in compiler-dependent. At the very worst,
31 the performance of an atomic is the same mutex locking.
32 Atomics, in general, are not copy-constructable. This has to do with
33 thread safety (e.g. making a copy while another thread tries to update)
34 This is why atomics cannot be used in STL containers. The implementation
35 in atomic.hh has limited copy-construction and still cannot be used in
36 STL containers. Use these copy-constructors with extreme caution. See
37 opening comments of G4atomic.hh for more details.
38
39 The newly provided classes in this example (G4atomic, G4TAtomicHitsMap, and
40 G4TAtomicHitsCollection) are intended for applications where memory is a
41 greater concern than performance. While atomics generally perform better than
42 mutex locking, the synchronization is not without a cost. However, since
43 the memory consumed by thread-local hits maps scales roughly linearly
44 with the number of threads, simulations with a large number of scoring
45 volumes can decrease simulation time by increasing the number of threads
46 beyond what was previously allowed due to the increase in memory consumption.
47
48 The G4TAtomicHitsMap and G4TAtomicHitsCollection work exactly the same way
49 as the standard G4THitsMap and G4THitsCollection, respectively, with the
50 exception(s) that you should only implement one instance and provide a
51 pointer/reference of that instance to the threads instead of having the
52 threads create them. Additionally, there is no need to include them
53 in the G4Run::Merge().
54
55 2- GEOMETRY DEFINITION
56
57 The geometry is constructed in the TSDetectorConstruction class.
58 The setup consists of a box filling the world. The volume is divided into
59 subregions, where the outermost boxes are a different material. The materials
60 by default are water and boron as these have large scattering cross-sections
61 for neutrons (the default particle).
62
63 3- PHYSICS LIST
64
65 The particle's type and the physic processes which will be available
66 in this example are set are built from a variety of physics constructors.
67 The chosen physics lists are extensive, primarily
68 The constructors are:
69
70 G4EmStandardPhysics_option4
71 G4DecayPhysics
72 G4RadioactiveDecayPhysics
73 G4HadronPhysicsQGSP_BERT_HP
74 G4HadronElasticPhysicsHP
75 G4StepLimiterPhysics
76 G4IonElasticPhysics
77 G4IonBinaryCascadePhysics
78
79 4- ACTION INITALIZATION
80
81 TSActionInitialization, instantiates and registers to Geant4 kernel
82 all user action classes.
83
84 While in sequential mode the action classes are instatiated just once,
85 via invoking the method:
86 TSActionInitialization::Build()
87 in multi-threading mode the same method is invoked for each thread worker
88 and so all user action classes are defined thread-local.
89
90 A run action class is instantiated both thread-local
91 and global that's why its instance is created also in the method
92 TSActionInitialization::BuildForMaster()
93 which is invoked only in multi-threading mode.
94
95 5- PRIMARY GENERATOR
96
97 The primary generator is defined in the TSPrimaryGeneratorAction class.
98 The default kinematics is a 1 MeV neutron, randomly distributed in front
99 of the target across 100% of the transverse (X,Y) target size.
100 This default setting can be changed via the Geant4 built-in commands
101 of the G4ParticleGun class.
102
103 6- DETECTOR RESPONSE
104
105 This example demonstrates a scoring implemented
106 in the user action classes and TSRun object.
107
108 The energy deposited is collected per event in the PrimitiveScorer
109 G4PSEnergyDeposit (as part of a MultiFunctionalDetector)
110 and the thread-local version are merged at the end of the run.
111
112 The number of steps is collected per event in the PrimativeScorer
113 G4PSNoOfSteps and the thread-local version are merged at the end of the run.
114
115 When the MFD is recording an event i.e. TSRun::RecordEvent(const G4Event*),
116 the global atomic hits map adds the same hits collections
117
118 In multi-threading mode the energy accumulated in TSRun MFD object per
119 workers is merged to the master in TSRun::Merge().
120
121 TSRun contains five hits collections types:
122 1) a thread-local hits map,
123 2) a global atomic hits map
124 3) a global "mutex" hits map
125 4) a global G4StatAnalysis hits deque
126 5) a global G4ConvergenceTester hits deque
127
128 The thread-local hits map is the same as you will find in many other
129 examples.
130
131 The atomics hits map is the purpose of this example. Code-wise, the
132 implementation looks extremely similar to the thread-local version with
133 3 primary exceptions:
134 (1) construction - there should only be one instance so it should be a
135 static member variable or a pointer/reference to a single instance
136 (2) It does not need to, nor should be, summed in G4Run::Merge()
137 (3) destruction -- it should only be cleared by the master thread since
138 there is only one instance.
139
140 The "mutex" hits map is also included as reference for checking the results
141 accumulated by the thread-local hits maps and atomic hits maps. The
142 differences w.r.t. this hits maps are computed in
143 TSRunAction::EndOfRunAction
144
145 The "G4StatAnalysis" and "G4ConvergenceTester" hits deques are
146 memory-efficient version of the standard G4THitsMap. While maps are
147 ideal for scoring at the G4Event-level, where sparsity w.r.t. indices
148 is common; at the G4Run-level, these data structures require much
149 less memory overhead. Due to a lack of
150 G4ConvergenceTester::operator+=(G4ConvergenceTester), the static version
151 of G4ConvergenceTester is the only valid way to use G4ConvergenceTester
152 in a scoring container. This is not the case for G4StatAnalysis, which
153 can be used in lieu of G4double.
154
155 7- HOW TO RUN
156
157 - Execute ts_scorers in the 'interactive mode' with visualization:
158 % ./ts_scorers
159 and type in the commands from run.mac line by line:
160 Idle> /control/verbose 2
161 Idle> /tracking/verbose 1
162 Idle> /run/beamOn 10
163 Idle> ...
164 Idle> exit
165 or
166 Idle> /control/execute run.mac
167 ....
168 Idle> exit
169
170 - Execute ts_scorers in the 'batch' mode from macro files
171 (without visualization)
172 % ./ts_scorers run.mac
173 % ./ts_scorers run.mac > run.out
