Title of Project:  Atlfast-Athena

Requirements/Use Cases Document

Version 2 :
Status: Submited for requirements review 25-Jan-2001
 

Outline of project:

The task is to provide a very fast, stable simulation of the output of the ATLAS detector as needed to make physics analyses. An existing product, Atlfast, provides much of the required functionality and forms the initial reference. The primary motivation is to re-engineer the functionality into an OO design for long term evolution and maintainability. The secondary motivation is to provide an easy to use application running within the Atlas offline framework, Athena, in order to encourage ATLAS collaborators to switch to the new software environment. A first prototype based on the functionality of ATLFAST++ has been implemented. This document is intended to specify the requirements which will dictate future evolution of the design.

Source documents

  1. http://atlasinfo.cern.ch/Atlas/GROUPS/PHYSICS/HIGGS/Evolution/html/Evolution.html     --> Evolution.ps
  2. Entity requirements list: D.Rousseau
 
 
 

 Requirements

UR1: Atlfast should produce as output the following simulated reconstructed entitites:
Muon
Electron
Photon
Tau-jet
b-jet
c-jet
light-jet
Track

Missing Transverse momentum

Cells ???

UR2: Atlfast should produce as output suitable entitites containing the following  simulated global event information:
Level 1Trigger simulation
Level2 Trigger simulation
Event shape variables

Event weight from the Monte Carlo truth information.

UR3:  In the first instance Atlfast should, insofar as possible, simulate all output entities using the strategies and parameterisations documented in a note of June 2000 edited by E.richter Was "Documentation of algorithms for fast simulation of ATLAS detector".
 
UR4: The information which the user needs to know about each of the Electron, Photon and Muon entities is:
The kinematic attributes (four-momentum measured at some point)
The information needed to define the trajectory of the particle
        ( eg position of definition of four-momentum , charge and signed radius of curvature).
The identified particle type (pdg identity code)
Reconstruction efficiency
Whether isolated according to some isolation algorithm
Conflict: Either general history access :
A way to generally access the MC truth history from which it was made (eg a reference to an entry point in the MC truth record)
or only a subset of specific information required by the user of Track :
The kinematic attributes of the generator particle from which is was created
The particle type of the generator particle from which it was created (pdg_identity code)
?????????????? what else is specifically required from the MC truth ??????????????????????
Source of conflict : see UR13 and UR19
UR5: The information which the user needs to know about the quark jet entities is:
The kinematic attributes (total four-momentum)
Labelling as b,ctau or light jet .
Tagging efficiency
?????????????? what  is required from the MC truth for a jet ??????????????????????
 
UR6: The information which the user needs to know about the Tau-jet  entity is:
 
The kinematic attributes (total four-momentum)
Labelling as b,ctau or light jet .
?????????????? what  is required from the MC truth for a tau jet ??????????????????????
 
UR7: The information which the user needs to know about the Track  entity is:
The kinematic attributes (four-momentum measured at a point)
The "Helix" parameters of the track + corresponding correlation matrix.
Any further information needed to define the trajectory  (eg  the signed radius of curvature).

Conflict: Either general history access:

A way to generally access the MC truth history from which this Track was made (eg a reference to an entry pointi n the MC truth record)
or only a subset of specific information required by the user of Track
The kinematic attributes of the generator particle from which is was created
The particle type of the generator particle from which it was created (pdg_identity code)
???????????????  what  else is actually wanted  by the user ?????????????????
???????????????  how is the multiple parent list actually used for b physics ??????
Source of conflict : see UR13 and UR19
UR8:  Atlfast should, insofar as possible,  produce as output the "Standard Ntuple"  (defined in ???????????????? ).
 
UR9: A quick inspection of the existing code has shown that the default strategies which are to be provided (following requirement   UR3 ) operate very simply. They merely smear the 4-momentum of a generator particle accrding to some detector and particle specific parameterisation.  There are several such parameterisations for each entity. It is required that the user can select between these in a simple way.

