Bogus

"The name Bogus is provisional; if you've got a better one, let me know. Personally, I think it's hard to beat!
BaBar reco/analysis will have two data sources: the real detector and the Bogus detector" - T.Wenaus

Introduction
Requirements & Design
Specifications & Subsystem status
Geant4 & Bogus installation steps
Running Bogus standalone
Bogus in the BaBar Framework
Running Bogus in the BaBar Framework: BgsSequences
Running Bogus as a Beta application in the Framework
Geant4 Tools
Geant4 Physics Data

1. Introduction

Bogus is the BaBar application layer over the Geant4 simulation toolkit.
Main goals:

Implement and exercise the key design elements of Geant4 required to support a unified (full + fast) simulation
Serve as framework for the implementation of parameterized detector models and multiple detector representations
Serve as framework for the implementation of native Geant4 detector models
Exercise the BaBar-developed tools for migration from Geant3 to Geant4, dual-use code, and coexistence of BBSIM and an OO simulation with as much commonality and as little redundancy as possible
Objectives:

Form the basis for a fast simulation to replace Aslund.
Form the basis for a full and intermediate simulation to be used to validate Geant4 tracking, physics in the near and middle term and replace BBSIM in the long term.

2. Bogus Requirements & Design

Category diagram - Class diagram
The Bogus design must meet a number of requirements:

Capability to model the detector geometry, materials, magnetic field, particle interactions and decays, and detector response with a high degree of accuracy commensurate with the precision physics goals of BaBar.
Physics of particle interactions in matter that is trusted, proven and sufficently complete in the domains relevant for BaBar.
Efficient utilization of CPU such that the high statistics required can be attained with the available resources without compromising required levels of simulation detail.
Flexible architecture with selectable levels of simulation detail at the subsystem level such that the modelling detail matches the requirements of the analysis, and doesn't waste resources and unnecessarily increase the turnaround time to deliver the required statistics.
Architectural compatibility with the rest of the BaBar software infrastructure. Concretely, this means an object-oriented architecture based on C++.
Modular design compatible with highly distributed development and subsystem development efforts with a high degree of autonomy.
Support for a migration path from our present Geant3.21-based simulation that utilizes limited manpower efficiently, avoids redundant effort by supporting dual-use code, and is based on a single development effort rather than two largely decoupled efforts. Central to this migration plan is keeping the Geant3.21 based simulation the fully-featured production simulation until Bogus physics performance is fully verified.
Fulfilling these requirements is driving the design and implementation of Bogus and has driven the requirements and design input BaBar has given to Geant4 to make the required functionality available.

3. Specifications & Subsystem status

Interface to geometry database:

The DBIO interface is progressively being replaced by a mechanism based on proxy classes able to store and retrieve geometry parameters data from ODBMS. Schemas for defining persistent data are implemented as well. An intermediate layer of representation of the transient objects is implemented in each schema design, therefore making proxies and persistent data classes totally independent from Geant4. Usage of Geant4 classes has to be confined to just simulation in Bogus and subsystem-related packages (simulation and reco-like simulation).

Interface to material database:

A factory class BgsMatFactory has been implemented to allow retrivial of data from ODBMS via the MatEnv package and automatic building of G4Material transient objects according to the needs of each subsystem. An intermediate layer of representation of the transient objects is implemented in each schema design in MatEnv, therefore making proxies and persistent data classes totally independent from Geant4. Data retrieved through MatEnv are also used in Reconstruction.

Detector description object model: (see class diagram).

Multiple models are supported for each subsystem, and managed by a model manager class. Geometry models and model manager for each subsystem are implemented inside the respective package. Here is the list of subsystem packages: BgsDchSim, BgsDrcSim, BgsEmcSim, BgsIfrSim, BgsPepSim, BgsSvtSim.
Current status of subsystem models:

DCH (BgsDchSim package), provides three models:

fast-cylinder: model defining the chamber as a simple cylindrical volume. No hit scoring.

cylinder: model containing a detailed description of the materials. The gas volume is a simple cylindrical sensitive volume.
layer: model containing a detailed description of the materials. The gas volume is made of 40 sensitive volumes (one for each layer).

