Merge pull request #469 from OpenGATE/spatial_blur_for_param_volumes

Consolidation3

Author: dsarrut

core/opengate_core/opengate_lib/GateSimulationStatisticsActor.cpp

@@ -54,18 +54,16 @@ void GateSimulationStatisticsActor::StartSimulationAction() {
   fStartRunTimeIsSet = false;
 
   // initialise the counts
-  fCounts["run_count"] = 0;
-  fCounts["event_count"] = 0;
-  fCounts["track_count"] = 0;
-  fCounts["step_count"] = 0;
+  fCounts["runs"] = 0;
+  fCounts["events"] = 0;
+  fCounts["tracks"] = 0;
+  fCounts["steps"] = 0;
 }
 
 py::dict GateSimulationStatisticsActor::GetCounts() {
   auto dd = py::dict(
-      "run_count"_a = fCounts["run_count"],
-      "event_count"_a = fCounts["event_count"],
-      "track_count"_a = fCounts["track_count"],
-      "step_count"_a = fCounts["step_count"],
+      "runs"_a = fCounts["runs"], "events"_a = fCounts["events"],
+      "tracks"_a = fCounts["tracks"], "steps"_a = fCounts["steps"],
       "duration"_a = fCountsD["duration"], "init"_a = fCountsD["init"],
       "start_time"_a = fCountsStr["start_time"],
       "stop_time"_a = fCountsStr["stop_time"], "track_types"_a = fTrackTypes);
@@ -124,10 +122,10 @@ void GateSimulationStatisticsActor::EndOfSimulationWorkerAction(
   G4AutoLock mutex(&GateSimulationStatisticsActorMutex);
   threadLocal_t &data = threadLocalData.Get();
   // merge all threads (need mutex)
-  fCounts["run_count"] += data.fRunCount;
-  fCounts["event_count"] += data.fEventCount;
-  fCounts["track_count"] += data.fTrackCount;
-  fCounts["step_count"] += data.fStepCount;
+  fCounts["runs"] += data.fRunCount;
+  fCounts["events"] += data.fEventCount;
+  fCounts["tracks"] += data.fTrackCount;
+  fCounts["steps"] += data.fStepCount;
   if (fTrackTypesFlag) {
     for (auto v : data.fTrackTypes) {
       if (fTrackTypes.count(v.first) == 0)

core/opengate_core/opengate_lib/digitizer/GateDigitizerSpatialBlurringActor.cpp

@@ -108,6 +108,13 @@ void GateDigitizerSpatialBlurringActor::BlurCurrentThreeVectorValue() {
     l.fNavigator->LocateGlobalPointAndUpdateTouchable(vec, &fTouchableHistory);
     auto vid = GateUniqueVolumeID::New(&fTouchableHistory);
     phys_vol = vid->GetVolumeDepthID().back().fVolume;
+    // If the volume is parameterised, we consider the parent volume to compute
+    // the extent (otherwise the keep in solid will consider one single instance
+    // of the repeated solid, instead of the whole parameterised volume).
+    if (phys_vol->IsParameterised()) {
+      auto n = vid->GetVolumeDepthID().size();
+      phys_vol = vid->GetVolumeDepthID()[n - 2].fVolume;
+    }
   }
 
   // consider local position

docs/source/user_guide_2_4_actors.md

@@ -34,8 +34,8 @@ Several tests depict usage of DoseActor: test008, test009, test021, test035, etc
 
 ````python
 dose = sim.add_actor("DoseActor", "dose")
-dose.output = output_path / "test008-edep.mhd"
-dose.mother = "waterbox"
+dose.output_filename = output_path / "test008-edep.mhd"
+dose.attached_to = "waterbox"
 dose.size = [99, 99, 99]
 mm = gate.g4_units.mm
 dose.spacing = [2 * mm, 2 * mm, 2 * mm]
@@ -50,7 +50,7 @@ A PhaseSpaceActor stores any set of particles reaching a given volume during the
 
 ```python
 phsp = sim.add_actor("PhaseSpaceActor", "PhaseSpace")
-phsp.mother = plane.name
+phsp.attached_to = plane.name
 phsp.attributes = [
     "KineticEnergy",
     "Weight",
@@ -64,7 +64,7 @@ phsp.attributes = [
     "LocalTime",
     "EventPosition",
 ]
-phsp.output = "test019_hits.root"
+phsp.output_filename = "test019_hits.root"
 f = sim.add_filter("ParticleFilter", "f")
 f.particle = "gamma"
 phsp.filters.append(f)
@@ -105,21 +105,28 @@ Note: all three conditions may be combined (if one condition is True, the partic
 
 ### Hits-related actors (digitizer)
 
-In legacy Gate, the digitizer module is a set of tools used to simulate the behaviour of the scanner detectors and signal processing chain. The tools consider a list of interactions occurring in the detector (e.g. in the crystal), named as "hits collections". Then, this collection of hits is processed and filtered by different modules to end up with a final digital value. To start a digitizer chain, we must start defining a `HitsCollectionActor`, explained in the next sections.
+The digitizer module is a set of tools used to simulate the behaviour of the scanner detectors and signal processing chain. The tools consider a list of interactions occurring in the detector (e.g. in the crystal), named as "hits collections". This collection of hits is then processed and filtered by different modules to produce a final digital value. To initiate a digitizer chain, you begin by defining a `HitsCollectionActor`, as explained in the following sections.
+
+Common features of all digitizer actors:
+
+- Most digitizers have a root output (with the exception for `DigitizerProjectionActor`, which outputs an image). This output can be written to disk with `my_digitizer.root_output.write_to_disk = True`. Multiple digitizers can share the same root output file, with each storing data in a separate branch named after the actor.
+
+- `authorize_repeated_volumes`: Set this to True if you want the digitizer to work with repeated volumes. This is useful, for example, when the digitizer is attached to a region with repeated crystal volumes (as in a PET system). However, if you are repeating some SPECT heads, you may not want the digitizer to record hits from both heads in the same file (in which case, set the flag to False).
+
 
 #### DigitizerHitsCollectionActor
 
 The `DigitizerHitsCollectionActor` is an actor that collects hits occurring in a given volume (or one of its daughters). Every time a step occurs in the volume a list of attributes is recorded. The list of attributes is defined by the user as follows:
 
 ```python
 hc = sim.add_actor('DigitizerHitsCollectionActor', 'Hits')
-hc.mother = ['crystal1', 'crystal2']
-hc.output = 'test_hits.root'
+hc.attached_to = ['crystal1', 'crystal2']
+hc.output_filename = 'test_hits.root'
 hc.attributes = ['TotalEnergyDeposit', 'KineticEnergy', 'PostPosition',
                  'CreatorProcess', 'GlobalTime', 'VolumeName', 'RunID', 'ThreadID', 'TrackID']
 ```
 
-In this example, the actor is attached (`mother` option) to several volumes (`crystal1` and `crystal2` ) but most of the time, one single volume is sufficient. This volume is important: every time an interaction (a step) is occurring in this volume, a hit will be created. The list of attributes is defined with the given array of attribute names. The names of the attributes are as close as possible to the Geant4 terminology. They can be of a few types: 3 (ThreeVector), D (double), S (string), I (int), U (unique volume ID, see DigitizerAdderActor section). The list of available attributes is defined in the file `core/opengate_core/opengate_lib/GateDigiAttributeList.cpp` and can be printed with:
+In this example, the actor is attached (`attached_to` option) to several volumes (`crystal1` and `crystal2` ) but most of the time, one single volume is sufficient. This volume is important: every time an interaction (a step) is occurring in this volume, a hit will be created. The list of attributes is defined with the given array of attribute names. The names of the attributes are as close as possible to the Geant4 terminology. They can be of a few types: 3 (ThreeVector), D (double), S (string), I (int), U (unique volume ID, see `DigitizerAdderActor` section). The list of available attributes is defined in the file `core/opengate_core/opengate_lib/GateDigiAttributeList.cpp` and can be printed with:
 
 ```python
 import opengate_core as gate_core
@@ -192,29 +199,29 @@ The two actors used to convert some `hits` to one `digi` are "DigitizerHitsAdder
 This actor groups the hits per different volumes according to the option `group_volume` (by default, this is the deeper volume that contains the hit). All hits (in the same event) occurring in the same volume are gathered into one single digi according to one of the two available policies:
 
 - EnergyWeightedCentroidPosition:
-  - the final energy ("TotalEnergyDeposit") is the sum of all deposited energy
-  - the position ("PostPosition") is the energy-weighted centroid position
-  - the time ("GlobalTime") is the time of the earliest hit
+  - the final energy (`TotalEnergyDeposit`") is the sum of all deposited energy
+  - the position (`PostPosition`) is the energy-weighted centroid position
+  - the time (`GlobalTime`) is the time of the earliest hit
 
 - EnergyWinnerPosition
-  - the final energy ("TotalEnergyDeposit") is the energy of the hit with the largest deposited energy
-  - the position ("PostPosition") is the position of the hit with the largest deposited energy
-  - the time ("GlobalTime") is the time of the earliest hit
+  - the final energy (`TotalEnergyDeposit`) is the energy of the hit with the largest deposited energy
+  - the position (`PostPosition`) is the position of the hit with the largest deposited energy
+  - the time (`GlobalTime`) is the time of the earliest hit
 
 ```python
 sc = sim.add_actor("DigitizerAdderActor", "Singles")
-sc.output = 'test_hits.root'
+sc.output_filename = 'test_hits.root'
 sc.input_digi_collection = "Hits"
 sc.policy = "EnergyWeightedCentroidPosition"
 # sc.policy = "EnergyWinnerPosition"
 sc.group_volume = crystal.name
 ```
 
-Note that this actor is only triggered at the end of an event, so the `mother` volume to which it is attached has no effect. Examples are available in test 037.
+Note that this actor is only triggered at the end of an event, so the `attached_to` volume to which it is attached has no effect. Examples are available in test 037.
 
 #### DigitizerReadoutActor
 
-This actor is the same as the previous one (DigitizerHitsAdderActor) with one additional option: the resulting positions of the digi are set in the center of the defined volumes (discretized). We keep two different actors (Adder and Readout) to be close to the previous legacy GATE versions. The additional option `discretize_volume` indicates the volume name in which the discrete position will be taken.
+This actor is the same as the previous one (`DigitizerHitsAdderActor`) with one additional option: the resulting positions of the digi are set in the center of the defined volumes (discretized). We keep two different actors (Adder and Readout) to be close to the previous legacy GATE versions. The additional option `discretize_volume` indicates the volume name in which the discrete position will be taken.
 
 ```python
 sc = sim.add_actor("HitsReadoutActor", "Singles")
@@ -239,7 +246,7 @@ For Linear: `blur_reference_value`, `blur_reference_value` and `blur_slope`  EQU
 
 ```python
 bc = sim.add_actor("DigitizerBlurringActor", "Singles_with_blur")
-bc.output = "output.root"
+bc.output_filename = "output.root"
 bc.input_digi_collection = "Singles_readout"
 bc.blur_attribute = "GlobalTime"
 bc.blur_method = "Gaussian"
@@ -306,7 +313,7 @@ As parameters, Coincidence Sorter expects as input:
 
 #### Policies
 
-When more than two singles are found in coincidence, several type of behavior could be implemented. GATE allows to model 5 different policies to treat multiple coincidences that can be used. Mutliple coincidences or "multicoincidence" are composed of at least three singles detected in the same **time window** that could form coincidence. The list of policies along with their explanation are given in Table below. The 5 policies, same as in [Gate9.X](https://opengate.readthedocs.io/en/latest/digitizer_and_detector_modeling.html#id43), were selected for the implementation as the most used. If an option that you need is missing, please, don't hesitate to report it in [Issues](https://github.com/OpenGATE/opengate/issues).
+When more than two singles are found in coincidence, several type of behavior could be implemented. GATE allows to model 5 different policies to treat multiple coincidences that can be used. Multiple coincidences or "multicoincidence" are composed of at least three singles detected in the same **time window** that could form coincidence. The list of policies along with their explanation are given in Table below. The 5 policies, same as in [Gate9.X](https://opengate.readthedocs.io/en/latest/digitizer_and_detector_modeling.html#id43), were selected for the implementation as the most used. If an option that you need is missing, please, don't hesitate to report it in [Issues](https://github.com/OpenGATE/opengate/issues).
 
 
 **Available multiple policies and associated meaning**. When a multiple coincidence involving n *singles* is processed, it is first decomposed into a list of n·(n−1) pairs which are analyzed individually.
@@ -368,7 +375,7 @@ The Compton splitting actor generates N particles, each with a weight equal to t
 
 ```python
 compt_splitting_actor = sim.add_actor("ComptSplittingActor", "ComptSplitting")
-compt_splitting_actor.mother = W_tubs.name
+compt_splitting_actor.attached_to = W_tubs.name
 compt_splitting_actor.splitting_factor = nb_split
 compt_splitting_actor.russian_roulette = True
 compt_splitting_actor.rotation_vector_director = True

opengate/actors/miscactors.py

@@ -8,7 +8,7 @@
 from ..exception import warning
 
 
-def _setter_hook_output_filename(self, output_filename):
+def _setter_hook_stats_actor_output_filename(self, output_filename):
     # By default, write_to_disk is False.
     # However, if user actively sets the output_filename
     # s/he most likely wants to write to disk also
@@ -40,6 +40,7 @@ class ActorOutputStatisticsActor(ActorOutputBase):
                 "Relative paths and filenames are taken "
                 "relative to the global simulation output folder "
                 "set via the Simulation.output_dir option. ",
+                "setter_hook": _setter_hook_stats_actor_output_filename,
             },
         ),
         "write_to_disk": (
@@ -57,10 +58,10 @@ def __init__(self, *args, **kwargs):
 
         # predefine the merged_data
         self.merged_data = Box()
-        self.merged_data.run_count = 0
-        self.merged_data.event_count = 0
-        self.merged_data.track_count = 0
-        self.merged_data.step_count = 0
+        self.merged_data.runs = 0
+        self.merged_data.events = 0
+        self.merged_data.tracks = 0
+        self.merged_data.steps = 0
         self.merged_data.duration = 0
         self.merged_data.start_time = 0
         self.merged_data.stop_time = 0
@@ -74,7 +75,7 @@ def __init__(self, *args, **kwargs):
     def pps(self):
         if self.merged_data.duration != 0:
             return int(
-                self.merged_data.event_count / (self.merged_data.duration / g4_units.s)
+                self.merged_data.events / (self.merged_data.duration / g4_units.s)
             )
         else:
             return 0
@@ -83,7 +84,7 @@ def pps(self):
     def tps(self):
         if self.merged_data.duration != 0:
             return int(
-                self.merged_data.track_count / (self.merged_data.duration / g4_units.s)
+                self.merged_data.tracks / (self.merged_data.duration / g4_units.s)
             )
         else:
             return 0
@@ -92,7 +93,7 @@ def tps(self):
     def sps(self):
         if self.merged_data.duration != 0:
             return int(
-                self.merged_data.step_count / (self.merged_data.duration / g4_units.s)
+                self.merged_data.steps / (self.merged_data.duration / g4_units.s)
             )
         else:
             return 0
@@ -112,10 +113,10 @@ def get_data(self, **kwargs):
 
     def get_processed_output(self):
         d = {}
-        d["runs"] = {"value": self.merged_data.run_count, "unit": None}
-        d["events"] = {"value": self.merged_data.event_count, "unit": None}
-        d["tracks"] = {"value": self.merged_data.track_count, "unit": None}
-        d["steps"] = {"value": self.merged_data.step_count, "unit": None}
+        d["runs"] = {"value": self.merged_data.runs, "unit": None}
+        d["events"] = {"value": self.merged_data.events, "unit": None}
+        d["tracks"] = {"value": self.merged_data.tracks, "unit": None}
+        d["steps"] = {"value": self.merged_data.steps, "unit": None}
         val, unit = g4_best_unit_tuple(self.merged_data.init, "Time")
         d["init"] = {
             "value": val,
@@ -209,12 +210,6 @@ def __initcpp__(self):
         g4.GateSimulationStatisticsActor.__init__(self, self.user_info)
         self.AddActions({"StartSimulationAction", "EndSimulationAction"})
 
-    # def __finalize_init__(self):
-    #     super().__finalize_init__()
-    #     # this attribute is considered sometimes in the read_stat_file
-    #     # we declare it here to avoid warning
-    #     self.known_attributes.add("date")
-
     def __str__(self):
         s = self.user_output["stats"].__str__()
         return s
@@ -233,7 +228,9 @@ def initialize(self):
 
     def StartSimulationAction(self):
         g4.GateSimulationStatisticsActor.StartSimulationAction(self)
-        self.user_output.stats.nb_threads = self.simulation.number_of_threads
+        self.user_output.stats.merged_data.nb_threads = (
+            self.simulation.number_of_threads
+        )
 
     def EndSimulationAction(self):
         g4.GateSimulationStatisticsActor.EndSimulationAction(self)

opengate/contrib/linacs/elektasynergy.py

@@ -37,7 +37,7 @@ def add_linac(sim, name="linac", sad=1000):
     # sim.volume_manager.add_material_database('../contrib/elekta_synergy_materials.db')
 
     # check overlap
-    sim.g4_check_overlap_flag = True
+    sim.check_volumes_overlap = True
 
     # global box
     linac = add_empty_linac_box(sim, name, sad)

opengate/contrib/phantoms/nemaiec.py

@@ -39,7 +39,7 @@ def add_iec_phantom(
     create_material(simulation)
 
     # check overlap only for debug
-    simulation.g4_check_overlap_flag = check_overlap
+    simulation.check_volumes_overlap = check_overlap
 
     # Outside structure
     iec, _, _ = add_iec_body(simulation, name)

opengate/contrib/spect/ge_discovery_nm670.py

@@ -58,7 +58,7 @@ def add_spect_head(sim, name="spect", collimator_type="lehr", debug=False):
         sim.volume_manager.add_material_database(fdb)
 
     # check overlap
-    sim.g4_check_overlap_flag = False  # set to True for debug
+    sim.check_volumes_overlap = False  # set to True for debug
 
     # spect head
     head, lead_cover = add_spect_box(sim, name)

opengate/contrib/spect/siemens_intevo.py

@@ -35,7 +35,7 @@ def add_spect_head(sim, name="spect", collimator_type="lehr", debug=False):
         sim.volume_manager.add_material_database(fdb)
 
     # check overlap
-    sim.g4_check_overlap_flag = debug
+    sim.check_volumes_overlap = debug
 
     # main box
     head = add_head_box(sim, name)

opengate/geometry/volumes.py

@@ -239,9 +239,10 @@ def __getstate__(self):
 
     def __finalize_init__(self):
         super().__finalize_init__()
-        # need to add this explciitly because anytree does not properly declare
+        # need to add this explicitly because anytree does not properly declare
         # the attribute __parent in the NodeMixin.__init__ which leads to falls warnings
         self.known_attributes.add("_NodeMixin__parent")
+        self.known_attributes.add("_NodeMixin__children")
 
     def _update_node(self):
         """Internal method which retrieves the volume object

opengate/tests/src/test004_simple_mt.py

@@ -77,7 +77,7 @@
     # gate_test4_simulation_stats_actor
     # Gate mac/main.mac
     stats_ref = utility.read_stat_file(paths.gate_output / "stat.txt")
-    stats_ref.counts.run_count = sim.number_of_threads
+    stats_ref.counts.runs = sim.number_of_threads
     is_ok = utility.assert_stats(stats, stats_ref, tolerance=0.01)
 
     utility.test_ok(is_ok)

opengate/tests/src/test004_simple_visu_gdml.py

@@ -59,7 +59,7 @@
     sim.run()
 
     stats = sim.get_actor("Stats")
-    stats.counts.run_count = 1
+    stats.counts.runs = 1
 
     # gate_test4_simulation_stats_actor
     # Gate mac/main.mac

opengate/tests/src/test006_runs.py

@@ -87,10 +87,10 @@
 
     stats_ref = gate.actors.miscactors.SimulationStatisticsActor(name="stat_ref")
     c = stats_ref.counts
-    c.run_count = 3
-    c.event_count = 7800
-    c.track_count = 37584  # 56394
-    c.step_count = 266582  # 217234
+    c.runs = 3
+    c.events = 7800
+    c.tracks = 37584  # 56394
+    c.steps = 266582  # 217234
     # stats_ref.pps = 4059.6 3 3112.2
     c.duration = 1 / 4059.6 * 7800 * sec
     print("-" * 80)

opengate/tests/src/test007_volumes.py

@@ -215,10 +215,10 @@ def check_mat(se):
     # check
     stats_ref = gate.actors.miscactors.SimulationStatisticsActor(name="ref")
     c = stats_ref.counts
-    c.run_count = 1
-    c.event_count = 1280
-    c.track_count = 17034  # 25668
-    c.step_count = 78096  # 99465
+    c.runs = 1
+    c.events = 1280
+    c.tracks = 17034  # 25668
+    c.steps = 78096  # 99465
     # stats_ref.pps = 506.6
     sec = gate.g4_units.second
     c.duration = 2.5267 * sec