better options and remove root in b2 yaml

maureeungaro · maureeungaro · commit 3ff152de504a · 2026-06-13T15:23:00.000-04:00
diff --git a/examples/basic/b2/b2.yaml b/examples/basic/b2/b2.yaml
@@ -28,4 +28,3 @@ gmultipoles:
     rotaxis: z
     rotation_angle: "30*deg"
 
-root: G4Box, 12*cm, 12*cm, 18*cm, G4_WATER
diff --git a/gemc/eventDispenser/eventDispenser_options.cc b/gemc/eventDispenser/eventDispenser_options.cc
@@ -24,10 +24,13 @@ GOptions defineOptions() {
 	goptions.defineOption(GVariable("n", 1, "number of events to process"), help);
 
 	// Option: run number
-	// Clarify that this is the *conditions run number* (constants/TT selection), not the Geant4 internal run id.
-	help = "Not to be confused with the geant4 run number - g4runno is set automatically \n \n";
+	// Clarify that this is the *event* run number, distinct from -runno (geometry selection)
+	// and from the Geant4 internal run id (g4runno, set automatically).
+	help = "Run number assigned to the generated events; it is also the key looked up in the\n";
+	help += "-run_weights file. This is distinct from -runno, which selects the geometry/conditions\n";
+	help += "variation from the database, and from the Geant4 run id g4runno, set automatically.\n \n";
 	help += "Example: -run=12\n";
-	goptions.defineOption(GVariable("run", 1, "sets run number"), help);
+	goptions.defineOption(GVariable("run", 1, "event run number"), help);
 
 	// Option: run weights file
 	help = "Text file with run number and their weights.\n \n";
diff --git a/gemc/g4display/g4display_options.cc b/gemc/g4display/g4display_options.cc
@@ -161,12 +161,12 @@ GOptions defineOptions() {
 	goptions.defineOption("g4light", "Defines the geant4 light source direction", g4light, help);
 
 	// dawn
-	help = "Defines the dawn camera view point and take a dawn screenshot \n \n ";
+	help = "Defines the dawn camera view point and takes a dawn screenshot \n \n ";
 	help += "Example: -dawn=\"[{phi: 20*deg, theta: 15*deg}]\"  \n ";
 
 	std::vector<GVariable> dawn = {
-		{"phi", 30, "dawn phi"},
-		{"theta", 30, "dawn theta"}
+		{"phi", "30*deg", "dawn camera phi"},
+		{"theta", "30*deg", "dawn camera theta"}
 	};
 
 	goptions.defineOption("dawn", "Defines the dawn view point", dawn, help);
diff --git a/gemc/g4system/g4systemDoxy.h b/gemc/g4system/g4systemDoxy.h
@@ -82,10 +82,7 @@
  *   - Type: boolean (switch)
  *   - Meaning: print the materials used by the loaded systems in this simulation
  *
- * - `checkOverlaps`
- *   - Type: boolean (switch)
- *   - Meaning: enable Geant4 overlap checks at construction time (human-readable switch)
- *   - Note: some code paths use `check_overlaps` (integer) for mode selection; keep these consistent in applications.
+ * Overlap checking is controlled solely by the integer `check_overlaps` option above.
  *
  * This module’s option schema is composed by \c g4system::defineOptions(), which aggregates:
  * - \c gsystem::defineOptions()
diff --git a/gemc/g4system/g4system_options.cc b/gemc/g4system/g4system_options.cc
@@ -37,19 +37,19 @@ GOptions defineOptions() {
 	// Human-readable switches used for diagnostics and validation.
 	goptions.defineSwitch("showPredefinedMaterials", "log GEMC Predefined Materials");
 	goptions.defineSwitch("printSystemsMaterials", "print the materials used in this simulation");
-	goptions.defineSwitch("checkOverlaps", "check geant4 volume overlaps at construction time");
 
-	// Overlap checking mode:
+	// Overlap checking mode (the integer "check_overlaps" option below is the single control):
 	// - 0 disables overlap checks
 	// - 1 enables overlap checking at placement time
 	// - 2 uses Geant4 overlap validator with default surface sampling
 	// - N>100 uses Geant4 overlap validator with N surface points
 	help = "Check for overlaps at physical volume construction.\n\n";
 	help += "Possible values are:\n";
 	help += " - 0 (default): no check.\n";
-	help += " - 1: check for overlaps at physical volume construction.\n";
+	help += " - 1: enable the G4PVPlacement surface overlap check (pSurfChk) at volume placement.\n";
 	help += " - 2: use the geant4 overlap validator with the default number of points on the surface\n";
-	help += " - Any N greater than 100: use the geant4 overlap validator with N points on the surface\n";
+	help += " - Any N greater than 100: use the geant4 overlap validator with N points on the surface\n \n";
+	help += "Example: -check_overlaps=1\n";
 	goptions.defineOption(GVariable("check_overlaps", 0, "check overlaps"), help);
 
 	return goptions;
diff --git a/gemc/gfields/gfield_options.cc b/gemc/gfields/gfield_options.cc
@@ -52,7 +52,10 @@ GOptions defineOptions() {
 	goptions += gfactory::defineOptions();
 
 	std::string help;
-	help                               = "Adds gmultipoles field(s) to the simulation \n ";
+	help = "Adds electromagnetic multipole field(s) to the simulation. \n \n";
+	help += "Mandatory keys: name, pole_number, rotaxis, strength. \n \n";
+	help += "Example (a quadrupole centered 30 cm downstream): \n";
+	help += "-gmultipoles=\"[{name: q1, pole_number: 4, rotaxis: Z, strength: 1.2, vz: 30*cm}]\"\n";
 	std::vector<GVariable> gmultipoles = {
 		{"name", goptions::NODFLT, "Field name (unique key used by GMagneto maps)"},
 		{"integration_stepper", GFIELD_DEFAULT_INTEGRATION_STEPPER, "Geant4 integration stepper name (string)"},
diff --git a/gemc/goptions/goptions.cc b/gemc/goptions/goptions.cc
@@ -22,6 +22,7 @@
 // c++
 #include <iostream>
 #include <cstring>
+#include <cctype>
 
 using namespace std;
 
@@ -45,15 +46,19 @@ GOptions::GOptions(int argc, char* argv[], const GOptions& user_defined_options)
 	addGOptions(user_defined_options);
 
 	// switches for all everyone
-	defineSwitch("gui", "use Graphical User Interface");
-	defineSwitch("i", "use interactive batch mode");
+	defineSwitch("gui", "run with the graphical user interface (Qt window)");
+	defineSwitch("i", "drop into the interactive Geant4 terminal session (non-GUI mode)");
 	defineOption(
-		GVariable("conf_yaml", "saved_configuration", "the prefix for filename that store the used options"),
-		"The default value appends \"_saved_configuration\" to the executable name.");
+		GVariable("conf_yaml", "saved_configuration", "infix for the YAML file that records the resolved options"),
+		"On exit the resolved configuration is written to <executable>.<conf_yaml>.yaml,\n"
+		"so the default value produces, for example, gemc.saved_configuration.yaml.\n \n"
+		"Example: -conf_yaml=run12   ->   saves to gemc.run12.yaml\n \n");
 
 	// add test timeout for the tests
-	defineOption(GVariable("tt", 500, "tests timeout (ms)"),
-	             "Timeout in milliseconds for the code tests that have GUI. ");
+	defineOption(GVariable("tt", 500, "GUI test timeout (ms)"),
+	             "Milliseconds a GUI-based test waits before it auto-closes, so the module\n"
+	             "example/test programs can run unattended in CI.\n \n"
+	             "Example: -tt=1000\n \n");
 
 	// version is a special option, not settable by the user
 	// it is set by the gversion.h file
@@ -72,16 +77,25 @@ GOptions::GOptions(int argc, char* argv[], const GOptions& user_defined_options)
 	help        += " - 0: (default) = shush\n";
 	help        += " - 1: log detailed information\n";
 	help        += " - 2: log extra detailed information\n \n";
-	help        += "Example: -verbosity.gemc=1 \n \n";
-	help        += "The YAML value can include multiple logger keys.\n \n";
+	help        += "Each key names a class or module; run 'help verbosity' to list the available keys.\n \n";
+	help        += "Example (one key):      -verbosity.gemc=1\n";
+	help        += "Example (several keys): -verbosity=\"[{gemc: 1}, {<another_key>: 2}]\"\n \n";
+	help        += "Equivalent YAML:\n";
+	help        += "   verbosity:\n";
+	help        += "     - gemc: 1\n";
+	help        += "     - <another_key>: 2\n \n";
 	defineOption("verbosity", "Sets the log verbosity for various classes", option_verbosity_names, help);
 
 	// debug option: boolean or integer, depending on consumer expectations
 	help = "Debug information Types: \n \n";
 	help += " - false: (default): do not print debug information\n";
 	help += " - true: print debug information\n\n";
-	help += "Example: -debug=\"[{gemc: true}]\" \n \n";
-	help += "The YAML value can include multiple logger keys.\n \n";
+	help += "Each key names a class or module; run 'help debug' to list the available keys.\n \n";
+	help += "Example (on/off):       -debug.gemc=true\n";
+	help += "Example (several keys): -debug=\"[{gemc: true}, {<another_key>: 1}]\"\n \n";
+	help += "Equivalent YAML:\n";
+	help += "   debug:\n";
+	help += "     - gemc: true\n \n";
 	defineOption("debug", "Sets the debug level for various classes", option_verbosity_names, help);
 
 	// Process help/version command-line arguments.
@@ -105,6 +119,12 @@ GOptions::GOptions(int argc, char* argv[], const GOptions& user_defined_options)
 			else { printHelp(); }
 			exit(EXIT_SUCCESS);
 		}
+		else if (strcmp(argv[i], "search") == 0) {
+			// "gemc search <value>" lists options/switches whose name or description contains <value>.
+			if (i + 1 < argc) { printSearch(argv[i + 1]); }
+			else { printHelp(); }
+			exit(EXIT_SUCCESS);
+		}
 	}
 
 	// finds and parse the yaml files
@@ -295,6 +315,42 @@ void GOptions::printOptionOrSwitchHelp(const std::string& tag) const {
 	exit(EC__NOOPTIONFOUND);
 }
 
+// Private method: see header. Kept undocumented here to avoid duplicate param docs.
+void GOptions::printSearch(const std::string& tag) const {
+	// Case-insensitive substring match against switch/option names and descriptions.
+	auto to_lower = [](string s) {
+		transform(s.begin(), s.end(), s.begin(), [](unsigned char c) { return std::tolower(c); });
+		return s;
+	};
+	const string needle = to_lower(tag);
+	auto         matches = [&](const string& a, const string& b) {
+		return to_lower(a).find(needle) != string::npos || to_lower(b).find(needle) != string::npos;
+	};
+
+	long int fill_width = string(HELPFILLSPACE).size() + 1;
+	cout.fill('.');
+	cout << KGRN << KBOLD << " Options and switches matching \"" << tag << "\":" << RST << endl << endl;
+
+	bool found = false;
+	for (auto& s : switches) {
+		if (matches(s.first, s.second.getDescription())) {
+			found = true;
+			cout << KGRN << " " << left;
+			cout.width(fill_width);
+			cout << "-" + s.first + RST + " " << ": " << s.second.getDescription() << endl;
+		}
+	}
+	for (auto& option : goptions) {
+		if (option.name != GVERSION_STRING && matches(option.name, option.description)) {
+			found = true;
+			option.printHelp(false);
+		}
+	}
+	if (!found) { cout << TPOINTITEM << "no match found." << endl; }
+	cout << endl << " Use " << KGRN << "help <value>" << RST << " for the detailed help of a single option." << endl
+		<< endl;
+}
+
 // Private method: see header. Kept undocumented here to avoid duplicate param docs.
 vector<string> GOptions::findYamls(int argc, char* argv[]) {
 	vector<string> yaml_files;
@@ -523,7 +579,7 @@ void GOptions::printHelp() const {
 		string("help <value>") + RST,
 		string("print detailed help for option <value> and exit"),
 		string("search <value>") + RST,
-		string("list all options containing <value> in the description and exit\n")
+		string("list all options/switches whose name or description contains <value> and exit\n")
 	};
 	unsigned half_help = helps.size() / 2;
 	for (unsigned i = 0; i < half_help; i++) {
diff --git a/gemc/goptions/goptions.h b/gemc/goptions/goptions.h
@@ -397,6 +397,7 @@ class GOptions
 	std::vector<GOption>::iterator getOptionIterator(const std::string& name);
 	[[nodiscard]] std::vector<GOption>::const_iterator getOptionIterator(const std::string& name) const;
 	void printOptionOrSwitchHelp(const std::string& tag) const;
+	void printSearch(const std::string& tag) const;
 	void printHelp() const;
 	void printWebHelp() const;
 	void saveOptions() const;
diff --git a/gemc/gphysics/gphysics_options.cc b/gemc/gphysics/gphysics_options.cc
@@ -60,8 +60,8 @@ GOptions defineOptions() {
 	physicsListHelp += string(HELPFILLSPACE) + " - _PEN to use G4EmPenelopePhysics\n";
 	physicsListHelp += string(HELPFILLSPACE) + " - _SS to use G4EmStandardPhysicsSS\n";
 	physicsListHelp += string(HELPFILLSPACE) + " - _WVI to use G4EmStandardPhysicsWVI\n";
-	physicsListHelp += "\n" + string(HELPFILLSPACE) + "For example, FTFP_BERT_LIV would replace the default e.m. physics with the Livermode model \n\n";
-	physicsListHelp += "\n" + string(HELPFILLSPACE) + "Additional physics can be loaded by adding its constructor name to the list using the " + " sign\n";
+	physicsListHelp += "\n" + string(HELPFILLSPACE) + "For example, FTFP_BERT_LIV would replace the default e.m. physics with the Livermore model \n\n";
+	physicsListHelp += "\n" + string(HELPFILLSPACE) + "Additional physics can be loaded by adding its constructor name to the list using the + sign\n";
 	physicsListHelp += "\n" + string(HELPFILLSPACE) + "For example: FTFP_BERT + G4OpticalPhysics. The available constructors are: \n\n";
 	physicsListHelp += string(HELPFILLSPACE) + " - G4ChargeExchangePhysics\n";
 	physicsListHelp += string(HELPFILLSPACE) + " - G4DecayPhysics\n";
@@ -142,6 +142,9 @@ GOptions defineOptions() {
 	physicsListHelp += string(HELPFILLSPACE) + " - G4StoppingPhysicsFritiofWithBinaryCascade\n";
 	physicsListHelp += string(HELPFILLSPACE) + " - G4UnknownDecayPhysics\n";
 	physicsListHelp += string(HELPFILLSPACE) + " - G4WeightWindowBiasing\n";
+	physicsListHelp += "\n" + string(HELPFILLSPACE) + "Command-line examples:\n";
+	physicsListHelp += string(HELPFILLSPACE) + " -phys_list=FTFP_BERT\n";
+	physicsListHelp += string(HELPFILLSPACE) + " -phys_list=\"FTFP_BERT_EMZ + G4OpticalPhysics\"\n";
 	goptions.defineOption(GVariable("phys_list", DEFAULTPHYSICSLIST, "Select Physics List"), physicsListHelp);
 
 	goptions.defineSwitch("showPhysics", "Log Geant4 Physics Available Modules that can be used with the \"phys_list\" option and exit");
diff --git a/gemc/gstreamer/gstreamer_options.cc b/gemc/gstreamer/gstreamer_options.cc
@@ -67,8 +67,11 @@ GOptions defineOptions() {
 	// Buffer flush limit:
 	// controls how many events each streamer instance may retain in memory
 	// before the base class forces a flush to the backend.
+	string ebuffer_help = "Number of events each streamer keeps in memory before flushing them to the\n";
+	ebuffer_help        += "output file. Larger values reduce I/O frequency at the cost of more memory.\n \n";
+	ebuffer_help        += "Example: -ebuffer=100\n";
 	goptions.defineOption(GVariable("ebuffer", DEFAULT_GSTREAMER_BUFFER_FLUSH_LIMIT,
-	                                "number of events kept in memory before flushing them to the filestream"), help);
+	                                "number of events kept in memory before flushing them to the filestream"), ebuffer_help);
 
 	// Schema of each object in the -gstreamer array.
 	vector<GVariable> gstreamer = {
@@ -77,7 +80,7 @@ GOptions defineOptions() {
 		{"type", "event", "type of output file"},
 	};
 
-	goptions.defineOption(GSTREAMER_LOGGER, "define a gstreamer output", gstreamer, help);
+	goptions.defineOption("gstreamer", "define a gstreamer output", gstreamer, help);
 
 	// Merge dependent-module options so callers can build a single composite
 	// GOptions definition for applications and examples.
diff --git a/gemc/gsystem/gsystem_options.cc b/gemc/gsystem/gsystem_options.cc
@@ -116,21 +116,25 @@ GOptions defineOptions() {
 
 	// add sql option to define host or sqlite file
 	help = "sqlite file or sql host. Default is: " + std::string(GSYSTEMSQLITETDEFAULTFILE) + ". \n\n";
+	help += "Example (sqlite file): -sql=myGeometry.sqlite\n";
 	goptions.defineOption(GVariable("sql", GSYSTEMSQLITETDEFAULTFILE, "sql host or sqlite file"),
 	                      help);
 
 	// add ascii_db option to define an alternative search path for the ascii factory
 	help = "ascii search path. Default is: " + std::string(GSYSTEMSASCIISEARCHDIR) + ". \n\n";
-	goptions.defineOption(GVariable("ascii_db", GSYSTEMSASCIISEARCHDIR, "sql host or sqlite file"),
+	help += "Example: -ascii_db=/path/to/geometry/text/files\n";
+	goptions.defineOption(GVariable("ascii_db", GSYSTEMSASCIISEARCHDIR, "ascii factory search path"),
 	                      help);
 
 	// add the experiment option to define the experiment, common for all systems
 	goptions.defineOption(GVariable("experiment", "examples", "experiment selection"),
-	                      "Each experiment has a subset of unique systems");
+	                      "Each experiment has a subset of unique systems.\n \nExample: -experiment=clas12\n");
 
 	// add run number options, common for all systems
-	goptions.defineOption(GVariable("runno", 1, "run number"),
-	                      "All systems share this run number");
+	goptions.defineOption(GVariable("runno", 1, "geometry/conditions run number"),
+	                      "Run number used to select the geometry/conditions variation loaded from the\n"
+	                      "database; all systems share it. This is distinct from -run, the run number\n"
+	                      "assigned to generated events.\n \nExample: -runno=11\n");
 
 	return goptions;
 }
diff --git a/releases/0.3.md b/releases/0.3.md
@@ -11,6 +11,8 @@ This version includes:
 - Unified `value*unit` notation for `gparticle` kinematic fields
 - `GEMC_PLUGIN_PATH` and `-plugin_path` for external plugin discovery
 - Pre-parse plugin options hook for dynamic plugin option registration
+- Clearer command-line help: reviewed every module's option/switch help, added usage examples, and
+  implemented the previously-advertised `search <value>` command
 - ROOT gstreamer and event-action bug fixes
 - Fixed TOOLSSG_OFFSCREEN batch crash (race condition between screenshot rendering and vis subthread)
 - Optical photon trajectories rendered in cyan in both GUI and offscreen screenshots
@@ -479,3 +481,27 @@ Both x86_64 and ARM64 platforms are supported.
   photons inherit the `drawByCharge` neutral-particle default color, making them indistinguishable
   from neutrons and other neutral tracks — particularly against the light-colored default background
   used in screenshots and the GUI.
+- Reviewed and clarified command-line option/switch help across the whole `gemc/` tree, adding usage
+  examples where they were missing. In the core `goptions` module: reworded the built-in `-gui`, `-i`,
+  `conf_yaml`, and `tt` help; corrected the `conf_yaml` help, which described the saved-configuration
+  filename incorrectly; expanded the `verbosity` and `debug` examples; and implemented the
+  `search <value>` command, which `printHelp()` advertised but was never wired up (it now lists
+  options and switches whose name or description contains the search term).
+- Fixed stale or copy-pasted option help in several modules:
+  - `gphysics`: the `phys_list` help lost the literal `+` that joins extra constructors (it rendered
+    as "using the  sign"); fixed a "Livermode" → "Livermore" typo; added concrete `-phys_list` examples.
+  - `gstreamer`: the `ebuffer` option reused the large `gstreamer` help block; it now has its own help
+    and example, and the structured option registers under the literal name `"gstreamer"`.
+  - `gsystem`: corrected the `ascii_db` description (copied from `sql`) and added examples for `sql`,
+    `ascii_db`, `experiment`, and `runno`.
+  - `gfields`: added a `gmultipoles` usage example.
+  - `g4display`: polished the `dawn` help wording and made its default `phi`/`theta` use the same
+    `value*unit` notation as `g4camera`/`g4light`.
+- Clarified the two distinct run-number options that coexist in the full application: `runno`
+  (`gsystem`, selects the geometry/conditions variation) versus `run` (`eventDispenser`, the run number
+  assigned to generated events and the key used with `-run_weights`); both descriptions and help now
+  cross-reference each other and the automatic Geant4 `g4runno`.
+- Removed the unused `checkOverlaps` switch from `g4system`: it was registered and shown in help but
+  never read. Overlap checking is controlled solely by the integer `check_overlaps` option, whose
+  value `1` already enables the `G4PVPlacement` surface overlap check (`pSurfChk`) at volume placement;
+  the help now documents this and the doxygen page was updated to match.

Original file line number	Diff line number	Diff line change
`@@ -28,4 +28,3 @@ gmultipoles:`
`28`	`28`	`rotaxis: z`
`29`	`29`	`rotation_angle: "30*deg"`
`30`	`30`
`31`		`-root: G4Box, 12cm, 12cm, 18*cm, G4_WATER`
Original file line number	Diff line number	Diff line change
`@@ -82,10 +82,7 @@`
`82`	`82`	`* - Type: boolean (switch)`
`83`	`83`	`* - Meaning: print the materials used by the loaded systems in this simulation`
`84`	`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.
	`85`	+ * Overlap checking is controlled solely by the integer `check_overlaps` option above.
`89`	`86`	`*`
`90`	`87`	`* This module’s option schema is composed by \c g4system::defineOptions(), which aggregates:`
`91`	`88`	`* - \c gsystem::defineOptions()`