You are here: Foswiki>Main Web>BambooMC (2018-04-12, XunChen)Edit Attach

BambooMC for everyone

The BambooMC is a GEANT4 based program developed for the simulation of PandaX experiment. It can also be used in other experiments.

Design Philosophy

The BambooMC is designed to be a modularized simulation program based on GEANT4 that enables users to combine different detector components, physics processes and data managers freely. That would be very effective for the optimization of particle detectors.

The user need to tell the program which components will be used in the simulation with an XML file. An example of the XML file is given below:

A root node of "BambooMC" need to be declared in the file. The root node have 4 types of children nodes: run, geometry, generator and analysis. Run number can be set as a parameter of the "run" node. The type of generator and analysis modules can be set in the "generator" and "analysis" node. The node of geometry is of most complex. It has children nodes of "parameter" and "detector". The "parameter" nodes in "geometry" define the global parameters for detector construction. Each detector node defines a detector components need to be simulated with the specified parameters.

BambooMC for Users

How to run the executable

The default format to run the executable of BambooMC from command line is

${path_to_bamboomc}/BambooMC -x xml_file [ -m macro_file ] [ -n nevents ] [ -o output_file ] [ -i ]

The xml_file gives the definition of the detectors, event generator and physics used for the simulation. It is necessary for a simulation. Other paramters are optional. The macro file uses the default G4macro format and can used to define some parameters in the simulation. The "-n" parameter defines how many events (nevents) will be simulated. The "-o" parameter defines the name of the output file. The "-i" option will make the program runs in interactive mode. Following gives a summary of these parameter.
  • -x: gives the xml file,
  • -f: gives the macro file, same as "-m"
  • -m: gives the macro file, same as "-f"
  • -n: gives the number of events to be simulated
  • -o: gives the output parameter
  • -i: program runs in interactvie mode

The construction of a detector


You can specify the materials used in your own detector part, or just the materials provided by a Material class. The latter case is highly recommended, and a "material" node need to be specified in the xml file. A list of available materials is given in the page of BambooMCAvailableMaterials.

The detector hierachy

In the xml file, one need to define the hierachy of different detector part. That is done with the definiton of the "parent" property for node "detector". A detector part should have only one parent or have no parent. The part without parent is treated as the "world" volume of the detector. So only one detector part in the xml can have no parent.

Detector parameters

Avalible detector parts

A list of available detector part is given in the BambooMCAvailableDetectorParts.

Physics definition

The "physics" node in the xml specifies the physics class used in the simulation. Only one physics class can be specified. A list of available physics classes can be found in the BambooMCAvailablePhysics.

Generator definition

The "generator" node in the xml specifies the primary event generator used in the simulation. Only one generator can be specified. A list of available generators can be found in the BambooMCAvailableGenerators.

Selection of Analysis

The "analysis" node in the xml specifies the Analysis class, which is mainly responsible for the output of simulation, used in the simulation. A list of available analysis classes can be found in the page of BambooMCAvailableAnalysis.

Collection of xml files and macro files for users

You can find the collection of xml files and macros files in the page of BambooMCXmlAndMacro.

BambooMC for Developers

The information in this page is pretty old now. Please refer to BuildBambooMCNew for the "factory" branch and all branches derived from it.

Get the source

You can get the source code from our git system:

git clone

Currently we are working on the "pandax_ii" branch. Some features are not merged into the "master" branch.

The " factory " branch contains new features. Please try to use it.

The Structure of the source code

You can find following files/directories in the source directory.

├── CMakeLists.txt
├── detectors/
├── include/
├── macro/
├── scripts/
├── src/
├── test/
├── xml/

The defines the main function of the program. The "src" and "include" directories contain the source and header files to be built. The "detectors" directory gives the sources of detector parts grouped in categories (each sub directory in this directory defines a category.) The "xml" directory gives the sample XML files. The "macro" directory gives some examples of macro files in simulation.

The definitions of the detectors are splitted out from the main source tree into the "detector" directory. They will not be compiled by default unless they are copied into the main source tree. Some scripts are used to do the jobs of enabling the detectors and disabling them. Please see this section for more details.


The software depends on both GEANT4.9.6 and Qt4. We have tested it on Debian jessie (with Qt4.8) and Scientific Linux 6.5 (with Qt4.6). To build it, cmake (>2.6) is required. Assuming you have get into the top level of the source tree, you can invoke following commands to build it

