Changes related to multithreading

.github/workflows/validation.yml

@@ -269,7 +269,7 @@ jobs:
           source ${{ env.REST_PATH }}/thisREST.sh
           cd ${{ env.REST_PATH }}/examples/restG4/07.FullChainDecay/
           restG4 fullChain.rml -o Run00001_U238_FullChainDecay.root
-          restRoot -b -q Validate.C'("Run00001_U238_FullChainDecay.root", 16)'
+          restRoot -b -q Validate.C'("Run00001_U238_FullChainDecay.root", 17)'
           restG4 singleDecay.rml -o Run00002_U238_SingleChainDecay.root
           restRoot -b -q Validate.C'("Run00002_U238_SingleChainDecay.root", 1)'
           export REST_ISOTOPE=Be7
@@ -374,6 +374,48 @@ jobs:
           restManager --c analysis.rml --f xrays_simulation.root --o xrays_simulation_analysis.root
           restRoot -b -q GetQE.C'("xrays_simulation_analysis.root")'
 
+  restG4-examples-12:
+    name: "Example 12: Generators"
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/lobis/root-geant4-garfield:rest-for-physics
+    needs: [ check-installation, restG4-examples-01 ]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Restore cache
+        uses: actions/cache@v3
+        id: framework-install-restG4-cache
+        with:
+          path: ${{ env.REST_PATH }}
+          key: ${{ env.BRANCH_NAME }}-${{ github.sha }}
+      - name: Run example
+        run: |
+          source ${{ env.REST_PATH }}/thisREST.sh
+          cd ${{ env.REST_PATH }}/examples/restG4/12.Generators/
+          restG4 CosineSquaredCircle.rml -o CosineSquaredCircle.root
+          restRoot -b -q Validate.C'("CosineSquaredCircle.root")'
+
+  restG4-examples-13:
+    name: "Example 13: IAXO"
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/lobis/root-geant4-garfield:rest-for-physics
+    needs: [ check-installation, restG4-examples-10 ]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Restore cache
+        uses: actions/cache@v3
+        id: framework-install-restG4-cache
+        with:
+          path: ${{ env.REST_PATH }}
+          key: ${{ env.BRANCH_NAME }}-${{ github.sha }}
+      - name: Run example
+        run: |
+          source ${{ env.REST_PATH }}/thisREST.sh
+          cd ${{ env.REST_PATH }}/examples/restG4/13.IAXO/
+          restG4 Neutrons.rml -o Neutrons.root -e 1
+          restRoot -b -q Validate.C'("Neutrons.root")'
+
   # Reference version of Geant4
 
   framework-install-reference:
@@ -459,6 +501,28 @@ jobs:
           restG4 NLDBD.rml -o Run00001_NLDBD_Test.root
           restRoot -b -q Validate.C'("Run00001_NLDBD_Test.root")'
 
+
+  restG4-examples-06-reference:
+    name: "Reference Example 06: Ion recoils"
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/lobis/root-geant4-garfield:rest-for-physics-reference-jun2022
+    needs: [ framework-install-reference, check-installation-reference ]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Restore cache
+        uses: actions/cache@v3
+        id: framework-install-restG4-cache-reference
+        with:
+          path: ${{ env.REST_PATH }}
+          key: ${{ env.BRANCH_NAME }}-${{ github.sha }}
+      - name: Run example
+        run: |
+          source ${{ env.REST_PATH }}/thisREST.sh
+          cd ${{ env.REST_PATH }}/examples/restG4/06.IonRecoils/
+          restG4 recoils.rml -o Run00001_F20_Recoils.root
+          restRoot -b -q Validate.C'("Run00001_F20_Recoils.root")'
+
   restG4-examples-07-reference:
     name: "Reference Example 07: Decay"
     runs-on: ubuntu-latest

.gitlab-ci.yml

@@ -124,7 +124,7 @@ Load REST Libraries:
     - cd ${CI_PROJECT_DIR}/install/examples/restG4/07.FullChainDecay/
     - restG4 fullChain.rml
     - restG4 singleDecay.rml
-    - restRoot -b -q Validate.C'("Run00001_U238_FullChainDecay.root", 16)'
+    - restRoot -b -q Validate.C'("Run00001_U238_FullChainDecay.root", 17)'
     - restRoot -b -q Validate.C'("Run00002_U238_SingleChainDecay.root", 1)'
     - export REST_ISOTOPE="Be7"
     - restG4 singleDecay.rml

README.md