DRC (BgsDrcSim package), provides three models (see also related documentation):

fast-cylinder: model based on an empty cylinder which can hold CST and SST. No hit scoring.
very-fast: model without SOB. Has SST, CST, bar boxes and bars filled with true materials. It produces track hits and PID hits.
fast-empty: model containing only bars description, no materials inside. Same hits produced in the "very-fast" model.

EMC (BgsEmcSim package), provides two models, both of them implementing fast parameterization and producing "fast-hit" collections:

fast-param-cylinder: model based on an empty cylinder envelope.

fast-param-PCone: model based on a CSG PCone (G4Polycone) volume envelope.
Other two models with no hit scoring are also provided:

fast-cylinder: model based on an empty cylinder.
fast-Pcone: model based on a CSG PCone solid.
Two models are also provided for doing full simulation and producing full GHits (still under testing):

full-model: retrieves detector geometry through the BgsEucIntfce (Euclid interface for Geant4).
sliced-cylinder: simplified full geometry based on a single cylinder volume sliced in such a way that it mimics the real EMC crystal numbering. Barrel and the end-cap are in the cylinder and the geometry is non-projective.

IFR (BgsIfrSim package), implements two models:

fast-cylinder: model based on an empty cylinder. This model implements fast parameterization and produces "fast-hit" collections.
bbsim-euclid: model for full simulation using the Euclid interface defined in Bogus (still under testing).

PEP (BgsPepSim package), implements two models:

fast-cylinder: model based on an empty cylinder. No hit scoring.
fast-model: model implementing a simple geometry for the beam-pipe and the support tube. The geometry parameters are retrieved from the conditions database.

SVT (BgsSvtSim package), implements three models for fast simulation:

fast-cylinder: model based on an empty cylinder. No hit scoring.
fast-model: model implementing a simplified geometry of wafers and retrieving geometry from the conditions database.
fast-param: fast-parametrized model of the SVT. Uses the BgsCEPack algorithm for geometry navigation and tracking, bypassing Geant4.
A model is also defined for full simulation (currently under testing):

full-model: implements full SVT geometry for detailed simulation.

A detector description class BgsDescription manages the definition of a detector description to be used in a given simulation run. Provides the capability to specify the model to be used for each subsystem, perform consistency checks across subsystem selections, and (later) select models conditionally depending on the circumstances, eg. different models for different particle types, different regions of the detector, etc.
The detector description class works with subsystem description classes implemented by the subsystems that implement the model-selection capabilities and consistency cross-checks for a subsystem.
Models are named, and selected by name (selection is currently handled in BgsFlags.hh).
Only models actually used in a given simulation are built.
An environment class BgsEnv manages global environment aspects, reading the database, building materials, initializing objects and managing the various managers, etc.
A common abstract implementation of "fast-hit" is defined in Bogus (class BgsTrkHit) for tracker subsystems and the beam-pipe. BgsTrkHit acts as base class for the hits defined on those subsystems for the fast simulation.

Interface to Euclid geometries:
the BgsEucIntfce class defines a Geant4 concrete implementation of the Euclid interface.
Interface to g3tog4 geometries:
The g3tog4 tool available in Geant4 has been used in the early development stage in Bogus to implement the SVT and IFR detailed geometry descriptions. Usage of g3tog4 is now being progressively phased-out. Some restrictions applies however for the detailed geometry description of the PEP subsystem which is still under development.
Parameterized detector response:
Parameterized detector response is integrated for EMC and IFR (SVT under development).
For the EMC and IFR, the fast Geant4 parameterization is used defining a simple envelope.

4. Geant4 & Bogus installation steps

Bogus is integrated into SRT; it is an SRT package (Bogus) and relies upon 6 packages which implement the underlying subsystem related simulation: BgsDchSim, BgsDrcSim, BgsEmcSim, BgsIfrSim, BgsPepSim and BgsSvtSim.
The Geant4 toolkit is needed as well for header files and linking libraries.
To work with Bogus at present you need to have the Geant4 toolkit installed on your system. At SLAC, the most recent version of the toolkit is available on: $BFROOT/simu/geant4 both as archive-file and fully installed with precompiler libraries for all BaBar supported platforms. Libraries include also OpenGLX, DAWN, RAYX and VRML drivers for visualization.
These are the steps you should follow if you need to install the Geant4 toolkit locally, otherwise skip them directly to point 9. if using the SLAC installation (example for BB00-02 distribution):

