Skip to content

Commit bf4d56a

Browse files
maureeungaromaureeungaro
committed
updated doxygen
1 parent 6f39f4f commit bf4d56a

21 files changed

Lines changed: 724 additions & 170 deletions

File tree

‎actions/event/gEventAction.cc‎

Lines changed: 76 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -9,83 +9,87 @@
99

1010

1111
GEventAction::GEventAction(const std::shared_ptr<GOptions>& gopt, GRunAction* run_a) :
12-
GBase(gopt, EVENTACTION_LOGGER),
13-
goptions(gopt),
14-
run_action(run_a) {
15-
// Constructor: store shared config and a non-owning pointer to the run action for this thread.
16-
auto desc = "GEventAction " + std::to_string(G4Threading::G4GetThreadId());
17-
log->debug(CONSTRUCTOR, FUNCTION_NAME, desc);
12+
GBase(gopt, EVENTACTION_LOGGER),
13+
goptions(gopt),
14+
run_action(run_a) {
15+
// Constructor: store shared config and a non-owning pointer to the run action for this thread.
16+
auto desc = "GEventAction " + std::to_string(G4Threading::G4GetThreadId());
17+
log->debug(CONSTRUCTOR, FUNCTION_NAME, desc);
1818
}
1919

2020
void GEventAction::BeginOfEventAction([[maybe_unused]] const G4Event* event) {
21-
// Begin-of-event hook: logs event id and thread id for tracing.
22-
int thread_id = G4Threading::G4GetThreadId();
23-
int eventID = event->GetEventID();
21+
// Begin-of-event hook: logs event id and thread id for tracing.
22+
int thread_id = G4Threading::G4GetThreadId();
23+
int eventID = event->GetEventID();
2424

25-
log->debug(CONSTRUCTOR, FUNCTION_NAME, " event id ", eventID, " in thread ", thread_id);
25+
log->debug(CONSTRUCTOR, FUNCTION_NAME, " event id ", eventID, " in thread ", thread_id);
2626
}
2727

2828
void GEventAction::EndOfEventAction([[maybe_unused]] const G4Event* event) {
29-
// End-of-event hook: collect hit collections, digitize hits, and publish the event to streamers.
30-
G4HCofThisEvent* HCsThisEvent = event->GetHCofThisEvent();
31-
if (!HCsThisEvent) return;
32-
if (!run_action) {
33-
log->error(ERR_GRUNACTION_NOT_EXISTING, FUNCTION_NAME, " run_action is null - cannot access digitization routines or streamers.");
34-
}
35-
36-
int thread_id = G4Threading::G4GetThreadId();
37-
int eventID = event->GetEventID();
38-
39-
// Create the event data container that will receive digitized data and truth information.
40-
auto gevent_header = std::make_unique<GEventHeader>(goptions, eventID, thread_id);
41-
auto eventDataCollection = std::make_shared<GEventDataCollection>(goptions, std::move(gevent_header));
42-
43-
// Loop over all hit collections produced by sensitive detectors in this event.
44-
for (G4int hci = 0; hci < HCsThisEvent->GetNumberOfCollections(); hci++) {
45-
auto thisGHC = (GHitsCollection*)HCsThisEvent->GetHC(hci);
46-
47-
if (thisGHC) {
48-
std::string hcSDName = thisGHC->GetSDname();
49-
auto digi_map = run_action->get_digitization_routines_map();
50-
if (!digi_map) {
51-
log->error(ERR_GDIGIMAP_NOT_EXISTING, FUNCTION_NAME, " no digitization routines map available for collection ", hcSDName,
52-
" in thread ", thread_id);
53-
}
54-
55-
log->info(2, FUNCTION_NAME, " worker ", thread_id,
56-
" for event number ", eventID,
57-
" for collection number ", hci + 1,
58-
" collection name: ", hcSDName);
59-
60-
// Select the digitization routine by hit collection name, then publish through all streamers.
61-
auto it = digi_map->find(hcSDName);
62-
if (it == digi_map->end()) {
63-
log->error(ERR_GDIGIMAP_NOT_EXISTING, FUNCTION_NAME, " no digitization routine registered for collection ", hcSDName,
64-
" in thread ", thread_id);
65-
}
66-
auto digitization_routine = it->second;
67-
68-
auto gstreamers_map = run_action->get_streamer_map();
69-
if (!gstreamers_map) {
70-
log->error(ERR_STREAMERMAP_NOT_EXISTING, FUNCTION_NAME, " no gstreamer map available in thread ", thread_id);
71-
}
72-
73-
if (digitization_routine != nullptr) {
74-
// Loop over hits in this collection and append produced data to the event container.
75-
for (size_t hitIndex = 0; hitIndex < thisGHC->GetSize(); hitIndex++) {
76-
auto thisHit = (GHit*)thisGHC->GetHit(hitIndex);
77-
// PRAGMA TODO: switch these on/off with options
78-
auto true_data = digitization_routine->collectTrueInformation(thisHit, hitIndex);
79-
auto digi_data = digitization_routine->digitizeHit(thisHit, hitIndex);
80-
eventDataCollection->addDetectorDigitizedData(hcSDName, std::move(digi_data));
81-
eventDataCollection->addDetectorTrueInfoData(hcSDName, std::move(true_data));
82-
}
83-
84-
for (const auto& [name, gstreamer] : *gstreamers_map) {
85-
// Publish the event to the gstreamer.
86-
gstreamer->publishEventData(eventDataCollection);
87-
}
88-
}
89-
}
90-
}
29+
// End-of-event hook: collect hit collections, digitize hits, and publish the event to streamers.
30+
G4HCofThisEvent* HCsThisEvent = event->GetHCofThisEvent();
31+
if (!HCsThisEvent) return;
32+
if (!run_action) {
33+
log->error(ERR_GRUNACTION_NOT_EXISTING, FUNCTION_NAME,
34+
" run_action is null - cannot access digitization routines or streamers.");
35+
}
36+
37+
int thread_id = G4Threading::G4GetThreadId();
38+
int eventID = event->GetEventID();
39+
40+
// Create the event data container that will receive digitized data and truth information.
41+
auto gevent_header = std::make_unique<GEventHeader>(goptions, eventID, thread_id);
42+
auto eventDataCollection = std::make_shared<GEventDataCollection>(goptions, std::move(gevent_header));
43+
44+
// Loop over all hit collections produced by sensitive detectors in this event.
45+
for (G4int hci = 0; hci < HCsThisEvent->GetNumberOfCollections(); hci++) {
46+
auto thisGHC = (GHitsCollection*)HCsThisEvent->GetHC(hci);
47+
48+
if (thisGHC) {
49+
std::string hcSDName = thisGHC->GetSDname();
50+
auto digi_map = run_action->get_digitization_routines_map();
51+
if (!digi_map) {
52+
log->error(ERR_GDIGIMAP_NOT_EXISTING, FUNCTION_NAME,
53+
" no digitization routines map available for collection ", hcSDName,
54+
" in thread ", thread_id);
55+
}
56+
57+
log->info(2, FUNCTION_NAME, " worker ", thread_id,
58+
" for event number ", eventID,
59+
" for collection number ", hci + 1,
60+
" collection name: ", hcSDName);
61+
62+
// Select the digitization routine by hit collection name, then publish through all streamers.
63+
auto it = digi_map->find(hcSDName);
64+
if (it == digi_map->end()) {
65+
log->error(ERR_GDIGIMAP_NOT_EXISTING, FUNCTION_NAME,
66+
" no digitization routine registered for collection ", hcSDName,
67+
" in thread ", thread_id);
68+
}
69+
auto digitization_routine = it->second;
70+
71+
auto gstreamers_map = run_action->get_streamer_map();
72+
if (!gstreamers_map) {
73+
log->error(ERR_STREAMERMAP_NOT_EXISTING, FUNCTION_NAME, " no gstreamer map available in thread ",
74+
thread_id);
75+
}
76+
77+
if (digitization_routine != nullptr) {
78+
// Loop over hits in this collection and append produced data to the event container.
79+
for (size_t hitIndex = 0; hitIndex < thisGHC->GetSize(); hitIndex++) {
80+
auto thisHit = (GHit*)thisGHC->GetHit(hitIndex);
81+
// PRAGMA TODO: switch these on/off with options
82+
auto true_data = digitization_routine->collectTrueInformation(thisHit, hitIndex);
83+
auto digi_data = digitization_routine->digitizeHit(thisHit, hitIndex);
84+
eventDataCollection->addDetectorDigitizedData(hcSDName, std::move(digi_data));
85+
eventDataCollection->addDetectorTrueInfoData(hcSDName, std::move(true_data));
86+
}
87+
88+
for (const auto& [name, gstreamer] : *gstreamers_map) {
89+
// Publish the event to the gstreamer.
90+
gstreamer->publishEventData(eventDataCollection);
91+
}
92+
}
93+
}
94+
}
9195
}

‎actions/run/gRunAction.cc‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// gemc
22
#include "gRunAction.h"
33
#include "gRun.h"
4+
#include "../gactionConventions.h"
45

56
// geant4
67
#include "G4Threading.hh"
@@ -38,15 +39,21 @@ void GRunAction::BeginOfRunAction(const G4Run* aRun) {
3839
gstreamer_map = gstreamer::gstreamersMapPtr(goptions, thread_id);
3940
}
4041

42+
// (Re)-open streamer connections for this run on worker threads.
4143
// (Re)-open streamer connections for this run on worker threads.
4244
if (!IsMaster()) {
43-
for (auto& [name, gstreamer] : *gstreamer_map) {
44-
if (!gstreamer->openConnection()) {
45-
log->error(1, "Failed to open connection for GStreamer ", name, " in thread ", thread_id);
45+
if (gstreamer_map == nullptr) {
46+
log->error(1, FUNCTION_NAME, " gstreamer_map is null in thread ", thread_id, " - cannot open connections.");
47+
} else {
48+
for (auto& [name, gstreamer] : *gstreamer_map) {
49+
if (!gstreamer->openConnection()) {
50+
log->error(ERR_STREAMERMAP_NOT_EXISTING, "Failed to open connection for GStreamer ", name, " in thread ", thread_id);
51+
}
4652
}
4753
}
4854
}
4955

56+
5057
std::string what_am_i = IsMaster() ? "Master" : "Worker";
5158

5259
log->info(2, FUNCTION_NAME, " ", what_am_i, " [", thread_id, "], for run ", run, ", events to be processed: ", neventsThisRun);
@@ -61,12 +68,19 @@ void GRunAction::EndOfRunAction(const G4Run* aRun) {
6168
std::string what_am_i = IsMaster() ? "Master" : "Worker";
6269

6370
if (!IsMaster()) {
64-
for (const auto& [name, gstreamer] : *gstreamer_map) {
65-
log->info(2, FUNCTION_NAME, " ", what_am_i, " [", thread_id, "], for run ", run,
66-
" closing connection for gstreamer ", name);
67-
if (!gstreamer->closeConnection()) { log->error(1, "Failed to close connection for GStreamer ", name, " in thread ", thread_id); }
71+
if (gstreamer_map == nullptr) {
72+
log->error(ERR_STREAMERMAP_NOT_EXISTING, FUNCTION_NAME, " gstreamer_map is null in thread ", thread_id, " - cannot close connections.");
73+
} else {
74+
for (const auto& [name, gstreamer] : *gstreamer_map) {
75+
log->info(2, FUNCTION_NAME, " ", what_am_i, " [", thread_id, "], for run ", run,
76+
" closing connection for gstreamer ", name);
77+
if (!gstreamer->closeConnection()) {
78+
log->error(1, "Failed to close connection for GStreamer ", name, " in thread ", thread_id);
79+
}
80+
}
6881
}
6982
}
83+
7084
}
7185

7286
// (Legacy/experimental streaming logic remains commented out below.)

‎dbselect/dbselectDoxy.h‎

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -63,19 +63,38 @@
6363
* computed count of matching geometry entries.
6464
* - Changing variation/run recomputes counts and availability.
6565
*
66-
* @section dbselect_options Available Options and usage
67-
*
68-
* The module’s options are defined by dbselect::defineOptions(), which aggregates the
69-
* options provided by gdetector::defineOptions().
70-
*
71-
* The dbselect code path uses the following option keys:
72-
* - \c --sql : path or identifier of the SQLite database file to open (read-only).
73-
* - \c --experiment : default experiment name to preselect in the view.
74-
* - \c --gui : if enabled, the example starts a Qt event loop and shows the widget.
75-
*
76-
* If additional options are added by gdetector::defineOptions(), they may also affect
77-
* detector construction and geometry reload behavior. Refer to the gdetector option
78-
* documentation for the full list.
66+
* @section options_sec Available Options and their usage
67+
*
68+
* This module reads the following option keys from the runtime option provider:
69+
*
70+
* - `sql`
71+
* - Type: string
72+
* - Meaning: path (or identifier) of the SQLite database file to open (read-only)
73+
* - Behavior:
74+
* - the database is opened during \c DBSelectView construction
75+
* - the value is also used as the default geometry source when building a \c SystemList
76+
* - Note: this key is commonly provided by the aggregated gsystem/g4system option sets.
77+
*
78+
* - `experiment`
79+
* - Type: string
80+
* - Meaning: default experiment name to preselect in the view
81+
* - Behavior:
82+
* - when present, the view attempts to select that experiment on startup
83+
* - if the experiment is not found, the view falls back to the first available experiment
84+
*
85+
* - `gui`
86+
* - Type: boolean (switch)
87+
* - Meaning: enable GUI execution path for examples / host applications
88+
* - Behavior:
89+
* - when \c true, example programs typically start a Qt event loop and show the widget
90+
* - when \c false, examples may run in CLI mode (no widget created)
91+
* - Note: this switch is defined by \ref GOptions::GOptions "GOptions(argc,argv,...)" and is globally available.
92+
*
93+
* This module’s option schema is composed by \c dbselect::defineOptions(), which aggregates:
94+
* - \c gdetector::defineOptions()
95+
*
96+
* Additional keys contributed by \c gdetector::defineOptions() may affect detector construction
97+
* and geometry reload behavior. Refer to the gdetector documentation for the full list.
7998
*
8099
* @section dbselect_verbosity Module verbosity
81100
*

‎eventDispenser/eventDispenserDoxy.h‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,43 @@
2929
* - Query the computed distribution with \ref EventDispenser::getRunEvents "getRunEvents()".
3030
* - Run the workflow using \ref EventDispenser::processEvents "processEvents()".
3131
*
32+
* @section options_sec Available Options and their usage
33+
*
34+
* This module reads the following option keys from the runtime option provider:
35+
*
36+
* - `n`
37+
* - Type: integer
38+
* - Meaning: requested number of events to process
39+
* - Behavior:
40+
* - `0` typically means "no events requested" (module may still initialize and report configuration)
41+
* - positive values are used to compute the per-run event allocation
42+
*
43+
* - `run`
44+
* - Type: integer
45+
* - Meaning: conditions run number used when no run-weight file is provided
46+
* - Behavior:
47+
* - used as the single run number for the full event set when `run_weights` is unset
48+
* - Note: not to be confused with the Geant4 internal run id (\c g4runno), which GEMC manages separately.
49+
*
50+
* - `run_weights`
51+
* - Type: string (path)
52+
* - Meaning: text file containing run numbers and relative weights
53+
* - Behavior:
54+
* - when set, the module reads the file and distributes events across the listed run numbers
55+
* - weights are interpreted as relative ratios and normalized internally
56+
* - File format:
57+
* - two columns: `<run_number> <weight>`
58+
* - example:
59+
* - `11 0.1`
60+
* - `12 0.7`
61+
* - `13 0.2`
62+
*
63+
* This module’s option schema is composed by \c eventDispenser::defineOptions(), which aggregates:
64+
* - \c gdynamicdigitization::defineOptions()
65+
*
66+
* Additional keys contributed by \c gdynamicdigitization::defineOptions() affect digitization selection
67+
* and per-run initialization behavior. Refer to that module’s documentation for the full list.
68+
*
3269
* \section verbosity_sec Module verbosity
3370
* EventDispenser uses the standard GEMC logging infrastructure (classes derived from glogger).
3471
* The practical meaning of verbosity levels is:

‎g4dialog/g4dialogDoxy.h‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,17 @@
2222
* - **Command execution**: paste a selected command into the prompt and execute it.
2323
* - **History**: avoid retyping by recalling previously executed commands.
2424
*
25+
* @section options_sec Available Options and their usage
26+
*
27+
* This module currently does not define additional module-specific option keys.
28+
*
29+
* Notes:
30+
* - The surrounding application may still use global switches/options defined by
31+
* \ref GOptions::GOptions "GOptions(argc,argv,...)" (for example `gui`, `verbosity`, and `debug`)
32+
* to control whether a Qt event loop is started and how much logging is emitted.
33+
* - Visualization-related options are defined by other modules (e.g. g4display) and may be used
34+
* in the same executable, but they are not consumed directly by this module.
35+
*
2536
* \section g4dialog_verbosity Verbosity and logging
2637
*
2738
* This module follows the GEMC-style logging conventions via GBase/Glogger integration.

‎g4system/g4systemDoxy.h‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,45 @@
5454
* - @ref g4system_factory : Runtime creation of system builders and object factories
5555
* - @ref g4system_geometry : Conversion from GEMC DB records into Geant4 geometry/material objects
5656
*
57+
* @section options_sec Available Options and their usage
58+
*
59+
* This module reads the following option keys from the runtime option provider:
60+
*
61+
* - `useBackupMaterial`
62+
* - Type: string
63+
* - Meaning: fallback Geant4 material name used when a requested material is not found
64+
* - Behavior:
65+
* - when unset (equal to \c NO_USE_DEFAULT_MATERIAL), GEMC treats missing materials as fatal
66+
* - when set to a valid Geant4 material (e.g. `G4_AIR`), missing materials are replaced by this fallback
67+
*
68+
* - `check_overlaps`
69+
* - Type: integer
70+
* - Meaning: request for Geant4 overlap checks during geometry construction
71+
* - Behavior:
72+
* - `0` disables overlap checks
73+
* - `1` checks overlaps at physical volume construction time
74+
* - `2` triggers the Geant4 overlap validator with the default surface sampling
75+
* - values `> 100` trigger the Geant4 overlap validator with that many surface points
76+
*
77+
* - `showPredefinedMaterials`
78+
* - Type: boolean (switch)
79+
* - Meaning: print the inventory of GEMC predefined materials
80+
*
81+
* - `printSystemsMaterials`
82+
* - Type: boolean (switch)
83+
* - Meaning: print the materials used by the loaded systems in this simulation
84+
*
85+
* - `checkOverlaps`
86+
* - Type: boolean (switch)
87+
* - Meaning: enable Geant4 overlap checks at construction time (human-readable switch)
88+
* - Note: some code paths use `check_overlaps` (integer) for mode selection; keep these consistent in applications.
89+
*
90+
* This module’s option schema is composed by \c g4system::defineOptions(), which aggregates:
91+
* - \c gsystem::defineOptions()
92+
*
93+
* Additional keys contributed by \c gsystem::defineOptions() (e.g. `sql`, `gsystem`, `experiment`, `runno`)
94+
* control what geometry is loaded and therefore indirectly affect this module.
95+
*
5796
* @section verbosity_sec Verbosity and debug output
5897
* Most classes in this module use the common logging infrastructure (classes derived from
5998
* the logger-enabled base). The following behavior is typical:

‎gboard/gboardDoxy.h‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,17 @@
2323
* - converts common ANSI SGR sequences to HTML
2424
* - appends the result to GBoard
2525
*
26+
* @section options_sec Available Options and their usage
27+
*
28+
* This module currently does not define or consume any module-specific option keys.
29+
*
30+
* Notes:
31+
* - Host applications commonly control whether the GUI is enabled through the global `gui` switch
32+
* defined by \ref GOptions::GOptions "GOptions(argc,argv,...)".
33+
* - Logger routing and verbosity for this module are typically controlled by the global `verbosity`
34+
* and `debug` structured options (also defined by \ref GOptions::GOptions "GOptions(argc,argv,...)" ),
35+
* using the logger name \c gboard (see \c GBOARD_LOGGER).
36+
*
2637
* ## Ownership and lifecycle
2738
*
2839
* - GBoard is a Qt widget: it owns its child widgets via Qt parent/child ownership.

0 commit comments

Comments
 (0)