The GAUSS Project

 

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.

External libraries

The generator phase uses a set of external libraries taken from the LCG Generator services builds or built as Gauss packages by LHCb

Generator libraries used by Gauss, with links to their documentation, and contact people for their use in LHCb:

Library	Description	Contact	Validation
In production
HepMC	Generator event record	Patrick Robbe, Gloria Corti
PYTHIA 6	General purpose generator used for pp collisions	Patrick Robbe	GENSER test
LHAPDF	Library of Parton Density Functions		GENSER test
EvtGen	Decay library specialized for b-hadrons. Special LHCb build for hadron machines and additional decay models. Uses PYTHIA6 for some decays.	John Back, Tomas Pilar
PHOTOS	Handles radiative decays, used by EvtGen.		GENSER test
HIJING	Heavy Ion Jet Interactions Generator, used for simulation of beam gas events	(Vincenzo Vignoni did the original implementation)	GENSER test
BcVegPy	Production of Bc meson and its excited states. Uses PYTHIA6.	Jibo He, Patrick Robbe
PYTHIA 8	The new C++ Pythia, to replace Pythia 6	Aurelien Martens, Alex Grecu	GENSER test
Under integration
PHOTOS++	Replacement of PHOTOS to be used by newer version of EvtGen for radiative decays
Taula++	Decay package for tau decays to be used by newer version of EvtGen
GenChicc	Generator for Chi_cc. Uses PYTHIA6.	Feng Zhang
SHERPA	General purpose generator in C++, can also be used as a decay tool instead of EvtGen	Tobias Brambach, Julian Wishahi	GENSER test
HERWIG++	General purpose generator, C++ successor of Herwig	Philip Ilten	GENSER test
To be recommissioned
ALPGEN	A collection of codes for the generation of multi-parton processes in hadronic collisions	(Ivan Belyaev did the original implementation)	GENSER test
HiddenValley	Simulates Hidden Valleys at hadron colliders, q qbar -> Z' -> v-quarks, followed by v-showering and v-hadronization to v-pions. Uses PYTHIA6	Ivan Belyaev
To be removed soon
HERWIG	General purpose generator, can be used instead of Pythia.	(Karl Harrison did the original implementation)	GENSER test
JIMMY	To be used with HERWIG. Generate multiple scattering events in hadron hadron interactions	(Karl Harrison did the original implementation)	GENSER test
MCatNLO	Package to combine a Monte Carlo event generator with Next-to-Leading-Order calculations of rates for QCD processes. Uses HERWIG.	(Karl Harrison did the original implementation)	GENSER test

The full list of generator libraries built and distributed by LCG, including validation and test, is available from the GENerator SERvices web page.

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:

Option Name	Default Value	Description
SampleGenerationTool	"MinimumBias"	Name of the Sample Generation Tool to be used in the generation. Defines the kind of sample which will be produced.
EventType	30000000	Event type of the sample which will be generated. Event type conventions are described in the note.
HepMCEventLocation	"/Event/Gen/HepMCEvents"	Location where to store generated events in HepMC format.
GenHeaderLocation		Location where to store GenHeaders.
GenCollisionLocation		Location where to store information on collisions.
PileUpTool	"FixedLuminosity"	Name of the Pile Up tool used to determine the number of pile-up interactions in each event.
DecayTool	"EvtGenDecay"	Name of the Decay tool used to decay all hadrons. If empty, all hadrons will be left undecayed.
VertexSmearingTool	"BeamSpotSmearVertex"	Name of the Smearing tool used to smear the collision vertex. If left empty, no smearing is applied.
FullGenEventCutTool	""	Name of the Full Event Cut tool to use to apply generator level cuts and reject events base on all the properties (including pile-up interactions). If left empty, no cut will be applied at this level.

 

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: 26 April 2006

Please send questions or comments to Patrick Robbe