diff --git a/documentation/docs/components/geomodeltools/gmcat/index.md b/documentation/docs/components/geomodeltools/gmcat/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..79e75363eb22c9b4616e4d4cc96dd7809cf33f97
--- /dev/null
+++ b/documentation/docs/components/geomodeltools/gmcat/index.md
@@ -0,0 +1,34 @@
+# GeoModelCat
+
+GeoModelCat (`gmcat`) is a command line tool that allows to concatenate different geometry files into a single final SQLite file. It is possible to concatenate plugins (.dylib/.so) and/or SQLite (.db) files.
+
+*gmcat* has the following parameters:
+
+``` bash
+-o [MANDATORY] Name of the output .db file
+-v [OPTIONAL] Print verbose output to the screen (default: direct verbose output to /tmp)
+-g [OPTIONAL] Path to the local GeoModelATLAS repository (default: .)
+
+```
+
+## Examples
+
+In order to combine three different plugins into one single detector file one need to call gmcat in the following way:
+
+```bash
+
+./gmcat libPixelGeoPlugin.0.0.1.dylib libSCTGeoPlugin.0.0.1.dylib libTRTGeoPlugin.0.0.1.dylib -o InnerDetector.db
+
+```
+
+<!--To convert a GDML geometry and save it in SQLite format with *gdml2gm* :-->
+<!--``` bash-->
+<!--./gdml2gm -f myGeometry.gdml -o myGeometry.db-->
+<!--``` -->
+<!---->
+<!--To visualize a GDML geometry with *gmex*, the user has to set the following environment variable: GDML_FILE_NAME. It has to point to the GDML file that the user wants to plug into *gmex*. Then it is sufficient to call gmex together with the *libGDMLtoGM.dylib/so* library:-->
+<!---->
+<!--``` bash-->
+<!--export GDML_FILE_NAME=<path-to-my-geometry-file>/myGeometry.gdml-->
+<!--./gmex ../lib/libGDMLtoGM.dylib -->
+<!--``` -->
diff --git a/documentation/docs/components/geomodeltools/gmstatistics/index.md b/documentation/docs/components/geomodeltools/gmstatistics/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..87fde0f53b1b424733a0c67335629cac1c1d7a08
--- /dev/null
+++ b/documentation/docs/components/geomodeltools/gmstatistics/index.md
@@ -0,0 +1,87 @@
+# GeoModelStatistics
+
+GeoModelStatistics (`gmstatistics`) is a command line tool that allows to extract information on the memory footprint of your detector description code. It takes one or more plugins (.dylib/.so) as input.
+
+*gmstatistics* has the following parameters:
+
+``` bash
+./gmstatistics [-p] [plugin1.dylib] [plugin2.dylib]
+
+```
+
+## Examples
+
+If you want to analyse the memory occupancy of your plugin (i.e. PixelGeoPlugin) you can type:
+
+```bash
+./gmstatistics ../lib/libPixelGeoPlugin.0.dylib
+
+```
+
+This is the output retrieved by gmstatistics:
+
+```bash
+ GeoLogVol 9998 instances 2239552 bytes
+ GeoTransform 9856 instances 1419264 bytes
+ GeoBox 9835 instances 472080 bytes
+ GeoPhysVol 7941 instances 1905840 bytes
+ GeoNameTag 4904 instances 235392 bytes
+ GeoIdentifierTag 4293 instances 68688 bytes
+ GeoFullPhysVol 4088 instances 1896832 bytes
+ GeoAlignableTransform 2059 instances 494160 bytes
+ GeoAlignableTransform[216] 2058 instances 32928 bytes
+ GeoShapeShift 1914 instances 306240 bytes
+ GeoShapeSubtraction 1190 instances 57120 bytes
+ GeoMaterial 812 instances 116928 bytes
+ GeoMaterial[56] 794 instances 48752 bytes
+ GeoTube 746 instances 35808 bytes
+ GeoMaterial[120] 571 instances 25408 bytes
+ GeoShapeUnion 492 instances 23616 bytes
+ GeoMaterial[72] 447 instances 35904 bytes
+ GeoTubs 190 instances 12160 bytes
+ GeoMaterial[64] 167 instances 5280 bytes
+ GeoLogVol[32] 132 instances 4544 bytes
+ GeoElement 97 instances 7760 bytes
+ GeoMaterial[128] 87 instances 2080 bytes
+ GeoPhysVol[48] 71 instances 2720 bytes
+ GeoMaterial[32] 60 instances 1920 bytes
+ GeoPhysVol[40] 49 instances 3392 bytes
+ GeoSimplePolygonBrep 45 instances 3600 bytes
+ GeoTrap 44 instances 4928 bytes
+ GeoMaterial[136] 36 instances 2144 bytes
+ GeoSimplePolygonBrep[40] 29 instances 960 bytes
+ GeoSimplePolygonBrep[64] 29 instances 960 bytes
+ GeoPhysVol[56] 22 instances 2560 bytes
+ GeoTrd 20 instances 1280 bytes
+ GeoSimplePolygonBrep[32] 16 instances 1120 bytes
+ GeoCons 15 instances 1200 bytes
+ GeoSimplePolygonBrep[48] 11 instances 832 bytes
+ GeoFullPhysVol[56] 10 instances 17408 bytes
+ GeoPgon 10 instances 1280 bytes
+ GeoSimplePolygonBrep[56] 9 instances 576 bytes
+ GeoPgon[48] 9 instances 144 bytes
+ GeoPgon[56] 9 instances 144 bytes
+ GeoPara 8 instances 640 bytes
+ GeoFullPhysVol[40] 7 instances 20992 bytes
+ GeoPgon[104] 7 instances 112 bytes
+ GeoSimplePolygonBrep[72] 3 instances 192 bytes
+ GeoPgon[72] 2 instances 32 bytes
+ GeoPgon[80] 2 instances 32 bytes
+ GeoNameTag[32] 1 instances 32 bytes
+ GeoElement[56] 1 instances 16 bytes
+ GeoPgon[96] 1 instances 16 bytes
+Total GeoModel object allocation: 9.51557MB
+
+```
+
+<!--To analyse a GDML geometry and save it in SQLite format with *gdml2gm* :-->
+<!--``` bash-->
+<!--./gdml2gm -f myGeometry.gdml -o myGeometry.db-->
+<!--``` -->
+<!---->
+<!--To visualize a GDML geometry with *gmex*, the user has to set the following environment variable: GDML_FILE_NAME. It has to point to the GDML file that the user wants to plug into *gmex*. Then it is sufficient to call gmex together with the *libGDMLtoGM.dylib/so* library:-->
+<!---->
+<!--``` bash-->
+<!--export GDML_FILE_NAME=<path-to-my-geometry-file>/myGeometry.gdml-->
+<!--./gmex ../lib/libGDMLtoGM.dylib -->
+<!--``` -->
diff --git a/documentation/docs/components/geomodelvisualization/gmex/Fig 1.png b/documentation/docs/components/geomodelvisualization/gmex/Fig 1.png
new file mode 100644
index 0000000000000000000000000000000000000000..96dc92a81ef75a0bdd0187636bd9f5307c666f51
Binary files /dev/null and b/documentation/docs/components/geomodelvisualization/gmex/Fig 1.png differ
diff --git a/documentation/docs/components/geomodelvisualization/gmex/Fig 2.png b/documentation/docs/components/geomodelvisualization/gmex/Fig 2.png
new file mode 100644
index 0000000000000000000000000000000000000000..35a95c10f30bd9998c178c982a4447a8b3639e96
Binary files /dev/null and b/documentation/docs/components/geomodelvisualization/gmex/Fig 2.png differ
diff --git a/documentation/docs/components/geomodelvisualization/gmex/Fig 3.png b/documentation/docs/components/geomodelvisualization/gmex/Fig 3.png
new file mode 100644
index 0000000000000000000000000000000000000000..cc0265d4141a1b2dd13eefd49594e47c36b9e800
Binary files /dev/null and b/documentation/docs/components/geomodelvisualization/gmex/Fig 3.png differ
diff --git a/documentation/docs/components/geomodelvisualization/gmex/Fig 4.png b/documentation/docs/components/geomodelvisualization/gmex/Fig 4.png
new file mode 100644
index 0000000000000000000000000000000000000000..7aa8a388a9ec3ee04c4fa5547e50591a925bb0f8
Binary files /dev/null and b/documentation/docs/components/geomodelvisualization/gmex/Fig 4.png differ
diff --git a/documentation/docs/components/geomodelvisualization/gmex/Fig 4a.png b/documentation/docs/components/geomodelvisualization/gmex/Fig 4a.png
new file mode 100644
index 0000000000000000000000000000000000000000..db4b53355cde7abd92d486b8836aec3c836a8da7
Binary files /dev/null and b/documentation/docs/components/geomodelvisualization/gmex/Fig 4a.png differ
diff --git a/documentation/docs/components/geomodelvisualization/gmex/Fig 5.png b/documentation/docs/components/geomodelvisualization/gmex/Fig 5.png
new file mode 100644
index 0000000000000000000000000000000000000000..5f83e3a3360c255c59954013945d0b3e3f7414b1
Binary files /dev/null and b/documentation/docs/components/geomodelvisualization/gmex/Fig 5.png differ
diff --git a/documentation/docs/components/geomodelvisualization/gmex/Fig 6.png b/documentation/docs/components/geomodelvisualization/gmex/Fig 6.png
new file mode 100644
index 0000000000000000000000000000000000000000..319345cb10008fbdd70a04cde11b656975f19bd8
Binary files /dev/null and b/documentation/docs/components/geomodelvisualization/gmex/Fig 6.png differ
diff --git a/documentation/docs/components/geomodelvisualization/gmex/index.md b/documentation/docs/components/geomodelvisualization/gmex/index.md
index d763d21f90266e86aa616de37ca2ed26c2ca3efe..7981c5991179b9f8ceaf95187c538f4dab987ccd 100644
--- a/documentation/docs/components/geomodelvisualization/gmex/index.md
+++ b/documentation/docs/components/geomodelvisualization/gmex/index.md
@@ -1,12 +1,71 @@
# GeoModelVisualization
-GeoModelVisualization (gmex)
+GeoModelVisualization (gmex) is a 3D interactive visualization tool that allows you to display, navigate and debug complex detector geometries as the HEP experiments ones.
+
+## Examples
+
+In order to launch gmex you could simply type:
``` bash
./gmex
```
+This will open a dialogue window where you will be able to select a SQLite (.db) file that you want to display (see Figure 1).
-## Examples
+{{ imgutils_image_caption('Fig 1.png',
+ alt='GmexGui',
+ cap='Figure 1: Gmex GUI with dialogue window to select the geometry to be visualized.',
+ urlFix=False)
+}}
+
+Alternatively you can feed the geometry to `gmex` directly via the command line. For example:
+
+``` bash
+./gmex myGeometry.db
+```
+
+Once the geometry is selected, by clicking on the `Geo`tab on the left, gmex will diplay a list of all the subdetectors present in the loaded geometry, as shown in Figure 2
+{{ imgutils_image_caption('Fig 2.png',
+ alt='Subdetectors',
+ cap='Figure 2: List of all the subdetectors present in the loaded geometry.',
+ urlFix=False)
+}}
+
+In order to visualize all or some of them you have to click on the respective checkbox and click on the `eye icon` on the right (3rd icon from the top, in the right panel).
+
+{{ imgutils_image_caption('Fig 3.png',
+ alt='SelectedGeometry',
+ cap='Figure 3: Visualization of the selected geometry.',
+ urlFix=False)
+}}
+
+Now that you have loaded your geometry you can start investigating it. A good way to improve the visualization experience is to apply Phi sector cutouts. To do that you have to click on the `Display` tab under `Geo` (Figure 4), unselect a few of the `phi sector cutaways` (Fig 4a) and then click `Close`.
+
+{{ imgutils_image_caption('Fig 4.png',
+ alt='DisplayTab',
+ cap='Figure 4: `Display` tab under `Geo`.',
+ urlFix=False)
+}}
+
+{{ imgutils_image_caption('Fig 4a.png',
+ alt='PhiSector',
+ cap='Figure 4a: Select/unselect the `phi sector cutaways`.',
+ urlFix=False)
+}}
+
+At this point you have a cutaway view of your detector (Fig 5) and you can start investigating it by "opening" it.
+
+{{ imgutils_image_caption('Fig 5.png',
+ alt='Cutaway',
+ cap='Figure 5: Cutaway view of the ATLAS detector.',
+ urlFix=False)
+}}
+
+In order to do so you can follow the instructions written on the bottom part of the left panel. For instance, if you want to expand to child volumes you will have to use the following combination 'Ctrl/Cmd'+click. In this way you will remove the first layer of your geometry and be able to inspect its content (see Fig. 6).
-To run *gmex*
+{{ imgutils_image_caption('Fig 6.png',
+ alt='TrackDisplay',
+ cap='Figure 6: Cutaway view of the ATLAS detector without the first mother volume layer.',
+ urlFix=False)
+}}
+
diff --git a/documentation/docs/fullsimlight/fullsimlight/StepDisplay.png b/documentation/docs/fullsimlight/fullsimlight/StepDisplay.png
new file mode 100644
index 0000000000000000000000000000000000000000..314f96c709a5d52c90769a869914f2c666be96fd
Binary files /dev/null and b/documentation/docs/fullsimlight/fullsimlight/StepDisplay.png differ
diff --git a/documentation/docs/fullsimlight/fullsimlight/TrackDisplay.png b/documentation/docs/fullsimlight/fullsimlight/TrackDisplay.png
new file mode 100644
index 0000000000000000000000000000000000000000..82473bbd216972be35add8fd39974b00ba997379
Binary files /dev/null and b/documentation/docs/fullsimlight/fullsimlight/TrackDisplay.png differ
diff --git a/documentation/docs/fullsimlight/fullsimlight/index.md b/documentation/docs/fullsimlight/fullsimlight/index.md
index 10b3a15edeaf06d493307adbd52249bc2ba9d56d..4a73278ae360f9a568a831ffb670995d25adb72c 100644
--- a/documentation/docs/fullsimlight/fullsimlight/index.md
+++ b/documentation/docs/fullsimlight/fullsimlight/index.md
@@ -2,29 +2,38 @@
FullSimLight package consists of different tools based on [Geant4](https://geant4.web.cern.ch) toolkit, that can be run on multiple geometries:
-- fullSimLight: a light particle transport simulation (geometry, transport in magnetic field and basic physics scoring)
-- fsl: GUI for fullSimLight configuration
-- gmclash: a tool that runs clash detection on your input geometry, producing a json file report
-- gmgeantino: a tool to generate geantino maps from your input geometry
-- gm2gdml: a tool to convert geometries and dump them in gdml format.
+- **fullSimLight**: a light particle transport simulation (geometry, transport in magnetic field and basic physics scoring)
+- **fsl**: GUI for fullSimLight configuration
+- **gmclash**: a tool that runs clash detection on your input geometry, producing a json file report
+- **gmgeantino**: a tool to generate geantino maps from your input geometry
+- **gmmasscalc**: a tool to compute the mass of a given piece of detector geometry
+- **gm2gdml**: a tool to convert geometries and dump them in gdml format.
-For instructions on how to build FullSimLight, please refer to the [Build FullSimLight ](https://geomodel.web.cern.ch/home/dev/build_fullsimlight/) page.
+For instructions on how to build FullSimLight, please refer to the [Build FullSimLight ](https://geomodel.web.cern.ch/home/dev/build_fullsimlight/) page.
+For information on the specific tool please refer to the relevant section.
-## Detector Construction
+## FullSimLight: an experiment agnostic simulation tool
-### Geometry:
+`fullSimLight` is an experiment agnostic simulation tool that allows to easily run `Geant4` simulations by supporting multiple detector description formats (.gdml, plugins .dylib/.so,.db). It provides extended functionality by allowing the user to customise their simulation adding Geant4 User Actions, Sensitive Detectors, Physics Lists, Particle generators, etc. A built-in visualization for `fullSimLight` output is available in gmex (the interactive 3D geometry visualization tool which is part of GeoModel). As an example the following figures can be seen.
-The supported geometry formats are SQLite (.db), GDML (.gdml) and plugins that build from scratch a GeoModel geometry (.dylib/.so). An example of geometry plugins can be found in the [GeoModelExamples folder](https://gitlab.cern.ch/GeoModelDev/GeoModel/-/tree/main/GeoModelExamples/KitchenSinkPlugin).
-Use the -g flag to specify the name of the input geometry file.
+{{ imgutils_image_caption('StepDisplay.png',
+ alt='StepDisplay',
+ cap='Figure 1: Steps Display of primaries transported with fullSimLight in the full ATLAS detector.',
+ urlFix=False)
+}}
-### ATLAS Geometry Files:
+{{ imgutils_image_caption('TrackDisplay.png',
+ alt='TrackDisplay',
+ cap='Figure 2: Track Display of primaries transported with fullSimLight in the full ATLAS detector.',
+ urlFix=False)
+}}
-If you are interested in running with the ATLAS geometry files, please refer to the [ATLAS Extensions](https://geomodel.web.cern.ch/home/fullsimlight/atlas-extensions/) page.
## FullSimLight: run and options
-The fullSimLight application can be built and used both with sequential and multithreaded Geant4 builds. In case of multithreaded Geant4 toolkit, the applications will run in proper multithreaded mode. You can find the executables under the build/bin directory and/or under the *< path-to-install > /bin* dir.
+
+`fullSimLight` can be built and used both with sequential and multithreaded `Geant4` builds. In case of multithreaded Geant4 toolkit, the applications will run in proper multithreaded mode. You can find the executables under the build/bin directory and/or under the *< path-to-install > /bin* dir.
NB: Before running fullSimLight make sure to source the *geant4.sh* file to set correctly all the Geant4 environment variables.
@@ -32,139 +41,49 @@ NB: Before running fullSimLight make sure to source the *geant4.sh* file to set
source <path_to_geant4_install_dir>/bin/geant4.sh
```
-To run FullSimLight you can specify a json configuration file (generated with fsl) with the -c flag or use the following command line parameters. Run the executable with the --help option to see the available options:
+To run `fullSimLight` you can specify a json configuration file (generated with `fsl`) with the -c flag or use the following command line parameters. Run the executable with the --help option to see the available options:
``` bash
--c : json configuration file generated with fsl
+-c : [OPTIONAL] : json configuration file generated with fsl
-g : [REQUIRED] : the Geometry file name - if not specified in the configuration file
-m : [OPTIONAL] : the standard Geant4 macro file name
-o : flag ==> run the geometry overlap check (default: FALSE)
-f : physics list name (default: FTFP_BERT)
--P : use Pythia primary generator [config. available: ttbar/higgs/minbias or use a Pythia command input file]
--p : flag ==> run the application in performance mode i.e. no user actions
+-P : [OPTIONAL] :use Pythia primary generator [config. available: ttbar/higgs/minbias or use a Pythia command input file]
+-p : [OPTIONAL] :flag ==> run the application in performance mode i.e. no user actions
: - ==> run the application in NON performance mode i.e. with user actions (default)
```
-FullSimLight uses by default the Geant4 particle gun as primary generator, but it supports also
-input events from the Pythia generator (see the Primary generator section below for more details), HepMC3 formats or custom generators plugins.
-
-A minimal set of "observables" is collected during the simulation per-primary
-particle type: mean energy deposit, mean charged and neutral step lengths,
-mean number of steps made by charged and neutral particles, mean number of
-secondary e-, e+ and gamma particles. The result is reported at the end of
-each event for each primary particle that was transported in the given event.
-At the end of the simulation a final report is printed showing the run time,
-the primary generator and magnetic field settings used during the run, the
-total number of events and primary particles transported and the per-primary
-type simulation statistics of the above-mentioned quantities.
-
-The simulation can be executed in "performance" mode by providing the -p
-input flag. No any user actions are created in this case beyond the
-only one RunAction (only for the Master-thread in case of MT) that will
-start and stop a timer at the beginning and the end of the simulation
-(initialization time won't be included). Therefore, there is no scoring
-in this case.
-
-## Examples
-
-`FullSimLight` can be very easily configured and run via `fsl`, both from within the GUI or from the command-line, passing the configuration file with the -c flag. Alternatively, `FullSimLight` can be executed via command line using the basic available flags. The only mandatory parameter necessary for starting a simulation is the geometry file (can be specified inside the config file or with the -g flag). Following are some examples that illustrates the different possibilities.
-
-If you have created your custom configuration file <myconfig.json> with fsl, you can simply run fullSimLight as follows:
-
-``` bash
-./fullSimLight -c myconfig.json
-```
-This is the best and more complete way of configuring FullSimLight because it allows you to customize also the use of plugins and to use all the different primary particles generation methods.
-
-As an alternative to using the json configuration file, one can use the available command line options and a classical geant4 macro to configure fullsimlight.
-
-During the installation a default macro file *<macro.g4>* will be installed in your *< install-path >/share/FullSimLight* directory. So the macro file doesn't need to be specified if you intend to use the default one.
-
-To execute the application using the default < macro.g4 > macro file, with the default FTFP_BERT
-Physics List, not in performance mode and building the detector from < mygeometry.db > file:
-
-``` bash
-./fullSimLight -g mygeometry.db
-```
-
-To execute the application using the default < macro.g4 > macro file and building the detector with a geometry described in one of the [GeoModelPlugins repo](https://gitlab.cern.ch/atlas/geomodelatlas/GeoModelATLAS/-/tree/master/GeoModelPlugins?ref_type=heads), i.e. *PixelPlugin* :
-
-``` bash
-./fullSimLight -g libPixePlugin.1.0.0.dylib/.so
-```
-
-To execute the application using a custom <mymacro.g4> macro file, with the ATLAS FTFP_BERT_ATL Physics List, in performance mode and building the detector from the geometry-ATLAS-R2-2016-01-00-01.db file :
-
-``` bash
-./fullSimLight -m mymacro.g4 -f FTFP_BERT_ATL -p -g geometry-ATLAS-R2-2016-01-00-01.db
-```
-
-Please note that the last option is deprecated, as it doesn't allow full flexibility, and we suggest to configure your simulation via `fsl`.
-
-
## Parameters configuration via fsl (suggested)
-For details on how to configure your simulation with fsl, please refer to the [fsl page](https://geomodel.web.cern.ch/home/fullsimlight/fsl).
-
-## Parameters configuration via Geant4 macro (deprecated)
-
-FullSimLight and in general Geant4 based simulations, need a Geant4 macro to read some input parameters. The default macro used by fullSimLight is called 'macro.g4' and it should be found under the *< install-path > /share/FullSimLight* directory. The macro can be edited to change some parameters, i.e the verbosity, the number of threads, or to tune the simulation. The most relevant macro commands are explained in what follows.
-
-## Magnetic field
-
- A constant magnetic field can be set through the macro command:
-
-``` bash
-/FSLdet/setField <field-value> <unit>
-```
-
-The default value is a uniform magnetic field of 4 Tesla.
-
-## ATLAS Magnetic Field
-
-The ATLAS magnetic field is integrated in FullSimLight and can be used from it. The magnetic field map file used and supported are:
+For details on how to configure your simulation with `fsl` GUI, please refer to the [fsl page](https://geomodel.web.cern.ch/home/fullsimlight/fsl).
-- full_bfieldmap_7730_20400_14m_version5.root
-- solenoid_bfieldmap_7730_0_14m_version5.root
-- toroid_bfieldmap_0_20400_14m_version5.root
-- bmagatlas_09_fullAsym20400.data
-If the magnetic field maps are not available to the user, a constant magnetic field can be set through the macro file. The test application "testMagneticField" can be used to test the different magnetic field maps and produce Maps in 2D histograms that are saved in a ROOT file (i.e 'ATLAS_BField_default.root') .
-Please notice that no dependency on ROOT is introduced, because the histograms are created, filled and saved using the *G4AnalysisManager*.
+## Parameters configuration via Geant4 macro (deprecated)
-### testMagneticField examples:
-Run the application with the --help flag to see the options:
+`fullSimLight` and in general Geant4 based simulations, need a Geant4 macro to read some input parameters. The default macro used by fullSimLight is called 'macro.g4' and it should be found under the *< install-path > /share/FullSimLight* directory. The macro can be edited to change some parameters, i.e the verbosity, the number of threads, or to tune the simulation. The most relevant macro commands are explained in section [Particle gun](#particle-gun) and [Magnetic field](#magnetic-field)
-``` bash
-./testMagneticField --help
--f : OPTIONAL: magnetic field filename [.data/.root] (default : use ATLAS magnetic field maps)
--r : FLAG: use root field map (default : false, use .data file)
--s : FLAG: set Solenoid Off
--t : FLAG: set Toroids Off
-```
+## Detector Construction
-By default the file tested is the *bmagatlas_09_fullAsym20400.data*. Use the -r option to test the ROOT file maps, add the -s flag to set the solenoid off and use the *toroid_bfieldmap_0_20400_14m_version5.root*:
+The supported geometry formats are SQLite (.db), GDML (.gdml) and plugins that build from scratch a GeoModel geometry (.dylib/.so). An example of geometry plugins can be found in the [GeoModelExamples folder](https://gitlab.cern.ch/GeoModelDev/GeoModel/-/tree/main/GeoModelExamples/KitchenSinkPlugin).
+Use the -g flag to specify the name of the input geometry file.
-``` bash
-./testMagneticField -r -s
-```
+### ATLAS Geometry Files
-Use the -t to set the Toroids off, and test the *solenoid_bfieldmap_7730_0_14m_version5.root* file.
+If you are interested in running with the ATLAS geometry files, please refer to the [ATLAS Extensions](https://geomodel.web.cern.ch/home/fullsimlight/atlas-extensions/) page.
-``` bash
-./testMagneticField -r -t
-```
+## Event generation
-## Primary Generators
+`fullSimLight` uses by default the `Geant4` particle gun as primary generator, but it supports also
+input events from the [Pythia generator](http://home.thep.lu.se/Pythia/), [HepMC3](https://gitlab.cern.ch/hepmc/HepMC3) formats or custom generators plugins.
-The primary generator used by default is the Geant4 particle gun, but FullSimLight also supports the [Pythia generator](http://home.thep.lu.se/Pythia/) and HepMC3 format.
-## Particle gun
+### Particle gun
The particle gun used by default will generate primary particles
at the (0,0,0) position with the following options:
-### Number of primaries per event:
+#### Number of primaries per event:
The number of primary particles per event can be set through the macro
command:
@@ -174,7 +93,7 @@ command:
By default, i.e. if it is not specified by the above command, the number of primary particles will be randomly selected for each individual event from the [1, 10] interval uniformly.
-### Primary particle energy:
+#### Primary particle energy:
The primary particle energy can be set through the macro command:
``` bash
@@ -182,7 +101,7 @@ The primary particle energy can be set through the macro command:
```
By default, i.e. if it is not specified by the above command, the kinetic energy will be randomly selected for each individual primary particle from the [1 GeV, 100 GeV] uniformly.
-### Primary particle direction:
+#### Primary particle direction:
The primary particle momentum direction can be set through the macro command:
``` bash
@@ -190,18 +109,18 @@ The primary particle momentum direction can be set through the macro command:
```
By default, i.e. if it is not specified by the above command, the momentum direction will be randomly selected for each individual primary particle from isotropic distribution.
-### Primary particle type:
+#### Primary particle type:
The primary particle type can be set through the macro command:
``` bash
/FSLgun/particle <particle-name>
```
-By default, i.e. if it is not specified by the above command, the type will be randomly selected from a pre-defined list for each individual primary particle uniformly. The current list of particles includes e-, e+ and gamma particles. It can be extended by adding more particles to the list in the FSLPrimaryGeneratorAction class.
+By default, i.e. if it is not specified by the above command, the type will be randomly selected from a pre-defined list for each individual primary particle uniformly. The current list of particles includes e-, e+ and gamma particles. It can be extended by adding more particles to the list in the `FSLPrimaryGeneratorAction` class.
-## Pythia generator
+### Pythia generator
- FullSimLight supports Pythia as primary particles generator. In order to use Pythia, the user should have it installed in their system and if Pythia is found FullSimLight will be compiled with the support on. There are three different default options available when using the -P or --pythia flag (i.e. *ttbar*, *higgs* and *minbias*):
+ `fullSimLight` supports Pythia as primary particles generator. In order to use Pythia, the user should have it installed in their system and if Pythia is found `fullSimLight` will be compiled with the support on. There are three different default options available when using the -P or --pythia flag (i.e. *ttbar*, *higgs* and *minbias*):
``` bash
-P : generate events with Pythia [config. available: ttbar/higgs/minbias or use ascii input file]
@@ -211,14 +130,60 @@ By default, i.e. if it is not specified by the above command, the type will be r
For example, in order to simulate the default *ttbar* events, the command to be run is the following:
``` bash
-./fullSimLight -m ../share/FullSimLight/pythia.g4 -P ttbar -g geometry-ATLAS-R2-2016-01-00-01.db
+./fullSimLight -m ../share/FullSimLight/pythia.g4 -P ttbar -g mygeometry.db
```
The number of events that the user wants to simulate must be specified in the Geant4 macro file. A specific *pythia.g4* macro file can be found in the *< path-to-install >/share/FullSimLight* directory, that should be used when simulating Pythia events and can be edited according to the user needs.
-## HepMC3 events input
+### HepMC3 events input
+
+`fullSimLight` supports reading events in HepMC3 format both the standard Asciiv3 format (introduced in HepMC3) as well as the old Ascii format (used in HepMC and HepMC2). This option is only available when configuring fullSimLight with FSL and the json configuration file. Please refer to the [FSL section](https://geomodel.web.cern.ch/home/fullsimlight/fsl/) for more info.
+
+## Magnetic field
+
+ A constant magnetic field can be set through the macro command:
+
+``` bash
+/FSLdet/setField <field-value> <unit>
+```
-FullSimLight supports reading events in HepMC3 format both the standard Asciiv3 format (introduced in HepMC3) as well as the old Ascii format (used in HepMC and HepMC2). This option is only available when configuring fullSimLight with FSL and the json configuration file. Please refer to the [FSL section](https://geomodel.web.cern.ch/home/fullsimlight/fsl/) for more info.
+The default value is a uniform magnetic field of 4 Tesla.
+
+### ATLAS Magnetic Field
+
+If you are interested in running with the ATLAS magnetic field map, please refer to the [ATLAS Extensions](https://geomodel.web.cern.ch/home/fullsimlight/atlas-extensions/) page.
+
+<!--- full_bfieldmap_7730_20400_14m_version5.root-->
+<!--- solenoid_bfieldmap_7730_0_14m_version5.root-->
+<!--- toroid_bfieldmap_0_20400_14m_version5.root-->
+<!--- bmagatlas_09_fullAsym20400.data-->
+<!---->
+<!--If the magnetic field maps are not available to the user, a constant magnetic field can be set through the macro file. The test application "testMagneticField" can be used to test the different magnetic field maps and produce Maps in 2D histograms that are saved in a ROOT file (i.e 'ATLAS_BField_default.root') .-->
+<!--Please notice that no dependency on ROOT is introduced, because the histograms are created, filled and saved using the `G4AnalysisManager`.-->
+<!---->
+<!--### testMagneticField examples:-->
+<!--Run the application with the --help flag to see the options:-->
+<!---->
+<!--``` bash-->
+<!--./testMagneticField --help-->
+<!---->
+<!---f : OPTIONAL: magnetic field filename [.data/.root] (default : use ATLAS magnetic field maps)-->
+<!---r : FLAG: use root field map (default : false, use .data file)-->
+<!---s : FLAG: set Solenoid Off -->
+<!---t : FLAG: set Toroids Off -->
+<!--```-->
+<!---->
+<!--By default the file tested is the *bmagatlas_09_fullAsym20400.data*. Use the -r option to test the ROOT file maps, add the -s flag to set the solenoid off and use the *toroid_bfieldmap_0_20400_14m_version5.root*:-->
+<!---->
+<!--``` bash-->
+<!--./testMagneticField -r -s -->
+<!--```-->
+<!---->
+<!--Use the -t to set the Toroids off, and test the *solenoid_bfieldmap_7730_0_14m_version5.root* file. -->
+<!---->
+<!--``` bash-->
+<!--./testMagneticField -r -t -->
+<!--```-->
## Physics List
@@ -227,3 +192,58 @@ FullSimLight supports reading events in HepMC3 format both the standard Asciiv3
must be in upper case, exactly as the corresponding header file. By default,
i.e. if the Physics List name is not provided as an input argument, the FTFP_BERT
Physics List will be used.
+
+## Scoring
+
+A minimal set of "observables" is collected during the simulation per-primary
+particle type: mean energy deposit, mean charged and neutral step lengths,
+mean number of steps made by charged and neutral particles, mean number of
+secondary e-, e+ and gamma particles. The result is reported at the end of
+each event for each primary particle that was transported in the given event.
+At the end of the simulation a final report is printed showing the run time,
+the primary generator and magnetic field settings used during the run, the
+total number of events and primary particles transported and the per-primary
+type simulation statistics of the above-mentioned quantities.
+
+The simulation can be executed in "performance" mode by providing the -p
+input flag. No any user actions are created in this case beyond the
+only one RunAction (only for the Master-thread in case of MT) that will
+start and stop a timer at the beginning and the end of the simulation
+(initialization time won't be included). Therefore, there is no scoring
+in this case.
+
+## Examples
+
+`fullSimLight` can be very easily configured and run via `fsl`, both from within the GUI or from the command-line, passing the configuration file with the -c flag. Alternatively, `fullSimLight` can be executed via command line using the basic available flags. The only mandatory parameter necessary for starting a simulation is the geometry file (can be specified inside the config file or with the -g flag). Following are some examples that illustrates the different possibilities.
+
+If you have created your custom configuration file <myconfig.json> with fsl, you can simply run fullSimLight as follows:
+
+``` bash
+./fullSimLight -c myconfig.json
+```
+This is the best and more complete way of configuring `fullSimLight` because it allows you to customize also the use of plugins and to use all the different primary particles generation methods.
+
+As an alternative to using the json configuration file, one can use the available command line options and a classical geant4 macro to configure fullsimlight.
+
+During the installation a default macro file *<macro.g4>* will be installed in your *< install-path >/share/FullSimLight* directory. So the macro file doesn't need to be specified if you intend to use the default one.
+
+To execute the application using the default < macro.g4 > macro file, with the default FTFP_BERT
+Physics List, not in performance mode and building the detector from < mygeometry.db > file:
+
+``` bash
+./fullSimLight -g mygeometry.db
+```
+
+To execute the application using the default < macro.g4 > macro file and building the detector with a geometry described in one of the [GeoModelPlugins repo](https://gitlab.cern.ch/atlas/geomodelatlas/GeoModelATLAS/-/tree/master/GeoModelPlugins?ref_type=heads), i.e. *PixelPlugin* :
+
+``` bash
+./fullSimLight -g libPixePlugin.1.0.0.dylib/.so
+```
+
+To execute the application using a custom <mymacro.g4> macro file, with the ATLAS FTFP_BERT_ATL Physics List, in performance mode and building the detector from the <mygeometry.db> file :
+
+``` bash
+./fullSimLight -m mymacro.g4 -f FTFP_BERT_ATL -p -g mygeometry.db
+``` s
+
+Please note that the last option is deprecated, as it doesn't allow full flexibility, and we suggest to configure your simulation via `fsl`.
diff --git a/documentation/docs/index.md b/documentation/docs/index.md
index d1b571a6801e02f9412b41e037caf6d23169194f..c0c23e59728cd057a6d249f199ca58f417e76aa9 100755
--- a/documentation/docs/index.md
+++ b/documentation/docs/index.md
@@ -73,6 +73,17 @@ A standalone tool to **generate geantino maps** of your newly built detector
+The GeoModel Toolkit includes:
+
+* **gmex**, the geometry explorer, an interactive 3D geometry visualizer
+* **gmstatistics**, tool to monitor the memory consumption
+* **fullsimlight**, a command-line tool to run experiment agnostic Geant4 simulation, and its graphical user interface, *fsl*.
+* **gmclash**, a Geant4 based command-line tool to perform clash detection
+* **gmgeantino**, a Geant4 based command-line tool to generate geantino maps
+* **gmmasscalc**, a Geant4 based command-line tool to compute the mass of a given piece of detector geometry
+* **gm2gdml** and **gdml2gm**, command line tools to convert GeoModel to and from GDML
+* **gmcat**, a command line tool to assemble geometry from multiple inputs
+
----
## External Dependencies
diff --git a/documentation/docs/start/install.md b/documentation/docs/start/install.md
index eb668ff46b1a7be799dd7efa48285390d7e7d844..1a59c69bffec957a31c33eab2f521297bb16bcc1 100644
--- a/documentation/docs/start/install.md
+++ b/documentation/docs/start/install.md
@@ -2,17 +2,6 @@
In this section, you will find instructions on how to **install** the latest **stable** version of GeoModel applications and development kits on different platforms. If you are a developer and would like to install the GeoModel toolkit from source, please refer to the [Developers installation instructions](../dev/index.md).
-The GeoModel applications include:
-
-* **gmex**, the geometry explorer, an interactive 3d geometry visualizer
-* **gmstatistics**, tool to monitor the memory consumption
-* **fullsimlight**, a command-line tool to run Geant4 simulation, and its graphical user interface, *fsl*.
-* **gmclash**, a Geant4 based command-line tool to perform clash detection
-* **gmgeantino**, a Geant4 based command-line tool to generate geantino maps
-* **gmmasscalc**, a Geant4 based command-line tool to compute the mass of a given piece of detector geometry
-* **gm2gdml** and **gdml2gm**, command line tools to convert GeoModel to and from GDML
-* **gmcat**, a command line tool to assemble geometry from multiple inputs
-
The development kits include header files and precompiled libraries for the development of detector description code. On some platforms (macOS) the development environment is installed together with the prebuild applications and libraries.
diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml
index a1e7b923e42fc87fa6a99e4951aff00f140d483b..5442752406e0e11770540be763340b7111896865 100755
--- a/documentation/mkdocs.yml
+++ b/documentation/mkdocs.yml
@@ -27,7 +27,9 @@ nav:
- 'Overview': 'components/kernel/overview/index.md'
- 'Class Reference': 'components/kernel/reference/index.md'
- GeoModelTools:
- - 'GDML2GeoModel': 'components/geomodeltools/gdml2gm/index.md'
+ - 'GeoModelCat (gmcat)': 'components/geomodeltools/gmcat/index.md'
+ - 'GeoModelStatistics (gmstatistics)': 'components/geomodeltools/gmstatistics/index.md'
+ - 'GDML2GeoModel (gdml2gm)': 'components/geomodeltools/gdml2gm/index.md'
- GeoModelXML:
- 'GeoModelXML Overview' : 'components/geomodelxml/index.md'
- 'Building a geometry' : 'components/geomodelxml/buildinggeometry.md'
@@ -40,18 +42,18 @@ nav:
- 'Troubleshooting' : 'components/geomodelxml/troubleshooting.md'
- 'User Guide (old, ATLAS specific)' : 'components/geomodelxml/old.md'
- GeoModelVisualization:
- - 'GeoModelExplorer': 'components/geomodelvisualization/gmex/index.md'
+ - 'GeoModelExplorer (gmex)': 'components/geomodelvisualization/gmex/index.md'
- FullSimLight tools:
- 'FullSimLight': 'fullsimlight/fullsimlight/index.md'
- - 'GeoModelClash': 'fullsimlight/gmclash/index.md'
- - 'GeoModelGeantino': 'fullsimlight/gmgeantino/index.md'
- - 'GeoModelMassCalculator': 'fullsimlight/gmmasscalc/index.md'
- - 'GeoModel2GDML': 'fullsimlight/gm2gdml/index.md'
- - 'fsl': 'fullsimlight/fsl/index.md'
+ - 'fsl GUI': 'fullsimlight/fsl/index.md'
+ - 'GeoModelClash (gmclash)': 'fullsimlight/gmclash/index.md'
+ - 'GeoModelGeantino (gmgeantino)': 'fullsimlight/gmgeantino/index.md'
+ - 'GeoModelMassCalculator (gmmasscalc)': 'fullsimlight/gmmasscalc/index.md'
+ - 'GeoModel2GDML (gm2gdml)': 'fullsimlight/gm2gdml/index.md'
+
- 'Plugin Examples': 'fullsimlight/plugins/index.md'
- 'Plugin Support': 'fullsimlight/plugin-support/index.md'
- 'ATLAS Extensions': 'fullsimlight/atlas-extensions/index.md'
- - FAQ: 'faq.md'
- For Developers:
- 'Build the Libraries and Tools': 'dev/index.md'
- 'Build FullSimLight': 'dev/build_fullsimlight.md'
@@ -60,6 +62,7 @@ nav:
- 'Doxygen documentation': https://cern.ch/geomodel/doxygen
- 'Contributing to the Documentation': 'dev/docs-contrib.md'
- 'Dev FAQ': 'dev/dev-faq.md'
+ - FAQ: 'faq.md'
- Papers & Presentations: 'papers.md'
# - 'Public': 'papers/public.md'
# - 'Internal': 'papers/internal.md'