Other generator/introduction

Table Of Contents

Previous topic

Kinematic Generators

Next topic


This Page

Daya Bay Links

Content Skeleton


Generators provide the initial kinematics of events to be further simulated. They must provide a 4-position, 4-momentum and a particle type for every particle to be tracked through the detector simulation. They may supply additional “information” particles that are otherwise ignored. The incoming neutrino or radioactive decay parent are two examples of such particles.

Generator output

Each generated event is placed in the event store at the default location /Event/Gen/GenHeader but when multiple generators are active in a single job they will place their data in other locations under /Event/Gen.

The data model for this object is in DataModel/GenEvent. The GenHeader object is simply a thin wrapper that holds a pointer to a HepMC::GenEvent object. See HepMC documentation for necessary details on using this and related objects.

Generator Tools

A GenEvent is built from one or more special Gaudi Tools called GenTools. Each GenTool is responsible for constructing part of the kinematic information and multiple tools work in concert to produce a fully described event. This lets the user easily swap in different tools to get different results.

Generator Packages

There are a number of packages providing GenTools. The primary package is called GenTools and provides basic tools as well as the GtGenerator algorithm that ties the tools together. Every execution cycle the algorithm will run through its tools, in order, and place the resulting event in the event data store. A separate package, GenDecay, provides GenTools that will produce kinematics for various radioactive nuclear decays.

The GtGenerator is suitable only for “linear” jobs that only simulate a single type of event. In order to mix multiple events together the, so called, Fifteen suite of packages (see Ch fifteen) are used. To configure for this type of job the Gnrt package’s Configure is used.

Types of GenTools

The available GenTools and a sample of their properties are given. You can query their full properties with properties.py ToolName.

GenTools package

provides a local vertex 3-position. It does it by placing the vertex at its given point or distributing it about its given volume in various ways.
provides global vertex 3-position and 3-direction given local ones. This will take existing an position and direction, interpret them as being defined in the given volume and transform them into global coordinates (needed for further simulation). It can optionally transform only position or direction.
provides a vertex time. Based on a given lifetime (rate) it can distribute times exponentially or uniformly. It can also set the time in an “Absolut” (spelling intentional) or Relative manner. The former will set the time unconditionally and the latter will add the generated time to any existing value.
provides a local 4-momentum. It simulates a virtual particle “gun” that will shoot a given particle type in various ways. It can be set to point in a given direction or spray particles in a few patterns. It can select a fixed or distributed momentum.
provides a global 3-vertex and a global 4-momentum. It produces a parallel beam of circular cross section pointed at some detector element and starting from a given direction and distance away.
provides a relative 3-vertex and local 4-momentum. It simulates the diffuser balls used in calibration. Subsequent positioner and transform tools are needed to place it at some non origin position relative to an actual volume.
provides a local 4-momentum. It is used to read in kinematics in HepEVT format either from a file or through a pipe from a running executable. Depending on the HepEVT source it may need to be followed by positioner, timerator or transform tools.

GenDecay Package

The GenDecay package simulation radioactive decay of nuclei. It relies on Evaluated Nuclear Structure Data File (ENSDF) data sets maintained by National Nuclear Data Center (NNDC) located at BNL. It is fully data driven in that all information on branching fractions, half lifes and radiation type are taken from the ENSDF data sets. GenDecay will set up a hierarchy of mothers and daughters connected by a decay radiation. When it is asked to perform a decay, it does so by walking this hierarchy and randomly selecting branches to follow. It will apply a correlation time to the lifetime of every daughter state to determine if it should force that state to decay along with its mother. The abundances of all uncorrelated nuclear states must be specified by the user.

The GenDecay package provides a single tool called GtDecayerator which provides a local 4-vertex and 4-momentum for all products. It should be followed up by positioner and transformer tools.


General configuration is described in Ch Offline Framework. The GenTools and related packages follow these conventions. This section goes from low level to high level configuration.


As described above, a GtGenerator algorithm is used to collect. It is configured with the following properties

sets an absolute starting time in integral number of seconds. Note, the unit is implicit, do not multiple by seconds from the system of units.
sets the ordered list of tools to apply.
sets a label for this generator.
sets where in the event store to place the results.