@@ -1,5 +1,65 @@
 [![pipeline status](https://gitlab.cern.ch/rest-for-physics/restg4/badges/master/pipeline.svg)](https://gitlab.cern.ch/rest-for-physics/restg4/-/commits/master)
 [![Validation](https://github.com/rest-for-physics/restG4/actions/workflows/validation.yml/badge.svg)](https://github.com/rest-for-physics/restG4/actions/workflows/validation.yml)
 
-This README must be written yet! :(
+## Table of Contents
 
+- Usage
+- Structure of the output file
+
+## Usage
+
+Typing `restG4 -h` will show all available options.
+
+### Basic Usage
+
+`restG4 simulation.rml` will launch a simulation using `simulation.rml` as the configuration file. The output file will
+be saved to the specified path in the configuration.
+
+### Multithreading
+
+`restG4` makes use of the multithreading capabilities of Geant4 and can be used in multithreading mode to significantly
+increase simulation speed.
+
+- `restG4 simulation.rml -t 8` will launch a simulation using 8 worker threads.
+
+By default `restG4` is executed in serial mode (one single thread) and is equivalent to the `-t 0` option.
+
+Simulation results are determined by the random seed and the number of threads, so using different number of threads
+with the same seed will produce different results. Using the same seed and same number of threads produces the same
+results.
+
+The multithreading implementation of `restG4` is new and although it looks to work properly it may have some bugs. If
+you find one of such bugs, please post an issue [here](https://github.com/rest-for-physics/restG4/issues) with
+the `multithreading` label.
+
+We encourage our users to use the multithreading feature especially when performing exploratory simulations.
+
+### Overriding values from the RML
+
+The CLI interface allows to set a few different parameters without having to modify the RML.
+
+- `restG4 simulation.rml -o output.root` to specify the output file.
+- `restG4 simulation.rml -n 1000` to set the number of processed events
+  (`n` in Geant4's `/run/beamOn n` or `nEvents` in the rml configuration).
+- `restG4 simulation.rml -g geometry.gdml` to specify the geometry file.
+
+### Ending the simulation early
+
+The simulation run will naturally end when the selected number of events have been processed. They can either be
+specified in the RML file or via the `-n` flag on the CLI. However, the user can also specify additional conditions to
+end the simulation early.
+
+- `restG4 simulation.rml -N 1000` will signal the simulation to stop once 1000 events have been marked as valid (saved
+  on the output file). The final simulation will probably have a slightly higher number of entries than the value
+  specified in the case of multithreading as the worker threads may still be working on valid events, or they may not
+  have been saved yet. The number of processed events (the equivalent of `nEvents`) will be adjusted to the real number
+  of processed events, overriding the selected value of the user, so the resulting simulation would be equivalent to a
+  plain simulation using this value as `nEvents`. This holds more accurately the large the `-N` parameter.
+- `restG4 simulation.rml -S 1h20m30s` will signal the simulation to stop after 1 hour 20 minutes and 30 seconds have
+  elapsed since the start. You can specify any value using this format such as `1h15m`, `30s`, etc.
+- Sending the interrupt signal (typically via `CTRL+C`) will signal the simulation to stop, and it will attempt to save
+  the results into disk before closing the process.
+
+## Structure of the output file
+
+TODO

examples/01.NLDBD/NLDBD.rml

@@ -1,4 +1,4 @@
-<?xml version="4.0" encoding="UTF-8" standalone="no" ?>
+<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 
 <!-- Constructing XML-like REST metadata input file
      File : config.rml
@@ -56,8 +56,8 @@ By default REST units are mm, keV and degrees
 
             ///3. geant4 internal
             <!--<source use="geant4" particle="Na22" excitedLevel="0.0" fullChain="on">
-              <angularDist type="isotropic" />
-              <energyDist type="mono" energy="0.0" units="MeV" />
+              <angular type="isotropic" />
+              <energy type="mono" energy="0.0" units="MeV" />
             </source>-->
         </generator>
 
@@ -67,10 +67,12 @@ By default REST units are mm, keV and degrees
             <biasingVolume size="2050mm" position="(0,0,0)mm" factor="2" energyRange="(0,5)MeV"/>
         </biasing>
 
-        <storage sensitiveVolume="gas">
+        <detector>
             <parameter name="energyRange" value="(0,5)" units="MeV"/>
-            <activeVolume name="gas" chance="1" maxStepSize="1mm"/>
-        </storage>
+            <parameter name="activateAllVolumes" value="false"/>
+            <volume name="gas" sensitive="true" maxStepSize="1mm"/>
+        </detector>
+
     </TRestGeant4Metadata>
 
     <TRestGeant4PhysicsLists name="default" title="First physics list implementation.">

examples/01.NLDBD/Validate.C

@@ -47,7 +47,8 @@ Int_t Validate(const char* filename) {
     const bool isReferenceGeant4Version = geant4Metadata->GetGeant4Version() == "10.4.3";
 
     if (geant4Metadata->GetNumberOfActiveVolumes() != 1) {
-        cout << "The number of registered does not match the reference value of 1" << endl;
+        cout << "The number of active volumes does not match the reference value of 1. Value: "
+             << geant4Metadata->GetNumberOfActiveVolumes() << endl;
         return 7;
     }
 
@@ -62,10 +63,10 @@ Int_t Validate(const char* filename) {
     const double averageSensitiveEnergyRef = (!isReferenceGeant4Version) ? 2280.96 : 2221.55;
 
     double averageNumberOfHits = 0;
-    const double averageNumberOfHitsRef = (!isReferenceGeant4Version) ? 3071.17 : 342.37;
+    const double averageNumberOfHitsRef = (!isReferenceGeant4Version) ? 5371.17 : 353.2;
 
     double averageNumberOfTracks = 0;
-    const double averageNumberOfTracksRef = (!isReferenceGeant4Version) ? 2161.43 : 10.11;
+    const double averageNumberOfTracksRef = (!isReferenceGeant4Version) ? 2300 : 10.83;
 
     TVector3 averagePosition = {};
     const TVector3 averagePositionRef = (!isReferenceGeant4Version) ? TVector3(-38.8987, 27.5536, 91.3969)

examples/02.TREXDM/FullChainFromReadout.rml

@@ -41,16 +41,16 @@
 
         <generator type="virtualWall" position="(0,0,158-1.25+0.001)mm" rotation="(0,0,0)" lenX="20cm" lenY="20cm">
             <source particle="${REST_ISOTOPE}" excitedLevel="0.0" fullChain="on">
-                <angularDist type="isotropic"/>
-                <energyDist type="mono" energy="0.0" units="keV"/>
+                <angular type="isotropic"/>
+                <energy type="mono" energy="0.0" units="keV"/>
             </source>
         </generator>
 
-
-        <storage sensitiveVolume="gas">
+        <detector>
             <parameter name="energyRange" value="(0,1)" units="GeV"/>
-            <activeVolume name="gas" chance="1" maxStepSize="${STEP_SIZE}"/>
-        </storage>
+            <volume name="gas" sensitive="true" maxStepSize="${STEP_SIZE}"/>
+        </detector>
+
     </TRestGeant4Metadata>
 
     <TRestGeant4PhysicsLists name="default" file="common/physics.xml"/>

examples/03.Fluorescence/electron.rml

@@ -1,4 +1,4 @@
-<?xml version="4.0" encoding="UTF-8" standalone="no" ?>
+<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 
 <!-- Constructing XML-like REST metadata input file
      File : config.rml
@@ -42,15 +42,16 @@ By default REST units are mm, keV and degrees
 
         <generator type="point" position="(0,0,-200)" units="mm">
             <source particle="e-">
-                <angularDist type="flux" direction="(0,0,1)"/>
-                <energyDist type="mono" energy="30.0" units="keV"/>
+                <angular type="flux" direction="(0,0,1)"/>
+                <energy type="mono" energy="30.0" units="keV"/>
             </source>
         </generator>
 
-        <storage sensitiveVolume="detector">
+        <detector>
             <parameter name="energyRange" value="(0,30)" units="keV"/>
-            <activeVolume name="detector" chance="1" maxStepSize="1mm"/>
-        </storage>
+            <volume name="detector" sensitive="true" maxStepSize="1mm"/>
+        </detector>
+
     </TRestGeant4Metadata>
 
     <TRestGeant4PhysicsLists name="default" title="First physics list implementation.">

examples/03.Fluorescence/gamma.rml

@@ -1,4 +1,4 @@
-<?xml version="4.0" encoding="UTF-8" standalone="no" ?>
+<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 
 <!-- Constructing XML-like REST metadata input file
      File : config.rml
@@ -41,15 +41,16 @@ By default REST units are mm, keV and degrees
 
         <generator type="point" position="(0,0,-200)" units="mm">
             <source particle="gamma">
-                <angularDist type="flux" direction="(0,0,1)"/>
-                <energyDist type="mono" energy="30.0" units="keV"/>
+                <angular type="flux" direction="(0,0,1)"/>
+                <energy type="mono" energy="30.0" units="keV"/>
             </source>
         </generator>
 
-        <storage sensitiveVolume="detector">
+        <detector>
             <parameter name="energyRange" value="(0,30)" units="keV"/>
-            <activeVolume name="detector" chance="1"/>
-        </storage>
+            <volume name="detector" sensitive="true"/>
+        </detector>
+
     </TRestGeant4Metadata>
 
     <TRestGeant4PhysicsLists name="default" title="First physics list implementation.">

examples/04.MuonScan/CosmicMuonsFromCircle.rml

@@ -18,9 +18,9 @@
         <parameter name="gdmlFile" value="setup.gdml"/>
         <parameter name="subEventTimeDelay" value="100us"/>
 
-        <parameter name="nEvents" value="5000"/>
+        <parameter name="nEvents" value="10000"/>
 
-        <parameter name="seed" value="17021981"/>
+        <parameter name="seed" value="1702198"/>
         <parameter name="saveAllEvents" value="false"/>
         <parameter name="printProgress" value="true"/>
 
@@ -29,16 +29,17 @@
                    position="(0,100,0)mm" size="(400,0,0)mm"
                    rotationAngle="90deg" rotationAxis="(1,0,0)">
             <source particle="mu-" excitedLevel="0.0" fullChain="on">
-                <energyDist type="TH1D" file="Muons.root" spctName="cosmicmuon"/>
-                <angularDist type="TH1D" file="CosmicAngles.root" spctName="Theta2" direction="(0,-1,0)"/>
+                <energy type="TH1D" file="Muons.root" name="cosmicmuon"/>
+                <angular type="formula" name="Cos2" direction="(0,-1,0)"/>
             </source>
         </generator>
 
-        <storage sensitiveVolume="det_dw_01">
+        <detector>
             <parameter name="energyRange" value="(0,10)" units="GeV"/>
-            <activeVolume name="det_dw_01" chance="1" maxStepSize="1mm"/>
-            <activeVolume name="det_up_01" chance="1" maxStepSize="1mm"/>
-        </storage>
+            <volume name="det_dw_01" sensitive="true" maxStepSize="1mm"/>
+            <volume name="det_up_01" maxStepSize="1mm"/>
+        </detector>
+
     </TRestGeant4Metadata>
 
     <TRestGeant4PhysicsLists name="default" title="First physics list implementation." verboseLevel="warning">

examples/04.MuonScan/CosmicMuonsFromWall.rml

@@ -22,23 +22,25 @@ First concept author G. Luzón (16-11-2020) -->
         <parameter name="subEventTimeDelay" value="100us"/>
 
         <parameter name="nEvents" value="1000"/>
+        <parameter name="seed" value="17021981"/>
 
         <parameter name="saveAllEvents" value="false"/>
         <parameter name="printProgress" value="true"/>
 
         <generator type="surface" shape="wall" position="(0,0,50)cm" size="(30,30,0)cm" rotationAngle="0"
                    rotationAxis="(1,0,0)">
             <source particle="mu-" excitedLevel="0.0" fullChain="on">
-                <energyDist type="TH1D" file="Muons.root" spctName="cosmicmuon"/>
-                <angularDist type="TH1D" file="CosmicAngles.root" spctName="Theta2" direction="(0,0,-1)"/>
+                <energy type="TH1D" file="Muons.root" name="cosmicmuon"/>
+                <angular type="formula" name="Cos2" direction="(0,0,-1)"/>
             </source>
         </generator>
 
-        <storage sensitiveVolume="det_dw_01">
+        <detector>
             <parameter name="energyRange" value="(0,10)" units="GeV"/>
-            <activeVolume name="det_dw_01" chance="1" maxStepSize="1mm"/>
-            <activeVolume name="det_up_01" chance="1" maxStepSize="1mm"/>
-        </storage>
+            <volume name="det_dw_01" sensitive="true" maxStepSize="1mm"/>
+            <volume name="det_up_01" maxStepSize="1mm"/>
+        </detector>
+
     </TRestGeant4Metadata>
 
     <TRestGeant4PhysicsLists name="default" title="First physics list implementation." verboseLevel="warning">

examples/04.MuonScan/Muon.rml

@@ -24,16 +24,16 @@
 
         <generator type="point" position="(0,0,-50)cm">
             <source particle="mu-" excitedLevel="0.0">
-                <energyDist type="mono" energy="100GeV"/>
-                <angularDist type="flux" direction="(0,0,1)"/>
+                <energy type="mono" energy="100GeV"/>
+                <angular type="flux" direction="(0,0,1)"/>
             </source>
         </generator>
 
-        <storage sensitiveVolume="det_dw_01">
+        <detector>
             <parameter name="energyRange" value="(0,10)" units="GeV"/>
-            <activeVolume name="det_dw_01" chance="1" maxStepSize="1mm"/>
-            <activeVolume name="det_up_01" chance="1" maxStepSize="1mm"/>
-        </storage>
+            <volume name="det_dw_01" sensitive="true" maxStepSize="1mm"/>
+            <volume name="det_up_01" maxStepSize="1mm"/>
+        </detector>
 
     </TRestGeant4Metadata>