GEMC Utilities Module

Runtime utilities used during GEMC initialization and configuration. More...

Functions
std::unique_ptr< QCoreApplication >	gemc::makeQtApplication (int &argc, char *argv[], bool gui)
	Create a Qt application instance suitable for GUI or batch execution.
int	gemc::get_nthreads (const std::shared_ptr< GOptions > &gopts, const std::shared_ptr< GLogger > &log)
	Determine the number of worker threads to use for the run.
std::vector< std::string >	gemc::verbosity_commands (const std::shared_ptr< GOptions > &gopts, const std::shared_ptr< GLogger > &log)
	Build a list of Geant4 UI commands that reduce verbosity across subsystems.
std::vector< std::string >	gemc::initial_commands (const std::shared_ptr< GOptions > &gopts, const std::shared_ptr< GLogger > &log, bool configure_visualization=true)
	Build a list of Geant4 UI commands needed at startup.
void	gemc::run_manager_commands (const std::shared_ptr< GOptions > &gopts, const std::shared_ptr< GLogger > &log, const std::vector< std::string > &commands)
	Execute a sequence of Geant4 UI commands through the UI manager.
void	gemc::define_new_gemc_units ()
void	gemc::start_random_engine (const std::shared_ptr< GOptions > &gopts, const std::shared_ptr< GLogger > &log)
	Select and start the random engine, then seed it.

Detailed Description

This module is focused on startup/runtime glue code:

• determining thread counts from user options
• producing Geant4 UI command lists based on options
• applying UI command lists
• selecting and seeding the random engine
• creating a Qt application instance in GUI or batch mode

Ownership and lifecycle considerations are documented per-function.

Function Documentation

define_new_gemc_units()

void gemc::define_new_gemc_units

(

)

Definition at line 247 of file gemcUtilities.cc.

get_nthreads()

int gemc::get_nthreads	(	const std::shared_ptr< GOptions > &	gopts,
		const std::shared_ptr< GLogger > &	log )

This helper reads the nthreads option from gopts and clamps it to the available CPU core count reported by G4Threading::G4GetNumberOfCores().

Behavior:

• If nthreads == 0, the maximum number of available cores is used.
• If nthreads > available_cores, the value is clamped to available_cores.
• Otherwise the user-provided nthreads value is used.

The function logs the chosen number of threads using log.

Parameters

gopts	Runtime options provider. The key used is nthreads.
log	Logger used to report the chosen thread count.

Returns

The number of threads that should be used.

Definition at line 74 of file gemcUtilities.cc.

initial_commands()

std::vector< std::string > gemc::initial_commands	(	const std::shared_ptr< GOptions > &	gopts,
		const std::shared_ptr< GLogger > &	log,
		bool	configure_visualization = true )

This function prepares commands based on options:

• check_overlaps (typically provided by the G4 system options set)
• gui

Behavior:

• If check_overlaps == 2, schedule an overlap test with a resolution of 50 points.
• If check_overlaps >= 100, schedule an overlap test with that many points.
• Include "/run/initialize" after overlap configuration, except in GUI mode when no startup geometry is configured.
• If visualization setup is disabled, return the list after initialization.
• Otherwise open the viewer, then create an attached scene containing the initialized GEMC root volume.
• If gui is false and offscreen rendering is not requested, return after scene setup.
• Otherwise append visualization scene/viewer configuration commands: configure trajectories/hits and background color, disable/enable auto-refresh around setup, and finally flush the viewer.

Parameters

gopts	Runtime options provider. Keys used include check_overlaps and gui.
log	Logger used to report which overlap test (if any) will be executed.
configure_visualization	If false, skip visualization commands after /run/initialize; in GUI mode this also defers initialization until setup reload.

Returns

A list of UI command strings to be executed in order.

Definition at line 129 of file gemcUtilities.cc.

makeQtApplication()

std::unique_ptr< QCoreApplication > gemc::makeQtApplication ( int & argc, char * argv[], bool gui )

inline

• When gui is true, this function returns a QApplication instance (returned as a std::unique_ptr<QCoreApplication> for uniform handling).
• When gui is false, this function:
  1. Creates a GBatch_Session instance.
  2. Transfers its ownership to Geant4 by calling G4UImanager::GetUIpointer()->SetCoutDestination(...).
  3. Returns a QCoreApplication instance.

Ownership and lifecycle

• The returned std::unique_ptr<QCoreApplication> owns the Qt application object.
• In batch mode, the created GBatch_Session is released and then owned by Geant4 via SetCoutDestination. The caller must not delete it.

Parameters

argc	Standard main() argument count (passed by reference as required by Qt).
argv	Standard main() argument array (passed through to Qt).
gui	If true, create a QApplication; otherwise create a QCoreApplication and redirect Geant4 cout to a GBatch_Session.

Returns

A std::unique_ptr<QCoreApplication> owning either a QCoreApplication or a QApplication instance.

Definition at line 72 of file gemcUtilities.h.

run_manager_commands()

void gemc::run_manager_commands	(	const std::shared_ptr< GOptions > &	gopts,
		const std::shared_ptr< GLogger > &	log,
		const std::vector< std::string > &	commands )

This function obtains the global UI manager pointer and applies each command in commands in order. Each command is logged at an informational verbosity suitable for tracing configuration activity.

Parameters

gopts	Runtime options provider (currently unused by this implementation).
log	Logger used to trace command execution.
commands	List of UI command strings to apply, in order.

Definition at line 236 of file gemcUtilities.cc.

start_random_engine()

void gemc::start_random_engine	(	const std::shared_ptr< GOptions > &	gopts,
		const std::shared_ptr< GLogger > &	log )

This function reads:

• randomEngine : the name of the random engine implementation
• seed : the numeric seed value

If the seed is SEEDNOTSET, a seed is generated from a combination of wall time, process CPU clock, and the process id.

Supported engine names

The engine names correspond to CLHEP random engines (examples include DRand48Engine, DualRand, HepJamesRandom, MTwistEngine, RanluxEngine, etc.). The selection is performed by matching the randomEngine option string.

Error handling

If an unknown engine name is provided, an error is logged using the module error code EC__RANDOMENGINENOTFOUND.

Parameters

gopts	Runtime options provider. Keys used: randomEngine, seed.
log	Logger used to report the chosen engine and seed, or errors.

Definition at line 257 of file gemcUtilities.cc.

verbosity_commands()

std::vector< std::string > gemc::verbosity_commands	(	const std::shared_ptr< GOptions > &	gopts,
		const std::shared_ptr< GLogger > &	log )

The returned commands are intended to keep Geant4 output quiet in typical runs. They include .../verbose 0 style settings for major categories such as: control, hit, process, tracking, geometry navigator, event, cuts, run, material, visualization, and particle messages.

Parameters

gopts	Runtime options provider (currently unused by this implementation).
log	Logger (currently unused by this implementation).

Returns

A list of UI command strings to be executed in order.

Definition at line 90 of file gemcUtilities.cc.