This page is obsolete and no longer maintained.

The new address for the Gauss/Generator web site is:

http://cern.ch/LHCb-release-area/DOC/gauss/generator

The first phase of the Gauss simulation software consists in generating pp collisions and the decay of unstable particles. The generator events are then given to the simulation phase where they are tracked inside the detector volumes. Interfacing a new external generator to Gauss usually means to write a new Production tool.

General Structure

The generator sequence uses one main algorithm Generation calling several tools to perform specific actions needed during the generation of events. Generally, the logic of the generation sequence is the following:

1. Compute the number of pile-up interactions to generate for this event (done with a Pile-Up tool)
2. Generate this many interactions:
   1. Compute the beam parameters for this interaction (done with a Beam tool)
   2. Generate an interaction according to these parameters with an external generator (done with a Production tool)
3. Analyze the event:
1. Keep only events with the interesting particles (done in a Sample Generation tool)
2. Apply generator level cuts for this interaction (done in a Cut tool)
4. Decay all particles (done in a Decay tool)
5. Apply generator level cuts on the full event, including pile-up interactions (done in a Full Event Cut tool)
6. Smear the vertex of the collision (done in a Smearing tool)

The locations where the various tools are executed are:

• Generation calls:
• Pile-Up tool.
• Sample Generation tool, which calls:
• Production tool, which calls:
• Beam tool
• Decay tool (optionally)
• Cut tool
• Decay tool
• Full Event Cut tool
• Smearing tool

The main algorithm and the abstract interfaces of these tools are located in the package Gen/Generators.

At the end of the Gauss job, various counters are printed to compute cross-sections, efficiencies and to monitor the generation behaviour. They are described in more details here.

Main Algorithm

The main algorithm is called Generation. It has the following options which can be set to obtain different configurations:

Pile-Up Tool

Abstract Interface: IPileUpTool.h

Available Implementations:

• FixedLuminosity : uses a fixed luminosity value to determine the number of pile-up events.

Option Name	Default Value	Description
Luminosity	2.e32/cm2/s	Value of the instantaneous luminosity.
CrossingRate	30*megahertz	Visible beam crossing rate.
TotalXSection	102.4*millibarn	Total cross section.

• VariableLuminosity : uses a exponentially decreasing luminosity to determine the number of pile-up events.

Option Name	Default Value	Description
Luminosity	2.e32/cm2/s	Value of the instantaneous luminosity.
CrossingRate	30*megahertz	Visible beam crossing rate.
TotalXSection	102.4*millibarn	Total cross section.
FillDuration	7*3600*s	Duration of the fill.
BeamDecayTime	10*3600*s	Beam decay time.

• FixedNInteractions : generates always the same number of pile-up per event.

Option Name	Default Value	Description
NInteractions	1	Number of interactions per event

How to write a new Pile-Up Tool 

Write a tool inheriting from the base class IPileUpTool and which overloads the 2 mandatory virtual functions:

• unsigned int numberOfPileUp( double & currentLuminosity ) returning the number of pile-up interactions to generate. An estimate of the current (instantaneous) luminosity must also be returned to be saved together with the event in the GenHeader event model class. This will allow to generate correctly spill-over events.
• void printPileUpCounters( ) which will print monitoring counters at the end of the Gauss job. Here should be printed the number of generated interactions (and also the number of events containing 0 interaction).

Sample Generation Tool

Abstract Interface: ISampleGenerationTool.h

Available Implementations:

• MinimumBias: generates events with pile-up, without any generator level cuts, simply calling the Production Tool.

Option Name	Default Value	Description
ProductionTool	PythiaProduction	Name of the Production tool to use to generate interactions.
DecayTool	EvtGenDecay	Name of the Decay tool to use.
LhaPdfCommands	"lhacontrol lhaparm 17 LHAPDF", "lhacontrol lhaparm 16 NOSTAT"	Commands to setup LHAPDF library.

• Inclusive: generates events calling the Production Tool with minimum bias pile-up, keeps only events with PDG Id specified in a list (after having decayed with a Decay Tool all unstable particles heavier than the ones specified in the list) and apply on them generator level cuts implemented in a Cut Tool.

Option Name	Default Value	Description
ProductionTool	PythiaProduction	Name of the Production Tool to use to generate interactions.
DecayTool	EvtGenDecay	Name of the Decay tool to use to decay excited states.
CutTool	LHCbAcceptance	Name of the Cut tool to apply on the main interaction.
LhaPdfCommands	"lhacontrol lhaparm 17 LHAPDF", "lhacontrol lhaparm 16 NOSTAT"	Commands to setup LHAPDF library.
InclusivePIDList		List of PDG IDs of particles to produce inclusively.

• SignalPlain: generates events calling the Production tool with minimum bias pile-up, keeps only events with signal PDG Id specified in a list (after having decayed with a Decay Tool all unstable particles heavier than the signal), force the decay of the signal particle to the signal decay mode using the Decay Tool and apply on the interaction generator level cuts implemented in the Cut tool.

Option Name	Default Value	Description
ProductionTool	PythiaProduction	Name of the Production Tool to use to generate interactions.
DecayTool	EvtGenDecay	Name of the Decay tool to use to decay excited states.
CutTool	LHCbAcceptance	Name of the Cut tool to apply on the main interaction.
LhaPdfCommands	"lhacontrol lhaparm 17 LHAPDF", "lhacontrol lhaparm 16 NOSTAT"	Commands to setup LHAPDF library.
SignalPIDList		List of PDG IDs of particles to produce inclusively.
Clean	false	Generates clean events putting the clean event in .

• SignalForcedFragmentation: same than SignalPlain but uses forced fragmentation to obtain quickly the signal particle.