UR10: Following  UR9  , new parameterisations can in general to be developed by people who are experts in the response of a particular detector. It is required that such suppliers can provide a new response parameterisation in a simple encapsulated way, and not be required to know about the detailed implementation of Atlfast. This requirement was specifically flagged by A.Nariz in the document referenced in  UR3
 
UR11: One of the important features of Atlfast is its flexibility to be able to vary a simulation strategy on a species by species basis for a particular study. Thus although the default electron simulation simply smears generated electrons, it may be that some other strategy is required for a future study( eg a simple track/cluster matching). It is therefore required that the entire strategy used to simulate each entity (as opposed to just its parameterisation) is easily replaceable.
 

UR12: The package must run quickly in order to be able to generate a large number of events in a short time.  In relative terms the package should be fast with respect to the generator package.

UR13:  One of the main uses of this package will be to generate and store a very large number of events for furture use. Therefore due consideration needs to be given to keeping the data volume per event small so that generated datasets are manageable.

In particular it must not be assumed that  the complete Generator information sturcture can be stored alongside the Atlfast output. This has implications for history recording. and referencing.  This may be inclonflict with UR19.
 
UR14: Assuming that ATLAS agrees common interface(s) for kinematic quantitites, then the appropriate Atlfast entities should honour this.
 
UR15: The new Atlfast should run within the Athena framework, and make full use of its services insofar as possible. In other words no ad hoc service should be invented in parallel for Atlfast use unless Athena cannot provide it, or cannot be developed to provide it.

UR16: The user should be able to invoke Atlfast via a very simple interaction with the configuration system of Athena. Preferably by a single reference to "Atlfast".
 
UR17: It should be possible to simulate the action of a range of Jet Finders when forming the Jet entity.

UR18: Atlfast should be capable of simulating pile up

UR19: Some users have indicated that it is a requirement to have extensive access to Monte Carlo truth history.  This may however conflict with the storage space requirement of UR13.

The following has been suggested by D.Rousseau:

One way to solve the truth information problem is to have  it highly configurable, so that each user can devise a compromise between information available and size of the output. One could  envisage that the truth information is not extracted from HepMC event,  but that only some selected HepMC particles and vertices are written  out (through the convertor). For example, the following possibilities  could be chosen from the jobOption.txt
 - complete truth information
 - almost complete truth information, with a Pt threshold and an eta  range, maybe without the pi0 decay photons
 - only the so-called "history" block, with hard scatter
 - all particles refered to from a simulated particle (see UR4,UR5,UR6)
 - all final charged particle or electron or photon or muon or tau in the detector acceptance with some pt threshold
 - the mother tree of the particles above up to the first unstable particle or up to the top
 - all B and D hadrons, possibly with their decay tree down to the final daughters
 - any particle flagged by the user
 - creation and decay vertices of all selected particles
 
This issue is manifestly much wider than Atlfast itself, and should be addressed at an appropriate level before a final solution for Atlfast itself can be chosen.

 UR20: The Atlfast output objects should be compatible with the requirements of the ATLAS display tools. This has potential implications for the Atlfast output objects in terms of interfaces it should implement to make themselves displayable.

UR21: From  input received from D.Froidevaux  and Ed Moyse: Atlfast should produce an output corresponding to the full calorimeter Cell list (Cell to be defined). This is needed for high pT top reconstruction.
>>>>> to be checked as this affects the philosophy substantially <<<<<<
>>>>> what is actually needed and would it be satisfied by a more general Calorimeter object <<<<<<
 

UR22: The user should be able to specify that Atlfast only creates and outputs a subset of simulated reconstructed entities as they desire.

UR23: It must be possible to run Atlfast in parallel with full simulation. Example uses of this are:

To compare full and fast simulation

To mix, for example, fast calorimeter and muon smearing with full track simulation

 
 
UR24: It should be possible to smear the same generator event differently several times.

  
UR25: It should be possible to regenerate any given event (without having to re-generate all preceeding events). This requires the implementation of a random seed saving service centrally.

   

UR26: The user  would like to have some control histograms stored in the output, histograms which monitor performnce of the simulation algorithms themselves.
 