Copy the compressed Geant4 archive from $BFROOT/simu/geant4/BB00-02/geant4.tar.gz at SLAC and have a look to the README file therein; you'll find also information on how to build the Geant4 libraries with visualization drivers.
Make sure you have a version of Rogue Wave Tools.h++ at your site compatible with the current one in use for BaBar (consult the Computing Tools page and/or Charlotte Hee for more information).
In your environment, set $G4INSTALL to point to the area you've installed the Geant4 toolkit (by default, it points in our case to $BFROOT/simu/geant4/BB00-02/geant4.
Check that $RWBASE is pointing to the correct Rogue-Wave installation area for your system (this should be handled already by your BaBar software setup).
In your environment, set $CLHEP_BASE_DIR to point to the area where CLHEP is installed (by default, it points in our case to $BFROOT/dist/releases/$BFCURRENT). It should refer to the CLHEP package version in the current SRT (the most recent version of CLHEP is suggested).
Set the corresponding G4VIS_BUILD_xxx_DRIVER environment variable (xxx = OPENGLX or OPENGL, DAWN, DAWNFILE, RAYX, VRML, VRMLFILE, OPACS) to have the selected graphics driver library built. In case of OpenGL or OpenGLX also specify where the graphics libraries are installed in your system (OGLHOME environment variable; at SLAC OGLHOME must be set to the default area $BFROOT/package/Mesa/Mesa-2.4/$BFARCH).
Set $G4SYSTEM appropriately for your system in your login (AIX-xlC, DEC-cxx, SUN-CC or HP-aCC). See architecture.gmk in geant4/config for the options. For your selected option, make sure the environment variables set up in that script are appropriate. Customize if necessary and tell me how you've had to customize it.
Build all Geant4 libraries! Type 'gmake global' from the geant4/source directory.
For more details on the installation procedure of Geant4, please refer to the installation guide in the official user documentation of the toolkit.
Make an SRT test release directory for a recent release (8.1.X for BB00-01 distribution of Geant4, i.e.: newrel -t 8.1.23 mytestrel). If you don't know what this means and/or don't know how to set one up, read the BaBar Users Guide on the Computing page.
Go to your SRT directory and do 'addpkg geant4' (not needed if using Geant4 libraries installation at SLAC).
(Optional) - depending on the graphics systems installed locally and on the graphics drivers built in the Geant4 visualization library (G4VIS_BUILD_xxx_DRIVER flags), set the correspondent G4VIS_USE_xxx flag to build a graphical version of Bogus. In case the OpenGL or OpenGLX driver is used, also OGLHOME must be defined to point to the area where the graphics libraries are installed ($BFROOT/package/Mesa/Mesa-2.4/$BFARCH at SLAC).
From your SRT directory, do 'addpkg Bogus ; gmake cold' will build the Bogus library and the standalone Bogus application.
!! Note !! - Whenever a change/update to external packages like Geant4, RW-Tools.h++ or CLHEP is made, it is necessary to rebuild Bogus and ALL related subsystem packages (including rebuilding of G4 headers through the 'geant4' package and the related $G4INSTALL variable). A change to CLHEP or RW-Tools.h++ might also require to rebuild all Geant4 libraries !
!! Note !! - If you are using the default Geant4 libraries installed for a release, you DO NOT need to have ANY of the G4 environment variables defined in your environment, except for those which specify the kind of graphics system you want to use (i.e. G4VIS_USE_xxx variables and OGLHOME).

5. Running Bogus standalone

