documentation update (a01aa4a6) · Commits · ICSC_G4_HPC / BoGEMMS-HPC

doc/examples.md

+119 −2

Original line number	Diff line number	Diff line
		@@ -8,6 +8,8 @@ scintillation detector, generating optical light in the crystal and collecting t

		<img src="images/CsI.png" width="400" height="120" >

		Reference: [Ciabattoni et al., 2025](https://ui.adsabs.harvard.edu/abs/2025ExA....60....9C/abstract)

		The scintillation test case is part of the verification
		activity for the Geant4 optical physics library ([Ciabattoni et al.,
		2024](https://ui.adsabs.harvard.edu/abs/2024SPIE13093E..7YC/abstract)
		@@ -199,6 +201,9 @@ Set number of simulated particles:

		<img src="images/scattering_example.png" width="400" height="120" >

		Reference: [Fioretti et al.
		(2024)](https://ui.adsabs.harvard.edu/abs/2024A%26A...691A.229F/abstract)

		Low-energy, or soft, protons (< 300 keV) that enter the field
		of view of X-ray focusing telescopes can scatter at grazing angles with the surface of Wolter-type mirrors and reach the focal plane, causing unpredictable flares in the background rate
		of the instruments ([Marelli et al., 2017](https://ui.adsabs.harvard.edu/abs/2017ExA....44..297M/abstract); [Freyberg et al., 2020](https://ui.adsabs.harvard.edu/abs/2021SPIE11444E..1OF/abstract)).
		@@ -380,22 +385,134 @@ Target type: 1 = eRosita
		Detector distance (distance from the target center to the detector surface) in mm:
		`GEOM.PANEL.DISTANCE = 933.`

		</details>

		<details><summary> GDML
		</summary>

		</details>
		<img src="images/gdml.png" width="400" height="120" >

		This example application imports GDML volumes from a file and selects which volumes are sensitive.

		To run the example:

		`> bogemms -c read_gdml.conf -m visGDML.mac`

		###### Configuration file read_gdml.conf:

		Selection of output files:

		`IO.FILETYPE.FITS = true`

		`IO.FILETYPE.FITS.COMPRESS = true`

		`IO.FILE.XYZ = true`


		IO XYZ file configuration:

		`IOXYZ.EVT_ID = true`

		`IOXYZ.TRK_ID = true`

		`IOXYZ.PARENT_TRK_ID = true`

		`IOXYZ.VOLUME_ID = true`

		`IOXYZ.VOLUME_NAME = true`

		`IOXYZ.MOTHER_ID = true`

		`IOXYZ.E_DEP = true`

		`IOXYZ.X_ENT = true`

		`IOXYZ.Y_ENT = true`

		`IOXYZ.Z_ENT = true`

		`IOXYZ.X_EXIT = true`

		`IOXYZ.Y_EXIT = true`

		`IOXYZ.Z_EXIT = true`

		`IOXYZ.E_KIN_ENT = true`

		`IOXYZ.E_KIN_EXIT = true`

		`IOXYZ.MDX_ENT = true`

		`IOXYZ.MDY_ENT = true`

		`IOXYZ.MDZ_ENT = true`

		`IOXYZ.MDX_EXIT = true`

		`IOXYZ.MDY_EXIT = true`

		`IOXYZ.MDZ_EXIT = true`

		`IOXYZ.GTIME_ENT = true`

		`IOXYZ.GTIME_EXIT = true`

		`IOXYZ.PARTICLE_ID = true`

		`IOXYZ.PARTICLE_NAME = false`

		`IOXYZ.PROCESS_ID = true`

		`IOXYZ.PROCESS_NAME = false`

		Volume selection:

		`IOXYZ.volumeselection.number = 1`

		`IOXYZ.volumeselection.0.start = 0`

		`IOXYZ.volumeselection.0.end = 10000000`


		Number of rows for each file:

		`IOXYZ.NRows = 1000`

		Write only volume with energy deposit (this do not exclude the world):

		`IOXYZ.writeonlyifenergydeposit = 0`

		Exclude the world (NB: the world contains the initial energy and momentum):

		`IOXYZ.removeWorldEvent = 0`

		We used for this example the Space EM Physics List and the QGSP BIC HP hadronic physics list:

		`PHYS.VERSION = AREMBESPhys`

		`AREMBESPhys.PHYSLIST = SpacePhysics_QGSP_BIC_HP`

		In the geometry configuration, we select first the class GDMLread:

		`GEOM.VERSION = GDMLread`

		Then we select the path to the GDML file and the name of the file. BoGEMMS-HPC has a dedicated directory for the GDML models but the user can select any path of choice:

		`GEOM.GDML.PATH = <path-to>/BoGEMMS-HPC/gdml_files`

		`GEOM.GDML.FILENAME = solids.gdml`

		The following keywords define the number of sensitive volumes:

		`N.SENSITIVE.VOLUMES = 2`

		and the name of the sensitive logical volumes:

		`NAME.SENSITIVE.VOLUME.0 = vol0`

		`NAME.SENSITIVE.VOLUME.1 = vol1`

		The macro file opens a VRML2 scene and draws the volumes into a .wrl output files together with the trajectories. The user requires a wrl reader to open and visualize the file.

		</details>

doc/getting_started.md

+30 −0

Original line number	Diff line number	Diff line
		@@ -21,6 +21,36 @@ To create an independent application, with separated geometry and physics defini
		If new files are added to the directory, cmake must be run again.
		The user can copy and modify in the user path the geometry and physics classes of the example applications, or starting from the templates provided [here](https://www.ict.inaf.it/gitlab/icsc_g4_hpc/BoGEMMS-HPC/-/tree/main/templates?ref_type=heads).

		### Adding a sensitive volume

		To built the detector, the user can modify the provided examples or refer to the Geant4 standard documentation. To define a volume as sensitive, i.e. any interaction with that volume is written to the output, the user only needs to use this method, that exploits BoGEMMS global memory functionality:

		`gm.AddXYZDetector( < logical volume >);`

		For example, `gm.AddXYZDetector( log_erosita_coating)`.

		### Defining a custom parameter

		Both in the geometry and the physics user classes, the user can define custom parameters that are then set at runtime using the configuration file. The same class can then be used for multiple applications:

		`<data_type> par_name = <value> * <unit>;` (initializing the parameter, this can also be moved to the header)

		`gm.config->readInto(par_name, "SET.PAR.NAME");` (setting the parameter)

		In the configuration file use:

		`SET.PAR.NAME = <value>`

		For example:

		`G4double customCut = 0.001 * mm;`

		`gm.config->readInto(customCut, "REGION.CUT");`

		In the configuration file:

		REGION.CUT = 0.1

		## Configuration file

		### Units and system of reference

examples/GDML/read_gdml.conf

+2 −3

Original line number	Diff line number	Diff line
		######################################################
		# Selection of output files
		IO.FILETYPE.FITS = true
		IO.FILETYPE.FITSEND = false

		IO.FILETYPE.FITS.COMPRESS = true
		IO.FILE.XYZ = true

		#######################################################
		@@ -38,7 +37,7 @@ IOXYZ.PROCESS_NAME = false
		#volume selection
		IOXYZ.volumeselection.number = 1
		IOXYZ.volumeselection.0.start = 0
		IOXYZ.volumeselection.0.end = 1000000000
		IOXYZ.volumeselection.0.end = 10000000

		#number of rows for each file
		IOXYZ.NRows = 1000

examples/GDML/visGDML.mac

+1 −13

Original line number	Diff line number	Diff line
		@@ -6,17 +6,14 @@

		/vis/scene/add/volume
		/vis/scene/add/trajectories
		#/vis/scene/add/hits
		/vis/viewer/set/lightsThetaPhi 90. 0.
		#/vis/viewer/set/viewpointThetaPhi 0. 90.
		/vis/viewer/set/viewpointVector 0 1 0
		#/vis/viewer/set/style surface
		/vis/viewer/zoom 1

		#/vis/set/lineWidth 0.1

		#/vis/viewer/set/hiddenEdge true
		#Create drawByParticleID model, highlighting photons
		# draw particle by id
		/vis/modeling/trajectories/create/drawByParticleID
		/vis/modeling/trajectories/drawByParticleID-0/set gamma green
		/vis/modeling/trajectories/drawByParticleID-0/set e- yellow
		@@ -26,12 +23,6 @@
		/vis/modeling/trajectories/drawByParticleID-0/set proton blue
		/vis/modeling/trajectories/drawByParticleID-0/set neutrino grey

		#Create drawByCharge model, colouring photons white
		#/vis/modeling/trajectories/create/drawByCharge
		#/vis/modeling/trajectories/drawByCharge-0/set 1 blue
		#/vis/modeling/trajectories/drawByCharge-0/set -1 red
		#/vis/modeling/trajectories/drawByCharge-0/set 0 white

		/vis/scene/endOfEventAction accumulate

		/gps/particle gamma
		@@ -44,12 +35,9 @@
		/gps/direction 0 0 -1



		/gps/ene/mono 50 keV


		# Set number of particles and start
		/random/resetEngineFrom currentEvent.rndm
		/run/beamOn 100
		/random/saveThisRun

templates/geometry_template.cc

+7 −3

Original line number	Diff line number	Diff line
		@@ -119,11 +119,15 @@ G4VPhysicalVolume* geometry_template::ConstructGeometry(G4VPhysicalVolume* World
		// ----> BUILD GEOMETRY

		// example of getting material from list
		material_selection = materials->GetMaterial(<number>);
		// material_selection = materials->GetMaterial(<number>);

		// example on how to define custom parameters to be used in the .conf file
		<data_type> par_name = <value> * <unit>;
		gm.config->readInto(par_name, "PARAMETER NAME IN THE .CONF");
		// <data_type> par_name = <value> * <unit>;
		// gm.config->readInto(par_name, "SET.PAR.NAME");
		// in the configuration file use: SET.PAR.NAME = <value>

		// example on how to set a volume "sensitive". Any interaction with a sensitive volume is written to the output file
		// gm.AddXYZDetector( < logical volume >);

		return World_phys;
		}