diff --git a/GeoModelExamples/SiliconSystemExample/src/SiliconSystemPlugin.cxx b/GeoModelExamples/SiliconSystemExample/src/SiliconSystemPlugin.cxx
index abfeb3933691a5668750ebc0a1e55d264796beaf..9b56e4c9f612da3238cd2a331bbd479985b78d25 100644
--- a/GeoModelExamples/SiliconSystemExample/src/SiliconSystemPlugin.cxx
+++ b/GeoModelExamples/SiliconSystemExample/src/SiliconSystemPlugin.cxx
@@ -119,18 +119,35 @@ void SiliconSystemPlugin::create(GeoVPhysVol *world, bool /*publish*/) {
GeoLogVol *boxLog = new GeoLogVol("BoxLog",boxShape,Air);
GeoPhysVol *worldBOX = new GeoPhysVol(boxLog);
- for (int k=0;k<3;k++) {
- for (int j=0;j<3;j++) {
- GeoBox *box = new GeoBox (0.1,(j+1)*1.7,20);
- GeoLogVol *boxLog=new GeoLogVol("SiDet", box, Aluminium);
+ GeoBox *box1 = new GeoBox (0.1,1*1.7,20);
+ GeoLogVol *boxLog1 = new GeoLogVol("SiDet", box1, Aluminium);
+
+ GeoBox *box2 = new GeoBox (0.1,2*1.7,20);
+ GeoLogVol *boxLog2 = new GeoLogVol("SiDet", box2, Aluminium);
- GeoRectSurface* rectSurface = new GeoRectSurface((j+1)*1.9, 20.2);
- GeoVSurface* surf = new GeoVSurface(rectSurface);
+ GeoBox *box3 = new GeoBox (0.1,3*1.7,20);
+ GeoLogVol *boxLog3 = new GeoLogVol("SiDet", box3, Aluminium);
+ GeoRectSurface* rectSurface1 = new GeoRectSurface(1*1.9, 20.2);
+ GeoRectSurface* rectSurface2 = new GeoRectSurface(2*1.9, 20.2);
+ GeoRectSurface* rectSurface3 = new GeoRectSurface(3*1.9, 20.2);
+
+ for (int k=0;k<3;k++) {
+ for (int j=0;j<3;j++) {
+ GeoLogVol* boxLog;
+ if(j==0) boxLog = boxLog1;
+ else if(j==1) boxLog = boxLog2;
+ else boxLog = boxLog3;
+
+ GeoRectSurface* rectSurface;
+ if(j==0) rectSurface = rectSurface1;
+ else if(j==1) rectSurface = rectSurface2;
+ else rectSurface = rectSurface3;
+
for (int i=0;i<16;i++) {
double theta = i/16.0*2*M_PI;
GeoFullPhysVol *boxPhys=new GeoFullPhysVol(boxLog);
-
+ GeoVSurface* surf = new GeoVSurface(rectSurface);
// Initial transform is very tricky. Because the Virtual surface is always facing to Z axis initially.
GeoAlignableTransform* xf0 = new GeoAlignableTransform(GeoTrf::RotateZ3D(theta)*GeoTrf::TranslateX3D((j+1)*8.0+0.4*(i%2))*GeoTrf::TranslateX3D(0.5)*GeoTrf::TranslateZ3D((k-1)*44.0)*GeoTrf::RotateX3D(M_PI/2.0)*GeoTrf::RotateY3D(M_PI/2.0));
GeoAlignableTransform *xf = new GeoAlignableTransform(GeoTrf::RotateZ3D(theta)*GeoTrf::TranslateX3D((j+1)*8.0+0.4*(i%2)));
@@ -163,14 +180,14 @@ void SiliconSystemPlugin::create(GeoVPhysVol *world, bool /*publish*/) {
}
}
+ double L=10.0;
+ GeoTrapezoidSurface* trapezoid = new GeoTrapezoidSurface(1.2, 5.2, L);
+ GeoTrd *trd=new GeoTrd(.2, .2, 1, 5, L);
+ GeoLogVol *trdLog=new GeoLogVol("SiDetEnd", trd,Aluminium);
+
for (int j=0;j<16;j++) {
for (int i=-1;i<2;i+=2) {
-
- double L=10.0;
- GeoTrapezoidSurface* trapezoid = new GeoTrapezoidSurface(1.2, 5.2, L);
GeoVSurface* surf = new GeoVSurface(trapezoid);
- GeoTrd *trd=new GeoTrd(.2, .2, 1, 5, L);
- GeoLogVol *trdLog=new GeoLogVol("SiDetEnd", trd,Aluminium);
GeoFullPhysVol *trdPhys=new GeoFullPhysVol(trdLog);
GeoTransform *sf0=new GeoTransform(GeoTrf::RotateY3D(j*2*M_PI/16.0)*GeoTrf::RotateX3D(M_PI/2.0)*GeoTrf::TranslateY3D(1.5*L));
diff --git a/athena_ci/athena_build.sh b/athena_ci/athena_build.sh
index b2e11f57485b7c75c2f70a582075fd9f94d2df69..8a0c34aa2aede7ef4c04c1717b723fe29f37130c 100755
--- a/athena_ci/athena_build.sh
+++ b/athena_ci/athena_build.sh
@@ -122,7 +122,7 @@ cmake -S "${SCRIPT_DIR}/.." -B geomodel-build \
-DCMAKE_MAKE_PROGRAM="$NINJA" \
-DCMAKE_CXX_FLAGS="$EXTRA_FLAGS" \
-DCMAKE_INSTALL_PREFIX=$gm_install_dir \
- -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+ -DCMAKE_BUILD_TYPE=Release \
-DGEOMODEL_BUILD_TOOLS=ON \
heading "Build GeoModel"
@@ -196,6 +196,7 @@ cmake "$ATHENA_SOURCE/Projects/WorkDir" \
-DCMAKE_MAKE_PROGRAM="$NINJA" \
-DCMAKE_CXX_FLAGS="$EXTRA_FLAGS -isystem ${gm_install_dir}/include" \
-DATLAS_PACKAGE_FILTER_FILE="$package_filters" \
+ -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=$install_dir
popd
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/components/kernel/overview/MaterialGeometry.md b/documentation/docs/components/kernel/overview/MaterialGeometry.md
index 32280d9df11e2fb0820647b7e828dd7cdd626f51..1aee36f31594fb8868d703ec61934d7b11d86410 100644
--- a/documentation/docs/components/kernel/overview/MaterialGeometry.md
+++ b/documentation/docs/components/kernel/overview/MaterialGeometry.md
@@ -21,20 +21,15 @@ Material classes, as well as all other classes, use the units defined in `GeoMod
#include "GeoModelKernel/Units.h"
#define SYSTEM_OF_UNITS GeoModelKernelUnits
...
-GeoMaterial *water = new GeoMaterial(“H20â€, 1.0*SYSTEM_OF_UNITS::gram/SYSTEM_OF_UNITS::cm3);
+GeoIntrusivePtr<GeoMaterial> water{new GeoMaterial(“H20â€, 1.0*SYSTEM_OF_UNITS::gram/SYSTEM_OF_UNITS::cm3)};
```
To finish constructing this material, water, one needs to follow the constructor with the following lines
```cpp
-GeoElement *hydrogen = new GeoElement("Hydrogen",
- "H",
- 1.0,
- 1.010);
-GeoElement *oxygen = new GeoElement("Oxygen",
- "O",
- 8.0,
- 16.0);
+GeoIntrusivePtr<GeoElement> hydrogen{new GeoElement("Hydrogen", "H", 1.0, 1.010)};
+GeoIntrusivePtr<GeoElement> oxygen{new GeoElement("Oxygen", "O", 8.0, 16.0)};
+
water->add(hydrogen,0.11);
water->add(oxygen,0.89);
water->lock();
@@ -44,7 +39,7 @@ The materials are then used to together with shapes to form logical volumes, dis
### Shapes
-Shapes are created using the new operator. Essentially, shapes within this system are required to store and provide access to the geometrical constants that describe their geometrical form. This data is, insofar as possible, to be specified on the constructor.
+Essentially, shapes within this system are required to store and provide access to the geometrical constants that describe their geometrical form. This data is, insofar as possible, to be specified on the constructor.
Shapes are extensible and custom shapes can be built.
@@ -55,7 +50,7 @@ double length = 100*SYSTEM_OF_UNITS::cm;
double width = 200*SYSTEM_OF_UNITS::cm;
double depth = 33*SYSTEM_OF_UNITS::cm;
-GeoBox* box = new GeoBox(length, width, depth);
+GeoIntrusivePtr<GeoBox> box{new GeoBox(length, width, depth)};
```
Most objects can be constructed along similar lines; exceptions are objects with multiple planes such as polycones and polygons; their interface allows one to add planes successively. For the polycone, for example, the shape is built as follows:
@@ -65,7 +60,7 @@ double dphi = 10*SYSTEM_OF_UNITS::deg;
double sphi = 40*SYSTEM_OF_UNITS::deg;
// Create polycone object
-GeoPcon* polycone = new GeoPcon(dphi,sphi);
+GeoIntrusivePtr<GeoPcon> polycone{new GeoPcon(dphi,sphi)};
// Add planes successively
double z0 = 0.;
@@ -89,9 +84,11 @@ This creates a polycone whose projection subtends an angle of 10 degrees between
The shapes can provide their data to a client through their accessors, and in addition support several other operations. Boolean operations on shapes are possible. They can be accomplished through Boolean operators in class [GeoShape](../reference/#introduction_1):
```cpp
-GeoShape * donut = new GeoTube();
-GeoShape * hole = new GeoTube();
-const GeoShape & result = (donut->subtract(*hole));
+#include "GeoModelKernel/GeoShapeSubtraction.h"
+...
+GeoIntrusivePtr<GeoShape> donut{new GeoTube(.....)};
+GeoIntrusivePtr<GeoShape> hole{new GeoTube(.....)};
+const GeoShape & result = donut->subtract(*hole);
```
The result of a Boolean operation is a shape in a boolean expression tree that can, for example, be decoded when the geometry is declared to GEANT4.
@@ -114,9 +111,7 @@ The methods `typeId()` and `classTypeId()` return unsigned integers, making the
Logical volumes represent, conceptually, a specific manufactured piece that can be placed in one or more locations around the detector. A logical volume is created by specifying a name tag for the volume, a shape, and a material:
```cpp
-const GeoLogVol *myLog = new GeoLogVol("MyLogVol",
- myShape,
- gNitrogen);
+GeoIntrusivePtr<const GeoLogVol> myLog{GeoLogVol("MyLogVol", myShape, myMaterial)};
```
### Physical Volumes and the Geometry Graph
@@ -126,17 +121,17 @@ Having created elements, materials, shapes, and logical volumes, you are now rea
* Regular Physical Volumes, designed to be small.
* Full Physical Volumes, designed to hold in cache complete information about how the volume is located with respect to the world volume, its formatted name string and other important information.
-There is a common abstract [base class](#geomodel-kernel-overview) for all of these: `GeoVPhysVol`. In addition both the full physical volumes have another layer of abstraction, `GeoVFullPhysVol`. All physical volumes allow access to their children.
+There is a common abstract [base class](#geomodel-kernel-overview) for all of these: `GeoVPhysVol`. In addition the full physical volumes have another layer of abstraction, `GeoVFullPhysVol`. All physical volumes allow access to their children.
The concrete subclasses that you have at your disposition for detector description are called [GeoPhysVol](../reference/#geophysvol) and [GeoFullPhysVol](../reference/#geofullphysvol). Both of these have a method to add either volumes or volume properties:
```cpp
-GeoPhysVol* myVol;
+GeoIntrusivePtr<GeoPhysVol> myVol{new GeoPhysVol(myLog)};
myVol->add(aTransformation);
myVol->add(anotherVolume);
```
-When you add a transformation, you change the position of the subsequent volume with respect to the parent. If you add no transformation, you will not shift the daughter relative to the parent and commonly will create a daughter which is centered directly in the parent. If you add more than one transformation to the volume before adding a parent, they will be multiplied. The last transformation to be added is applied first to the child. Transformations are discussed next. Like logical volumes, they may be shared.
+When you add a transformation, you change the position of the subsequent volume with respect to the parent. If you add no transformation, you will not shift the daughter relative to the parent and commonly will create a daughter which is centered directly in the parent. If you add more than one transformation to the volume before adding a child volume, they will be multiplied. The last transformation to be added is applied first to the child. Transformations are discussed next. Like logical volumes, they may be shared.
Like physical volumes, transformations come in two types:
@@ -145,7 +140,7 @@ Like physical volumes, transformations come in two types:
When you create a transformation, you must choose the type.
-The model of the raw geometry is a tree of nodes, property nodes and volume nodes. The tree can be thought of as a tree of volumes, each one “having†a set of properties (inherited from property nodes throughout the tree). The subsystem engineer judiciously chooses which of the volumes are to contain full, cached, position information – usually, these first-class volumes are to be associated with a detector. He or she also judiciously decides which of the transformations are to be alignable—usually these are the transformations which position something that ultimately has a detector bolted, glued, riveted or otherwise clamped onto a sensitive piece. Then, the developer can apply several techniques for keeping track of these pointers so that the important volumes can later be connected to detector elements, and the alignable transformations can be connected to the alignment database for periodic updating.
+The model of the raw geometry is a tree of nodes, property nodes and volume nodes. The tree can be thought of as a tree of volumes, each one “having†a set of properties (inherited from property nodes throughout the tree). The subsystem engineer judiciously chooses which of the volumes are to contain full, cached, position information – usually, these first-class volumes are to be associated with a detector. The subsystem engineer also judiciously decides which of the transformations are to be alignable—usually these are the transformations which position something that ultimately has a detector bolted, glued, riveted or otherwise clamped onto a sensitive piece. Then, the developer can apply several techniques for keeping track of these pointers so that the important volumes can later be connected to detector elements, and the alignable transformations can be connected to the alignment database for periodic updating.
Finally, we provide three mechanisms for giving names to volumes:
@@ -157,19 +152,19 @@ In effect this last method can be thought of as a way of parametrizing the name
### Actions
-There are two ways of getting raw geometry information out of the model. Suppose that one has access to a particular physical volume (it could be the “World†physical volume). One can access its children, there names, and their transformations with respect to the parent in the following way:
+There are two ways of getting raw geometry information out of the model. Suppose that one has access to a particular physical volume (it could be the “World†physical volume). One can access its children, their names, and their transformations with respect to the parent in the following way:
```cpp
-PVConstLink myVol;
+PVConstLink myVol; // PVConstLink is a typedef to GeoIntrusivePtr<const GeoVPhysVol>
for(int c=0; c<myVol->getNChildVols(); ++c) {
PVConstLink child = myVol->getChildVol(c);
GeoTrf::Transform3D xf = getXToChildVol(c);
}
```
-One could then iterate in a similar way over the grand children, by using a double loop. Ultimately one would probably to visit all the volumes, whatever their depth in the tree, so probably this would call on some form of recursion. An easy way would be to embed the small sample of code shown above in a recursive subroutine or method. That would be fine and is conceptually simple. However, within the geometry model’s kernel, we have provided an alternate, probably better way to visit the entire tree.
+One could then iterate in a similar way over the grand children, by using a double loop. Ultimately one would probably want to visit all the volumes, whatever their depth in the tree, so probably this would call on some form of recursion. An easy way would be to embed the small sample of code shown above in a recursive subroutine or method. That would be fine and is conceptually simple. However, within the geometry model’s kernel, we have provided an alternate, probably better way to visit the entire tree.
-That mechanism involves a `GeoVolumeAction`. A `GeoVolumeAction` is a way (for applications programmers) to obtain recursive behavior without writing any recursive routines. It’s a class with a handler routine (`handleVPhysVol()`) which is called for each node before (or after) it is called on its children. This can descend to an arbitrary depth in the tree. The `GeoVolumeAction` is an abstract base class and should be subclassed by programmers to suit their needs. Another class `TemplateVolAction` is provided as a template that one can take and modify. To run it, one does this:
+That mechanism involves a `GeoVolumeAction`. A `GeoVolumeAction` is a way (for applications programmers) to obtain recursive behavior without writing any recursive routines. It’s a class with a handler routine (`handleVPhysVol()`) which is called for each node before (or after) it is called on its children. This can descend to an arbitrary depth in the tree. The `GeoVolumeAction` is a base class and should be subclassed by programmers to suit their needs. Another class `TemplateVolAction` is provided as a template that one can take and modify. To run it, one does this:
```cpp
PVConstLink myVol;
@@ -184,8 +179,8 @@ Incidentally, there is another kind of action in the library called `GeoNodeActi
```cpp
PVConstLink myVol;
for(int c=0; c<myVol->getNChildVols(); ++c) {
- GeoAccessVolumeAction av(c);
- myVol->exec(&ac);
+ GeoAccessVolumeAction av(c,nullptr);
+ myVol->exec(&av);
PVConstLink child = av.getVolume();
GeoTrf::Transform3D xf = av.getTransform();
}
@@ -197,7 +192,7 @@ This, it turns out, will execute faster than the loop shown above, which (intern
We now come to the important topic of how objects in this system are created and destroyed. The geometry kernel uses a technique called reference counting. Reference counting, shortly stated, is a way to perform an automatic garbage collection of nodes that are no longer in use. This is important when describing a large tree of information, much of which is ideally to be shared — used again and again in many places.
-You may have noticed, in several code examples used throughout the GeoModel Kernel Overview section many of the objects have been created using operator `new`. You may have also noticed, if you’ve tried to play around with the kernel classes, that statements which allocate most kernel classes on the stack, such as
+You may have noticed, in several code examples used throughout the GeoModel Kernel Overview section many of the objects have been created using operator `new`, and the resulting pointers were never used directly. Instead they have always been wrapped into objects of a special smart pointer class `GeoIntrusivePtr`. You may have also noticed, if you’ve tried to play around with the kernel classes, that statements which allocate most kernel classes on the stack, such as
```cpp
GeoBox box(100*SYSTEM_OF_UNITS::cm
@@ -210,13 +205,13 @@ are not allowed. Who is going to clean up the memory after all these `new `opera
Let's consider this example:
```cpp
-const GeoBox* worldBox = new GeoBox(100*SYSTEM_OF_UNITS::cm
- , 100*SYSTEM_OF_UNITS::cm
- , 100*SYSTEM_OF_UNITS::cm);
-const GeoLogVol* worldLog = new GeoLogVol("WorldLog"
- , worldBox
- , worldMaterial);
-GeoPhysVol* worldPhys = new GeoPhysVol(worldLog);
+GeoIntrusivePtr<const GeoBox> worldBox{new GeoBox(100*SYSTEM_OF_UNITS::cm
+ , 100*SYSTEM_OF_UNITS::cm
+ , 100*SYSTEM_OF_UNITS::cm)};
+GeoIntrusivePtr<const GeoLogVol> worldLog{new GeoLogVol("WorldLog"
+ , worldBox
+ , worldMaterial)};
+GeoIntrusivePtr<GeoPhysVol> worldPhys{new GeoPhysVol(worldLog)};
```
Each of the three objects (`worldBox`, `worldLog`, and `worldPhys`) are created with a reference count. `worldBox`’s is initially zero, at the time it is created. `worldLog`’s is also zero when it is created. However, when `worldLog` is created, the reference count of `worldBox` increases to one, since now it is referenced somewhere — namely by the logcal volume `worldLog`. Now, when the physical volume `worldPhys` is created, the reference count of the logical volume will increase to one — since it is used once by a single physical volume.
@@ -225,22 +220,6 @@ Each time a physical volume is positioned within another physical volume, its re
When the very last node referencing the physical volume is destroyed, this means that the physical volume itself has outlived its usefulness and *should disappear*. And that is what happens. The destruction of objects is carried out automatically when the reference count falls to zero. And in fact, the only way to delete an object is to arrange for all of its references to disappear. This is because the destructor of all reference counted objects is private.
-This scheme applies to elements, materials, shapes, logical volumes, physical volumes, full physical volumes, and instances of all other classes which also inherit from the `RCBase` class.
-
-So far, we have described what happens to an object when it is no longer used by any other node in the tree. However, what about the top of the tree, which has no nodes that refer to it? Since the destructors of our physical volumes are private, how do you arrange to get it to go away?
-
-Reference counts can also be manipulated manually, by using the methods `ref()` and `unref()`. The physical volume at the head of the tree, often known as the “world†physical volume, can be referenced manually using this call:
-
-```cpp
-worldPhys->ref(); // increments reference count by one
-```
-
-Later, you can destroy the world volume and trigger a global collection of garbage by using this call:
-
-```cpp
-worldPhys->unref() // decrements reference count by one
-```
-
-When the reference count becomes 0, the world physical volume deletes itself, decreasing the reference counts of its logical volume and any children. These will then begin dereferencing and possibly deleting their own children, until all the memory has been freed.
+This scheme applies to elements, materials, shapes, logical volumes, physical volumes, full physical volumes, and instances of all other classes which also inherit from the `RCBase` class. The reference counting machanism described above is implemented automatically by the smart pointer class `GeoIntrusivePtr` (which works similarly to [Boost intrusive_ptr](https://www.boost.org/doc/libs/1_86_0/libs/smart_ptr/doc/html/smart_ptr.html#intrusive_ptr)). While in theory it is possible to operate GeoModel objects by using bare pointers and manual handling of reference counting (by calling `ref()` and `unref()` methods of the `RCBase` base class), it is *not recommended* to do that as this approach is error-prone, and it can easily lead to memory leaks and other memory access problems.
-Suppose now that you want to arrange for a node to not be deleted automatically in this fashion — even when nobody references it any more. In order to do this, simply call the `ref()` method on this object. That way, the reference counts starts at 1 and will not fall to zero until you call `unref()`, manually.
+So far, we have described what happens to an object when it is no longer used by any other node in the tree. However, what about the top of the tree, which has no nodes that refer to it? How do you arrange to get it to go away? Well, the answer on this question is pretty simple: it is enough for all corresponding instances of the `GeoIntrusivePtr` to go out of scope. This will bring the embedded reference count of the tree top object to 0 and the object will delete itself, decreasing the reference counts of its logical volume and any children. These will then begin dereferencing and possibly deleting their own children, until all the memory has been freed.
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Annulus.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Annulus.png
new file mode 100644
index 0000000000000000000000000000000000000000..d21fbb3db11f1afc5ff4518480f23d79dcd52931
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Annulus.png differ
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/AnnulusDemo.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/AnnulusDemo.png
new file mode 100644
index 0000000000000000000000000000000000000000..9a9826b16a555bb28c6d1383df83cd87604759e6
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/AnnulusDemo.png differ
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/AnnulusDemo2.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/AnnulusDemo2.png
new file mode 100644
index 0000000000000000000000000000000000000000..e26e38f03c1546a914f4244162b2aa2c161ec278
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/AnnulusDemo2.png differ
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Diamond.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Diamond.png
new file mode 100644
index 0000000000000000000000000000000000000000..348e347132f0a3a2cf5952adb087a77ddc5c68fc
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Diamond.png differ
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/DiamondDemo.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/DiamondDemo.png
new file mode 100644
index 0000000000000000000000000000000000000000..9736ca97c6e52551ab135fd35c5a912867bca645
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/DiamondDemo.png differ
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoAnnulusSurface.md b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoAnnulusSurface.md
new file mode 100644
index 0000000000000000000000000000000000000000..d27674bea68ec8522656c08e6324d9114e6309b6
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoAnnulusSurface.md
@@ -0,0 +1,33 @@
+### GeoAnnulusSurface
+
+
+```cpp
+// === GeoAnnulusSurface ===
+
+ // Constructor:
+ // The default position of the cylinder center is at (0,0,0)
+ // Ox, Oy: the deviation of the focusing point from the default position
+ // radius_in: the inner radius of the annulus
+ // radius_out: the outer radius of the annulus
+ // phi: the span angle of the deviated circular sector, when phi = 2*PI, it is an annulus
+ GeoAnnulusSurface(double Ox, double Oy, double radius_in, double radius_out, double phi);
+
+
+ // Public Methods:
+ double getOx() const;
+ double getOy() const;
+ double getRadiusIn() const;
+ double getRadiusOut() const;
+ double getPhi() const;
+ void exec (GeoShapeAction *action) const override final;
+ virtual bool isOnSurface (const double Px, const double Py, const double Pz, const GeoTrf::Transform3D & trans) const override final;
+```
+
+A `GeoAnnulusSurface` represents an annulus (or circular sector) virtual surface initialized at XOY plane. It is specified by *Ox (X-position of deviated center)*, *Oy (Y-position of deviated center)*, *Inner Radius*, *Outer Radius*, and *Span Angle $\Phi$*, all input parameters of the constructor. The methods `getOx()`, `getOy()`, `getRadiusIn()`, `getRadiusOut()`, and `getPhi()` return the shape boundaries of the surface. When $\phi = 2\pi$, the circular section returns to an annulus.
+
+
+{{ imgutils_image_caption('RCBase/GeoVSurfaceShape/Annulus.png',
+ alt='The GeoAnnulusSurface shape',
+ cap='Figure: Shape boundaries of annulus surface.',
+ urlFix=False)
+}}
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoDiamondSurface.md b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoDiamondSurface.md
new file mode 100644
index 0000000000000000000000000000000000000000..7cdcc792b33673f470833d5ce7deec534bc27d8e
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoDiamondSurface.md
@@ -0,0 +1,31 @@
+### GeoDiamondSurface
+
+
+```cpp
+// === GeoDiamondSurface ===
+
+ // Constructor:
+ GeoDiamondSurface (double X_bottom_half, double X_mid_half, double X_top_half, double Y_bottom_half, double Y_top_half);
+
+
+ // Public Methods:
+ double area() const;
+
+ double getXbottomHalf () const;
+ double getXmidHalf () const;
+ double getXtopHalf () const;
+ double getYbottomHalf () const;
+ double getYtopHalf () const;
+ void exec (GeoShapeAction *action) const override final;
+ virtual bool isOnSurface (const double Px, const double Py, const double Pz, const GeoTrf::Transform3D & trans) const override final;
+```
+
+A `GeoDiamondSurface` represents a diamond virtual surface initialized at XOY plane. It is specified by *X half-length bottom*, *X half-length middle*, *X half-length top* in X-direction and *Y half-length bottom*, *Y half-length top* in Y-direction, which are input parameters of the constructor. The public methods `exec` and `isOnSurface` inherits methods from `GeoVSurfaceShape`, methods `getXbottomHalf()`, `getXmidHalf()`, `getXtopHalf()`, `getYbottomHalf()`, and `getYtopHalf()` return the shape boundaries of the surface. `area()` returns the area of the diamond.
+
+
+{{ imgutils_image_caption('RCBase/GeoVSurfaceShape/Diamond.png',
+ alt='The GeoDiamondSurface shape',
+ cap='Figure: Shape boundaries of diamond surface.',
+ urlFix=False)
+}}
+
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoRectSurface.md b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoRectSurface.md
new file mode 100644
index 0000000000000000000000000000000000000000..c225fd08347c7ca0ae02182dc45ac429ea081629
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoRectSurface.md
@@ -0,0 +1,27 @@
+### GeoRectSurface
+
+
+```cpp
+// === GeoRectSurface ===
+
+ // Constructor:
+ GeoRectSurface (double XHalfLength, double YHalfLength);
+
+
+ // Public Methods:
+ double area() const;
+ double getXHalfLength () const;
+ double getYHalfLength () const;
+ void exec (GeoShapeAction *action) const override final;
+ virtual bool isOnSurface (const double Px, const double Py, const double Pz, const GeoTrf::Transform3D & trans) const override final;
+```
+
+A `GeoRectSurface` represents a rectangle virtual surface initialized at the XOY plane. It is specified by a *half-length* in X-direction and a *half-length* in Y-direction, which are input parameters of the constructor. Methods `getXHalfLength()`, `getYHalfLength()` return the shape boundaries of the surface. `area()` returns the area.
+
+
+{{ imgutils_image_caption('RCBase/GeoVSurfaceShape/Rect.png',
+ alt='The GeoRectSurface shape',
+ cap='Figure: Shape boundaries of rectangle surface.',
+ urlFix=False)
+}}
+
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoTrapezoidSurface.md b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoTrapezoidSurface.md
new file mode 100644
index 0000000000000000000000000000000000000000..0f8793bd50fb3247bc98278530976b732e2dad7b
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoTrapezoidSurface.md
@@ -0,0 +1,27 @@
+### GeoTrapezoidSurface
+
+
+```cpp
+// === GeoTrapezoidSurface ===
+
+ // Constructor:
+ GeoTrapezoidSurface (double XHalfLengthMin, double XHalfLengthMax, double YHalfLength);
+
+
+ // Public Methods:
+ double area() const;
+ double getXHalfLengthMin () const;
+ double getXHalfLengthMax () const;
+ double getYHalfLength () const;
+ void exec (GeoShapeAction *action) const override final;
+ virtual bool isOnSurface (const double Px, const double Py, const double Pz, const GeoTrf::Transform3D & trans) const override final;
+```
+
+A `GeoTrapezoidSurface` represents a trapezoid virtual surface initialized at XOY plane. It is specified by *X half-length minimum* (or bottom half-length) and *X half-length maximum* (or top half-length) in X-direction and *Y half-length* in Y-direction, which are input parameters of the constructor. The methods `getXHalfLengthMin()`, `getXHalfLengthMax`, and `getYHalfLength()` return the shape boundaries of the surface. `area()` returns the area of the trapezoid.
+
+
+{{ imgutils_image_caption('RCBase/GeoVSurfaceShape/Trapezoid.png',
+ alt='The GeoTrapezoidSurface shape',
+ cap='Figure: Shape boundaries of trapezoid surface.',
+ urlFix=False)
+}}
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoVSurface.md b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoVSurface.md
new file mode 100644
index 0000000000000000000000000000000000000000..fc766ba8e2bae75b5783b08af9ccfe4e4338db84
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoVSurface.md
@@ -0,0 +1,23 @@
+### GeoVSurface
+
+
+The class GeoVSurface takes [Virtual Surface Shape](#geovsurfaceshape) as input to the constructor, and is used to embed the shape within the geometry tree. It provides access to the SurfaceShape and can determine whether a triplet of coordinates lies on and within the surface.
+
+
+```cpp
+// === GeoVSurface ===
+
+ //Constructor:
+ GeoVSurface(const GeoVSurfaceShape *SurfShape);
+
+ //Public Methods:
+ const GeoVSurfaceShape* getShape () const
+ virtual void exec(GeoNodeAction *action) const;
+ bool isOnSurface(const double Px, const double Py, const double Pz) const;
+```
+For example, if we want to construct a rectangle virtual surface node, we just need to first construct the surface shape and then construct the virtual surface node:
+
+```cpp
+ GeoRectSurface* rectangle = new GeoRectSurface(5, 9); // 5 is X half length and 9 is Y half length
+ GeoVSurface* surface = new GeoVSurface(rectangle); // construct a virtual surface node in rectangle shape
+```
\ No newline at end of file
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoVSurfaceShape.md b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoVSurfaceShape.md
new file mode 100644
index 0000000000000000000000000000000000000000..46ed45d46d2574464124522c2ed690b42d27b151
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/GeoVSurfaceShape.md
@@ -0,0 +1,19 @@
+### GeoVSurfaceShape
+
+
+The abstract class GeoVSurfaceShape defines the interface for subclasses, specifically the `isOnSurface` method.
+
+```cpp
+// === GeoVSurfaceShape ===
+
+ //Constructor:
+ GeoVSurfaceShape () = default;
+
+ //Public Methods:
+ //Executes a GeoShapeAction on the surface shape
+ virtual void exec (GeoShapeAction *action) const = 0;
+ //Determines whether the point(Px,Py,Pz) is on the surface, can be overriden by child methods
+ virtual bool isOnSurface (const double Px, const double Py, const double Pz, const GeoTrf::Transform3D & trans) const = 0;
+```
+
+All surface shapes are initialized at X-O-Y plane. In *gmex* when visualized, the side initially facing at +Z direction is in red color, while the side initially facing at -Z direction is in green color. The following subsections show specific examples of virtual surface shapes.
\ No newline at end of file
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Rect.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Rect.png
new file mode 100644
index 0000000000000000000000000000000000000000..21ae1c57a0d18f6df62f9ba97ab1da915052c3c6
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Rect.png differ
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/RectDemo.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/RectDemo.png
new file mode 100644
index 0000000000000000000000000000000000000000..82796f1e0c82c7bfe8887df86da60fbf08892139
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/RectDemo.png differ
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/SurfaceClassRef.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/SurfaceClassRef.png
new file mode 100644
index 0000000000000000000000000000000000000000..9d42ba7aa6a92752c85ca076975e0904e2548175
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/SurfaceClassRef.png differ
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Trapezoid.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Trapezoid.png
new file mode 100644
index 0000000000000000000000000000000000000000..deb177c9ecf1fc22e06efa7fe06f338ac7b0d25b
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/Trapezoid.png differ
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/TrapezoidDemo.png b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/TrapezoidDemo.png
new file mode 100644
index 0000000000000000000000000000000000000000..da24d089cece86b0b68ddb735bbea22238fddd7c
Binary files /dev/null and b/documentation/docs/components/kernel/reference/RCBase/GeoVSurfaceShape/TrapezoidDemo.png differ
diff --git a/documentation/docs/components/kernel/reference/VirtualSurface.md b/documentation/docs/components/kernel/reference/VirtualSurface.md
new file mode 100644
index 0000000000000000000000000000000000000000..d2c2b184e7cd52616973aa1ea7e8ad19a9ab753e
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/VirtualSurface.md
@@ -0,0 +1,14 @@
+
+## Virtual Surfaces
+
+### Introduction
+
+Virtual surface classes are light weight classes describing geometrical objects devoid of any material properties. They are introduced for particle tracking and fast simulation purposes. Like `GeoVFullPhysVol`, the `GeoVSurface` class caches its absolute position locally and responds to alignment updates further up the tree. Virtual surface nodes may be parented within *physical volumes*, but they do not have any child nodes of any kind. The node actions are adapted to work with surface classes as well.
+
+{{ imgutils_image_caption('RCBase/GeoVSurfaceShape/SurfaceClassRef.png',
+ alt='The GeoVSurface inheritance',
+ cap='Figure: GeoVSurface inheritance relations.',
+ urlFix=False)
+}}
+
+{% include 'components/kernel/reference/RCBase/GeoVSurfaceShape/GeoVSurface.md' %}
\ No newline at end of file
diff --git a/documentation/docs/components/kernel/reference/VirtualSurfaceShape.md b/documentation/docs/components/kernel/reference/VirtualSurfaceShape.md
new file mode 100644
index 0000000000000000000000000000000000000000..3eca9cdd3192f1a9bc162a2025241612e10f86dd
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/VirtualSurfaceShape.md
@@ -0,0 +1,35 @@
+
+
+## Virtual Surface Shape
+
+
+### Introduction
+
+The virtual surface shape classes are designed to describe the geometry of two dimensional virtual surfaces. The specific surface shape classes are used as input variables of `GeoVSurface`, as described in section [GeoVSurface](#geovsurface). The set of surfaces is extensible.
+
+
+
+In the table here below, a list of the existing virtual surface shapes in the GeoModelKernel package is given:
+
+
+| Class | Virtual Surface Shape |
+| ------- | ----- |
+| [GeoRectSurface](#georectsurface) | Rectangle |
+| [GeoTrapezoidSurface](#geotrapezoidsurface) | Trapezoid |
+| [GeoDiamondSurface](#geodiamondsurface) | Diamond |
+| [GeoAnnulusSurface](#geoannulussurface) | Annulus / Circular Sector |
+
+The surface shapes can be visualized by *gmex*, and some screenshots appear in the following documentation.
+
+
+{% include 'components/kernel/reference/RCBase/GeoVSurfaceShape/GeoVSurfaceShape.md' %}
+
+{% include 'components/kernel/reference/RCBase/GeoVSurfaceShape/GeoRectSurface.md' %}
+
+{% include 'components/kernel/reference/RCBase/GeoVSurfaceShape/GeoTrapezoidSurface.md' %}
+
+{% include 'components/kernel/reference/RCBase/GeoVSurfaceShape/GeoDiamondSurface.md' %}
+
+{% include 'components/kernel/reference/RCBase/GeoVSurfaceShape/GeoAnnulusSurface.md' %}
+
+
diff --git a/documentation/docs/components/kernel/reference/index.md b/documentation/docs/components/kernel/reference/index.md
index 3914f0ebd38ec659685ce16fce1d9b856323b4c1..2289376fa8fa2231c0d4ecdf6470dcaedf8bcded 100644
--- a/documentation/docs/components/kernel/reference/index.md
+++ b/documentation/docs/components/kernel/reference/index.md
@@ -15,6 +15,10 @@ Detailed descriptions of the geometry kernel classes follow.
{% include 'components/kernel/reference/LogicalVolumes.md' %}
+{% include 'components/kernel/reference/VirtualSurfaceShape.md' %}
+
+{% include 'components/kernel/reference/VirtualSurface.md' %}
+
{% include 'components/kernel/reference/PhysicalVolumes.md' %}
{% include 'components/kernel/reference/Transformations.md' %}
diff --git a/documentation/docs/fullsimlight/fsl/fslDemo.mov b/documentation/docs/fullsimlight/fsl/fslDemo.mov
new file mode 100644
index 0000000000000000000000000000000000000000..8824532d7c1a22b4ab774bb1d14703223ef142d0
Binary files /dev/null and b/documentation/docs/fullsimlight/fsl/fslDemo.mov differ
diff --git a/documentation/docs/fullsimlight/fsl/fsl_gmclashDemo.mov b/documentation/docs/fullsimlight/fsl/fsl_gmclashDemo.mov
new file mode 100644
index 0000000000000000000000000000000000000000..8c5da98ebcd2f174899e67540dc17d5b03c781a6
Binary files /dev/null and b/documentation/docs/fullsimlight/fsl/fsl_gmclashDemo.mov differ
diff --git a/documentation/docs/fullsimlight/fsl/index.md b/documentation/docs/fullsimlight/fsl/index.md
index 8e842685904ee679a8fdf86a8749e53354b55be7..197ed9a95141ffec2193c6b63cffe6c9b1ddb8bc 100644
--- a/documentation/docs/fullsimlight/fsl/index.md
+++ b/documentation/docs/fullsimlight/fsl/index.md
@@ -1,24 +1,30 @@
-# fsl
+# FullSimLight GUI: fsl
-fsl is a GUI for FullSimLight introduced in GeoModel release 4.3.0. It allows users to configure their simulations in FullSimLight easily and without conflicts by providing a series of tabs which offer various configuration options. It can be ran from the command line through the fsl command.
+`fsl` is a GUI for `fullSimLight` introduced in `GeoModel` release `4.3.0`. It allows users to configure their simulations in `fullSimLight` easily and without conflicts by providing a series of tabs which offer various configuration options. It can be ran from the command line through the `fsl` command.
```bash
./fsl
```
- Compatibility of the simulation is ensured by the fsl interface by enabling and disabling options based on the selections made. Once the user has configured the simulation to their desire, they can save the configuration in a json file that can be used to run FullSimLight through the -c flag.
+ Compatibility of the simulation is ensured by the `fsl` interface by enabling and disabling options based on the selections made. Once the user has configured the simulation to their desire, they can save the configuration in a json file that can be used to run `fullSimLight` through the `-c` flag.
```bash
./fullSimLight -c /path/to/config.json
```
-Alternatively the user can run FullSimLight at any time within fsl itself with the current configuration. fsl also allows users to load in previously saved configurations through the **Open Configuration** option.
-One can also load in a configuration by running fsl with the -c flag.
+Alternatively, the user can run `fullSimLight` at any time within `fsl` itself with the current configuration. `fsl` also allows users to load in previously saved configurations through the `Open Configuration` option.
+One can also load in a configuration by running `fsl` with the `-c` flag.
```bash
./fsl -c /path/to/config.json
```
+!!! Tip "Watch!"
+
+ Watch the following video for a quick demo on how to configure and launch `fullSimLight` with its GUI `fsl`!
+
+ <video src="../fsl/fslDemo.mov" width="720" height="540" controls></video>
+
## Main Tab
@@ -36,9 +42,15 @@ The main tab allows configuration of the following parameters:
- Physics List
- Number of Threads
- Number of Events
-- G4UI Verbosity Commands
+- `G4UI` Verbosity Commands
+
+It also contains the view button which shows the current configuration on the main display. The user can also run `fullSimLight` in the main display at any time with the current configuration by clicking on the `fullSimLight` button in the main tab. `fsl` provides similar buttons to run `gmex` and `gmclash` once a geometry input has been selected through the interface.
+
+!!! Tip "Watch!"
-It also contains the view button which shows the current configuration on the main display. The user can also run FullSimLight in the main display at any time with the current configuration by clicking on the FullSimLight button in the main tab. fsl provides similar buttons to run gmex and gmclash once a geometry input has been selected through the interface.
+ Watch the following video for a demo on how to easily run clash detection and visualize the clashing point together with the 3D geometry directly within `fsl`!
+
+ <video src="../fsl/fsl_gmclashDemo.mov" width="720" height="540" controls></video>
## Generator Tab
@@ -54,28 +66,28 @@ It also contains the view button which shows the current configuration on the ma
The generator tab shown above contains a list of event generators that can be selected for event generation. The options provided are:
- Particle Gun
-- Pythia
-- HepMC3 File
+- `Pythia`
+- `HepMC3` File
- Generator Plugin
### 1. Particle Gun
-To use a Geant4 particle gun, the user must specify the particle type and the momentum vector.
+To use a `Geant4` particle gun, the user must specify the particle type and the momentum vector.
### 2. Pythia
-To use Pythia one can select one of the pre-customized options which are
+To use `Pythia` one can select one of the pre-customized options which are
- ttbar
- higgs
- minbias
Details about the default options can be found in the `PythiaPrimaryGeneratorAction` [class](https://gitlab.cern.ch/GeoModelDev/GeoModel/-/blob/main/FullSimLight/src/PythiaPrimaryGeneratorAction.cc).
-Alternatively one can also provide a custom Pythia configuration input file.
+Alternatively one can also provide a custom `Pythia` configuration input file.
### 3. HepMC3 File
-HepMC3 files containing events can be used in FullSimLight in both the standard Asciiv3 format (introduced in HepMC3) as well as the old Ascii format (used in HepMC and HepMC2).
+`HepMC3` files containing events can be used in `fullSimLight` in both the standard `Asciiv3` format (introduced in `HepMC3`) as well as the old `Ascii` format (used in `HepMC` and `HepMC2`).
### 4. Generator Plugin
@@ -91,7 +103,7 @@ In order to generate events one can also specify a plugin. Visit the [Plugin Sup
urlFix=False)
}}
-To set a Magnetic Field, there are two options
+To set a Magnetic Field, there are two options:
- Fixed Axial
- Magnetic Field Plugin
@@ -103,7 +115,13 @@ Sets a constant Magnetic field in the z-direction at the specified magnitude.
### 2. Magnetic Field Plugin
-In order to generate a Magnetic Field one can also specify a plugin. Visit the [Plugin Support page](https://geomodel.web.cern.ch/home/fullsimlight/plugin-support/) for more details. A custom ATLAS Magnetic Field Plugin comes with the GeoModel package ready to use. This is automatically contained in the atlas-conf.json configuration file provided by GeoModel. ***Warning: This Plugin requires the ATLAS Magnetic Field Map to be installed in a standard location. This Map is available to all ATLAS users on request.***
+In order to generate a Magnetic Field one can also specify a plugin. Visit the [Plugin Support page](https://geomodel.web.cern.ch/home/fullsimlight/plugin-support/) for more details.
+
+A custom ATLAS Magnetic Field Plugin comes with the `GeoModel` package ready to use with the ATLAS Extensions package. This is automatically contained in the `atlas-conf.json` configuration file provided by GeoModel.
+
+!!! Warning
+
+ This Plugin requires the ATLAS Magnetic Field Map to be installed in a standard location. For more info visit the [Atlas Extensions](https://geomodel.web.cern.ch/home/fullsimlight/atlas-extensions/) page.
## Regions Tab
@@ -116,7 +134,7 @@ In order to generate a Magnetic Field one can also specify a plugin. Visit the [
urlFix=False)
}}
-Geant4 regions can be added through the regions tab in FSL as shown above. For each region one must specify
+`Geant4` regions can be added through the regions tab in `fsl` as shown above. For each region one must specify
- Region name
- Root Logical Volumes
@@ -125,7 +143,7 @@ Geant4 regions can be added through the regions tab in FSL as shown above. For e
- Positron cut (GeV)
- Gamma cut (GeV)
-A list of ATLAS specific regions comes in the atlas-conf.json configuration file provided by GeoModel.
+A list of ATLAS specific regions comes in the `atlas-conf.json` configuration file provided by GeoModel.
## Sensitive Detectors Tab
@@ -137,7 +155,7 @@ A list of ATLAS specific regions comes in the atlas-conf.json configuration file
urlFix=False)
}}
-In order to add Geant4 Sensitive Detectors one can create plugins which can then be added to the simulation through the menu shown above. Visit the [Plugin Support page](https://geomodel.web.cern.ch/home/fullsimlight/plugin-support/) for more details.
+In order to add `Geant4` Sensitive Detectors one can create plugins which can then be added to the simulation through the menu shown above. Visit the [Plugin Support page](https://geomodel.web.cern.ch/home/fullsimlight/plugin-support/) for more details.
## User Actions Tab
@@ -150,4 +168,4 @@ In order to add Geant4 Sensitive Detectors one can create plugins which can then
urlFix=False)
}}
-In order to add Geant4 User Actions one can create plugins which can then be added to the simulation through the menu shown above. Visit the [Plugin Support page](https://geomodel.web.cern.ch/home/fullsimlight/plugin-support/) for more details.
+In order to add `Geant4` User Actions one can create plugins which can then be added to the simulation through the menu shown above. Visit the [Plugin Support page](https://geomodel.web.cern.ch/home/fullsimlight/plugin-support/) for more details.
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..5467a5e4521c77ba93ddda05cd1c15246f4b9340 100644
--- a/documentation/docs/fullsimlight/fullsimlight/index.md
+++ b/documentation/docs/fullsimlight/fullsimlight/index.md
@@ -1,113 +1,192 @@
# FullSimLight
-FullSimLight package consists of different tools based on [Geant4](https://geant4.web.cern.ch) toolkit, that can be run on multiple geometries:
+FullSimLight package consists of different tools based on the [Geant4](https://geant4.web.cern.ch) toolkit, that can be run on multiple geometries. It contains:
-- 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 `Geant4` 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 install FullSimLight from development kits please refer to the [Install library and tools section](https://geomodel.web.cern.ch/home/start/install/). If you are a developer and want to build FullSimLight from source code, 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 customized `Geant4` User Actions, Sensitive Detectors, specialised Physics Lists, custom particle generators, etc. These flexibility is provided through the mechanism of plugins which come in the form of shared libraries (.dylib or .so) containing user custom code.
-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.
+A built-in visualization for `fullSimLight` output is available in [gmex](https://geomodel.web.cern.ch/home/components/geomodelvisualization/gmex/) (the interactive 3D geometry visualization tool which is part of GeoModel). HITS steps and tracks generated with `fullSimLight` can be fed into `gmex`and consequently visualised. As an example the following figures can be seen. Figure 1 shows a HITS steps display of events transported with `fullSimLight` in the full ATLAS detector.
-### ATLAS Geometry Files:
+{{ imgutils_image_caption('StepDisplay.png',
+ alt='StepDisplay',
+ cap='Figure 1: Steps display of events 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.
+Figure 2 shows a HITS tracks display of events transported with `fullSimLight` in the full ATLAS detector.
+{{ imgutils_image_caption('TrackDisplay.png',
+ alt='TrackDisplay',
+ cap='Figure 2: Track display of primaries transported with fullSimLight in the full ATLAS detector.',
+ urlFix=False)
+}}
-## 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: run and main components
-NB: Before running fullSimLight make sure to source the *geant4.sh* file to set correctly all the Geant4 environment variables.
-```bash
-source <path_to_geant4_install_dir>/bin/geant4.sh
-```
+`fullSimLight` can be built and used both with sequential and multithreaded `Geant4` builds. In case of multithreaded installation of `Geant4`, the application 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.
+
+!!! note
+
+ Before running fullSimLight make sure to source the *geant4.sh* file to set correctly all the Geant4 environment variables.
+
+ ```
+ source <path_to_geant4_install_dir>/bin/geant4.sh
+ ```
+
+
+`fullSimLight` can be configured in multiple ways (using `fsl` generated json configuration files or the `Geant4` macro files) and run either from the command line or within `fsl`.
-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:
+
+## Configure and run fullSimLigth with its GUI fsl
+
+`fullSimLight` can be very easily configured and run via `fsl`, both from within the GUI or from the command-line, passing a json configuration file with the `-c` flag. Watch the following video for a quick demo on how to configure and launch `fullSimLight` with its GUI `fsl`!
+
+<video src="../fsl/fslDemo.mov" width="720" height="540" controls></video>
+
+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).
+
+## Run fullSimLigth from the command line
+
+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. It can be specified inside the config file or with the `-g` flag.
+
+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
- : - ==> run the application in NON performance mode i.e. with user actions (default)
+-P : [OPTIONAL] :use Pythia primary generator [config. available: ttbar/higgs/minbias or use a Pythia command input file]
```
+Please refer to the [Command line examples](#command-line-examples) section for some examples that illustrate the different possibilities.
-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.
+### Parameters configuration via Geant4 macro (disfauvored)
-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.
+`fullSimLight` and in general `Geant4` based simulations, need a `Geant4` macro to inject 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 `Geant4` verbosity, the number of threads, or to tune the simulation. The most relevant macro commands are explained in the sections [Particle gun](#particle-gun) and [Magnetic field](#magnetic-field).
-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.
+Please note that this option is deprecated, as it doesn't allow full flexibility, and we suggest to configure your simulation via `fsl`.
-## 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.
+## Detector Construction
-If you have created your custom configuration file <myconfig.json> with fsl, you can simply run fullSimLight as follows:
+The supported geometry formats are SQLite (.db), GDML (.gdml) and plugins compiled as shared libraries (.dylib/.so) that contains the C++ code that builds from scratch a GeoModel geometry. An example of geometry plugin can be found in the GeoModelExamples folder and it is the so-called [KitchenSinkPlugin](https://gitlab.cern.ch/GeoModelDev/GeoModel/-/tree/main/GeoModelExamples/KitchenSinkPlugin).
-``` 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.
+Use the `-g` flag to specify the name of the input geometry file.
+
+### ATLAS Geometry Files
+
+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.
+
+## Event generation
-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.
+`fullSimLight` uses by default the `Geant4` particle gun as primary generator. In addition, it supports also
+input events from the [Pythia](http://home.thep.lu.se/Pythia/) generator, [HepMC3](https://gitlab.cern.ch/hepmc/HepMC3) formats or custom event generators plugins.
-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:
+### Particle gun
+
+The particle gun can be tuned either via `fsl` or by editing the `Geant4` macro file. The default configuration of the `macro.g4` file will generate 10 GeV primary particles (randomly chosen between e-,e+ and gammas) at the (0,0,0) position with isotropic momentum direction.
+
+Following are the UI commands that can be used to tune the `fullSimLight` particle gun.
+
+#### Number of primaries per event:
+The number of primary particles per event can be set through the macro
+command:
``` bash
-./fullSimLight -g mygeometry.db
+/FSLgun/primaryPerEvt <number>
```
-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* :
+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:
+The primary particle energy can be set through the macro command:
``` bash
-./fullSimLight -g libPixePlugin.1.0.0.dylib/.so
+/FSLgun/energy <energy-value> <unit>
+```
+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:
+The primary particle momentum direction can be set through the macro command:
+
+``` bash
+/FSLgun/direction <xdir-value> <ydir-value> <zdir-value>
```
+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:
+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.
-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 :
+### 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 its support activated.
+
+ In order to specify that `fullSimLight` has o run with `Pythia` event, the `-P` or `--pythia` flag has to be used.
+ Three different default options are available to run with `Pythia` events: `ttbar`, `higgs` and `minbias`:
+
``` bash
-./fullSimLight -m mymacro.g4 -f FTFP_BERT_ATL -p -g geometry-ATLAS-R2-2016-01-00-01.db
+ -P : generate events with Pythia [config. available: ttbar/higgs/minbias or use ascii input file]
```
-Please note that the last option is deprecated, as it doesn't allow full flexibility, and we suggest to configure your simulation via `fsl`.
+The default configurations are currently defined as follows:
+``` bash
+
+static const char *pythia_minbias[] = {
+ "HardQCD:all = on",
+ "Beams:eCM = 13000.0",
+ "PhaseSpace:pTHatMin = 20.0",
+};
+
+static const char *pythia_higgs[] = {
+ "HiggsSM:all = on",
+ "Beams:eCM = 13000.0",
+ "PhaseSpace:pTHatMin = 20.0",
+};
+
+static const char *pythia_ttbar[] = {
+ "Top:gg2ttbar = on",
+ "Top:qqbar2ttbar = on",
+ "Beams:eCM = 13000.0",
+ "PhaseSpace:pTHatMin = 20.0",
+};
+```
+For example, in order to simulate the default *ttbar* events, the command to be run is the following:
+
+```bash
-## 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).
+./fullSimLight -m ../share/FullSimLight/pythia.g4 -P ttbar -g mygeometry.db
-## Parameters configuration via Geant4 macro (deprecated)
+```
+
+Alternatively, the user can plug their own Pythia configuration file to simulate the desired events.
+
+ The number of events that the user wants to simulate must be specified in a `Geant4` macro file. A specific `pythia.g4` macro file can be found in the `<path-to-install>/share/FullSimLight` directory. It should be used when simulating `Pythia` events and can be edited according to the user needs.
+
+### HepMC3 events input
-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.
+`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](https://geomodel.web.cern.ch/home/fullsimlight/fsl/) section for more info.
## Magnetic field
@@ -119,111 +198,130 @@ FullSimLight and in general Geant4 based simulations, need a Geant4 macro to rea
The default value is a uniform magnetic field of 4 Tesla.
-## ATLAS Magnetic Field
+### 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
-The ATLAS magnetic field is integrated in FullSimLight and can be used from it. The magnetic field map file used and supported are:
+ The Physics List can be specified as an input argument with the `-f` flag
+ (e.g. `-f FTFP_BERT_ATL`). Notice that the name of the `Geant4` built in Physics List
+ 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.
-- 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
+## Scoring
-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*.
+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.
-### testMagneticField examples:
-Run the application with the --help flag to see the options:
+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.
+Please see the following output as an example:
+
``` bash
-./testMagneticField --help
+=======================================================================================
+ Run terminated:
+ Number of events transported = 10
+ Time: User=0.020000s Real=0.021719s Sys=0.000000s [Cpu=92.1%]
+ =======================================================================================
+
+ ================================== Run summary =====================================
--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
-```
+ Number of events = 10
+
+ ----------------------------------------------------------------------------------------
-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*:
+ Mean energy deposit per event = 0.01572 +- 0.01243 [GeV]
-``` bash
-./testMagneticField -r -s
-```
+ Mean track length (charged) per event = 67.77 +- 43.66 [cm]
+ Mean track length (neutral) per event = 154.9 +- 113.1 [cm]
-Use the -t to set the Toroids off, and test the *solenoid_bfieldmap_7730_0_14m_version5.root* file.
+ Number of steps (charged) per event = 303.2 +- 215.3
+ Number of steps (neutral) per event = 348.3 +- 255.9
-``` bash
-./testMagneticField -r -t
+ Number of secondaries per event :
+ Gammas = 5.3 +- 4.649
+ Electrons = 11.4 +- 9.78
+ Positrons = 0.3 +- 0.4583
```
-## Primary Generators
-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.
+<!--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.-->
-## 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:
-The number of primary particles per event can be set through the macro
-command:
+
+## Command line examples
+
+If you have created your custom configuration file `myconfig.json` with `fsl`, you can simply run fullSimLight as it follows:
``` bash
-/FSLgun/primaryPerEvt <number>
-```
+./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.
-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.
+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`.
-### Primary particle energy:
-The primary particle energy can be set through the macro command:
+During the installation of FullSimLight a default macro file `macro.g4` will be installed in your `<install-path >/share/FullSimLight` directory. 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, building the detector from `mygeometry.db` file:
``` bash
-/FSLgun/energy <energy-value> <unit>
+./fullSimLight -g mygeometry.db
```
-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:
-The primary particle momentum direction can be set through the macro command:
+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
-/FSLgun/direction <xdir-value> <ydir-value> <zdir-value>
+./fullSimLight -g libPixePlugin.1.0.0.dylib/.so
```
-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:
-The primary particle type can be set through the macro command:
+To execute the application using a custom `mymacro.g4` macro file, with the ATLAS `FTFP_BERT_ATL` Physics List, with `Pythia` ttbar as primary events and building the detector from the `mygeometry.db` file :
``` 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.
-
-
-## 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*):
-
- ``` bash
- -P : generate events with Pythia [config. available: ttbar/higgs/minbias or use ascii input file]
- ```
-
- Alternatively the user can plug their own Pythia configuration file to simulate the desired events.
- 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
- ```
-
- 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
-
-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.
-
-## Physics List
-
- The Physics List can be specified as an input argument with the -f flag
- (e.g. -f FTFP_BERT). Notice that the name of the Geant4 built in Physics List
- 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.
+./fullSimLight -m mymacro.g4 -f FTFP_BERT_ATL -P ttbar -g mygeometry.db
+```
diff --git a/documentation/docs/index.md b/documentation/docs/index.md
index 1ab099478fa5c8882ee28c2483d9cd754dd8b7bc..738bf1bad8d645c5a50035571d2ed62e934dbe74 100755
--- a/documentation/docs/index.md
+++ b/documentation/docs/index.md
@@ -110,7 +110,21 @@ A standalone **mass calculator tool**, to quickly compute the masses of your det
A standalone tool to **generate geantino maps** of your newly built detector
-### Minimal Dependencies
+## Standalone Tools
+
+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
+
+
+## Minimal Dependencies
The GeoModel Toolkit introduces only **minimal** and **lightweight** external dependencies, and **only when you need them**.
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 fe5626b4707eee8e84c40428db1c30366e2de525..adf5cfc37cb13eda589b2c9b124d31d2faa03de2 100755
--- a/documentation/mkdocs.yml
+++ b/documentation/mkdocs.yml
@@ -115,7 +115,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'
@@ -128,18 +130,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'
@@ -148,6 +150,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'