Option Name	Default Value	Description
ProductionTool	PythiaProduction	Name of the Production Tool to use to generate interactions.
DecayTool	EvtGenDecay	Name of the Decay tool to use to decay excited states.
CutTool	LHCbAcceptance	Name of the Cut tool to apply on the main interaction.
LhaPdfCommands	"lhacontrol lhaparm 17 LHAPDF", "lhacontrol lhaparm 16 NOSTAT"	Commands to setup LHAPDF library.
SignalPIDList		List of PDG IDs of particles to produce inclusively.
Clean	false	Generates clean events putting the clean event in .

• SignalRepeatedHadronization: same than SignalPlain but uses repeated hadronization to obtain quickly the signal particle.

Option Name	Default Value	Description
ProductionTool	PythiaProduction	Name of the Production Tool to use to generate interactions.
DecayTool	EvtGenDecay	Name of the Decay tool to use to decay excited states.
CutTool	LHCbAcceptance	Name of the Cut tool to apply on the main interaction.
LhaPdfCommands	"lhacontrol lhaparm 17 LHAPDF", "lhacontrol lhaparm 16 NOSTAT"	Commands to setup LHAPDF library.
SignalPIDList		List of PDG IDs of particles to produce inclusively.
Clean	False	Generates clean events putting the clean event in .
MaxNumberOfRepetitions	500	Maximum number of times the hadronization can be repeated before cancelling the event.

• Special: simple implementation only generating one interaction (without pile-up), calling the Production Tool and applying generator level cuts using the Cut tool. This tool should be used to test a new generator, to call a special generator or to use a generator with special settings modifying the minimum bias definition.

Option Name	Default Value	Description
ProductionTool	PythiaProduction	Name of the Production Tool to use to generate interactions.
DecayTool	EvtGenDecay	Name of the Decay tool to use to decay excited states.
CutTool	LHCbAcceptance	Name of the Cut tool to apply on the main interaction.
LhaPdfCommands	"lhacontrol lhaparm 17 LHAPDF", "lhacontrol lhaparm 16 NOSTAT"	Commands to setup LHAPDF library.

How to write a new Sample Generation Tool 

The provided sample generation tools should already cover all needs.

Production Tool

Abstract Interface: IProductionTool.h

Available Implementations:

• PythiaProduction: generates events with PYTHIA.

Option Name	Default Value	Description
Commands	Settings for standard minimum bias	List of commands to setup PYTHIA.
BeamToolName	"CollidingBeams"	Name of the Beam tool used to generate beam parameters.

• HerwigProduction: generates events with HERWIG.

How to write a new Production Tool 

To interface a new external generator (for example MyGen) to Gauss, a new production tool must be written together with additional pieces of code to setup the external generator or to modify its behaviour. All these parts should be placed in a new cmt package called Gen/LbMyGen, depending on the base package Gen/Generators. In particular, it is important to use inside the external generator the same random number generator than the one used in Gauss (and based on the Gaudi Random Generator Service), in order to ensure a reproducible behaviour of the generator sequence. Examples can be found in the packages Gen/LbPythia and Gen/LbHerwig.

Then write a tool inheriting from the interface IProductionTool and implementing the following functions:

• StatusCode generateEvent ( HepMC::GenEvent * theEvent, HardInfo * theInfo ) which should call the external generator and return one generated event in HepMC format (inside a GenEvent) and some information about it, stored in the event model class HardInfo. In HepMC format, momentum should be in GeV, and position and time in mm (time multiplied by c). Also each particle should be given a status code (using the member function HepMC::GenParticle::set_status( int status )). The status is used by the Generation algorithm to know what to do with the particle:
  • the particle must be given a status 1 if it is stable or undecayed at the end of the processing by the external generator. It will then be decayed later by the Decay tool.
  • the particle must be given a status 2 if it has already been decayed or fragmented by the external generator. This particle will not be modified later and will be kept in the Monte Carlo truth history at the end of Gauss.
  • the particle must be given a status 3 if this is a particle which should not be modified and that is not necessary to be kept in the Monte Carlo truth at the end of Gauss (such as documentation particles in Pythia).
• void setStable( const ParticleProperty * thePP ) : declare a particle as stable in the external generator to force the external generator not to touch particles of the type thePP. This function is called by the general framework in order to define all particles that the Decay tool knows as stable for the external generator. This way, all particles will be decayed either by the Decay tool, either by the external generator but never by both.
• void updateParticleProperties( const ParticleProperty * thePP ): modify inside the external generator the properties (mass, width, lifetime) of the particle type identified by thePP. This will allow all generators in Gauss to use the same properties, taken from the Gaudi Particle Property service.
• void turnOffFragmentation() : switch off the fragmentation process in the external generator. If this is not relevant for the external generator, this function should be made dummy.
• void turnOnFragmentation() : idem to switch on fragmentation.
• StatusCode hadronize ( HepMC::GenEvent * theEvent, HardInfo * theInfo ): function similar to generateEvent but which is called only to perform the hadronization process on a allready generated parton-level event. If not relevant to the external generator, this function should be made dummy.

Beam Tool

Abstract Interface

Available Implementations

How to write a new Beam Tool 

Decay Tool

Abstract Interface

Available Implementations

How to write a new Decay Tool 

Cut Tool

Abstract Interface

Available Implementations

How to write a new Cut Tool 

Full Event Cut Tool

Abstract Interface

Available Implementations

How to write a new Full Event Cut Tool 

Smearing Tool

Abstract Interface

Available Implementations

How to write a new Pile-Up Tool 

Last update: 13 December 2006

Please send questions or comments to Patrick Robbe