Each tool is configured with its own, specific properties. For the most up to date documentation on them, use the properties.py tool. Common or important properties are described:

names a volume, specifically a Detector Element, in the geometry. The name is of the form “/dd/Structure/Detector/SomElement”.
sets a local position, relative to a volume’s coordinate system.
alone or as a modifier is used to specify some distribution width.
Strategy or Mode
alone or as a modifier is used to modify some behavior of the tool.

GenDecay Configurables

The GenDecay package provides a GtDecayerator tool which has the following properties.

names the nuclide that begins the decay chain of interest. It can use any libmore supported form such as “U-238” or “238U” and is case insensitive.
the abundance of this nuclide, that is, the number of nuclides of this type.
a map of abundances for all nuclides that are found in the chain starting at, and including, the parent. If the parent is listed and ParentAbundance is set the latter takes precedence.
If true (default), set abundances of uncorrelated daughter nuclides (see CorrelationTime property) to be in secular equilibrium with the parent. If any values are given by the AbundanceMap property, they will take precedence.
Any nuclide in the chain that has a decay branch with a half life (total nuclide halflife * branching fraction) shorter than this correlation time will be considered correlated with the parent(s) that produced it and the resulting kinematics will include both parent and child decays together and with a time chosen based on the parent abundance. Otherwise, the decay of the nuclide is considered dependent from its parent and will decay based on its own abundance.


The GenTools package’s Configure object will take care of setting up a GtGenerator and adding it to the list of “top algorithms”. The Configure object requires a “helper” object to provide the tools.

There are several helpers provided by GenTools and one provided by GenDecay that cover most requirements. If a job must be configured in a way that no helper provides, then a new helper can be written using the existing ones as examples. The only requirement is that a helper object provides a tools() method that returns a list of the tools to add to a GtGenerator algorithm.

Each helper described below takes a number of arguments in its constructor. They are given default values so a default helper can be constructed to properly set up the job to do something, but it may not be what you want. After construction the objects are available as object members taking the same name as the argument.

Helpers are self documented and the best way to read this is using the pydoc program which takes the full Python name. For example:

shell> pydoc GenTools.Helpers.Gun
Help on class Gun in GenTools.Helpers:

GenTools.Helpers.Gun = class Gun
 |  Configure a particle gun based kinematics
 |  Methods defined here:
 |  __init__(....)

Remember that __init__() is the constructor in Python.

The rest of this section gives the full Python name and a general description of the available helpers. Again, use pydoc to see the reference information.

takes a volume and a gun, positioner, timerator and a transformer to set up a GtGunGenTool based generator.
as above but sets up a diffuser ball. It also takes an AutoPositionerTool to modify the location of the diffuser ball in the geometry.
takes a source of HepEVT formatted data and positioner, timerator and transformer tools.
takes a volume and decayerator, positioner and timerator tools.

Gnrtr.Configure and its Stages

Currently, the, so called, “pull mode” or “Fifteen style” of mixing of different types of events configuration mechanisms need work.

GenTools Dumper Algorithm

The GenTools package provides an algorithm to dump the contents of the generator output to the log. It can be included in the job by creating an instance of the GenTools.Dumper class. The algorithm can be accessed through the resulting object via its .dumper member. From that you can set the properties:

in the event store to find the kinematics to dump.
set to True to use the dumper that HepMC provides. By default it will use one implemented in the algorithm.

GenTools Job Option Modules

The GenTools package provides a GenTools.Test Job Option Module which gives command line access to some of the helpers. It is used in its unit test “test_gentools.py”. It takes various command line options of its own which can be displayed via:

shell> nuwa.py -m 'GenTools.Test --help'
Importing modules GenTools.Test [ --help ]
Trying to call configure() on GenTools.Test
This module can be used from nuwa.py to run GenTools in a few canned way as a test.

It is run as a unit test in GenTools/tests/test_gentools.py

  -h, --help            show this help message and exit
  -a HELPER, --helper=HELPER
                        Define a "helper" to help set up GenTools is gun,
                        diffuser or hepevt.
  -v VOLUME, --volume=VOLUME
                        Define a volume to focus on.
  -s DATA_SOURCE, --data-source=DATA_SOURCE
                        Define the data source to use for HepEVT helper