The standalone application which can be built from the Bogus package uses the official Geant4 run manager to control runs and event generation and is completely independent from the BaBar Framework.
bgsControl.db is the run-control file used to select the geometry-model for each subdetector, the kind of magnetic-field, the kind of primary generator, the number of events to generate in a run, verbosity level, etc.. It is placed in the top-level directory in the Bogus package.
The geometry models are selected by choosing in the run-control file one of the available identifiers for each subsystem, according to the kind of simulation (fast or detailed). A subsystem can be totally excluded by specifying "none" as model for it or by not specifying any identifier. Models designed for fast simulation cannot be mixed together with models designed for full simulation and viceversa.
Bogus standalone offers the possibility to run Geant4 as a single-particle gun (Geant4 itself is used as primary generator), or by reading an stdhep ASCII file of generated primaries and instruct Geant4 to skip the primary-generation step. This modality is selected by choosing the appropriate value in bgsControl.db for the variable evtGen: "gun" or "hepevt" (default is "gun"). In case of "gun", the user must specify also the kind of primary particle, initial position, energy and direction. In case of "hepevt", the name of the ASCII file containing the generated primaries must be specified (the default is "Bogen.out"); the file must be placed in the current directory from where Bogus is run.
Bogus standalone must be run from workdir, assuming that your SRT configuration is correctly set up. Before running Bogus you must have your local database loaded properly (i.e. "database.import" done) and invoke two commands in order to correctly setup your environment and load your database for the PEP and IFR subsystems (the loading will be performed by default as soon as the schemas for the PEP and IFR geometries will be well established); i.e., from your test release or workdir:
      > setboot
      > PepSimGeomP
      > IfrSimGeomP
The former one should be done at every new login session; the latter two just once after your first "database.load", at the prompt (if requested) type: "ev begin -nev 1".
If not specified otherwise, the default control file bgsControl.db placed in the top-level directory of the Bogus package is parsed (this will start a batch test-simulation of 10 events - geantinos - on default detector models and parameters).
The control-file can either be given as argument to Bogus:
 i.e.
      > Bogus bgsControl.db
or placed in workdir from where Bogus is invoked and named as bogusrun.db. You then simply invoke Bogus:
 i.e.
      > cp $YOUR_TESTREL_DIR/Bogus/bgsControl.db bogusrun.db
      ... edit bogusrun.db and customize parameters
      > Bogus
By default Bogus is set to run in batch-mode. The interact flag is used to select the run mode, if batch or interactive. In case of interactive-mode the run control is left to the user and the default Geant4 shell is invoked. By typing "help", the directory of available commands is printed; choose the command number to view its related help screen. Commands can also be given by invoking a predefined macro-file. Refer to the Geant4 User Manual for a detailed description on how to use the Geant UI manager and how to visualize detector and events by using the built-in graphics systems.
The control parameters saveStatus, restoreStatus and engineFile are used to tell Bogus if save or restore the Random engine status at every event, in order to reproduce the last generated event.

6. Bogus in the BaBar Framework

Running the Framework application for Bogus means having the run-control and event generation controlled by the BaBar Framework. In this context AbsEvent objects are produced and generated one by one.
The SRT package BgsFwkModule implements a set of Framework modules which act as the main steering agents piloting the Bogus/G4 simulation in the BaBar Framework. (see category diagram) and also treat G4Event objects produced by simulation as AbsEvent.
In the full simulation, the format of the produced event is assured to be consistent to that expected by reconstruction. In this case, the GHits conversion is performed by specialized modules in the downstream framework packages: TrkBgsModules, DrcBgsModules, EmcBgsModules, IfrBgsModules; the former one includes PEP, DCH and SVT subsystems).
These are the basic services provided by BgsFwkModule:

Interface MC generators with Geant4, passing primary particle's data from AbsEvent/StdHep to Geant4 primaries. The interface is realized by properly selecting the generator provided in the GenFwkInt package.
Call appropriate Geant4 services to generate ONE event.
Integrate the generated event back to the AbsEvent.
Produce MC truth information and store it in AbsEvent.
The downstream Framework packages cited above includes Framework modules needed for the Fast Simulation to build directly reco-like objects (i.e. performing charged track smearing, energy and position resolutions, fast 3D clustering, etc.) ready to be analyzed out of the raw simulated events produced in BgsFwkModule. These packages also include a specialized module for full simulation to convert simulated G4 collections of hits to lists of GHits, separated for each subsystem.
To achieve these functionalities, an ad-hoc run manager is implemented in BgsFwkModule, together with specialized user stepping, tracking and generator actions, as well as detector setup description. Setup parameters (subsystem geometry model, magnetic field settings, verbosity level in Bogus) are fetched through the Framework Tcl interface and stored in a file bogus.tcl currently placed in workdir.
Geometry models for each subdetector are selected by choosing in bogus.tcl one of the available identifiers, according to the kind of simulation (fast or detailed). A subsystem can be totally excluded by specifying "none" as model for it or by not specifying any identifier. Models designed for fast simulation cannot be mixed together with models designed for full simulation and viceversa.

