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
Materials
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 git@pandax.physics.sjtu.edu.cn:software/BambooMC.git
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.
BambooMC
├── BambooMC.cc
├── CMakeLists.txt
├── detectors/
├── include/
├── macro/
├── README
├── scripts/
├── src/
├── test/
├── xml/
The BambooMC.cc 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.
Compilation
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 ..
make
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 "create_class.pl"
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/create_class.pl 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 "enable_detector.sh" script to enable it in the source tree.
The scripts of "enable_detector.sh" and "disable_detector.sh"
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:
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
Some texts are taken from
this slides.
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