mkdir build
cd build
cmake ..

Please make sure that you have already set the environment variables of GEANT4 by source the script provided by GEANT4.

The scripts

There is a directory called "scripts" inside the source tree. You can find some perl and shell scripts inside it. They are used to help you create new classes easily.

The scripts ""

This script is used to create a class for a detector/material/physics/analysis. For example, if you want to create a new detector part with the name of "StainlessSteelBox", you can do as follows:

./scripts/ detector StainlessSteelBox

Then you can get a source file and a header file with the necessary components. You can work on the files, add more variables and your own construction codes. After that, you can copy the file to a sub directory of "detector" and invoke the "" script to enable it in the source tree.

The scripts of "" and ""

The two scripts are used to enable or disable a set of detector parts defined in the "detector" directory. The argument for the scripts is the name of the directory you want to disable/enable. Following are some examples:

  • To enable the detector for pandax_ii
    ./scripts/ pandax_ii
  • To disable the detector for pandax_ii
    ./scripts/ pandax_ii

Factory Method and serveral base classes

The program defines serveral base classes for the description of detector, material, physics, generator and analysis. They are

class BambooDetectorPart;
class BambooMaterial;
class BambooAnalysis;
class BambooGenerator;
class BambooPhysics;

BambooMC for PandaX

BambooMC for PandaX-II

BambooMC for PandaX-II

BambooMC for PandaX-III

BambooMC for PandaX-III

Draft Note

Obtain information in Geant4

Some texts are taken from this slides.

Extract useful information

Given geometry, physics and primary track generation, Geant4 does proper physics simulation “silently”. You have to add a bit of code to extract information useful to you.

There are two ways:
  • Use user hooks (G4UserTrackingAction, G4UserSteppingAction, etc.) You have full access to almost all information Straight-forward, but do-it-yourself
  • Use Geant4 scoring functionality
    • Assign G4VSensitiveDetector to a volume
    • Hit is a snapshot of the physical interaction of a track or an accumulation of interactions of tracks in the sensitive (or interested) part of your detector.
    • Hits collection is automatically stored in G4Event object, and automatically accumulated if user-defined Run object is used.
    • Use user hooks (G4UserEventAction, G4UserRunAction) to get event/run summary

Data output in Geant4

To obtain information in the simulation, several classes are required.
  • data manager (optional)
  • subclass of G4UserRunAction
  • definition of hit
  • definition of sensitive detector
The data manager is a convenient class for the data output. It can be used to create the output data file, define the internal structure of the data (such as the Tree used in ROOT.) It will provide APIs to the user derived G4UserRunAction class.

The user derived subclass of G4UserRunAction class has two important virtual functions to be implemented: the BeginOfRunAction(const G4Run *) and the EndOfRunAction(const G4Run *) . As indicated by their name, these functions will be called at the start of the run or the end of the run. An object of the data manager class can be a data member of this class and the related APIs could be visited at proper time.

Reference from GEANT4 documentation

About the G4EventManager

G4EventManager is the manager class to take care of one event. It is responsible for:
  • converting G4PrimaryVertex and G4PrimaryParticle objects associated with the current G4Event object to G4Track objects. All of G4Track objects representing the primary particles are sent to G4StackManager.
  • Pop one G4Track object from G4StackManager and send it to G4TrackingManager. The current G4Track object is deleted by G4EventManager after the track is simulated by G4TrackingManager, if the track is marked as "killed".
  • In case the primary track is "suspended" or "postponed to next event" by G4TrackingManager, it is sent back to the G4StackManager. Secondary G4Track objects returned by G4TrackingManager are also sent to G4StackManager.
  • When G4StackManager returns NULL for the "pop" request, G4EventManager terminates the current processing event.
  • invokes the user-defined methods beginOfEventAction() and endOfEventAction() from the G4UserEventAction class.
-- XunChen - 08 Oct 2014
Topic attachments
I Attachment Action Size Date Who Comment
scoring.pdfpdf scoring.pdf manage 787 K 2015-04-06 - 11:21 XunChen Geant4 Scoring
Topic revision: r16 - 2018-04-12, XunChen - This page was cached on 2020-07-18 - 03:52.

This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback