Merge branch 'gm-mass-calculator' into 'master'

GeoModel mass calculator

See merge request !55

FullSimLight/CMakeLists.txt

@@ -101,6 +101,7 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${OUTPUT})
 
 add_executable(fullSimLight fullSimLight.cc ${sources} ${headers})
 add_executable(gmclash geoModelClash.cc ${sources} ${headers})
+add_executable(gmmasscalc geoModelMassCalculator.cc ${sources} ${headers})
 add_executable(fillHistogramExample fillHistogramExample.cc src/Histo.cc include/Histo.hh)
 add_executable(gmgeantino geantinoMaps.cc ${sources} ${headers})
 #add_executable(plotGeantinoMaps plotGeantinoMaps.cc)
@@ -119,6 +120,7 @@ endif()
 if( GEOMODEL_USE_BUILTIN_JSON )
   add_dependencies( fullSimLight JSONExt )
   add_dependencies( gmclash JSONExt )
+  add_dependencies( gmmasscalc JSONExt )
   add_dependencies( fillHistogramExample JSONExt )
   add_dependencies( gmgeantino JSONExt )
   add_dependencies( testMagneticField JSONExt )
@@ -132,6 +134,7 @@ endif()
 if( GEOMODEL_USE_BUILTIN_XERCESC )
     add_dependencies( fullSimLight XercesCBuiltIn )
     add_dependencies( gmclash XercesCBuiltIn )
+    add_dependencies( gmmasscalc XercesCBuiltIn )
     add_dependencies( fillHistogramExample XercesCBuiltIn )
     add_dependencies( gmgeantino XercesCBuiltIn )
     add_dependencies( testMagneticField XercesCBuiltIn )
