Introduction

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

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

gemc

gsystem

Definition gsystem_options.cc:16

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.