GEMC Detector System Module (gsystem)

Table of Contents

• Introduction
• Ownership and lifecycle
• Factories
• Available Options and their usage
• Verbosity and logging
• Examples
  • Example : gsystem_example.cc
• Design notes

Detector-system loading and world assembly

Introduction

The gsystem module provides the infrastructure that turns detector configuration into an in-memory representation of geometry and materials.

GEMC detector definition and simulation workflow

Core concepts:

• A GSystem is a logical detector subsystem (e.g. calorimeter, tracker).
• A GVolume is one placed volume record belonging to a GSystem.
• A GMaterial is a material definition belonging to a GSystem.
• A GWorld assembles multiple systems, applies modifiers, and assigns final names.
• A GSystemFactory loads a system from a concrete source (sqlite, ASCII, CAD, ...).

Ownership and lifecycle

• The world owns the system map container, and stores systems as shared pointers.
• Each system owns its collections of volumes and materials.
• Factories are temporary objects used during load; they may keep transient state such as open DB handles or search paths and should release them in closeSystem().

Factories

Factory selection is driven by system configuration:

• sqlite : loads geometry/materials from a sqlite database.
• ascii : loads geometry/materials from text files with positional fields.
• CAD : imports volumes from CAD assets (e.g. STL).
• GDML : placeholder for future GDML support.

Available Options and their usage

This module reads the following option keys from the runtime option provider:

• gsystem
  • Type: sequence of maps
  • Meaning: list of detector subsystems to load and assemble into the world
  • Behavior:
    • each entry becomes one GSystem created by gsystem::getSystems()
    • the selected factory controls the source backend (sqlite / ascii / CAD / GDML placeholder)
  • Subkeys used by this module:
    • name (string, mandatory): system name (and/or source identifier)
    • factory (string): factory label (default: sqlite)
    • variation (string): geometry variation (default: "default")
    • annotations (string): optional system annotations (default: UNINITIALIZEDSTRINGQUANTITY)
• gmodifier
  • Type: sequence of maps
  • Meaning: post-load volume modification rules applied by the world
  • Behavior:
    • each entry becomes one GModifier created by gsystem::getModifiers()
  • Subkeys used by this module:
    • name (string): volume name (default: goptions::NODFLT sentinel)
    • shift (string): shift triple (default: GSYSTEMNOMODIFIER)
    • tilt (string): tilt triple (default: GSYSTEMNOMODIFIER)
    • isPresent (bool): if false, remove volume from world (default: true)
• sql
  • Type: string
  • Meaning: sqlite file path (or SQL host, depending on factory) used as the default geometry source
  • Behavior:
    • used as the base database/location when creating systems
    • overridden by ascii_db when factory == "ascii"
• ascii_db
  • Type: string
  • Meaning: alternative search path/root used by the ASCII factory
  • Behavior:
    • when a system entry selects the ASCII factory, this value replaces sql as the source root
• experiment
  • Type: string
  • Meaning: experiment selection shared by all systems
  • Behavior:
    • passed into each created GSystem as the experiment context
• runno
  • Type: integer
  • Meaning: conditions/run number shared by all systems
  • Behavior:
    • passed into each created GSystem as the run context used for variation/run-dependent selection

Note: this module’s option schema is composed by gsystem::defineOptions(), and it also aggregates options from gfactory::defineOptions(). Any additional plugin-loader options are documented there.

Verbosity and logging

Most classes in this module derive from GBase and therefore use a GLogger.

Typical verbosity behavior (convention for classes derived from GBase / using GLogger):

• Level 0: high-level milestones and key warnings (e.g. missing optional files, major fallbacks).
• Level 1: normal informational messages (e.g. which systems/factories are loading).
• Level 2: detailed diagnostics (e.g. expanded SQL queries, per-column dumps, per-volume summaries).
• Debug: very fine-grained tracing such as constructor/function entry markers, internal state snapshots.

The exact interpretation is logger-dependent, but the module is structured so that higher levels add detail without changing semantics.

Examples

Example : gsystem_example.cc

Minimal program that:

• builds a GOptions instance with gsystem::defineOptions();
• constructs a GWorld, triggering full system load (factories, volumes/materials, modifiers).

See the example's full documentation here: gsystem_example.cc.

Example snippet:

./gsystem_example -gsystem="[{name: b1, factory: sqlite, variation: default}]" -sql=gemc.db

Design notes

• The module uses serialized parameter vectors to represent DB/ASCII rows. Parsing is positional.
• Post-load modifiers (shift/tilt/existence) are applied by the world after all volumes exist.
• Final Geant4 names are assigned as "<system>/<volume>" during world bookkeeping.

Author

© Maurizio Ungaro

e-mail: ungar.nosp@m.o@jl.nosp@m.ab.or.nosp@m.g