UR27: The user would like to have any parameters used to define Atlfast operation stored in the output.
 

Use case U1:  Perform an analysis within the Athena framework using the Atlfast output entities.


U1 -  Pre Conditions

The user has set up the Atlas software environment to be able to build the required Atlas software release including  Athena and Atlfast.

The user has been able to configure and run a chosen generator which will place its output into the Transient Event Store (TES). The output is stored in the HepMC format.

The user is able to use the Athena histogram services.
 

U1 -Main flow

The user interacts with the Athena configuration system to schedule the Atlfast package to be run after the generator, and then their own analysis algorithm to run after Atlfast..  The user may also interact with the configuration system to select one of a set of alternative parameterisations of the detector kinematic response to specific particles, and /or to change some variable settings which control the simulation process. Apart from these options, the user wants the default Atlfast strategies to be invoked for all simulated entities.

The user requires Atlfast to produce the simulated reconstruction entities enumerated in the a-priori requirements. In order to produce these entitites Atlfast uses the kinematic information contained in the generator output stored in the TES, Athena services, and detector geometry information stored in a suitable database. The simulated entitites are then stored in the TES. The users analysis Algorithm is scheduled to run after Atlfast, and this reads the simulated entitites from the TES. The user analysis Algorithm performs some analysis. The results of this analysis are a set of histograms which are written out for future use.
 

More detail:

U1-main-1. The user first interacts with the Athena configuration system (currently the jobOptions database). The user makes the following choices:
To schedule the Generator, then Atlfast, then the user Analysis

Changes the minimum pT and eta range within which entities are produced

In this instance the user wishes to use the default strategies for all simulations.  See the alternative flows for  some other actions possible at this point.

However they may chose to set some options within a given strategy.
 

U1-main-2  Athena is then started and in due course the Atlfast package is scheduled to run.

U1-main-3. Atlfast produces the "simple" simulated reconstructed entities listed above based upon the generator information stored in the TES.

U1-main-4. In order to do its job Atlfast accesses other static information such as detector geometry stored in a suitable data base.

U1-main-5. Atlfast also calculates the global event information in the list above and makes this available through a suitable simulated global information entity.

U1-main-6. Atlfast writes all of the simulated entitites out to the TES and then passes control back to Athena.

U1-main-7. The user analysis Algorithm is then scheduled. This reads the simulated enetitites form the TES and performs some "standard" anaylsis manipulations which include:

Plotting some distributions of the simulated reconstructed  kinematic quantitites.

Application of kinematic operations to collections of these entities (such as formation of invariant mass)

Plotting information associated with the generator entities from which the entity has been constructed.

 The resuts are made available through the standard Athena histogram services
 
 U1-Main-8: The user analysis Algorithm terminates. At some point later Athena terminates and the histograms are written to a file.
 
 

U1-Alternative-Flow-1: Use a different Muon simulation strategy.

This use case proceeds in the same way as before , except that during the configuration stage the user wishes to use a completely different strategy for simulating a Muon.

This is achieved by the user interacting with the configuration system to select the alternate strategy to be invoked for simulating muons.

Apart from this the use case continues in exactly the same way as per the main flow.
 

U1-Alternative-Flow 2: Create a Standard Ntuple to be stored for future use.

This use case is very similar except that the user no longer schedules their own user analysis Algorithm. Instead the user interacts with the configuration system in order to select an option which will produce the standard ntuple  from Atlfast itself.

The flow is therefore:

U1-Alt2-1. The user first interacts with the Athena configuration system (currently the jobOptions database). The user makes the following choices:

To schedule the Generator, then Atlfast

Changes the minimum pT and eta range within which entities are produced

In this instance the user wishes to use the default strategies for all simulations.

However they may chose to set some options within a given strategy.

The user selects the option to produce the standard ntuple.

 Then as for main flow U1-Main-2 to U1-Main-6 except that Atlfast doesnt pass control to Athena

U1-Alt2-2  Atlfast then causes all of the required quantities to be formed and written to a  Standard Ntuple. Atlfast then passes control to Athena.
 