@@ -146,6 +149,7 @@ target_link_libraries(testMagneticField ${Geant4_LIBRARIES} MagFieldServices Mag
 
 
 target_link_libraries(gmclash PUBLIC GeoModel2G4 ${Geant4_LIBRARIES} MagFieldServices MagFieldInterfaces)
+target_link_libraries(gmmasscalc PUBLIC GeoModel2G4 ${Geant4_LIBRARIES} MagFieldServices MagFieldInterfaces)
 target_link_libraries(fullSimLight PUBLIC GeoModel2G4 ${Geant4_LIBRARIES} MagFieldServices MagFieldInterfaces)
 target_link_libraries(gmgeantino PUBLIC GeoModel2G4 ${Geant4_LIBRARIES} MagFieldServices MagFieldInterfaces)
 target_link_libraries(gm2gdml PUBLIC GeoModel2G4 ${Geant4_LIBRARIES} MagFieldServices MagFieldInterfaces)
@@ -157,11 +161,13 @@ target_link_libraries(gm2gdml PUBLIC GeoModel2G4 ${Geant4_LIBRARIES} MagFieldSer
 # This is used when building distribution packages.
 if ( ${PROJECT_NAME}_INDIVIDUAL_BUILD ) # if built individually
     target_link_libraries( gmclash PUBLIC GeoModelCore::GeoModelKernel GeoModelIO::GeoModelRead GeoModelIO::GeoModelWrite )
+    target_link_libraries( gmmasscalc PUBLIC GeoModelCore::GeoModelKernel GeoModelIO::GeoModelRead GeoModelIO::GeoModelWrite )
     target_link_libraries( fullSimLight PUBLIC GeoModelCore::GeoModelKernel GeoModelIO::GeoModelRead GeoModelIO::GeoModelWrite )
     target_link_libraries( gmgeantino PUBLIC GeoModelCore::GeoModelKernel GeoModelIO::GeoModelRead GeoModelIO::GeoModelWrite )
     target_link_libraries( gm2gdml PUBLIC GeoModelCore::GeoModelKernel GeoModelIO::GeoModelRead GeoModelIO::GeoModelWrite )
 else() # if built as a part of GeoModel
     target_link_libraries( gmclash PUBLIC GeoModelKernel GeoModelRead GeoModelWrite )
+    target_link_libraries( gmmasscalc PUBLIC GeoModelKernel GeoModelRead GeoModelWrite )
     target_link_libraries( fullSimLight PUBLIC GeoModelKernel GeoModelRead GeoModelWrite )
     target_link_libraries( gmgeantino PUBLIC GeoModelKernel GeoModelRead GeoModelWrite )
     target_link_libraries( gm2gdml PUBLIC GeoModelKernel GeoModelRead GeoModelWrite )
@@ -175,6 +181,7 @@ endif()
 # system include folder (e.g., '/usr/local/include', '/usr/include', ...)
 if( nlohmann_json_FOUND )
     target_link_libraries( gmclash PRIVATE nlohmann_json::nlohmann_json )
+    target_link_libraries( gmmasscalc PRIVATE nlohmann_json::nlohmann_json )
     target_link_libraries( fullSimLight PRIVATE nlohmann_json::nlohmann_json )
     target_link_libraries( gmgeantino PRIVATE nlohmann_json::nlohmann_json )
     target_link_libraries( gm2gdml PRIVATE nlohmann_json::nlohmann_json )
@@ -210,6 +217,7 @@ endforeach()
 #
 install(TARGETS fullSimLight DESTINATION ${OUTPUT})
 install(TARGETS gmclash DESTINATION ${OUTPUT})
+install(TARGETS gmmasscalc DESTINATION ${OUTPUT})
 install(TARGETS fillHistogramExample DESTINATION ${OUTPUT})
 install(TARGETS gmgeantino DESTINATION ${OUTPUT})
 install(TARGETS testMagneticField DESTINATION ${OUTPUT})

FullSimLight/README.md

@@ -6,6 +6,7 @@ FullSimLight project consists of different tools based on [Geant4](https://geant
 - fullSimLight: a Geant4 based light simulation (geometry, transport in magnetic field and basic physics scoring)
 - 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: tool that calculates the inclusive and exclusive mass of an input geometry
 - gm2gdml: a tool to convert geometries and dump them in gdml format.
 
 The supported geometry formats are SQLite (.db), GDML (.gdml) and dual-use plugins (.dylib/.so) as the ones described in the [GeoModelPlugins repo](https://gitlab.cern.ch/atlas/GeoModelPlugins). The ATLAS detector geometry description can be imported via a SQLite or a GDML file. If the ATLAS magnetic field map is available to the user, it can be used in fullSimLight.
@@ -452,6 +453,101 @@ To produce geantino maps of a geometry described by one of the [GeoModelPlugins
 ./gmgeantino -m mymacro.g4 -g libHGTDPlugin.1.0.0.dylib -d -a -l -o geantinoMaps_HGTD.root 
 ``` 
 
+# GeoModelMassCalculator: run and options
+
+# GeoModelMassCalculator
+
+GeoModelMassCalculator (gmmasscalc) is a command line tool that calculates the inclusive and exclusive mass of a geometry specified as input with the -g flag. The mass report is given in an output json file (default: *gmmasscalc_report.json*).
+
+Run the executable with the --help option to see the available options:
+
+``` bash
+-g :   [MANDATORY] the Geometry file name [.db/.gdml/.dylib/.so] 
+-p :   [OPTIONAL] prefix of the Logical Volumes of interest (i.e. Pixel::) 
+-m :   [OPTIONAL] material of interest (i.e. Aluminium) 
+-o :   [OPTIONAL] mass report json file name (default: gmmasscalc_report.json)
+-v :   [OPTIONAL] verbose mode: 1 - print all the Logical Volume names and materials, 2 - print materials composition (default: off)
+``` 
+By default (if the optional flag are not used) *gmmasscalc*, takes the main *World Volume*, and calculates the inclusive and exclusive masses of the respective daughters, saving the calculated quantities in the output json file. At the end of the report, the total masses are reported for the whole *World Volume*. The output json file format is the following:
+
+``` bash
+"exclusiveMass[kg]": 1.3358800280858636,
+"inclusiveMass[kg]": 133.81273262584054,
+"logicalVolumeName": "SCT_ForwardC",
+"material": "Air",
+"physicalVolumeName": "SCT",
+"volumeCopyNo": 16969,
+"volumeEntityType": "G4Tubs"
+``` 
+where:
+- *exclusiveMass* is the mass of the considered volume only (from which the volumes occupied by the daughters volumes have been subtracted)
+- *inclusiveMass* is the mass of the considered volume, comprehensive of the masses of the respective daughters (propagated in an iterative way to their daughter volumes).
+
+At the end of the report, additional information about the whole geometry is reported. The last item of the json file will look like the following:
+
+``` bash
+"apparentWeightInAir[kg]": 2405.2018407511378,
+"densityThreshold[g/cm3]": 0.02,
+"excludedFilteredMass[kg]": 14.649883998898723,
+"exclusiveMass[kg]": 1.3704943478464804,
+"inclusiveFilteredMass[kg]": 2406.500411630485,
+"inclusiveMass[kg]": 2421.156760687377,
+"logicalVolumeName": "newWorldLog",
+"material": "Air",
+"volumeEntityType": "World Volume"
+``` 
+where:
+- *apparent weight in Air* by definition, the weight of a body as affected by the buoyancy of a fluid (such as air) in which it is immersed. It is calculated only on the total geometry, assuming that the World Volume is made of Air
+- *exclusiveFilteredMass* is the sum of the exclusive masses of all the volumes with density>densityThreshold (0.02 g/cm3)
+-*excludedFilteredMass*  is the sum of the exclusive masses of all the volumes with density<densityThreshold (0.02 g/cm3)
+
+In addition to the default behaviour, *gmmasscalc* offers the possibility to apply 2 filters to the geometry, described in what follows. 
+
+The -p (--prefix) option allows to indicate the prefix of the volumes of interest. In this case  *gmmasscalc* will loop over the geometry tree and calculate the mass of every Logical Volume that has the specified prefix in its name. For every Logical volume found, a different entry will be filled in the output report file.
+
+The -m (--material) option allows to specify to which material the user is interested. In this case  *gmmasscalc* will loop over the geometry tree and calculate the mass of those volumes that are made of the material of interest. 
+
+If both the -p and -m flags are used, *gmmasscalc* will combine the 2 filters and retrieve in the output file only the masses of the volumes containing the specified prefix and made of the desired material. 
+
+At the end of the report, the total exclusive mass for the requested geometry is  reported for all the volumes that satisfy the user request. The last item in the report will look like the following:
+
+```bash
+{
+"exclusiveMass[kg]": 14.676774220119631,
+"inclusiveMass[kg]": -999.0,
+"logicalVolumeName": "",
+"material": "CO2",
+"physicalVolumeName": "",
+"volumeCopyNo": 0,
+"volumeEntityType": "Total for filtered Geometry"
+}
+
+```
+where:
+- *logicalVolumeName*  and *material* are respectively the prefix used as filter for the Logical Volume names in the geometry tree navigation, and the material used as a second filter in the search. 
+
+The -v flag is a verbosity flag. Two different levels of verbosity can be set: level 1 prints all the logical volume names and respective materials, level 2 adds also the material composition for each material in the geometry. 
+
+## Examples
+
+To run GeoModelMassCalculator one has to specify with the -g flag the geometry file (this is mandatory). By default *gmmasscalc* writes out the masses report in the *gmmasscalc_report.json* file:
+``` bash
+./gmmasscalc -g geometry-ATLAS-R2-2016-01-00-01_wSPECIALSHAPE.db
+``` 
+To calculate the mass of a geometry described with the SQLite file *LArBarrel.db* and write out the masses report in the *mass_LArBarrel.json* file :
+``` bash
+./gmmasscalc -g LArBarrel.db -o mass_LArBarrel.json 
+``` 
+To calculate the mass of a geometry described with the SQLite file *SCT.db*, only for the logical volumes that have *BRLSensor* in their names, and only for those volumes that are made of *Silicon* and write out the masses report in the *mass_SCT.json* file:
+
+``` bash
+./gmmasscalc -g SCT.db -p BRLSensor -m Silicon -o mass_SCT.json 
+``` 
+To calculate the mass of a geometry described with one of the [GeoModelPlugins repo](https://gitlab.cern.ch/atlas/GeoModelPlugins), i.e.  *HGTDPlugin*, looking for volumes made of *Aluminium* and write out the masses report in the *mass_HGTD.json* file :
+``` bash
+./gmmasscalc -g libHGTDPlugin.1.0.0.dylib -m Aluminium -o mass_HGTD.json 
+``` 
+
 # GeoModel2GDML: run and options
 
 GeoModel2GDML (gm2gdml) is a command line tool based on Geant4, to convert geometries and dump them in gdml.

FullSimLight/geoModelMassCalculator.cc

+
+//--------------------------------------------------------
+// gmmasscalc application: November 2020 (README)
+//--------------------------------------------------------
+
+#include "G4Version.hh"
+#include "Randomize.hh"
+#include "MyDetectorConstruction.hh"
+
+#include <getopt.h>
+#include <err.h>
+#include <iostream>
+#include <iomanip>
+
+static G4String geometryFileName   ;
+static G4String prefixLogicalVolume= "";
+static G4String material= "";
+static G4String reportFileName     = "gmmasscalc_report.json";
+static G4int verbosityFlag = -1;
+
+void GetInputArguments(int argc, char** argv);
+void Help();
+
+int main(int argc, char** argv) {
+    
+    // Get input arguments
+    GetInputArguments(argc, argv);
+    
+    G4cout
+    << " ===================  Running GeoModelMassCalculator =================== "       << G4endl
+    << "   Geometry file name                     =  " << geometryFileName               << G4endl
+    << "   Prefix of Logical Volumes of interest  =  " << prefixLogicalVolume            << G4endl
+    << "   Material of interest                   =  " << material                       << G4endl
+    << "   Output mass report file name           =  " << reportFileName                 << G4endl
+    << " ============================================================== "                << G4endl;
+    
+    // version banner
+    G4String vs = G4Version;
+    vs = vs.substr(1,vs.size()-2);
+    G4String versionString = " Geant4 version ";
+    versionString += vs;
+    versionString += "   ";
+    versionString += G4Date;
+    G4cout << G4endl
+    << "**************************************************************" << G4endl
+    << versionString << G4endl
+    << "                       Copyright : Geant4 Collaboration" << G4endl
+    << "                      References : NIM A 506 (2003), 250-303" << G4endl
+    << "                                 : IEEE-TNS 53 (2006), 270-278" << G4endl
+    << "                                 : NIM A 835 (2016), 186-225" << G4endl
+    << "                             WWW : http://geant4.org/" << G4endl
+    << "**************************************************************" << G4endl
+    << G4endl;
+    
+    
+    // choose the Random engine: set to MixMax explicitely
+    // (default from 10.4)
+    G4Random::setTheEngine(new CLHEP::MixMaxRng);
+    // set seed and print info
+    G4Random::setTheSeed(12345678);
+    
+    G4cout << G4endl
+    << "   Random engine      = " << G4Random::getTheEngine()->name() << G4endl
+    << "   Initial seed       = " << G4Random::getTheSeed()           << G4endl
+    << G4endl;
+    
+    // Detector construction
+    MyDetectorConstruction* detector = new MyDetectorConstruction;
+    detector->SetRunMassCalculator(true);
+    detector->SetPrefixLogicalVolume(prefixLogicalVolume);
+    detector->SetMaterial(material);
+    detector->SetGeometryFileName (geometryFileName);
+    detector->SetReportFileName (reportFileName);
+    detector->SetVerbosity(verbosityFlag);
+    detector->Construct();
+    
+    delete detector;
+    return 0;
+}
+
+static struct option options[] = {
+    {"geometry file name"                         , required_argument, 0, 'g'},
+    {"prefix of the logical volume of interest "  , required_argument, 0, 'p'},
+    {"material of interest "                      , required_argument, 0, 'm'},
+    {"output mass report file name"               , required_argument, 0, 'o'},
+    {"verbosity flag"                             , required_argument, 0, 'v'},
+    {"help"                                       , no_argument,       0, 'h'},
+    {0, 0, 0, 0}
+};
+
+
+void Help() {
+  std::cout <<"\n " << std::setw(100) << std::setfill('=') << "" << std::setfill(' ') << std::endl;
+  G4cout <<"  GeoModelMassCalculator Geant4 application.    \n"
+            << std::endl
+            <<"  **** Parameters: \n\n"
+            <<"      -g :   [MANDATORY] the Geometry file name [.db/.gdml/.dylib/.so] \n"
+            <<"      -p :   [OPTIONAL] prefix of the Logical Volumes of interest (i.e. Pixel::) \n"
+            <<"      -m :   [OPTIONAL] material of interest (i.e. Aluminium) \n"
+            <<"      -o :   [OPTIONAL] mass report json file name (default: gmmasscalc_report.json)\n"
+            <<"      -v :   [OPTIONAL] verbose mode: 1 - print all the Logical Volume names and materials, 2 - print materials composition (default: off)\n"
+            << std::endl;
+  std::cout <<"\nUsage: ./gmmasscalc [OPTIONS]\n" <<std::endl;
+  for (int i=0; options[i].name!=NULL; i++) {
+    printf("\t-%c  --%s\t\n", options[i].val, options[i].name);
+  }
+  std::cout<<"\n "<<std::setw(100)<<std::setfill('=')<<""<<std::setfill(' ')<<std::endl;
+}
+
+
+void GetInputArguments(int argc, char** argv) {
+  // process arguments
+ if (argc == 1)
+ {
+     Help();
+     exit(0);
+     
+ }
+ while (true) {
+   int c, optidx = 0;
+   c = getopt_long(argc, argv, "g:p:m:o:hv:", options, &optidx);
+   if (c == -1)
+     break;
+   //
+   switch (c) {
+   case 0:
+     c = options[optidx].val;
+     break;
+   case 'g':
+     geometryFileName = optarg;
+     break;
+   case 'p':
+     prefixLogicalVolume = optarg;
+     break;
+   case 'm':
+     material = optarg;
+     break;
+   case 'o':
+     reportFileName = optarg;
+     break;
+   case 'v':
+     verbosityFlag = atoi(optarg);
+     break;
+   case 'h':
+     Help();
+     exit(0);
+   default:
+     Help();
+     errx(1, "unknown option %c", c);
+   }
+  }
+  // check if mandatory Geometry file was provided
+  if (geometryFileName=="") {
+      G4cout << "  *** ERROR : Geometry file is required. " << G4endl;
+      Help();
+      exit(-1);
+      
+  }
+}

FullSimLight/include/MyDetectorConstruction.hh

@@ -12,6 +12,15 @@
 #include "G4Cache.hh"
 #include "G4MagneticField.hh"
 
+//G4AnalysisMananager
+#include "MyAnalysis.hh"
+
+// Units
+#include "GeoModelKernel/Units.h"
+#define SYSTEM_OF_UNITS GeoModelKernelUnits // so we will get, e.g., 'GeoModelKernelUnits::cm'
+// ****
+
+
 using json = nlohmann::json;
 
 class G4VPhysicalVolume;
@@ -34,11 +43,14 @@ public:
 
   void SetGDMLFileName  (const G4String &gdmlfile)   { fGeometryFileName = gdmlfile;}
   void SetRunOverlapCheck(const bool runOvCheck)     { fRunOverlapCheck = runOvCheck; }
+  void SetRunMassCalculator(const bool runMassCalc)  { fRunMassCalculator = runMassCalc; }
+  void SetVerbosity(const int verbosity)            { fVerbosityFlag = verbosity; }
   void SetGeometryFileName(const G4String &geometryFileName) { fGeometryFileName = geometryFileName; }
+  void SetPrefixLogicalVolume(const G4String &prefixLV) { fPrefixLogicalVolume = prefixLV; }
+  void SetMaterial(const G4String &material) { fMaterial = material; }
   void SetReportFileName(const G4String &reportFileName)     { fReportFileName = reportFileName; }
   void SetOutputGDMLFileName(const G4String &outputGDMLFileName)     { fOutputGDMLFileName = outputGDMLFileName; }
   void SetDumpGDML(const bool dumpGDML)              {fDumpGDML=dumpGDML;}
-
   /// Common method to construct a driver with a stepper of requested type.
   G4VIntegrationDriver*
   createDriverAndStepper(std::string stepperType) const;
@@ -52,6 +64,8 @@ public:
 
   static G4double GetFieldValue() { return gFieldValue; }
     
+  void RecursiveMassCalculation (G4VPhysicalVolume* worldg4,GeoPhysVol* worldgeoModel, std::vector<json>& jlist);
+    
   void RecursivelyCheckOverlap(G4LogicalVolume* envelope, std::vector<json>& jlist);
   
   // Verifies if the placed volume is overlapping with existing
@@ -70,11 +84,19 @@ public:
   // Iterate from the volume envelope through all the daughter volumes, and look for the ancestors of
   // 'volume', populating the fTree vector of G4VPhysicalVolumes
   bool iterateFromWorld(G4LogicalVolume* envelope, G4VPhysicalVolume*volume, G4ThreeVector& local);
-  
+    
+  void calculateMass(G4LogicalVolume* logVol, G4VPhysicalVolume * physVol, std::vector<json>& jlist, double& exclusiveMass, bool writeRep);
+    
+  void iterateFromWorldMass(G4LogicalVolume* envelope, std::vector<json>& jlist, double& inclusiveMass, double& exclusiveMass, G4String prefix="", G4String material="");
+    
   GeoPhysVol* CreateTheWorld(GeoPhysVol* world);
 
   /// Clean the geometry  from Unidentified volumes before dumping it in GDML format
   void PullUnidentifiedVolumes( G4LogicalVolume* v );
+    
+  void printGeometryInfo(G4LogicalVolume* lv, G4int verbosity);
+
+  static G4AnalysisManager* fAnalysisManager;
 
 protected:
   G4Timer fTimer;
@@ -82,10 +104,16 @@ protected:
 private:
   // this static member is for the print out
   static G4double gFieldValue;
+  const G4double fDensityThreshold = 0.02 * SYSTEM_OF_UNITS::g/SYSTEM_OF_UNITS::cm3;
+  //G4int    fHistoID; //density histogram ID
   G4bool   fRunOverlapCheck;
+  G4bool   fRunMassCalculator;
+  G4int    fVerbosityFlag;
   G4bool   fDumpGDML;
   G4double fMinStep;
   G4String fGeometryFileName;
+  G4String fPrefixLogicalVolume;
+  G4String fMaterial;
   G4String fReportFileName;
   G4String fOutputGDMLFileName;
   G4double fFieldValue;

documentation/docs/fullsimlight/gmmasscalc/index.md

+# GeoModelMassCalculator
+
+GeoModelMassCalculator (gmmasscalc) is a command line tool that calculates the inclusive and exclusive mass of a geometry specified as input with the -g flag. The mass report is given in an output json file (default: *gmmasscalc_report.json*).
+
+Run the executable with the --help option to see the available options:
+
+``` bash
+-g :   [MANDATORY] the Geometry file name [.db/.gdml/.dylib/.so] 
+-p :   [OPTIONAL] prefix of the Logical Volumes of interest (i.e. Pixel::) 
+-m :   [OPTIONAL] material of interest (i.e. Aluminium) 
+-o :   [OPTIONAL] mass report json file name (default: gmmasscalc_report.json)
+-v :   [OPTIONAL] verbose mode: 1 - print all the Logical Volume names and materials, 2 - print materials composition (default: off)
+``` 
+By default (if the optional flag are not used) *gmmasscalc*, takes the main *World Volume*, and calculates the inclusive and exclusive masses of the respective daughters, saving the calculated quantities in the output json file. At the end of the report, the total masses are reported for the whole *World Volume*. The output json file format is the following:
+
+``` bash
+"exclusiveMass[kg]": 1.3358800280858636,
+"inclusiveMass[kg]": 133.81273262584054,
+"logicalVolumeName": "SCT_ForwardC",
+"material": "Air",
+"physicalVolumeName": "SCT",
+"volumeCopyNo": 16969,
+"volumeEntityType": "G4Tubs"
+``` 
+where:
+- *exclusiveMass* is the mass of the considered volume only (from which the volumes occupied by the daughters volumes have been subtracted)
+- *inclusiveMass* is the mass of the considered volume, comprehensive of the masses of the respective daughters (propagated in an iterative way to their daughter volumes).
+
+At the end of the report, additional information about the whole geometry is reported. The last item of the json file will look like the following:
+
+``` bash
+"apparentWeightInAir[kg]": 2405.2018407511378,
+"densityThreshold[g/cm3]": 0.02,
+"excludedFilteredMass[kg]": 14.649883998898723,
+"exclusiveMass[kg]": 1.3704943478464804,
+"inclusiveFilteredMass[kg]": 2406.500411630485,
+"inclusiveMass[kg]": 2421.156760687377,
+"logicalVolumeName": "newWorldLog",
+"material": "Air",
+"volumeEntityType": "World Volume"
+``` 
+where:
+- *apparent weight in Air* by definition, the weight of a body as affected by the buoyancy of a fluid (such as air) in which it is immersed. It is calculated only on the total geometry, assuming that the World Volume is made of Air
+- *exclusiveFilteredMass* is the sum of the exclusive masses of all the volumes with density>densityThreshold (0.02 g/cm3)
+-*excludedFilteredMass*  is the sum of the exclusive masses of all the volumes with density<densityThreshold (0.02 g/cm3)
+
+In addition to the default behaviour, *gmmasscalc* offers the possibility to apply 2 filters to the geometry, described in what follows. 
+
+The -p (--prefix) option allows to indicate the prefix of the volumes of interest. In this case  *gmmasscalc* will loop over the geometry tree and calculate the mass of every Logical Volume that has the specified prefix in its name. For every Logical volume found, a different entry will be filled in the output report file.
+
+The -m (--material) option allows to specify to which material the user is interested. In this case  *gmmasscalc* will loop over the geometry tree and calculate the mass of those volumes that are made of the material of interest. 
+
+If both the -p and -m flags are used, *gmmasscalc* will combine the 2 filters and retrieve in the output file only the masses of the volumes containing the specified prefix and made of the desired material. 
+
+At the end of the report, the total exclusive mass for the requested geometry is  reported for all the volumes that satisfy the user request. The last item in the report will look like the following:
+
+```bash
+{
+"exclusiveMass[kg]": 14.676774220119631,
+"inclusiveMass[kg]": -999.0,
+"logicalVolumeName": "",
+"material": "CO2",
+"physicalVolumeName": "",
+"volumeCopyNo": 0,
+"volumeEntityType": "Total for filtered Geometry"
+}
+
+```
+where:
+- *logicalVolumeName*  and *material* are respectively the prefix used as filter for the Logical Volume names in the geometry tree navigation, and the material used as a second filter in the search. 
+
+The -v flag is a verbosity flag. Two different levels of verbosity can be set: level 1 prints all the logical volume names and respective materials, level 2 adds also the material composition for each material in the geometry. 
+
+## Examples
+
+To run GeoModelMassCalculator one has to specify with the -g flag the geometry file (this is mandatory). By default *gmmasscalc* writes out the masses report in the *gmmasscalc_report.json* file:
+``` bash
+./gmmasscalc -g geometry-ATLAS-R2-2016-01-00-01_wSPECIALSHAPE.db
+``` 
+To calculate the mass of a geometry described with the SQLite file *LArBarrel.db* and write out the masses report in the *mass_LArBarrel.json* file :
+``` bash
+./gmmasscalc -g LArBarrel.db -o mass_LArBarrel.json 
+``` 
+To calculate the mass of a geometry described with the SQLite file *SCT.db*, only for the logical volumes that have *BRLSensor* in their names, and only for those volumes that are made of *Silicon* and write out the masses report in the *mass_SCT.json* file:
+
+``` bash
+./gmmasscalc -g SCT.db -p BRLSensor -m Silicon -o mass_SCT.json 
+``` 
+To calculate the mass of a geometry described with one of the [GeoModelPlugins repo](https://gitlab.cern.ch/atlas/GeoModelPlugins), i.e.  *HGTDPlugin*, looking for volumes made of *Aluminium* and write out the masses report in the *mass_HGTD.json* file :
+``` bash
+./gmmasscalc -g libHGTDPlugin.1.0.0.dylib -m Aluminium -o mass_HGTD.json 
+``` 

documentation/mkdocs.yml

@@ -30,7 +30,8 @@ nav:
         - 'FullSimLight': 'fullsimlight/fullsimlight/index.md'
         - 'GeoModelClash': 'fullsimlight/gmclash/index.md'
         - 'GeoModelGeantino': 'fullsimlight/gmgeantino/index.md'
-        - 'GeoModelToGDML': 'fullsimlight/gmtogdml/index.md'
+        - 'GeoModelMassCalculator': 'fullsimlight/gmmasscalc/index.md'
+        - 'GeoModel2GDML': 'fullsimlight/gm2gdml/index.md'
     - FAQ: 'faq.md'
     - For Developers:
         - 'Build the Libraries and Tools': 'dev/index.md'