7. Running Bogus in the BaBar Framework: BgsSequences

The BgsSequences package contains all Framework sequences and TCL scripts to control different simulation runs. The main Framework application BgsApp is also built from this package.
BgsSequences includes 6 set of files implementing 6 different sequences, each one providing an APPSequence class and a Tcl script to control it (parameters related to modules belonging to a specific sequence must be handled within their corresponding Tcl script!):

BgsInitSequence
It provides the "standard" set of modules initializing the environment of a Bogus Framework user application. It should generally be invoked before the user's own modules. It is NOT intended to contain various service modules, including PrintModule, DispModule, and regression tests.
Modules added in this sequence typically are: BfmInputModule (the input module for Bogus), GenBuildEnv, HbkTupleEnv, PdtInit and subsystem init sequences. BgsGenSequence is also invoked here.
BgsGenSequence
Utility sequence containing the "standard" set of modules for invoking MC generators provided in the GenFwkInt package. It should generally be invoked before every subsystem module. The control of the primary generators should be handled within the corresponding Tcl script BgsGenSequence.tcl. For information on how to control generators (i.e. - selecting the kind of generator, primary particle energy, direction, etc.), see the documentation for GenFwkInt, also available from the BaBar Offline Workbook)
BgsFastSequence
It consists of a set of modules needed for performing Fast Simulation. It is NOT intended to contain various service modules, including PrintModule, DispModule, and regression tests.
In this sequence are added all the downstream modules which perform the conversion of the simulated events into "reco-like" objects. Usage of this sequence is exclusive, it has NOT to be invoked together with BgsFullSequence.
BgsFullSequence
It consists of a set of modules needed for performing Full (Detailed) Simulation. It is NOT intended to contain various service modules, including PrintModule, DispModule, and regression tests.
Modules included in this sequence are essentially devoted to shuffle the collection of (full) hits (GHits) into lists, one for each subsystem, as expected by the Reconstruction. Events generated after this step are ready to be made persistent. Usage of this sequence is exclusive, it has NOT to be invoked together with BgsFastSequence.
BgsBetaSequence
Utility sequence which include the set of modules to setup Beta for basic analysis. It is NOT intended to contain various service modules, including PrintModule, DispModule, and regression tests. Those can be added if desired.
BgsUtilSequence
It consists of a set of utility modules for both Fast and Full Simulation. This sequence is meant to contain all various kind of service modules also subsystem specific.
BgsSequences includes also a Tcl script (BgsRandControl.tcl) to control the random number generation at different stages. See also documentation in the RandControl package itself and in GenFwkInt.
Before running the Framework application you must have your local database loaded properly (i.e. "database.import" done) and invoke two commands in order to correctly setup your environment and load your database for the PEP and IFR subsystems (the loading will be performed by default as soon as the schemas for the PEP and IFR geometries will be well established); i.e., from your test release or workdir:
      > setboot
      > PepSimGeomP
      > IfrSimGeomP
The former one should be done at every new login session; the latter two just once after your first "database.load", at the prompt (if requested) type: "ev begin -nev 1".
The main Tcl script to feed to the BgsApp Framework application is BgsApp.tcl, i.e. from workdir:
   BgsApp RELEASE/BgsSequences/BgsApp.tcl
The execution order of each sequence/module for the event(AbsEvent*) function call is determined in this script. These are the parameters and selections the user can customize through the main script (also selectable interactively from the Tcl prompt):