U1-Alternative-Flow 3: Run two different Jet finders in parallel in the same job, and compare their output.

This is very similar to alternative flow 3, except it is reuired to use an alternative strategy in addition rather than to replace.

U1-Alt3-1. The user first interacts with the Athena configuration system (currently the jobOptions database). The user makes the following choices:

To schedule the Generator, then Atlfast

Changes the minimum pT and eta range within which entities are produced

The user uses the default strategies for all simulations.

The user also schedule an alternative jet finder to be run in addition to the default jet finder, such that the jets it outputs are distinct from those of the jefault jetfinder

 
Then as for main flow U1-Main-2 to U1-Main-8 except that  within U1-Main-7 the user must be able to obtain both sets of Jets in a clear and easy way.
 
 

 

U1-Alternative-Flow 4: Cause all simulated output to be stored persistently.

This use case is very similar to alternative 2, except that rather than ntuple storage, the full aTLAS persistent storage is used (whatever that is). The flow is therefore:

U1-Alt2-1. The user first interacts with the Athena configuration system (currently the jobOptions database). The user makes the following choices:

To schedule the Generator, then Atlfast

Changes the minimum pT and eta range within which entities are produced

In this instance the user wishes to use the default strategies for all simulations.

However they may chose to set some options within a given strategy.

The user selects the option to save all output ot persistent storage.

 Then as for main flow U1-Main-2 to U1-Main-6 except that Atlfast doesnt pass control to Athena

U1-Alt2-2  Atlfast then causes all of the required quantities to be formed and written to persistent storage. Atlfast then passes control to Athena.
 
 
 

Use case U2:  Atlfast is used to pre-filter generator events for full simulation.

 

 U2 -  Pre Conditions

The user has set up the Atlas software environment to be able to build the required Atlas software release including  Athena, Generators, Atlfast and the full simulation package.

The user has been able to configure the chosen generator (which will place its output into the Transient Event Store (TES) in the HepMC format).

The user is able to configure the full simulation package which will to use the generator output to drive it.
 
 

U2 Main Flow

The user configures Athena to schedule the Generator followed by Atlfast in the same way as encapsulated in  U1 .

The user also schedule a selection algorithm to be run after Atlfast. This selection uses the Atlfast output to decide whether the event is required. Depending upon the decision of this selection algorithm the full simulation must then be run or not.
 

U2-Main-1. The user first interacts with the Athena configuration system (currently the jobOptions database). The user makes the following choices:

Schedules the Generator

Schedules Atlfast

Schedules their selection algorithm

Schedules the full simulation to be run if the selection algorithm gives the go-ahead.

Then as for main flow U1-Main-2 to U1-Main-6

U2-Main-2 . Athena then schedules the selection Algorithm. This reads the simulated entitites from the TES and applies some arbitrary selection criteria .

U2-Main-3 The decision must then be communicated to the Athena system such that it will control whether the full simulation is then scheduled.
 
U2-Main-4 For each event, both the fast and fully simulated output should be stored persistently. In ALL cases the fast simulation is stored (regardless of whether full simulation was subsequently selected).
 
 
 
 

U2-Alternative-Flow 1: Run both Fast and full in parallel for every event in order to make comparisons.

This is very similar to the main flow , except that the full simulation is run for every event. all steps are otherwise identical.
 
 

Derived Requirements:

 

The following additional requirements are derived from the use cases:

DR1: From  U1-main-1 : Atlfast must provide an easy way of setting kinematic selection criteria to be applied to the simulated entitites. For example a minimum pT cut, below which the entity is not created.
 
DR2: From  U1-main-7  : Atlfast must store its output in a way which makes it easy for a subsequent Athena Algorithms to find it. For example the user should not have to know an arbitrary geographical location string.

DR3: From U1-Alternative-Flow-1: Atlfast must provide a simple way for the user to select a different strategy to be used for simulating any specific particle species.

DR4: From U2 : a mechanism must be provided for conditionally scheduling an algorithm to follow atlfast.