Integration of Atlfast into
Athena Framework
User Guide to prototype release
Authors: E.Richter-Was, P.Clarke, H.Phillips, P.Sherwood,
R.Steward
Index
Context
Utilities used by the new Atlfast
Description of structure of prototype
new Atlfast
Description of output data classes:
ReconstructedParticle
Jet
Cluster
Track
Detailed description of Algorithms (Makers):
CellMaker
ClusterMaker
DefaultReconstructedParticleMaker
Isolator
JetMaker
EventHeaderMaker
StandardNtupleMaker
How to get going:
Scripts for:
Checking out
Building
Running
The jobOptions needed
Locations of output in the TES
A simple example user analysis Algorithm
Appendix: Known problems
Context of the
project
The current versions (Fortran and C++) of ATLFAST are widely used. These
are documented at ATLFAST-home-page
In brief the C++ version functions in the following way:
-
A set of so called "Makers" are scheduled to run one after the other
-
The first of these takes care of calling the event generator, and storing
particle information in a suitable container inside the Maker
-
Subsequent "Makers" use the particle information to create detector type
entities such as "Cells" and "Clusters". These are stored in suitable containers
inside the Maker
-
Subsequent "Makers" use the particle and detector simulated information
to create physics type entities such as "Electrons", "Muons" and "Jets".
These are stored in suitable containers inside the Maker
-
The Makers also accumulate standard histograms as they function
-
The program outputs a root tree.
With the ever increasing penetration of OO software into ATLAS,
and in particular with the adoption od the Gaudi (now = Athena) framework,
a request was made to integrate Atlfast into the framework, and at the
same time re-engineer to a more OO design.
In more detail the objectives of project are:
To integrate ATLFAST++ into the Athena framework.
To produce a structure which as far as possible conforms to the Athena
philosopy. That is to say not a simple wrapping, but a true integration
into the Athena environment .
To re-engineer the implementation toward a full OO design
To produce a structure which is modular in order to facilitate mainenance
and development, and in particular such that ATLFAST users may simply replace
components according to their needs.
To implement a prototype with the functionality of the present ATLFAST++
by September 00
This document is the first release of a user guide to the new Atlfast OO
code which has been written as a result of this project, up to this first
milestone of September-00.
Utilities used
by new Atlfast
During the development of the new Atlfast several "general" utilities
were developed to encapsulate oft repeated code. Also several interfaces
became apparent which could potentially have much wider applicability than
just Atlfast.
Since these are not Atlfast specific these have been implemented as
separate prototypes, with a view to possible discussion in a wider
ATLAS context.
These utilities are assumed and used extensively by the main Atlfast
code. They are referenced briefly here. The detailed documentation is linked.
The Phi class. This class has been furnished
to encapsulate cyclic algebra in the range {-Pi,Pi]
IKinematic interface. It is clear
that for a large number of analysis operations different classes such as
Particles, Clusters, Tracks.....etc need only be treated as simple
kinematic quantities. In addition it proved to be exceedingly useful to
define in an interface the access to several very commonly used quantities
(eg. pT( ), eta( ) ). This was formalised through adoption of the IKinematic
interface.
KinematicHelper. This collects together
a few commom functions which are applied often to kinematic quantities
(i.e. qunatities honouring the IKinematic interface. It was clear that
these functions are not specific to Atlfast and so have been collected
together ijn a helper class at least temporarily in order to make them
easily accessable to users.
HepMC. and McEvent????. This is the
ATLAS standard interface to generator output.
HepMC_helper class. Many operations connected with extracting information
from the HepMC::GeneratorEvent record are collected together in this helper
class.
Function objects for use with STL
generic algorithms
Description of
structure of prototype new Atlfast
Following an initial appraisal of the existing C++ code it was felt
that fundamental idea of "Makers" was perfectly fine and sensible and there
was therefore no reason to change this aspect of the modularity. In fact
it was felt that the functionality of a "Maker".matched almost perfectly
to the purpose of an Athena "Algorithm". Briefly an Athena "Algorithm"
is a fairly autonomous piece of code which is invoked onece per event.
It may read some input objects from the event store, apply some algorithmic
proccessing to them, and possibly write some resulting output objects back
to the store.
Although the idea of concept Makers was retained, the mapping between
original and new has changed quite significantly. This will become clear
in the detailed sections, but to give an overview:
-
In order to understand the factorisability of Atlfast functionality we
have (for at least prototype purposes) put most distinct pieces of functionality
into a distinct Algorithm. This enforces a minimum and well
defined coupling between them, with the purpose of makeing eventual encapsulation
into classes easy. For example there is at present a distinct Isolator
Algorithm.
-
Makers are, insofar as possible, based upon functionality, not particle
species. In the original code each XXX-Maker was a distinct piece of code
dealing with smearing, association and isolation for species XXX. In the
new code there is a single Particle-Maker which deals with smearing of
all particles, a single Isolator which deals with isolation of all particles...etc.
In each case specialisation is done via composition - i.e. passing species
specific tools to the algorithms at initialisation time. This has led to
a significant reduction in repeated code and consequent use of commom implementation.
-
The functions of Detector simulation, Reconstructed entity simulation and
Standard Histogramming have been seperated since they are logically separate,
and need to be evolved separately without unnecessary inter-dependence.
-
The Monte-Carlo generation is handled by a completely independent package
called McEvent ????html ref?????. This can be thought of as an Algorithm
which is run prior to Atlfast. It provides facilities to drive various
generators. The output is an McEvent object in the event store. This McEvent
object itself contains HepMC objects.
HepMC is the ATLA S standard format for generstor output. From the
point of view of Atlfast is it sufficient to know that the main use made
of the McEvent object is to obtain a collection of final state HepMC::Particle
objects which are the primary input to several algorithms. This is somewhat
different to the old code where MC generation was an integral part of Atlfast.
The resulting list of Athena Algorithms is as follows:
Algorithm |
Input object type |
Output object type |
Brief Description |
|
|
|
|
Detector simulation: |
|
|
|
CellMaker |
HepMC::Particle |
Cell |
Simulates deposition of energy in a simple flat model of the calorimeter. |
|
|
|
|
Raw reconstructed quantities |
|
|
|
Cluster maker |
Cell |
Cluster |
Makes Clusters (="pre-jets") by summing energy of Cells in a cone |
TrackMaker |
HepMC::Particle |
Track |
Makes tracks by smearing MC truth trajectory information. |
|
|
|
|
Reconstructed entities |
|
|
|
DefaultReconstructed
ParticleMaker |
HepMC::Particle |
ReconstructedParticle |
Makes particles by smering MC truth 4-vector information. Species is
set via parameters. |
JetMaker |
Cluster |
Jet |
Makes jets by smearing any Clusters which are not associated to isolated
electrons or photons. Includes also non-isolated muons. |
|
|
|
|
Ensemble properties |
|
|
|
Isolator |
ReconstructedParticle
Cell
Cluster |
ReconstructedParticle |
Determines whether input ReconstructedParticles are isolated from Cell
and Cluster energy.
Species is set via parameters. Outputs isolated and non-isolated lists. |
|
|
|
|
Global objects |
|
|
|
EventHeaderMaker |
everything |
EventHeader |
Calculates trigger information, missing Et...etc. outputs a single
global event object. |
|
|
|
|
User example analysis |
|
|
|
ExampleAnalysis |
any |
--none-- |
Shows user how to access Atlfast objects in TES and make some simple
histograms |
Output |
|
|
|
StandardNtupleMaker |
everything |
Common Ntuple format |
For validation tests and backward compatibility |
The full description of each of these is given in the sections which
follow.
Further observations:
-
Data objects are no longer stored inside the makers. Thus subsequent users
of data objects need have no knowledge whatsoever of upstream Makers.
-
Due to the simple and loose coupling between algorithms it is particularly
easy for a user to replace components (e.g. different jet finders) for
specialist studies.
-
All configuration of Algoritmhs (cut parameters ...etc) is done via the
Athena jobOptions service. This means that configuration is almost completely
standardised according to the framework documentation. (i.e. few private
files)
-
These Algorithms may be scheduled in any order which makes sense (i.e provided
its required inputs have already been made). There is no other coupling
to previously run Algorithms.The default order is of course set up for
you in the jobOptions supplied with the release.
Running the new Atlfast to generate data objects in the event store therefore
comprises scheduling these algorithms in an appropriate order, eg: (but
see later section for definitive current configuration)
CellMaker
TrackMaker
ClusterMaker
DefaultReconstructedParticleMaker // parameters
set to deal with electrons
DefaultReconstructedParticleMaker // parameters
set to deal with photon
DefaultReconstructedParticleMaker // parameters
set to deal with muons
Isolator
// parameters et to deal with electrons
Isolator
// parameters et to deal with photons
Isolator
// parameters et to deal with muons
JetMaker
EventHeaderMaker
To schedule the example analysis algorithm then add:
ExampleAnalysis
To cause the output to be written in the form of the common ntuple then
in addition one needs to schedule:
StandardNtupleMaker
[Note that as stated above for the prototype we purposely made almost everything
an Algorithm.We briefly considered the question of sub-algorithms but immediately
saw this to be not a relevant decision at this point. This is because sub-algorithms
are algorithms, but with less flexibility for the user to easily replace
components. It is trivial to go from algorithms -> sub-algorithms later
if there is a good reason, but not vice-versa]
Description of
output data classes
This section describes the output data classes intended for the user in
an analysis program. These classes are the products of Makers described
briefly above and in detail in later sections. These classes define the
interface between Atlfast and the user:
ReconstructedParticle
Jet
Cluster
Track
General notes:
-
In several cases it is necessary to furnish naviagation information to
go from the entity to the Monte-Carlo truth particle from which it was
made. At present there is NO SAFE WAY to do this. The developers of the
McEvent package are aware fo the problem and will in due course provide
an ATLAS-wide solution. In the meantime we have implemented this ina trivial
way which is in practice safe (but not guaranteed according to the rules).
Wherever this is required we have simple provided a method returning a
pointer to the HepMC::Particle. The user should be aware that this will
likelyt change.
-
In some cases more general associations are required. A simple example
is Clusters pointing to Cells from which it was made. A more complex example
is an association between an electron and cluster which are physically
near each other. This had led to a general raising of the problem which
is not trivial to solve in a correct way (simply throwing in pointers is
doomed in the long run). Whilst we await a proper solution, we have temporarily
implemented a dumb one. Each class inherits an AssociationManager
. This contains methods for setting and retrieving Athena SmartRefs
to the relevant objects. The user should be aware that this will certainly
change.
[This section does not inculde those intermediate classes
which are in the event store only because this is necessarry to connect
two Algorithms as these are not intended for the user. At present this
is only the Cell.class. The reader can still find out about these
from the standard linked code and auto-documantation, but be warned that
they are not considered to be supported Atlfast output, and may dissappear
in future releases.]
class
ReconstructedParticle
Declared in : AtlfastCode/ReconstructedParticle.h
Declaration of collection in TES: AtlfastCode/ReconstructedParticleCollection.h
Brief description:
This class represents a reconstructed particle which has been simulated
from a Monte-Carlo truth particle.
All particle species are represented by this class. Their species is
differentiated by a method which gives the PDG id code.
Its kinematic attributes are 4-momentum like and are available via the
IKinematic interface.
It has a method to acceess the MC truth particle from which it was made.
It has an association tracing utility to refer to any other entities
which may have been asociated with it (see note above regarding the
temporary implemetation of AssociationManager).
[Design note: A conscious decision was made that all particle species
should be represented by a single class, with a simple member variable
differentiating species. This is as opposed to a distinct class corresponding
to each particle species.This was decided after much debate as it was felt
that, apart form pdg_id, there was no fundamental difference between reconstructed
particles made from smeared MC truth particles. Their attributes simply
are those of a 4-momentum plus a link to the parent MC particle.
The design philosophy has therefore been to use a common ReconstructedParticle
class until a situation arises where distinct classes would be warranted.
The only reason we could at present foresee within the Atlfast context
is ease of dispatching (i.e. overloading methods on distinc particle class
type). However the potential disadvantages seem enormous (there are then
a semi-infinite number of classes to write for each and every possible
particle spcies).]
Interfaces implemented (and inheritances):
Interface name |
|
Description |
IKinematic |
|
Deals with access to all kinematic attributes |
AssociationManager |
|
Deals with storing and access to any associated objects (such as Clusters,
Tracks). |
Public methods intended for user:
Return type |
method name |
Description |
int |
pdg_id( ) |
PDG ID code of the particle. |
HepMC::Particle* |
truth( ) |
Returns pointer to MC truth particle from which it was made. |
Constructors:
Argument list |
Argument description |
Use |
() |
|
Default constructor required by Gaudi. Not meaningful for a user |
( const int pdg_id,
const HepLorentzVector& vec,
const HepMC::Particle* progenitor ) |
PDG id code for particle
4-momentum for particle
pointer to MC truth from which derived |
Principle constructor to be used by user.
|
( ReconstructedParticle&) |
|
Copy constructor |
(ReconstructedParticle*) |
|
Copy constructor |
Source code:
.h
.cxx
Auto-generated documentation --not done yet--
class
Jet
Declared in : AtlfastCode/Jet.h
Declaration of collection in TES: AtlfastCode/JetCollection.h
Brief description:
This class represents a Jet.
Its kinematic attributes are 4-momentum like and are available via the
IKinematic interface.
It has an association tracing utility to refer to any other entities
from which it has been constructed - typically Clusters (see note
above regarding the temporary implemetation of AssociationManager).
Interfaces implemented (and inheritances).
Interface name |
Description |
IKinematic |
Deals with access to all kinematic attributes |
AssociationManager |
Deals with storing and access to any associated objects (typically
Clusters from which made). |
Public methods intended for user:
Return type |
method name |
Description |
--none-- |
|
|
Source code:
.h
.cxx
Auto-generated documentation: --not done yet--
class
Cluster
Declared in : AtlfastCode/Cluster.h
Declaration of collection in TES: AtlfastCode/ClusterCollection.h
Brief description:
This class represents a cluster of energy with a centriod at a given
3-vector position. This information is made available by the IKinematic
interface with the constraints that eT=pT .
The class is general and may be formed by any ClusterMakeing algorithm.
The AssociationManager gives access to other objects from which it was
made,such as Cells.
Interfaces implemented (and inheritances).
Interface name |
Description |
IKinematic |
Deals with access to all kinematic attributes |
AssociationManager |
Deals with storing and access to any associated objects (typically
Cells). |
Public methods intended for user:
Return type |
method name |
Description |
---none---- |
|
|
Source code:
.h
.cxx
Auto-generated documentation: --not done yet--
class
Track
Declared in : AtlfastCode/Track.h
Declaration of collection in TES: AtlfastCode/TrackCollection.h
Brief description:
This class represents a track which has been simulated from a Monte-Carlo
truth particle.
Its kinematic attributes are 3-momentum like and are available via the
IKinematic interface with the constriant eT=pT..
It has a method to acceess the MC truth particle from which it was made.
It has an association tracing utility to refer to any other entities
which may have been asociated with it (see note above regarding the
temporary implemetation of AssociationManager).
Interfaces implemented (and inheritances).
Interface name |
Description |
IKinematic |
Deals with access to all kinematic attributes |
AssociationManager |
Deals with storing and access to any associated objects (typically
Cells). |
Public methods intended for user:
Return type |
method name |
Description |
HepMC::Particle* |
truth( ) |
Returns pointer to MC truth particle from which it was made. |
Source code:
.h
.cxx
Auto-generated documentation: --not done yet--
Description of
CellMaker Algorithm class
Brief definition:
CellMaker reads Monte Carlo information form the TES and causes a calorimeter
simulation of their energy deposits resulting in a collection of hit Cell
entities to be written to the TES
Input
McEvent monte Carlo information in the TES
Output
Cells to the TES
Source code:
.h .cxx
Long description
The prototype design suggested that detector simulation should be factorised
from simulation of reconstructed quantities. Accordingly the representation
of calorimeter energy deposits (Cell class) is constructed and written
to the TES by an independent CellMaker algorithm. Previously CellMaking
and ClusterMaking were combined.
We considered that as the design evolves there may be better ways to
represent the calorimeter, and to answer questions about calorimeter energy
deposits. Thus inside Cellmaker the Calorimeter is simulated by a Calorimeter
class. The notional purpose of this is to provide an interface between
an arbirtarily sophisticated calorimeter simulation and the Atlfast use
of it to ask for Cells. The design has not been taken any further at present,
nor has it been demonstrated that this is the best line to follow.
The Calorimeter class follows the original ATLFAST++ model.
-
When it is constructed it builds its internal calorimeter model. The model
should be arbitrary, and we would expect it to obtain all parameters from
the jobOptions service, or eventually the detector description in Athena.
Thus CellMaker could be given an arbitrary Calorimeter object. However
at the time of writing\state construction was not available through jobOptions
directly and therefore all parameters are temporarily passed in the Calorimeter
constructor (i.e. parameters are properties of CellMaker which then constructs
Calorimeter).
-
The calorimeter is taken to be a flat 2 dimensional map of square bins
in eta-phi space. The user specifies the eta coverage of the barrel calorimeter
and the total eta coverage (both assumed to be symmetric). The user specifies
the approximate granularity in eta and phi for both the barrel and forward
regions separately. The above parameters are used to determine an actual
granularity which divides an exact integer number of times into the total
coverage.
-
It implements a method which accepts a Monte Carlo truth particle (a HepMC::Particle
object) and causes its energy to be deposited in the appropriate bin. All
particles are deposited with 100% efficiency and no smearing except neutrinos
and muons which are ignored. A threshold in pT() is appied, all particles
below this are assumed to miss the calorimeter. Warning: the LSP should
also be ignored, but there is at present know way to identify this from
the generator information. This will be fixed later.
-
The effect of magnetic field is simulated as a simple phi shift. This can
be enabled/disabled turned by a switch.
-
It implements a method which returns a collection of all Cells with energy
deposits greater than a given threshold.
The Cellmaker algorithm is then simply a wrapper which feeds the Calorimeter
class particles, asks for the Cells back and writes them to the TES.
User parameters
The user can set the following parameters in jobOptions.txt. Defaults
are given in []
-
InputLocation [/Event/McEventCollection] : location in TES to obtain
Monte Carlo particle information
-
OutputLocation [/Event/Atlfast/Cells] : Location to write Cells
to in TES
-
EtaCoverage [5] : Overall eta coverage of the calorimeter. I.e the
maximum extent of the forward calorimeter. The range is taken to be symmetric
-
BarrelForwardEta [3] : eta coverage of the barrel section of the
calorimeter
-
GranBarrelEta [0.1] : Approximate eta granularity of the barrel
region (actual granularity obtained by such that calorimeter divides into
integer number of bins)
-
GranBarrelPhi [0.1] : Approximate phi granularity of barrel
-
GranForwardEta [0.2] : Approximate eta granularity of forward region
-
GranForwardPhi [0.2] : Approximate phi granularity of forward region
-
MinPTBField [0.5] : Minimin pT() below which a particle is assumed
not to reach the calorimeter
-
BField [true] : switch to enable/disable B-filed simulation. true=enabled
-
MinETCell [0.0] : Minimum eT() for a Cell to be returned to the
user.
Description of
ClusterMaker Algorithm class
Brief definition:
ClusterMaking is currently defined as a process which uses Cells from
the TES and forms Clusters from them. The strategy employed is to sum all
Cells in a given R-cone around an initiator. [Note: This might be more
correctly called pre-jet formation as the R-cones are of jet size and therefore
this algorithm does not really correspond to the normal notion of forming
clusters from,say, adjacent energy deposits.]
Input
Cells in the TES
Output
Clusters to the TES
Source code:
.h
.cxx
Long description of strategy
-
ClusterMaker obtains a collection of Cells from the TES. The location at
which it finds these Cells is given to it as a property.
-
The strategy maintains the concept of a list of "availableInitiators" which
means those cells which are to be regarded as available for consideration
as initiators of Clusters. This list is initially constructed as being
all cells read in from the TES which satisfy a transverse energy requirement:
cell.eT() > (some threshold)
-
The strategy selects the next highest transverse energy availableInitiatior
as a candidate to form a new Cluster
-
All availableCells within a specified R-cone of the initiator direction
are identified and their aggregate eT() and weighted centroid found
-
If the total transverse energy of the aggregate satisfies a requirement:
(sum of cells in cone ).eT() > (some threshold)
then
Þ A new cluster is formed using the
aggregate eT() and weighted centroid
Þ All cells used to form the cluster
are then removed completely from further consideration ( i.e they are neither
considered as initiators, or when summing cells in a subsequent R-cone
around an initiator)
-
Ii the total transverse energy of the aggregate fails the eT() requirement
then
Þ The candidate initiator is removed
from the list of availableInitiators.
Þ All cells, including the failed initiator,
remain available for summation in an R-cone to form subsequent clusters.
-
The strategy then iterates using the next highest eT() availableInitiator.
-
The strategy terminates when there are no further availableInitiators.
User parameters
The user can set the following parameters in jobOptions.txt
-
InputLocation ["/Event/AtlfastCells"]: location in the TES to find
Cells
-
OutputLocation ["/Event/AtlfastClusters"]: location in the TES to
place Clusters which are created
-
R-ConeBarrel [0.4]: radius of R-cone for summation of Cells to form
Cluster in the barrel region.
-
R-ConeForward [0.4]: radius of R-cone for summation of Cells to
form Cluster in forward region
-
minInitiatorET [1.5]: minimum transverse energy for Cell
to be used as initiator
-
minClusterET [10]: minimum transveres energy for aggregate
of Cells in R-cone to form new Cluster
Description of
DefaultReconstructedParticleMaker Algorithm class
Brief definition:
Reads Monte Carlo particle truth information from the TES and selects
a specific particle species (set via a parameter). For each such MC truth
particle it creates a ReconstructedParticle instance. The ReconstructedParticle
is created with a smeared energy which can be different for different species.
The ReconstructedParticles are written to the TES
Input
McEven MonteCarlo truth in the TES
Output
A collection (normally ObjectVector<ReconstructedParticle> of ReconstructedParticles
written to the TES . This collection is typedefined as ReconstructedParticleCollection.
Source code:
.h
.cxx
Long description
DefaultReconstructedParticleMaker is a single class which is able to
create ReconstructedParticles corresponding to any particle species for
which it has been configured. This is one of the major advances of the
new version. All of the code which was common, but repeated in several
different makers has been abstracted into one class which is configurable
wherever it needs to be different for specific particle species. In fact
only smearing is different and hence this maker is configured by
supplying it species specific Smearer.
-
The Algortithm is configured by the jobOptions service to operate upon
a chosen particle species. Currently this can be electron, photon or muon.
-
McEvent Monte Carlo truth information is read from the TES. All ocurrences
of the chosen species which are final state particles) are selected.
-
Pre-selection cuts on pT and phi are applied to the MC truth attributes
(these should be set much lower than the post smearing cuts which are to
be applied)
-
For each truth particle a candidate ReconstructedParticle (labelled as
the appropriate species) is constructed with a smeared 4-vector.
-
The smearing is performed by a contained tool which implements the ISmearer
interface. This accepts a 4-vector as input and returns a suitably smeared
4-vector
-
The candidate is tested against a pT( ) threshold and a fiducial cut on
eta.
-
All surviving candidates are collected together and written to the TES.
In a pure OO environment smearing would be an example of a behavioural
difference given to the Algorithm by composition. It would probably be
supplied through the constructor of the Algorithim. This option is not
available in Athena directly however we expect the advent of tools to allow
different smearers to be configured via jobOptions, and then given to this
Algorithm also by jobOptions. At the time of writing this facility was
not available yet and so a temporary fix up is used.
In this release the following smearers are supplied exactly as were
in ATLFAST++
These smearers encapsulate the only part of this maker which acts in a
species specific way. A user may in principle supply an arbitrarily sophisticated
smearing procedure for any particle species.
User parameters
The user can set the following parameters in jobOptions.txt. defaults
are given in []
-
MC_eventLocation [/Event/McEventCollection] : location in the TES
to find McEvent monte carlo information
-
OutPutLocation [/Event/Atlfast/ReconstructedParticle] : location
in TES to write ReconstructedParticles out to
-
ParticleType [11] : pdg code for particle species to simulate
-
McMinimumPt [0.0]: pT() acceptance threshold for MC truth particle
-
McMaximumEta [1000] : fiducial eta cut for MC truth particle
-
MinimumPt [5.0]: pT() acceptance threshold for simulated particle
-
MaximumEta [2.5] : fiducial eta cut for simulated particle
-
DoSmearing [true]: switch to enable/disable smearing (mainly for
testing purposes)
The following are neeed to configure the smearer. It is wrong to have them
here, but this can only be changed when tools can be used which can be
configured via jobOptions directly. Probably this will change by the next
release.
-
Luminosity [1] : 1=low lumi, 2=high lumi.
-
MuonSmearKey [6] : Corresponds to smearing options in old
ATLFAST++. Only 6 is implemented
And temporarily also we have to set a random seed. This should disappear
with the use of Athena random number services.
-
Ranseed [12345] : random number seed
Description of
Isolator Algorithm class
Brief definition:
Reads ReconstructedParticles from the TES and applies an isolation
test to them. Writes seperate lists of isolated and non-isolated particles
back out to the TES. The present algorithm implements exactly that of ATLFAST++,
and in order to do this it also reads Cells and Clusters from the TES.
The isolation test is performed by summing the transverse energy in a cone
around the test particle and comparing to a threshold. It operates
on a single particle species which is set via a parameter.
Input
Collection of ReconstructedParticles from TES
Collection of Cells from TES
Collection of Clusters form TES
Output
Collection of ReconstructedParticles to TES (isolated particles)
Collection of ReconstructedParticles to TES (inon-solated
particles)
Source code:
.h
.cxx
Long description
Following the stated goals of the prototype the function of isolation
testing has been implemented as a distinct algorithm [the purpose being
to help us factorise operations in atlfast]. The Isolator algorithms
class is therefore designed to be scheduled following the DefaultReconstructedParticleMaker
algorithm which writes all smeared particles to the TES without itself
performing any selection on isolation. Isolator reads these smeared
particles, divides them into isolated and non-isolated lists, and then
writes both lists back out to the TES at locations specified via
parameters. Thus the user is most likely to be interested in the the output
of Isolator rather than ReconstructedParticleMaker directly.
-
The Isolator algortithm is configured by a parameter to operate upon a
chosen particle species. Currently this can be electron, photon or muon.
-
A collection of ReconstructedParticles is read from the TES at a location
specified by a parameter. This collection must contain particles of the
appropriate species for which this instance of Isolator has been configured.
-
A collection of Clusters is read from the TES from a location specified
in a parameter.
-
A collection of Cells is read from the TES from a location specified in
a parameter.
-
For each particle, the nearest Cluster is found. If this is within a specified
distance then it is regarded as "temporarily associated" with the particle.
If so it is then ignored for the rest of the isolation test.
-
The eT of all other Clusters within a specified cone is summed. If this
exceeds a specified cut then the particle is declared to be non-isolated
-
If the particle survived the last cut then the same calculation is performed
using Cells. If the eT sum exceeds a specified cut then the particle is
declared non-isolated.
-
If the particle survived the last cut then it is declared isolated.
-
At this point then for isolated particles ONLY the temporary association
with a Cluster (if any) is made permanent by setting a bi-directional association
between the ReconstructedParticle and the Cluster. This is not done
for non-isolated particles (in other words the temporary association is
forgotten).
Note: in order to follow ATLFAST++ exactly the cut on sum Cluster eT should
be left at 0. This is because the original algorithm simply asked whether
any Cluster was within the isolation cone, but did not apply any cut.
User parameters
The user can set the following parameters in jobOptions.txt. defaults
are given in []
-
InputLocation ["unknown"] : location in the TES to find input ReconstructedParticles
-
IsolatedOutputLocation ["unknown"] : location in the TES to write
isolated ReconstructedParticles
-
NonIsolatedOutputLocation ["unknown"] : location in the TES to write
non-isolated ReconstructedParticles
-
CellLocation ["/Event/AtlfastCells"] : location in the TES to find
Cells
-
ClusterLocation ["/EventAtlfastClusters"] : location in the TES
to find Clusters
-
R-ClusterMatch[0.4] : R-cone within which nearest Cluster
must be to count as "associated"
-
R- ClusterIsolation[0.4] : R-cone within which to sum Cluster
eT around particle
-
E- ClusterIsolation[0.0] : Maximum allowed Cluster eT in R-cone
to be classified as isolated
-
R- CellIsolation[0.2] : R-cone within which to sum Cell eT
around particle
-
E- CellIsolation[10.0] : Maximum allowed Cell eT in R-cone to be
classified as isolated
Description of
JetMaker class
Brief definition:
Jet maker shares its misnoma with Cluster maker, in that it is actually
ClusterMaker which forms the Jets, followed by JetMaker which simply smears
the energy accoring to some parameterisation. Thus the action of this algorithm
is to read Clusters from the TES, smear their energy, add in any non-isolated
muons, and then create a Jet which is written out.
Input
Collection of Clusters from TES
Collection of Muons from TES
Output
Collection of Jets to TES
Source code:
.h
.cxx
Long description
The JetMaker starts from Clusters in the TES. Recall that Clusters are
in fact summations of energy in a jet-like cone (0.4 or 0.7) around an
initiator and are therefore nearly jets anyway. The JetMaker algorithm
performs the followng steps
-
Obtains all Clusters from the TES
-
Obtains all non-isolated muons from the TES
-
Traverses the Clusters and picks only those which are NOT associated with
electrons of photons
-
Creates a Jet candidate by smearing the 4-momentum of the Cluster. It does
this using a JetSmearer object which encapsulates
the parameterisation of this operation.
-
Finds the nearest non-isolated Muon. If this is within a specified R-cone
of the Jet candidate then this muon is added to the Jet. The relevant Muon
is then excluded from further consideration.
-
The resultant Jet is then subject to kinematic requirements on pT and eta.
These are specified in parameters.
-
Any surviving Jet is then output to the TES.
No jet -flavour tagging has been done for the prototype release purely
due to time constraints.
User parameters
The user can set the following parameters in jobOptions.txt. defaults
are given in []
-
InputLocation [/Event/???] : location in the TES to find Clusters
-
MuonLocation [/Event/???] : location in TES to find non-isolated
Muons
-
OutPutLocation [/Event/???] : location in TES to write Jets
-
RconeF[0.4] : Maximum R-cone for adding muons in the forward
region.
-
RconeB[0.4]: Maximum R-cone for adding muons in the barrel
region.
-
MinimumPT [10.0]: pT() acceptance threshold for Jet
-
MaximumEta [5.0] : fiducial eta cut for Jet
-
DoSmearing [true]: switch to enable/disable smearing (mainly for
testing purposes)
The following are neeed to configure the smearer. It is wrong to have them
here, but this can only be changed when tools can be used which can be
configured via jobOptions directly. Probably this will change by the next
release.
-
Luminosity [1] : 1=low lumi, 2=high lumi.
-
BarrelForwardEta [3.0] : Division between barrel and forward regions.
And temporarily also we have to set a random seed. This should disappear
with the use of Athena random number services.
-
Ranseed [12345] : random number seed
How to get going
In this section we attempt to take the user step by step through the process
needed to get going with the new Atlfast.
The reader is reminded at this point that the Atlfast works on the output
of any generator which has been installed in Athena and which conforms
to the output format of the McEvent package. The documentation of generators
is therefore no longer part of Atlfast proper. See ???? html ref to McEvent
?????. Thereofre in the following we show how to fire up an example generator,
but no attempt is made to describe it or its options in detail.
Scripts
Some example scripts have been created to demonstrate how to check
out the code, build the executable, and run the job. The scripts contain
a few lines where you should put in your own chosen path names corresponding
to the roots where you (a) want to put the checked out the source and (b)
want to build.
checkout.sh
This checks
out Athena ...etc, the Generators code (for Pythia ...etc), and then
Atlfast.
build.sh
Performs the configure and make steps to build the job.
run.sh
Runs the job from the appropriate directory.
Job Options
Athena is driven by a jobOptions file.
A job options file which will schedule a generator followed
by all the Atlfast algorithms is available in AtlfastFrame/share/jobOptions.txt
. This file in turn #includes AtlfastFrame/share/StandardAtlfastOptions.txt
a second file which contains all of the default parameter settings. This
is fairly heavily commented and the user should look at the latest version
for up to date details. A brief commentary is given here.
jobOptions.txt:
AtlfastFrame/share/jobOptions.txt
-
The file starts with some standard pre-amble which you shouldnt need to
change. Here you will see specification of file names for Histogram
and Ntuple output, number of events to run, and a printout level setting.
-
Next comes the main instruction which tells Athena exactly what it is going
to run. It starts:
ApplicationMgr.TopAlg = {
This is now going to list all of the Algorithms to run in the order
they are going to run.
-
Each Algorithm to be run appears within the { } as
"ClassName/NameOfInstance"
where the NameOfInstance is optional and only needed if you are making
more than one instance of the Algorithm with different parameters. We do
however tend to use this even when there is only one instance.
-
The first algorithm shown is probably
"IsajetModule" or "PythiaModule"
This is the instruction to schedule the generator.
-
The next entries schedule all of the Atlfast Algorithms. [Note: this will
be changed in future so that you dont see this explicity]. The first ones
to be run are those which take MC truth information and create Clusters
and Tracks in the TES
"Atlfast::CellMaker/CellMaker"
"Atlfast::ClusterMaker/ClusterMaker"
"Atlfast::TrackMakerMaker/TrackMaker"
-
The next algorithms create electrons, photons and muons and then
perform the isolation tests to finally create seperate lists of Isolated
and Non-Isolated particles in the TES. Note that here they all use the
same Algorithm, but three different instances of it are made to deal with
each of the three species. The same is true for isolation.
"Atlfast::DefaultReconstructedParticleMaker/ElectronMaker"
"Atlfast::DefaultReconstructedParticleMaker/PhotonMaker"
"Atlfast::DefaultReconstructedParticleMaker/MuonMaker"
and then
"Atlfast::Isolator/ElectonIsolator"
"Atlfast::Isolator/PhotonIsolator"
"Atlfast::Isolator/MuonIsolator"
-
Next the JetMaker is run. This has to come last as it needs both unacssociated
Clusters and lists of non-isolated muons
"Atlfast::JetMaker/JetMaker"
-
Finally there is the special maker which forms some global quantities
which can only be made after everything else is made.
"Atlfast::EventHeaderMaker/EventHeaderMaker"
-
At this point Atlfast will have made everything it is going to make. What
follows is some output and example analysis.
-
"Atlfast::StandardNtupleMaker/StandardNtupleMaker" causes some approximation
to the common ntuple ATLFAST entries to be written out.
-
"Atlfast::ExampleAnalysis" is a very simple and heavily commented Algorithms
which shows you how to access Atlfast output from the TES and make some
simple plots with it (see section below).
-
The instruction finishes with };
-
Then follows an instruction to #include a file "StandardAtlfastOptions.txt"
StandardAtlfastOptions.txt:
AtlfastFrame/share/StandardAtlfastOptions.txt
This file contains all of the parameter values to give to the instances
of each Algorithm. Most of the entries are self evident after reading the
description of each Algorithm given earlier in this documents. Note
that it is not an error to give parameters for Algorithms which hve not
been scheduled - in this case Athena simply ignores them.
-
Typically each Algorithm needs to be given the text string specifying the
location in the TES where is should get its input from, as well as write
any output to. In fact there is only one which is set externally to Atlfast,
and that is the location of the McEvent record which is the product of
the generator.
-
Most other locations simply have to be set so that the output of one Algorithm
is fed to the input of a subsequent one. I.e ClusterMaker stores Clusters
at /Event/AtlfastClusters. Then Isolator and JetMaker need to be told this
in order to read them back in
-
Other parameters are mainly cuts
The defaults set here are intended to follow those of the old ATLFAST++
as far as possible.
The user should NOT need to edit this file, as it should be sufficinet
to over-ride any parameters you wish in your own seperate file which should
be included in jobOptions.txt in the same way, but following StandardAtlfastOptions.txt.
Location of output
in the TES
All of the locations in the TES for input and output can be seen either
in the default parameters for eack maker (see this document above) or by
their overriden values given in the StandardAtlfastOptions.txt
file.
We repeat them her just for quick reference, and to show you the "general
naming scheme" used for the prototype. As will all documentation however,
this section may become inadvertantly out of date, but the job options
file will always give the exact values.
Output quantitiy |
Object Type |
Collection Type |
Location |
Electrons:
Isolated
Non-isolated |
ReconstructedParticle |
ReconstructedParticleCollection |
/Event/AtlfastIsolatedElectrons
/Event/AtlfastNonIsolatedElectrons |
Photons:
Isolated
Non-isolated
|
ReconstructedParticle |
ReconstructedParticleCollection |
/Event/AtlfastIsolatedPhotons
/Event/AtlfastNonIsolatedPhotons |
Muons:
Isolated
Non-isolated |
ReconstructedParticle |
ReconstructedParticleCollection |
/Event/AtlfastIsolatedMuons
/Event/AtlfastNonIsolatedMuons |
Jets |
Jet |
JetCollection |
/Event/AtlfastJets |
Clusters |
Cluster |
ClusterCollection |
/Event/AtlfastClusters |
Example analysis
Algorithm
A very simple example analysis Algorithm has been prepared in order
to show the user how to access Atlfast output from the TES and to make
some simple printout and plots with it.
This can be found in the AtlfastCode package and is called ExampleAnalysis
(.h
and .cxx).
This Algorithm should be scheduled after all other Atlfast operations as
described in a previous sub-section.
The example code has been very heavily documented in an attempt to explain
the meaning of each line. The histogram output appears in the file
specified in the jobOptions.txt file. [Note: the authors of Atlfast do
not claim to yet be experts as using Athena histogram services - so expect
bugs here].
Appendix: Known
problems
build:
- Problem in build which we dont understand. You have to copy something
by hand the first time. See build.sh script for details.
ClusterMaker:
- Uses fixed cone of 0.4 for all Clusters regardless of parameter settings.
Because no easy way to know barrel/ecap split yet.
- A possible problem was identified in ATLFClusterMaker to do with eT
weighted phi(). See PreCluster class for details. Implementation here is
therefore different.
StandardNtupleMaker:
Histograms and Ntuple dont work together Histograms have random
problems with output to file.