The kind of primary generator (currently "SingleParticle" or "EvtGen"). In case of "SingleParticle" the kind of primary particle has to be specified (particle identifiers are listed in PDT/pdt.table).
The G4 run-mode, batch or interactive (interact control flag). If the flag is set to 1, the interactive mode in Geant4 is activated and there's the possibility to invoke the Geant4 interactive shell by invoking the "g4" command from the Tcl prompt.
Due to possible syntax conflicts in the Tcl and G4 native shells, we however discourage to run the Framework application with G4 interactive mode ON. If you need interactivity and graphics in Geant4, try using the Bogus standalone application instead.
Disable modules or sequences (all activated by default), by explicitly doing this in the proper section of the script.
Set/unset verbose mode in Bogus.
Set run number and run's event number.
Selection of the geometry model for each subsystem, Bogus verbosity level or magnetic field setup can be controlled at initialization time only (i.e. not interactively at run-time) in the bogus.tcl script placed in workdir.
The lowest level of verbosity is selected by default both in Bogus and Framework modules.

8. Running Bogus as a Beta application in the Framework

Bogus in the Framework can also be run as a Beta application (reproducing in principle the same behavior of BgsApp with the same setup).
These are the steps one should follow in the current 8.1.X setup for Beta:
Add your analysis modules to the AppUserBuild.cc in BetaUser
Set the following environment variables:
      setenv BetaBogus yes
      setenv BetaSim no
      setenv BetaReco no
      setenv BetaBdb no
      setenv BetaAslund no
    
Add your analysis modules to the sequence in BetaUser/myAnalysis.tcl
Build libraries and BetaApp
From workdir (if not already done in your test release federation), run PepSimGeomP and IfrSimGeomP to load the geometry parameters of PEP and IFR.
Run BetaApp from workdir:
      BetaApp ../BetaUser/fbogus.tcl
    
At the current time no Geant4 visualization capabilities are possible when running Bogus as a Beta application, therefore when building the BetaUser module all environment variables G4VIS_USE_XXX must be unset in the user environment.
For more details on how to run a Beta analysis job, refer to the BaBar Offline Workbook.

9. Geant4 tools

Two visualization tools for Geant4 are available ad can be used also from Bogus:

DAWN Fukui Renderer (Drawer for Academic WritiNgs)
DAVID (DAwn's Visual Intersection Debugger)
DAVID is a tool useful to intercept polygon intersections of Geant4 physical volumes in a given detector geometry. It produces and analyses a postcript file by means of the DAWN graphics tool (one of the graphics drivers available in Geant4). The ouput is a postcript file automatically displayed with ghostview, where overlapping volumes in the detector geometry are displayed in red. It also produces a log file containing all the details.
Both tools are currently installed at SLAC for plaforms AIX, OSF and SUN:

$BFROOT/simu/g4apps/DAVID
$BFROOT/simu/g4apps/DAWN
Binaries are installed in $BFROOT/simu/g4apps/bin/$BFARCH. Archived sources and scripts are available in $BFROOT/simu/g4apps/archive.
A README file is included in each package with details about local installations and general usage.
Here is a short guide on how to use DAVID with Bogus:
Geant4 BB00-02 with the DAWN graphics driver installed (already installed at SLAC)
Build Bogus with these environment variables set:
     G4VIS_USE_DAWN = 1
     G4VIS_USE_DAWNFILE = 1
     G4DAWNFILE_VIEWER = david
     
Extend your environment $PATH to include the path where DAWN and DAVID are installed (i.e. $BFROOT/simu/g4apps/bin/$BFARCH at SLAC)
Run Bogus and select DAWNFILE as the possible graphics system choice.
i.e. at the G4 prompt:
     Idle >  /vis/create_view/new_graphics_system DAWNFILE
     Idle >  /vis/refresh/view
     

10. Geant4 physics data

An archive of data for hadronic processes (PhotonEvaporation) is available in $BFROOT/simu/geant4/BB00-02: data.tar.gz. The uncompressed directory data/ should be placed within geant4/ as the default. Data will be used at run-time by some hadronic processes. If placed in a different place, an environment variable $G4DATA must be defined to specify the exact path where data/ is placed (the default being $G4INSTALL/data).
More detailed instructions can be found in the Geant4 User Manual.