PHOTOS Interface in C++; Technical and Physics Documentation
aa r X i v : . [ h e p - ph ] A p r CERN-PH-TH/2010-261IFJPAN-IV-2010-6Updated version; for the program as of April 2015
PHOTOS Interface in C++
Technical and Physics Documentation
N. Davidson a , T. Przedzinski b , Z. Was c,d a Murdoch Childrens Research Institute, Royal Childrens Hospital,Flemington Road, Parkville 3052, Melbourne, VIC, Australia b The Faculty of Physics, Astronomy and Applied Computer Science,Jagellonian University, Stanislawa Lojasiewicza 11, 30-348 Cracow, Poland c Institute of Nuclear Physics, Polish Academy of Sciences,ul. Radzikowskiego 152, 31-342 Cracow, Poland d Theory Group, Physics Department, CERN, CH-1211, Geneva 23,Switzerland
Abstract
For five years now,
PHOTOS
Monte Carlo for bremsstrahlung in the decay of particles andresonances has been available with an interface to the
C++ HepMC event record. The mainpurpose of the present paper is to document the technical aspects of the
PHOTOS
Monte Carloinstallation and present version use. A multitude of test results and examples are distributedtogether with the program code.The
PHOTOS C++ physics precision is better than its
FORTRAN predecessor and more convenientsteering options are also available. An algorithm for the event record interface necessary forprocess dependent photon emission kernel is implemented. It is used in Z and W decays forkernels of complete first order matrix elements of the decays. Additional emission of finalstate lepton pairs is also available.Physics assumptions used in the program and properties of the solution are reviewed. Inparticular, it is explained how the second order matrix elements were used in design andvalidation of the program iteration procedure. Also, it is explained that the phase spaceparameterization used in the program is exact.Submitted to Comp. Phys. Commun. † This project is financed in part from funds of Polish National Science Centre under decisionsDEC-2011/03/B/ST2/00107 (TP), DEC-2011/03/B/ST2/00220 (ZW). This research was sup-ported in part by the Research Executive Agency (REA) of the European Union under theGrant Agreement PITNGA2012316704 (HiggsTools). able of Contents PHOTOS
Interface . . . . . . . . . . . . . . . . . . . . HepMC . . . . . . . . . HEPEVT type . . . . . . . . . . PHOTOS
Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MC-TESTER
Benchmark Files . . . . . . . . . . . . . . . . . . . . . . . . A Appendix: Interface to internal C part of PHOTOS . . . . . . . . . . . . . A.1 Common Blocks migrated to struct objects of C . . . . . . . . . . . A.2 Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B Appendix: User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.2 LCG configuration scripts; available from version 3.1 . . . . . . . . B.3 Elementary Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.4 Executing Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.5 How to Run
PHOTOS with Other Generators . . . . . . . . . . . . . . B.5.1 Running
PHOTOS C++ Interface in a
FORTRAN environment . . .
Appendix: User Configuration . . . . . . . . . . . . . . . . . . . . . . . . C.1 Suppress Bremsstrahlung . . . . . . . . . . . . . . . . . . . . . . . . . C.2 Force
PHOTOS
Processing . . . . . . . . . . . . . . . . . . . . . . . . . . C.3 Use of the processParticle and processBranch
Methods . . . . . . . C.4 Lepton pair emission and event record momentum unit . . . . . . . C.5 Logging and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . C.6 Other User Configuration Methods . . . . . . . . . . . . . . . . . . . C.7 Creating Advanced Plots and Custom Analysis . . . . . . . . . . . .
Introduction
For a long time,
PHOTOS
Monte Carlo [1, 2] has been used for the generation of bremsstrahlungin the decay of particles and resonances. Over the years the program has acquired popularityand it evolved into a high precision tool [3]. Since 2005, when multi-photon radiation wasintroduced [4] into the program (version 2.15), there were no further public upgrades of theprogram until 2010. The efforts were concentrated on documentation and new tests; phasespace treatment was shown to be exact [5] and for several processes [3, 5, 6] an exact matrixelement was studied with the help of optional weights. Benchmark distributions, includingcomparisons with other simulation programs, were collected on the
MC-TESTER [7] (specialprogram devoted to tests) web page [8] .Such high precision applications require good control of the event record content on which PHOTOS operates. On one side it requests skills and experience of the user and on the other itprovides the flexibility necessary for the study of effects like, for example, systematic errorsfor measurements of anomalous couplings or W cross section. Methods of correlated samplescan be applied .Until 2010 the HEPEVT [11] event record was used as the structure for communication betweenphysics Monte Carlo programs and detector/reconstruction packages. Experimental physi-cists used
HEPEVT for their own applications as well. Later, to gain flexibility,
FORTRAN wasreplaced by
C++ and instead of
HEPEVT , the
C++ event structure
HepMC [12] was used. Nothingprevented moving
PHOTOS to a
C++ environment, allowing the use of event records such as
HepMC , and to rewrite the whole of
PHOTOS to C++ . In fact implementation of the algorithm inthat language is clearer and easier to maintain. Because of its design the
PHOTOS algorithmbenefits from the object oriented features of
C++ . It is our third program, after
MC-TESTER [7]and the
TAUOLA interface [13], already previously ported to
HepMC and
C++ . This completesthe main step of migration of these three programs to the new style.Such migration is convenient for the users too; they can now work with homogeneous
C++ software. From the physics point of view, transformation of
PHOTOS from
FORTRAN to C++ brings some benefits as well. The channel dependent, complete first order matrix elements of
PHOTOS , in
FORTRAN , are available only in special kinematical configurations. With the helpof the new event record interface they become available for general use. For that purpose,better access to the information necessary to orient the spin state of decaying particles is nowprovided.Our paper is organized as follows. Section 2 is devoted to a description of the physics in-formation which must be available in the event record for the algorithm to function. Later,particular requirements for the information stored in
HepMC are given. Section 3 describesthe program structure. In Section 4 methods prepared for extensions to improve the physicsprecision of the generator are explained. Section 5 presents the program tests and bench-marks. A summary, section 6, closes the paper. There are three appendices A, B and Cattached to the paper. Respectively, they describe the interface to the old part of the code,which has been rewritten from
FORTRAN to C , provide a user guide and explain the programconfiguration methods and parameters.This document concentrates on features of PHOTOS version 3.60, for other versions, consult An up-to-date version of the
PHOTOS code described in this paper is available from the web page of ourproject [9]. To exploit such methods in the high precision regime, good control of matrix element properties is nec-essary. As was shown in [10], complications for such methods arise at the second order matrix element only,thus at the precision level of ( α QED π ) ≃ − . EADME files and changelog.txt of the documentation/doxygen directory.
PHOTOS
Interface
The algorithm of
PHOTOS
Monte Carlo can be divided into two parts. The first, internal part,operates on elementary decays. Thanks to carefully studied properties of the QED (scalarQED), the algorithm (with certain probability) replaces the kinematical configuration of theBorn level decay with a new one, where a bremsstrahlung photon, photons or lepton pairs areadded and other particle momenta are modified. This part of the program is sophisticatedfrom the physics point of view [3, 5], but from the point of view of data structures thealgorithm is simple. That is why the gain from re-writing this part of the program to C israther limited. Nonetheless, there were no obstacles for such a transformation to be performedand it is completed now. In fact it was already done previously [14], but the resulting programwas developed too early and did not attract users because of a lack of a C++ event recordformat standard at that time.The typical result of high energy process simulation are events of complex structure. Theyinclude, for example, initial state parton showers, hard scattering parts, hadronization andfinally chains of cascade decays of resonances. A structure similar to a tree is created, butproperties of such data structures are sometimes violated. For its action,
PHOTOS needs toscan an event record (tree) and localize decays (branches in the tree) where it is supposedto act. The decaying particle (mother) and its primary decay products (daughters) haveto be passed into the internal event structure of
PHOTOS . For calculation of matrix elementkernels, mothers of the decaying particle are needed as well. Finally for each daughter a listof all its subsequent decay products has to be formed. Kinematical modifications need to beperformed on all descendants of the modified daughter.In the new
C++ version of the event record part of the algorithm, additional functionalityis added. The first mother of the decaying particle will be localized and passed togetherwith the elementary branching to the internal part of the program. Prior to activation ofthe algorithm for photon(s) (and/or lepton pairs) generation and kinematic construction, thewhole decay branching (supplemented with its mother(s)) will be boosted into the decayingparticle’s rest frame and the first mother will be oriented along the z axis. In many cases, thespin state of the decaying particle can be calculated from kinematics of its production process.Later it is passed on, to the code which calculates the matrix element for the branching.The part of the code responsible for photon(s) (lepton pair) generation and kinematic con-struction has been also rewritten from FORTRAN to C . It has been extended over the last fiveyears and features the options presented above.Before an actual description of the program, let us list the tasks the event record interfacemust be able to perform:1. a method to read particles stored in the event tree.2. a method to add or modify particles of the event tree.3. a method to search for elementary decays over the entire tree of the event. We will use branching to refer to decay of particle or resonance (usually, but not always, represented bya decay vertex) which
PHOTOS can process.
4. a method to form lists of all subsequent decay products originating from each elementarydecay product.5. a method to localize the first mother of the decaying particle.6. a method to localize the second mother for the special case of a t ¯ t pair. The
C++ version of the
PHOTOS interface implements all functionality of its predecessor,
PHOTOS version 2.15 [4] coded in
FORTRAN . The program has the process-dependent correcting weightsof refs [3, 6] installed.
PHOTOS can be attached to any Monte-Carlo program, provided thatits output is available through an event record for which an interface has been provided. Thedefault distribution of
PHOTOS contains an interface for the
HepMC [12] event record, as wellas an interface for an old
FORTRAN event record,
HEPEVT .It seems that HepMC will remain a generally accepted standard for the near future. However,already now several different options for how
HepMC is used are widespread. The possibility ofthe flexible adaptation of our event record interface to different options has been consideredin the design, drawing experience from
MC-TESTER [7, 15].
HepMC
In adapting the
PHOTOS interface to the
C++ event record format the difference between the
HEPEVT event record, with its variant still used by the core of the
PHOTOS code (as a structtype), and the
HepMC event record has to be taken into account. In the first case a
FORTRANcommon block containing a list of particles with their properties and with integer variablesdenoting pointers to their origins and descendants is used. The
HepMC event structure is builtfrom vertices, each of them having pointers to their origins and descendants. Links betweenvertices represent particles (or fields). Fortunately, in both
FORTRAN and
C++ cases, the eventis structured as a tree ; the necessary algorithms are analogous, but nonetheless different.The HepMC structure based on vertices is more convenient for the
PHOTOS interface.In
HepMC , an event is represented by a
GenEvent object, which contains information such asevent id, units used for dimensional quantities in the event and the list of produced particles.The particles themselves are grouped into
GenVertex objects allowing access to mother anddaughter particles of a single decay. Vertices provide an easy way to point to the whole branchin a decay tree that needs to be accessed, modified or deleted if needed. The informationof a particle itself is stored in a
GenParticle object containing the particle id, status andmomentum as well as information needed to locate its position in the decay tree. Thisapproach allows traversing the event record structure in several different ways.The
HepMC event record format is evolving with time, making it necessary to adapt the codeto new versions. The
HepMC versions 2.06, 2.05 and 2.03 were used in the final tests of ourdistribution .Evolution of the HepMC format itself is not a crucial problem. In contrast, conventions on This standard is less commonly used, thus the interface to it is less tested. At least in principle, because in practice its properties may be rather like a graph without universallydefined properties. This makes our task challenging. The interface has also been tested and is fully compatible with the alpha4 version of
HepMC
HepMC represent the main source of technical and alsophysics challenges for our interface. This is quite similar to the previous
HEPEVT - FORTRAN case. Let us discuss this point in more detail now.
While many Monte-Carlo generators (e.g.
PYTHIA 8.1 [16],
HERWIG++ [17]),
SHERPA [18]can store events in
HepMC format, the representations of these events are not subject tostrict standards, and can therefore vary between Monte-Carlo generators or even physicsprocesses. Some examples of these variations include the conventions of status codes, theway documentary information on the event is added, the direction of pointers at a vertex andthe conservation (or lack of conservation) of energy-momentum at a vertex. Below is a listof properties for basic scenario we have observed in Monte-Carlo generators used for testingthe code.This list will serve as a declaration for the conventions of
HepMC filling, which the interfaceshould interpret correctly. • is assumed for all vertices in the event record where PHOTOS is expected to act. • Status codes: only information on whether a given particle is decaying (status 2) orstable (status 1) is used. • Pointers at a vertex are assumed to be bi-directional. That is, the record structuremay be traversed from mother to daughter and from daughter to mother along the samepath.
Extensions/Exceptions to these specifications are handled in some cases. We will callthem options for conventions of event record filling. • Vertices like τ ± → τ ± and τ ∓ → τ ∓ γ where the decaying particle flavor is among itsdecay products will prevent PHOTOS being invoked. • If there is 4-momentum non-conservation in the vertex, PHOTOS will not be invokedtoo. A special kinematic correcting method to remove smaller inconsistencies resultinge.g. from rounding errors is available, but it must be used carefully to avoid action onvertices where four-momentum is not conserved because of physics reasons. • As in the
FORTRAN cases, we expect that new types of conventions for filling the eventrecord will appear, because of physics motivated requirements. Unfortunately, theresulting options do not always guarantee an algebraically closed structure. Hostprogram-specific patches may need to be defined for
PHOTOS . Debugging can then betime consuming, and will need to be repeated for every new case. • In the case of low-mass particles that are vulnerable to numerical fluctuation (suchas muons and electrons), the correct information about a particle’s mass is expected.Since in such cases the mass calculated from a 4-vector can often be incorrect (includingnegative values). An appropriate method of
PHOTOS must be used to correct thatinformation (see C.6). For details see Appendix C.6.
6n the future, an important special case of event record’s filling, with information extractedfrom experimentally observed events (e.g. Z → µ + µ − modified later to Z → τ + τ − ) shouldbe allowed. Obviously, a new type (or types) of HepMC filling will then appear. The possibilityof reverse operation of
PHOTOS , actually to remove photons from the decay vertex may bethen envisaged.A good example for event record divergence from the standard, is the evolution of
PYTHIA .While in version 8.108 the status codes for our example processes took the values 0, 1 or 2only (in the part of the record important for
PHOTOS ), other values were already present inversion 8.135. As a consequence the status code for otherwise nicely decaying particles wasnot always 2 anymore. We have introduced a change in the file PhotosEvent.cxx to adjust.After the change the program should work for all previous cases as before, changes like thisone are usually difficult to validate and complicated tests are necessary. One could investigateif instead of changes to the
PHOTOS algorithm a different choice of input for
PYTHIA wouldnot be a more appropriate solution, but in this case we choose to adapt our algorithm . HEPEVT type
It was rather simple to rewrite
PHOTOS to C++ completely. To profit from numerical tests,the core of
PHOTOS was rewritten to essentially plain C . Common blocks were replaced withstructs, old names of methods and functions were preserved. The C++ part of the code searchesthe whole event for suitable
HepMC vertices for the generation of bremsstrahlung. Once sucha vertex is found it is copied to an internal event record struct which is called hep (in olderversions it was
FORTRAN PH HEPEVT common block); it uses
HEPEVT as a specification for structtype definition. The C code of PHOTOS is then executed. The data structure passed in thisway is rather simple. Only a single vertex consisting of the decaying particle along with itsmothers and daughters is passed. Information on mothers is nececcary for the calculation ofprocess dependent, matrix element based, kernels.A description of the interface to the internal, essentially plain C , parts of the code is given inAppendix A. The choice of splitting the source code into three main modules allows the separation ofthe C code of the numerical algorithm from the abstract C++ interface and the concreteimplementation of the interface created for the appropriate event record. • photos-C This part of the code includes numerical algorithms of
PHOTOS . In particular, the codefor generating photons as well as electron-positron and muon pairs. The
HEPEVT struct At present, our programs,
TAUOLA and
PHOTOS , supplement the event record with new particle entriescarrying bar codes with values starting from 10001. That is the choice resulting from our use of
HepMC methods and defaults.
PHOTOS C++ interface class relation diagramclass located here is responsible for writing the decay branch to be processed into theinternal event record struct hep as well as for writing the output of the processing backto the event record. For further details see Appendix A. • PHOTOS C++
Interface
This is an abstract interface to the event record. The class
PhotosEvent containsinformation regarding the whole event structure, while
PhotosParticle stores all in-formation regarding a single particle. All particles used by the interface are located inthe event in the form of a list of
PhotosParticle objects. The last class located here,
PhotosBranch , contains information regarding elementary branching to be processedby
PHOTOS . In particular, it contains the algorithm which selects single branching forprocessing and filters out branchings that will not be processed. • Event Record Interface
This contains the event record implementation classes. All classes stored here rep-resent the implementation of specific event record interfaces and are responsible forreading, traversing and writing to the event record structure. Only the
PhotosEvent and
PhotosParticle classes must be implemented. The
HepMC event record inter-face is implemented through
PhotosHepMCEvent and
PhotosHepMCParticle . Theseclasses are similar to the analogous
TAUOLA [13] event record classes. An exampleof a minimalistic interface to an event record has been provided through the classes8 hotosHEPEVTEvent and
PhotosHEPEVTParticle . For example, a separate set ofclasses deriving from PhotosParticle and
PhotosEvent can be written for
HepMC events generated by
PYTHIA , treating particle status codes differently than before, anda separate set for
HepMC events taken from other MC generators. The choice betweenthese two implementations can be introduced by the user’s code. • src/eventRecordInterfaces/ - source code for classes which interface with eventrecords. Currently, the HepMC interface and an interface to the
FORTRAN event record
HEPEVT are located here.Classes: – PhotosHepMCEvent - interface to HepMC::GenEvent objects. – PhotosHepMCParticle - interface to HepMC::GenParticle objects. – PhotosHEPEVTEvent - interface to the event structure of the
HEPEVT format,used in the interface to the
HEPEVT common block of
FORTRAN example only. – PhotosHEPEVTParticle - interface to a single particle from the
HEPEVT eventrecord, used in the interface to the
HEPEVT common block of
FORTRAN exampleonly. • src/photosCInterfaces/ - source code for the abstract event record interface.Classes: – Photos - controls the configuration and initialization of PHOTOS . – PhotosEvent - abstract base class for event information. – PhotosParticle - abstract base class for particles in the event. – PhotosBranch - contains one PhotosParticle and pointers to its mothers anddaughters. The main algorithms of the abstract interface, such as invoking
PHOTOS processing or filtering out branchings that will not be processed, is defined here. • src/utilities/ - source code for utilities.Files/classes: – Log - general purpose logging class that allows filtering out output messages ofthe PHOTOS C++ Interface and tracks statistics for each run. – PhotosRandom - random number generator from Ref. [19, 20] taken from
PHOTOSFORTRAN and rewritten to
C++ . – PhotosDebugRandom - static class derived from PhotosRandom that providesseveral tools to store and restore the state of the
PHOTOS random number generator. – PhotosUtilities.cxx - support functions (e.g. boosting, rotations, etc.) • src/photos-C/ - core PHOTOS code. Since version 3.54,
PHOTOS has been fully rewrit-ten to
C++ and located in its own namespace
Photospp . For algorithmic backward This interface is the only way of implementing NLO corrections in programs using the
HEPEVT eventrecord. Let us note that for this part of the code only minimal set of tests was completed, and its use shouldbe restricted, until further tests. This means that no part of the code is shared with old
PHOTOS FORTRAN and both versions can be loadedsimultanously without the risk of one version overwriting the options of the other. the code structure as in FORTRAN version is kept. The appropriate de-scriptions remain valid; in publications as well as in the code, now in
C++ .Files: – photos-C.cxx - core functionality of
PHOTOS . Structures of this code containinternal variables such as weights, angles, four momenta, etc. The
Photos classuses some of these structures to set several initialization options. – HEPEVT struct.cxx - static class translating information about particles passedthrough the abstract event record interface to a
HEPEVT -like structure used by thecore
PHOTOS code. – forW-MEc.cxx - routines to calculate the matrix element in W decays. Notedistinct programming style from the rest of code in the photos-C directory. – forZ-MEc.cxx - routines to calculate the matrix element in Z decays. Notedistinct programming style from the rest of code in the photos-C directory. – pairs.cxx - code for electron-positron and muon pairs emission. • examples/ - examples of different PHOTOS C++
Interface uses. – photos hepevt example - stand alone example with a simple e + e − → τ + τ − event written in HEPEVT format and then processed by
PHOTOS . – photos standalone example - the most basic example which loads pre-generatedevents stored in a file in HepMC format which are then processed by
PHOTOS . – single photos gun example - an example of using the processOne method toprocess only selected vertices within the event record. – photos pythia example - an example of e + e − → Z → µ + µ − events generatedby PYTHIA 8 and processed by
PHOTOS . The analysis is done using
MC-TESTER ,initialization for emission of lepton pairs is demonstrated. – photosLCG pythia example - similar to previous case, prepared to demon-strate LCG scripts. – tauola photos pythia example - an example of
TAUOLA linked with
PYTHIA 8 .The decay chain is processed by
PHOTOS and then analyzed with
MC-TESTER . – testing/photos tauola test - test program, may be useful as an example for theuser’s own work, but rather not as an introductory example. See README files ofthe directory. – testing/photos test - test program, may be useful as an example for user ownwork, but rather not as an introductory example. See
README files of the directory.An example of pair emission use is given. – testing/further subdirectories directories with numerical benchmark results,see Subsection 5.1. • include/ - directory for the header files. • lib/ - directory for the compiled libraries. • documentation/ - contains doxygen documentation and this latex file. The resulting modules are however not interchangeable and the program will not function if the
PHOTOSFORTRAN library is loaded instead of the code encapsulated in the src/photos-C/ directory. .3 Algorithm Outline An overview of the algorithm for the
PHOTOS C++ Interface is given below. For clarity, theexample assumes that the processed event is stored in the
HepMC event record structure.The first step is creation of a
PhotosHepMCEvent object from a
HepMC::GenEvent eventrecord. After that, the process() method should be executed by the user’s code , invokingthe following process:1. The HepMC event record is traversed and a list of all decaying particles is created.2. Each particle is checked and if the resulting branching is a self-decay it is skipped.3. For each remaining particle a branch, including the particle’s mothers and daughtersis created. Special cases consisting of mothers and daughters but without intermediateparticle to be decayed are also added to the list of branches.4. Branchings are filtered out again, this time with the user’s choice of processes to beskipped by PHOTOS .5. Each branching is processed by
PHOTOS separately:(a) The branch is written to a hep struct.(b) The
PHOTOS photon and pair adding algorithm is invoked.(c) The resulting branching is taken back from hep and introduced to the event record.(d) Any changes made by
PHOTOS to the already existing particles invokes kinematicalchanges to their whole decay trees.(e) Finally, the created particles are added to the event record.The underlying
HepMC::GenEvent is hence modified with the insertion of new particles. Al-ternatively, as in our example,
PHOTOS/examples/photos hepevt example.f , the interface
HEPEVT in FORTRAN is used and then the content of
HEPEVT is modified.
The first purpose of the
C++ interface to the
C PHOTOS algorithm is to make available allthe functionality of its
FORTRAN predecessor for
C++ data structures. Some new methods forimproved initialization are introduced. The new program functionality has been prepared toenable extensions, such as emission kernels based on matrix elements or emission of pairs.Let us briefly discuss some of these points. Instead of creating a
PhotosHepMCEvent and processing the whole event, a user may want to execute
Photos::processParticle(...) or Photos::processBranch(...) on the single branching or branch where
PHOTOS is expected to perform its tasks. For details see Appendix C.3. A history entry in the event record, like Z → Z or τ → τ . .1 PHOTOS
Extensions
So far we have presented an algorithm, as it was already implemented in
FORTRAN . Furtherextensions were introduced: • We have prepared the structure (branching including particle’s mothers) for the im-plementation of channel dependent matrix elements. This was integrated into the
C++ version of
PHOTOS . • Methods devised to check the content of the event record are described in AppendixC.5. They need to be used whenever
PHOTOS processes events from a new generator e.g.upgraded versions of
PYTHIA , which may fill the event record in an unexpected way.Experience gained from many years of developing and maintaining the algorithm haveshown that this is the most demanding task; the necessity to adapt to varying physicsand technical inputs of the event record pose a multitude of problems. The nature ofthese difficulties cannot be predicted in advance. • For the sake of debugging we have introduced new control methods and ones whichactivate internal printouts of the C part of the code. The routine PHLUPA [2] can beactivated to verify how an event is constructed/modified, and to investigate energymomentum (non-) conservation or other inconsistencies. This is quite convenient, forexample, for tracing problems in the information passed to
PHOTOS . • Numerical stability is another consideration; it cannot be separated from physics con-straints. The condition E − p = m may be broken because of rounding errors.However, due to intermediate particles with substantial widths, the on-mass-shell con-dition may not be applicable. PHOTOS may be adapted to such varying conditions, butit requires good interaction with users. The protection which removes inconsistenciesin the event record may be a source of unexpected difficulties in other cases.
In the times of
FORTRAN , the
PHOTOS interface used an internal event structure which wasbased on
HEPEVT , adding to it (understood as a data type) an extra variable defining thestatus of particles with respect to QED Bremsstrahlung. We still use event objects based on
HEPEVT but they are declared as C structs and used internally in the PHOTOS algorithm.In some cases, like τ → lν l ν τ , bremsstrahlung was already generated earlier by other gen-erator, and PHOTOS should not be active on such decays. At present, a set of initializationmethods is prepared as described in Appendix C.1. This superseeds the role of QED emissionflags of
FORTRAN times.There is definite room for improvement. For example if the vertex q ¯ q → l ± l ∓ g is encountered(note the presence of g in the final state), the interface could ‘on the fly’ add an intermediate Z into the record and enable PHOTOS on the temporarily constructed decay branching, Z → l ± l ∓ .We can process q ¯ q → l ¯ l without an intermediate Z though.Internally, in the C part of PHOTOS , the data structs of C based on HEPEVT : pho and hep areused, but they store only a single elementary decay. This solution prevented the need to redomany of the FORTRAN era benchmarks. 12
Testing
Some of the most important parts of the
PHOTOS project are its physics oriented tests. Severaldomains of physics tests should be mentioned. Users interested in precision simulations of Z or W decays will find the papers [6, 3, 4] most interesting. There, careful comparisonwith the first order matrix element and confirmation of the agreement was shown. For Z decays, comparisons with a Monte Carlo program based on exclusive exponentiation withup to the second order matrix element is possible and was performed on some benchmarkdistributions. Inclusion of a correcting weight for complete first order matrix elements wasfound to be numerically less important than the absence of the second order matrix elementin the YFS exponentiation scheme used by the reference programs. In these comparisonsthe Monte Carlo programs from LEP [21, 22] were used as the reference. In numerical tests MC-TESTER [7] was used. The advantage of the method is that
C++ and
FORTRAN programresults can be easily compared .For inclusive calculations, FSR radiative corrections are at the one permille level. For semi-inclusive cross sections, such as the total rates of Z decay for events where the hardest photonenergy (or two hardest photon energies) exceed 1 GeV in the Z rest frame, differences betweenresults from PHOTOS , with the matrix element correcting weight turned off, and and YFS basedgenerators of the first or second order were also at the 0.2 % level. On the other hand, iftwo hard photons were requested and invariant masses constructed from leptons and hardphotons were monitored, the level of differences exceeded 30 %. However, even in this regionof phase space,
PHOTOS , without the correcting weight, performs better than programs basedon exponentiation and the first order matrix element only.This conclusion needs to be investigated if realistic experimental cuts are applied. Fortunatelythe necessary programs are available for Z decay. In the case of W decay, second order MonteCarlo generators supplemented with exponentiation are not available at this moment.For users interested in the simulation of background for Higgs searches at the LHC and forany other applications where two hard photon configurations are important, studies basedon the comparison with a double photon matrix element are of interest. For PHOTOS
MonteCarlo such tests were initiated in refs. [2, 23, 24]. Finally, users interested in low energyprocesses where the underlying physics model for photon emission cannot be controlled bytheory sufficiently well (scalar QED may be considered only as the starting point), will profitfrom [5, 6]. In all cases it is important that the program generation cover the full phase-spaceand that there are no approximations in phase-space. As in the
FORTRAN version, the codefeatures approximation in the kernel. In some cases the process dependent complete firstorder kernel is available. At present such an option is prepared (see Section 2.3) for W and Z decays. It is also available for the decays of scalars into two scalars. Then, exact meansexact with respect to scalar QED only.The main purpose of the present paper is program documentation. This is why we also needto cover the program tests that guarantee its proper installation. The physics tests discussedabove do not guarantee that the program will perform well on a particular platform andinstallation. Tests and debugging of the installation are necessary too. If the content of theevent record is non-standard or rounding errors are large, the performance of PHOTOS willdeteriorate. We thank Andy Buckley for checking numerically that our conclusions on the first order exact YFSexponentiation results extend to the programs presently used at the LHC such as SHERPA and HERWIG++. In the phase space region where only one hard photon is tagged this conclusion seems to depend on thevariant of exponentiation in use, [21] or [22].
PHOTOS is whether some energy momentum non-conservationappears. Such offending events should be studied before
PHOTOS and after
PHOTOS is run tomodify them. If it is impossible to understand why inconsistencies for energy momentumnon-conservation were created by
PHOTOS , the authors should be contacted. Sometimes mon-itoring how an event is constructed inside the internal C part of the code may be useful. Forthat purpose a monitoring option is available from the C++ part of the code. In practiceonly rather advanced users will profit from the printouts. However, it may be sent to theauthors and help to quickly identify the cause of the problems.The next step in benchmarking relies on comparisons with reference distributions. At present,we store these tests using
ROOT [25] and our
MC-TESTER program [7].
MC-TESTER
Benchmark Files
Over years of development of the
TAUOLA and
PHOTOS programs a certain level of the au-tomation of tests was achieved. It was found that monitoring all the invariant mass dis-tributions which can be constructed out of a given decay represent a quite restrictive buteasy to implement test. Finding the relative fraction of events for each distinct final statecomplemented that test and is implemented now in the public version of
MC-TESTER . We haveapplied this method for
PHOTOS too. In this case, some soft final state particles have to beignored because we are bound to work with samples which otherwise would exhibit propertiesof unphysical infrared regulators (see Section 6.1 of ref [7] for more details). For the mostpopular decays the benchmarks are collected on our project web page [8]. In our distribu-tion, we have collected numerical results in the directory examples/testing and its sub-directories:
Htautau, pairs, ScalNLO, ttbar, Wenu, Wmunu, WmunuNLO, Zee, Zmumu,ZmumuNLO and
Ztautau . Each of them includes an appropriate initialization file for the par-ticular run of
PYTHIA . Numerical results from long runs of
MC-TESTER based tests are storedfor reference . At present, our choice of tests is oriented toward the LHC user and radiativecorrections in decay of W ’s, Z ’s and Higgs particles. Most users at low energy experimentsuse the FORTRAN version of the code, which is why our tests and examples for the
C++ versionare not geared toward low energy applications yet.
In principle, for the algorithm performing photon(s) construction, the
C++ interface of
PHOTOS introduces nothing new with respect to the version of
PHOTOS available in
FORTRAN . That iswhy the tests which are collected in [8] are not recalled here, they were only reproduced andfound to be consistent with the ones for old
PHOTOS FORTRAN . However the algorithm forcombining a modified branching, including the added photon(s), to the rest of the event treewas rewritten. Examples of spin dependent observables are of more interest because theytest this new part of the code. The π energy spectrum in the decaying Z boson rest-frameis the first example. The π ± originates from a τ ± → π ± ν decay and, as was already showna long time ago [26], its energy spectrum is modified by bremsstrahlung both in τ and Z decays. The net bremsstrahlung effect is similar to the one of e.g. Z polarization. In Fig. 2this result is reproduced.Let us now turn to tests using observables which are sensitive to transverse spin effects. For See Appendix C.5 for the command
Log::LogPhlupa(int from, int to) Details on the initialization for the runs are given in
README-benchfiles . H → τ + τ − , τ ± → ρ ± ν τ , ρ ± → π ± π , where PHOTOS may act on any of the branchings listed above. An inappropriate action of the
C++ part of
PHOTOS could result in faulty kinematics, manifesting itself in a failure of energy-momentumconservation or faulty spin correlation sensitive distributions. However, as we can see fromFig. 3, the distributions (as they should be) remain nearly identical to the ones given in[13, 27]. The emission of soft and/or collinear photons to the τ + or τ − does not changethe effects of spin correlations. The kinematical effects of hard, non collinear photons areresponsible for dips in the acoplanarity distributions at 0, π and 2 π . × (a) bremsstrahlung from τ + decay only × (b) bremsstrahlung from Z , τ + and τ − decays Figure 2: Bremsstrahlung effects for longitudinal spin observables for the cascade decay: Z → τ + τ − , τ ± → π ± ν . The π + energy spectrum in the Z rest-frame is shown. The redline is for bremsstrahlung switched off and green (light grey) when its effect is included.In the left plot, bremsstrahlung is in τ + decay only. In the right plot, bremsstrahlungfrom Z and τ ± decays is taken into account. These plots have been prepared using a cus-tom UserTreeAnalysis of MC-TESTER . They can be recreated with the test located in the examples/testing/Ztautau directory, see examples/testing/README-plots for technicaldetails. Results are consistent with Fig. 5 of Ref. [28]. × (a) selection C × (b) selection D Figure 3: Bremsstrahlung effects for transverse spin observable: The distribution of theacoplanarity angle of oriented planes spanned respectively on the π + ρ + and π − ρ − momentais shown. The distribution is defined in the rest frame of the ρ + ρ − pair for the scalarHiggs decay chain H → τ + τ − , τ ± → ρ ± ν τ , ρ ± → π ± π . PHOTOS is used to generatebremsstrahlung. The red curve indicates the distribution when bremsstrahlung effects areignored and for the green curve (light grey) only events with bremsstrahlung photons ofenergy larger than 1 GeV in the H rest frame are taken. For the definition of selections Cand D see. [29, 30]. These plots have been created using a custom UserTreeAnalysis of MC-TESTER . They can be recreated by the test located in the examples/testing/Htautau directory, see examples/testing/README-plots for technical details.In Ref. [31] a discussion of the systematic errors for the measurement of the Z cross sectionat the LHC is presented. One of the technical tests of our software is to obtain Fig. 1b15f that paper. In our Fig. 4 we have reproduced that plot using PYTHIA 8.1 and
PHOTOS .Qualitatively, the effect of FSR QED bremsstrahlung is quite similar in the two cases.In Fig. 4 we present a plot of the bare electron pair (which means electrons are not combinedwith the collinear photons that accompany them) from Z decay with and without PHOTOS .It is similar to the plots shown for
Horace or Winhac ; see Refs. [32, 33] and related studies.One should bear in mind that this is again a technical test with little direct application tophysics. As explained in the figure caption, the LHC production process was used.
40 50 60 70 80 90 100 110 120 130 14000.20.40.60.811.21.41.6110 Figure 4: Distribution of the bare e + e − invariant mass. The green curve (light grey)represents results when final state bremsstrahlung is generated (with the help of PHOTOS
Monte Carlo). For the red curve FSR bremsstrahlung is absent. The simulation of ppcollisions at 14 TeV center-of-mass energy is performed using
PYTHIA 8.1 . The
Z/γ medi-ated hard process is used. This plot has been created using a custom
UserTreeAnalysis of MC-TESTER . It can be recreated with the test located in the examples/testing/Zee directory,see examples/testing/README-plots for technical details.We have also checked that
PHOTOS works for t ¯ t events and the simulations explained in [24]can be repeated. For this purpose we have produced t ¯ t pairs in pp collisions at 14 TeV center-of-mass energy. We have produced rates for events with zero, one or at least two photons ofenergy above 0.001 of the t ¯ t pair mass (energies are calculated in the hard scattering frame).Results are given in the following table which is constructed from gg → t ¯ t events only:Final state Branching Ratio (%) ± Statistical Errors (%) e tt ± e ttγ ± e ttγγ ± ± Statistical Errors (100M event samples)
KKMC CEEX2 (%)
KKMC CEEX1 (%)
PHOTOS exp. (%) Z → µ + µ − ± ± ± Z → γµ + µ − ± ± ± Z → γγµ + µ − ± ± ± MC-TESTER ’s LC-analysis from Ref. [15] was used for calculation of the event rates . ROOT files for differential distri-butions are collected in the directory examples/testing/ttbar . Let us now turn to an example of the test for the two photon final state configuration. Wecompare (i)
KKMC [22] with exponentiation and second order matrix element (
CEEX2 ), (ii)
KKMC with exponentiation and first order matrix element (
CEEX1 ) and finally (iii) the resultsof
PHOTOS with exponentiation activated. As one can see from the table, the rates coincidefor the three cases up to two permille for the event configurations where zero, one or at leasttwo photons of energy above 1 GeV accompany the µ + µ − pair.Agreement at this level is not seen in the differential distributions, see Fig. 5. For examplethe spectrum of the two photon mass is quite different between the first and second orderexponentiation result. This is of potential interest for background simulations for H → γγ .In contrast, the difference between the results from PHOTOS and
CEEX2 are much smaller.
PHOTOS exploits the first order matrix element in a better way than exponentiation. As aconsequence it reproduces terms resulting in second order leading logarithms. This obser-vation is important not only for the particular case of Z decay but for the general case ofdouble bremsstrahlung in any decay as well.The numerical results collected here provide part of the program benchmarks. They areof limited but nonetheless of some physics interest as well. PHOTOS provides only one stepin the simulation chain: bremsstrahlung in decays of particles or resonances. One can askthe question of whether such a specialized unit is of interest and whether it is not betterto provide the complete chain for “truth physics simulation” as a single simulation package.Obviously, this will depend on particular needs. Final state QED corrections can be separatedfrom the remaining genuine electroweak corrections and in particular the initial state QEDbremsstrahlung from quarks. One should bear in mind, that final state bremsstrahlung needsto be disentangled from detector acceptance dependencies and is usually not of interest initself. This must be done e.g. to measure the properties of weak bosons.One should bear in mind that even for QED FSR alone, the discussion of the physics precisionof the simulation result requires further checks. In the case of Z decays, Refs. [3, 4] may not beenough. With increasing precision, the estimation of uncertainty becomes dependent on theparticular choice of details for the experimental cuts. Comparisons of different calculationsbecome important too. A good example of such work in the context of other measurementscan be found in Refs. [34, 35]; for the simulation of FSR QED corrections. The Monte Carloprograms collected for PHOTOS generator tests are probably enough. A discussion of QEDinitial final state interference may follow the strategy presented in [36]. There, the questionof experimental cuts must be included as well. Once these steps are finished, discussion of We do not supplement the list of final state particles with the second mother, in contrast to the choiceused in
LC-analysis from Ref. [15]. (a) CEEX2 : red;
CEEX1 : green (b) CEEX2 : red;
PHOTOS : green
Figure 5: The spectrum of the γγ invariant mass, for the bremstrahlung photons in Z → µ + µ − decays. Events with two hard photons, both of energy above 1 GeV in the Z rest frame are taken. Comparisons are shown for CEEX2 and
CEEX1 (left plot), and
CEEX2 and
PHOTOS (right plot). The prediction from
PHOTOS is clearly superior for the simulationof Higgs boson backgrounds. In the case of solutions based on YFS exponentiation, thesecond order matrix element must be taken into account. Fig. 5(b) was obtained from ourexample, examples/testing/Zmumu , after adaptation of the center-of-mass energy (91.17GeV) and test energy threshold (1 GeV). Samples of 100 million events were used. See examples/testing/README-plots for technical details. Reference
ROOT files for
KKMC CEEX samples are, however, created outside of the
PHOTOS distribution package.complete electroweak corrections in the context of realistic observables should be simplified.Genuine weak corrections have to be taken into account separately. Such solutions may bepossible, if together with the
PHOTOS Interface , weak corrections are provided, for example,using the
TAUOLA Interface . A discussion of the complete electroweak corrections, as shownin Fig. 1a of [31], is not the purpose of our document. Let us point out however thatelectroweak non-QED corrections can be, in principle, installed into the
PYTHIA 8.1 + PHOTOS simulation using the e.g.
TAUOLA interface [13]. But for such a solution to be precise, furtherwork is needed [37].Sizeable initial state QED corrections are usually embodied in units simulating parton show-ers. This may need some experimental analysis as well. Experimental data from LEP1were revisited by the DELPHI collaboration [38]. Tension between data and the theoret-ical description was mentioned. This may mean that the description of initial state QEDbremsstrahlung at the LHC will need to be re-investigated using LHC data as well. That isalso why it might be useful to keep initial state QED, final state QED and their interferencecorrections in separate modules.
We have presented a new version of
PHOTOS
Monte Carlo. The part of
PHOTOS which operateson event records is now rewritten into
C++ and an interface to the
HepMC event record isprepared. Interface to the
HEPEVT event record of
FORTRAN is provided as well. The physicsperformance of the program is the same, or better, than that of the
FORTRAN/HEPEVT versionand better steering options are introduced. When an elementary decay is to be modified by
PHOTOS , it is first transformed to its rest frame. The z -axis is orientated along the decayingparticle’s mother’s direction, as seen in this rest frame. Such modification is necessary to18alculate process dependent kernels featuring the complete first order matrix element. Theappropriate kernels explained in Refs. [3, 5, 6] are installed into the version, now fully in C ,of the internal algorithms of PHOTOS . The necessary information is extracted from the eventrecord and used. No more parts of the algorithm are left in
FORTRAN . The remaining
FORTRAN part of the code is for the optional interface to
HEPEVT .Finally let us point to ref. [39]. Thanks to this work, for LHC applications in Z and W decays, the PHOTOS
Monte Carlo systematic error was established at 0.3%, even 0.2% for thecase when matrix element corrections were activated. The estimation is valid for completefinal state radiative corrections, not for photonic bremsstrahlung alone, even in the case whenlepton pair emission is not taken into account.
Acknowledgements
Useful discussions with P. Golonka during the early stage of project development and discus-sions with members of the ATLAS and CMS collaborations and the LCG/Genser team areacknowledged. Nice atmosphere of Galileo Galilei Institute of Theoretical Physics in Firenzewhere part of this work was performed is mentioned.Partial support by the Polish-French collaboration no. 10-138 within IN2P3 through LAPPAnnecy and during the years leading to completion of this work is also acknowledged.
References [1] E. Barberio, B. van Eijk, and Z. W¸as,
Comput. Phys. Commun. (1991) 115.[2] E. Barberio and Z. W¸as, Comput. Phys. Commun. (1994) 291–308.[3] P. Golonka and Z. Was, Eur. Phys. J.
C50 (2007) 53–62, hep-ph/0604232 .[4] P. Golonka and Z. Was,
Eur. Phys. J.
C45 (2006) 97–107, hep-ph/0506026 .[5] G. Nanava and Z. Was,
Eur. Phys. J.
C51 (2007) 569–583, hep-ph/0607019 .[6] G. Nanava, Q. Xu, and Z. Was,
Eur.Phys.J.
C70 (2010) 673–688, .[7] N. Davidson, P. Golonka, T. Przedzinski, and Z. Was,
Comput.Phys.Commun. (2011) 779–789, .[8] P. Golonka, G. Nanava, and Z. Was, Tests of PHOTOS Hard Bremsstrahlung,http://mc-tester.web.cern.ch/MC-TESTER/PHOTOS-MCTESTER/.[9] N. Davidson, T. Przedzinski, and Z. Was, http://photospp.web.cern.ch/photospp/.[10] R. Kleiss,
Nucl. Phys.
B347 (1990) 67–85.[11] G. Altarelli, (Ed. ), R. Kleiss, (Ed. ), and C. Verzegnassi, (Ed. ), CERN-89-08-V-3.[12] M. Dobbs and J. B. Hansen,
Comput. Phys. Commun. (2001) 41–46,lcgapp.cern.ch/project/simu/HepMC/.[13] N. Davidson, G. Nanava, T. Przedzinski, E. Richter-Was, and Z. Was,
Com-put.Phys.Commun. (2012) 821–843, .[14] P. Golonka, Thesis for MSc. degree, FNPT, UMM Cracow,http://cern.ch/Piotr.Golonka/MC/photos.1915] P. Golonka, T. Pierzchala, and Z. Was,
Comput. Phys. Commun. (2004) 39–62, hep-ph/0210252 .[16] T. Sjostrand, S. Mrenna, and P. Skands,
Comput. Phys. Commun. (2008) 852–867, .[17] M. Bahr et al. , Eur. Phys. J.
C58 (2008) 639–707, .[18] T. Gleisberg et al. , JHEP (2009) 007, .[19] F. James, Comput. Phys. Commun. (1990) 329–344.[20] G. Marsaglia and A. Zaman, Florida State Univ. report FSU-SCRI-87-50 (1987).[21] S. Jadach, B. F. L. Ward, and Z. W¸as,
Comput. Phys. Commun. (1994) 503.[22] S. Jadach, Z. W¸as, and B. F. L. Ward, Comput. Phys. Commun. (2000) 260, Up todate source available from http://home.cern.ch/jadach/ .[23] E. Richter-Was,
Z. Phys.
C64 (1994) 227–240.[24] E. Richter-Was,
Z. Phys.
C61 (1994) 323–340.[25] I. Antcheva et al. , Comput. Phys. Commun. (2009) 2499–2512.[26] F. Boillot and Z. Was,
Z. Phys.
C43 (1989) 109.[27] N. Davidson, T. Przedzinski, E. Richter-Was, and Z. Was,http://tauolapp.web.cern.ch/tauolapp/.[28] P. H. Eberhard et al. , To appear in the Proceedings of the Workshop on Z Physics atLEP, edited by G. Altarelli, R. Kleiss and V. Verzegnassi (CERN-89-08 v.1-3) held inGeneva, Switzerland, Feb 20-21 and May 8-9, 1989.[29] G. R. Bower, T. Pierzchala, Z. Was, and M. Worek,
Phys. Lett.
B543 (2002) 227–234, hep-ph/0204292 .[30] K. Desch, A. Imhof, Z. Was, and M. Worek,
Phys. Lett.
B579 (2004) 157–164, hep-ph/0307331 .[31] N. E. Adam, V. Halyo, and S. A. Yost,
JHEP (2008) 062, .[32] C. M. Carloni Calame, G. Montagna, O. Nicrosini, and M. Treccani, Phys. Rev.
D69 (2004) 037301, hep-ph/0303102 .[33] W. Placzek and S. Jadach, http://cern.ch/placzek/winhac.[34] S. Jadach, E. Richter-Was, B. F. L. Ward, and Z. Was,
Phys. Lett.
B353 (1995) 362–372.[35] A. Arbuzov et al. , Phys. Lett.
B383 (1996) 238–242, hep-ph/9605239 .[36] S. Jadach, B. Pietrzyk, E. Tournefier, B. F. L. Ward, and Z. Was,
Phys. Lett.
B465 (1999) 254–259, hep-ph/9907547 .[37] D. Bardin, private communication.[38] DELPHI Collaboration, J. Abdallah et al. , Eur. Phys. J.
C67 (2010) 343–366, .[39] A. Arbuzov, R. Sadykov, and Z. Was,
Eur.Phys.J.
C73 (2013), no. 11 2625, .[40] http://root.cern.ch/root/Availability.html .2041] lcgsoft.web.cern.ch/lcgsoft/.[42] M. Kirsanov, A. Ribon, and O. Zenin,
PoS
ACAT08
Phys.Rev.
D49 (1994) 1178–1182.[45] R. Sadykov and Z. Was, in preparation. 21
Appendix: Interface to internal C part of PHOTOS
This appendix is addressed to developers of the interface, and special users interested inadvanced options of
PHOTOS . The
COMMON blocks of
FORTRAN discussed below were used in theprogram up to version 3.53. Starting from version 3.54 some of these
COMMON blocks werepreserved, as the struct objects of C . The following ones may be of particular interest forthe user: PHOCOP, PHOKEY, PHOSTA . Names of variables and structs are not modified withrespect to
FORTRAN , the
C++ definition style is however adopted: small letters are used forstructs and their variable names.The event record common block,
HEPEVT , is preserved but for use only in the
FORTRAN exam-ples. The interface is available through the classes
PhotosHEPEVTEvent.h and
PhotosHEPEVTParticle.h .Let us recall once again, that internally in the
C++ PHOTOS code, the
HEPEVT -like data typeis used in structs declaration.
A.1 Common Blocks migrated to struct objects of C
In the following let us list the original common blocks of
FORTRAN PHOTOS which are in fact nowreplaced with struct objects of C . To simplify and to preserve continuity of the mathematicalformulae shapes, in many places we use aliases to the struct elements which differ only inthat they are written in capital letters instead of small ones. Note that relevant parameterslisted only here, can be set through the appropriate accessors see Appendix C.6 for moreexplanations. PHOCOP coupling constant and related parameters.
ALPHA double coupling constant α QED . XPHCUT double minimal energy (in units of half of the decaying particle’s mass) forphotons to be explicitly generated.
PHOKEY keys and parameters controlling the algorithm options.
FSEC double internal variable for algorithm options, the default is FSEC=1.0 .
FINT double maximum interference weight.
EXPEPS double technical parameter which blocks the crude level high photon mul-tiplicity from configurations less probable than EXPEPS. The default is 10 − . INTERF bool switch for interference, in the matrix element weight.
ISEC bool switch for double bremsstrahlung generation.
ITRE bool switch for bremsstrahlung generation up to a multiplicity of 4.
IEXP bool switch for exponentiation mode.
IFTOP bool switch for photon emission in top pair production in quark (gluon) pairannihilation.
IFW bool switch for leading effects of the matrix element in leptonic W decays. PHOSTA
Status information.
STATUS[ 10 ] int Status codes for the last 10 errors/warnings that occurred.22
HPICO π value definition. PI double π . TWOPI double ∗ π . A.2 Routines
In the following let us list routines which are called from the interface.
PHODMP prints out the content of struct hep .Return type: void
Parameters: none
PHOTOS MAKE C like
PHOTOS MAKE from the
FORTRAN part of the interface, but now in C .Return type: void Parameters:1. int id
ID of the particle from which
PHOTOS starts processing. In the
C++ case theimportance of this parameter is limited as only one branch, reduced to the decay(process) under consideration, is in the hep struct at a time.
PHCORK initializes kinematic corrections.Return type: void
Parameters:1. int modcor type of correction. See Ref. [4] for details.
IPHQRK enables/blocks (2/1) emission from quarks.Return type: int
Parameters: int
IPHEKL enables/blocks (2/1) emission in: π → γe + e − .Return type: int Parameters: int
B Appendix: User Guide
B.1 Installation
Photos C++ Interface is distributed in the form of an archive containing source files andexamples. Currently only the Linux and Mac OS operating systems are supported: othersystems may be supported in the future if sufficient interest is found. For this case LCG configuration scripts explained in Appendix B.2 have to be used.
HepMC [12] (version 2.03 or later) and requires that eitherits location has been provided or compilation without
HepMC has been chosen as an optionduring the configuration step. The later is only sufficient to compile the interface and to runthe
HEPEVT example.In order to run further examples located in the /examples directory,
HepMC is required. Torun all of the available examples, it is required to install: • ROOT [40] version 5.18 or later • PYTHIA 8.2 [16] or later . • MC-TESTER [15, 7] version 1.24 or later. Do not forget to type make libHepMCEvent after compilation of
MC-TESTER is done. • TAUOLA [13] version 1.0.5 or later.
TAUOLA must be compiled with
HepMC .In order to compile the
PHOTOS C++
Interface: • Execute ./configure with the additional command line options: --with-hepmc= < path > provides the path to the HepMC installation directory. Onecan also set the
HEPMCLOCATION variable instead of using this directive. To compile theinterface without
HepMC use --without-hepmc--prefix= < path > specifies the installation path. The include and lib directorieswill be copied there if make install is executed later. If none has been provided, thedefault directory for installation is /usr/local . • Execute make • Optionally, execute make install to copy files to the directory provided during con-figuration.The
PHOTOS C++ interface will be compiled and the /lib and /include directories will containthe appropriate libraries and include files.In order to compile the examples, compile the
PHOTOS C++ interface, enter the /examples directory and: • Execute ./configure to determine which examples can be compiled. Optional paths,required to compile additional examples and tests, can be provided as command lineoptions (note that all of them are required for tests located in examples/testing directory): --with-pythia8= < path > provides the path to the Pythia8 installation directory.One can set the
PYTHIALOCATION variable instead of using this directive. --with-mc-tester= < path > provides the path to the MC-TESTER installation di-rectory (the libHepMCEvent must be compiled as well, see Ref. [7] for more details).One can set the
MCTESTERLOCATION variable instead of using this directive. This op-tion implies that
ROOT has already been installed (since it is required by
MC-TESTER ). Examples can be adapted to use pythia8.1 . The necessary changes are explained in examples/README-PYTHIA-VERSIONS . In fact, many of our numerical results stored in a code tar ball wereobtained with older versions of
PYTHIA . ROOT directory bin should be listed in the variable
PATH and the
ROOT libraries in
LD LIBRARY PATH . --with-tauola= < path > provides the path to the TAUOLA installation directory.One can set the
TAUOLALOCATION variable instead of using this directive. • Execute make
The /examples directory will contain the executable files for all examples that can be com-piled and linked. Their availability depends on the optional paths listed above. If neither
HepMC , Pythia8 , Tauola nor
MC-TESTER are accessible, only the
HEPEVT example will beprovided.
B.2 LCG configuration scripts; available from version 3.1
For our project still another configuration/automake system was prepared for use in LCG/Genserprojects [41, 42].To activate this set of autotool based [43] installation scripts, enter the platform directoryand execute the use-LCG-config.sh script. Then, the installation procedure and the namesof the configuration script parameters will differ from the ones described in our paper. In-struction given in the ’./INSTALL’ readme file, created by the use-LCG-config.sh script,should be followed. One can also execute ./configure --help , which will list all optionsavailable for the configuration script.Breif information on these scripts can be found in README in the main directory as well.
B.3 Elementary Tests
The most basic test which should be performed, for our custom examples but also for auser’s own generation chain, is verification that the interface is installed correctly, photonsare indeed added by the program and that energy momentum conservation is preserved .In principle, these tests have to be performed for any new hard process and after any newinstallation. This is to ensure that information is passed from the event record to the interfacecorrectly and that physics information is filled into the HepMC event in the expected manner.Misinterpretation of the event record content may result in faulty
PHOTOS operation. We have used the expertise and advice of Dmitri Konstantinov and Oleg Zenin in organization of config-uration scripts for our whole distribution tar-ball as well. Thanks to this choice, we hope, our solution will becompatible with ones in general use. We have performed such tests for
HepMC events obtained from
PYTHIA 8.1 , PYTHIA 8.135 , PYTHIA8.165 , PYTHIA 8.185 and
PYTHIA 8.201 using all configurations mentioned in this paper, all config filesin examples directory and subdirectories of examples/testing . Further options for initializations (partonshower hadronization or QED bremsstrahlung on/off etc.) were also studied for different
PYTHIA 8.1 versions.This was a necessary step in our program development.However, we do not document studies of
Pythia physics initialization for all of its versions. Thatis why, distributions monitoring production processes obtained from distributed initialization for
PYTHIA8.201 , may differ from the reference ones. See e.g.
User Histograms , plots mother-PT mother-eta , in examples/testing/ScalNLO or examples/testing/WmunuNLO . .4 Executing Examples Once elementary tests are completed one can turn to the more advanced ones. The purposeis not only to validate the installation but to demonstrate the interface use.The examples can be run by executing the appropriate .exe file in the /examples directory.In order to run some more specific tests for the following processes: H → τ + τ − , e + e − → t ¯ t , W → eν e , W → µν µ , Z → e + e − , Z → µµ or Z → τ + τ − , K S → ππ , the main programsresiding in the subdirectories of /examples/testing should be executed. Note that all pathslisted as optional in Appendix B.1 are required for these tests to work. In all cases thefollowing actions have to be performed: • Compile the
PHOTOS C++
Interface. • Check that the appropriate system variables are set. Execution of the script /configure.paths.sh can usually perform this task; the configuration step announcesthis script. • Enter the /examples/testing directory. Execute make . Modify test.inc if needed. • Enter the sub-directory for the particular process of interest and execute make .The appropriate .root files as well as .pdf files generated by
MC-TESTER will be created insidethe chosen directory. One can execute ’make clobber’ to clean the directory. One can alsoexecute ’make run’ inside the /examples/testing directory to run all available tests one afteranother. Changes in source code can be partly validated in this way. Most of the tests arerun using the executable examples/testing/photos test.exe . The K S → ππ , H → τ + τ − and Z → τ + τ − examples require examples/testing/photos tauola test.exe to be run.After generation, MC-TESTER booklets will be produced, comparisons to the benchmark fileswill be shown. A set of benchmark
MC-TESTER root files have been included with the interfacedistribution. They are located in the subdirectories of examples/testing/ . Note that forthe W → eν e , W → µν µ and Z → µµ examples, differences higher than statistical error willshow. This is because photon symmetrization was used in the benchmark files generated with KKMC , and not in the ones generated with
PHOTOS . In the case of
KKMC the generated photonsare strictly ordered in energy. In the case of
PHOTOS they are not. Nonetheless, on average,the second photon has a smaller energy than the one written as the first in the event record.The comparison booklets can be useful to start new work or simply to validate new versionsor new installations of the
PHOTOS interface.In Appendix C, possible modifications to the example’s settings are discussed. This may beinteresting as an initial step for user’s physics studies. The numerical results of some of thesetests are collected in Section 5.2 and can be thus reproduced by the user.
B.5 How to Run
PHOTOS with Other Generators
If a user is building a large simulation system she or he may want to avoid integration with ourfull configuration infrastructure and only load the libraries. For that purpose our stand-aloneexample examples/photos standalone example.exe is a good starting point.In order to link the libraries to the user’s project, both the static libraries and shared objectsare constructed. To use the
PHOTOS interface in an external project, additional compilationdirectives are required. For the static libraries:26 add -I
LD LIBRARY PATH .
Photos.h and
PhotosHepMCEvent.h (or any other header file for the class implementing abstract class
PhotosEvent ) With that,the
Photos class can be used for configuration and
PhotosHepMCEvent for event processing.
B.5.1 Running
PHOTOS C++ Interface in a
FORTRAN environment
For backward-compatibility with
HEPEVT event records, an interface has been prepared al-lowing the
PHOTOS C++ Interface to be invoked from the
FORTRAN project. An example, photos hepevt example.f , has been prepared to demonstrate how
PHOTOS can be initializedand executed from
FORTRAN code. Since
PHOTOS works in a
C++ environment, photos hepevt example interface.cxx must be introduced to invoke
PHOTOS .Since version 3.54,
PHOTOS is fully in
C++ and initialization can no longer be performed from
FORTRAN code through the use of common blocks. In particular, information from the field
QEDRAD localized in
FORTRAN times common block
PHOQED – the extension of
HEPEVT isignored. The
Photospp initialization methods can be used easily instead.Note that in the case of
HEPEVT , the
PHOTOS algorithm has to modify the pointers (stored asinteger variables) between mothers and daughters for all particles stored downstream of theadded photons or lepton pairs. This part of the code was not replicated in full detail. Also,most of our tests were performed only on cases where the modified decay was the last one inthe event record, thus shifting consecutive entries was not necessary. We do not foresee theuse of the program and its development for circumstances distinct from these.
C Appendix: User Configuration
C.1 Suppress Bremsstrahlung
In general,
PHOTOS will attempt to generate bremsstrahlung for every branching point in theevent record. This is of course not always appropriate. Already inside the internal C part of PHOTOS , bremsstrahlung is normally prevented for vertices involving gluons or quarks (withthe exception of top quarks). 27his alone is insufficient. By default we suppress bremsstrahlung generation for verticeslike l ± → l ± γ because a “self-decay” is unphysical. We cannot request that all incomingand/or outgoing lines are on mass shell, because it is not the case in cascade decays featuringintermediate states of sizeable width. If a parton shower features a vertex with l ± → l ± γ with the virtuality of the incoming l ± matching the invariant mass of the outgoing pair thenthe action of PHOTOS at this vertex will introduce an error. This is prevented by forbiddingbremsstrahlung generation at vertices where one of the decay products has a flavor whichmatches the flavor of an incoming particle.Some exceptions to the default behavior may be necessary. For example in cascade decays,the vertex ρ → ρπ may require the PHOTOS algorithm to be activated.Methods to re-enable these previously prevented cases or to prevent generation in specialbranches have been introduced and are presented below. • Photos::suppressBremForDecay(daughterCount, motherID, d1ID, d2ID, ...)
The basic method of channel suppression. The number of daughters,
PDGID of themother and the list of
PDGID s of daughters must be provided. There is no upper limitto the number of daughters. If a decay with the matching pattern is found,
PHOTOS will skip the decay. The decay will be skipped if it contains additional photons orother particles, as long as all of the particles from the pattern are present in the list ofdaughters. • Photos::suppressBremForDecay(0, motherID)
When only the
PDGID of the mother is provided, (the daughterCount is 0)
PHOTOS willskip all decay channels of this particle. • Photos::suppressBremForBranch(daughterCount, motherID, d1ID, d2ID, ...)Photos::suppressBremForBranch(0, motherID)
The usage of this function is similar to the two cases of the previous function. Thedifference is that
PHOTOS will skip not only the corresponding channel, but also allconsecutive decays of its daughters, making
PHOTOS skip the entire branch of decaysinstead of just one. • Photos::suppressAll()
All branchings will be suppressed except those that areforced using the methods described in the next section. • Example:
Photos::suppressBremForDecay(3, 15, 16, 11, -12);Photos::suppressBremForDecay(2, -15, -16, 211);Photos::suppressBremForDecay(0, 111);
If the decays τ − → ν τ e − ¯ ν e or τ + → ¯ ν τ π + are found, they will be skipped by PHOTOS .In addition, all decays of π will also be skipped. Note, that the minimum number ofparameters that must be provided is two - the number of daughters (which should be zeroif suppression for all decay channels of the particle is chosen) and the mother PDGID . Photos::suppressBremForBranch(2, 15, 16, -213);
When the decay τ − → ν τ ρ − is found, it will be skipped by PHOTOS along with the decays Note that the first line of this example states that any decays of τ − that contain ν τ , e − and ¯ ν e will beskipped regardless of how many other particles are in the decay. So, for example, τ − → ν τ e − ¯ ν e γ will beskipped as well. It is important to realize that excluding τ − → ν τ π − leads to exclusion of τ − → ν τ π − π aswell. If it is not required it must be allowed separately. f ρ − (in principle also ν τ ) and all their daughters. In the end, the whole decay treestarting with τ − → ν τ ρ − will be skipped. In future, an option to suppress a combination of consecutive branches may be introduced.For example if bremsstrahlung in leptonic τ decays is generated by programs prior to PHOTOS ,and the decay is stored in
HepMC as the cascade τ ± → W ± ν , W ± → l ± ν , PHOTOS must beprevented from acting on both vertices, but only in cases when they are present one afteranother. One can also think of another
PHOTOS extension. If a vertex q ¯ q → l ± l ∓ is found, thenit should not be ignored that intermediate state can be then attributed, q ¯ q → Z/γ ∗ → l ± l ∓ ,and used for matrix element calculation. C.2 Force
PHOTOS
Processing
Forcing
PHOTOS to process a branch can be used in combination with the suppression of allbranches i.e. to allow selection of only a particular processes for bremsstrahlung generation.Forced processing using the methods below has higher priority than the suppression describedin the previous section, therefore even if both forcing and suppressing of the same branch ordecay is done (regardless of order), the processing will not be suppressed. • Photos::forceBremForDecay(daughterCount, motherID, d1ID, d2ID, ...)Photos::forceBremForDecay(0, motherID)
The usage of this function is similar to
Photos::suppressBremForDecay(...) de-scribed in the previous section. If a decay with the matching pattern is found,
PHOTOS will be forced to process the corresponding decay, even if it was suppressed by any ofthe methods mentioned in the previous section. • Photos::forceBremForBranch(daughterCount, motherID, d1ID, d2ID, ...)Photos::forceBremForBranch(0, motherID)
The usage is similar to the above functions. The difference is that
PHOTOS will forcenot only the corresponding channel, but also all consecutive decays of its daughters,making
PHOTOS process the entire branch of decays instead of just one. This methodcan activate part of the later branch previously prevented. • Example:
Photos::suppressAll();Photos::forceBremForDecay(4, 15, 16, -211, -211, 211);Photos::forceBremForDecay(2, -15, -16, 211);Photos::forceBremForBranch(0, 111);
Since suppression of all processes is used, only the listed decays will be processed, theseare τ − → ν τ π − π − π + , τ + → ¯ ν τ π + and all instances of the decay of π and its descen-dants. C.3 Use of the processParticle and processBranch
Methods
In Section 3.3 the algorithm for processing a whole event record is explained and is providedthrough the process() method. To process a single branch in the event record, in a wayindependent of the entire event, a separate method is provided.29
Photos::processParticle(PhotosParticle *p)
The main method for processing a single particle decay vertex. A pointer to a particlemust be provided. Pointers to mothers and daughters of this particle should be acces-sible through this particle or its event record. From this particle a branch containingits mothers and daughters will be created and processed by
PHOTOS . • Photos::processBranch(PhotosParticle *p)
Usage is similar to the above function. When a pointer to a particle is provided,
PHOTOS will process the whole decay branch starting from the particle provided.An example, single photos gun example.c , is provided in the directory /examples showinghow this functionality can be used to process the decay of selected particles. Z → τ + τ − decays are generated and the event record is traversed searching for the first τ − particle inthe event record. Instead of processing the whole event, only the decay of a τ − is processedby PHOTOS . C.4 Lepton pair emission and event record momentum unit
For the purpose of pair emission, introduced for the first time with
Photos version 3.57,the information about the momentum unit (either
GEV or MEV ) used by the event has to beprovided. For other
Photos applications this information is not needed.In case of the
HepMC event record, this information is automatically obtained from the event.For
HEPEVT events,
GEV is assumed. For all other interfaces, the unit is undefined and has tobe set in the event record interface by calling
Photos::setMomentumUnit(MomentumUnits unit); (e.g.
Photos::setMomentumUnit(Photos::MEV); ).See constructors for the
PhotosHepMCEvent or PhotosHEPEVEvent class for further examples.To select available emission from
PHOTOS use: • Photos::setPairEmission(bool flag);
Turn on or off emission of pairs (electrons or muons). Default is off. • Photos::setPhotonEmission(bool flag);
Turn on or off emission of photons. Default is on.Tests and implementation of final state radiation pair emission, presently follow formulae 1and 11 from Ref. [44]. The agreement, when pair emission phase space was restricted to thesoft region, was at the 2-5 % level of the pair effect (which itself is at the 0.1 % level of thecross section). The phase space is parametrized without any mass or other approximations.This feature was checked separately with special runs (matrix element removed) of 100 Mevtsamples.The matrix element used for pair emission in decays is easy to improve. Dependence of four-momenta of final state particles is coded explicitly. Further work [45] will be devoted to thistask. 30 .5 Logging and Debugging
This section describes the basic functionality of the logging and debugging tool. For detailson its content we address the reader to comments in the /src/utilities/Log.h header file.Let us present however a general scheme of the tool’s functionality. The
PHOTOS interfaceallows control over the amount of message data displayed during program execution andprovides a basic tool for memory leak tracking. The following initialization functions can beused in a user’s main program. The
Log.h header has to be then incuded. • Log::LogPhlupa(int from, int to)
Turns logging of debug messages from the C part of the program on and off. Parametersof this routine specify the range of debug codes for the phlupa routine. • Log::Summary() - Displays a summary of all messages from
C++ part of the code. • Log::SummaryAtExit() - Displays the summary at the end of a program run. • Log::LogInfo(bool flag)Log::LogWarning(bool flag)Log::LogError(bool flag)Log::LogDebug(int s, int e)Log::LogAll(bool flag)
Turns the logging of info , warning , error and debug messages on or off depending onthe flag value being true or false respectively. In the case of debug messages - the rangeof message codes to be displayed must be provided. By default, only debug messages(from 0 to 65535) are turned off. If the range is negative ( s > e ) debug messages won’tbe displayed. The last method turns displaying all of the above messages on and off.With Log::LogDebug(s,e) messages of s to e range, will be printed at execution time, inparticular: • Debug(0) - seed used by the random number generator • Debug(1) - which type of branching was found in
HepMC (regular or a case without anintermediate particle, for details see
PhotosBranch.cxx ) • Debug(700) - execution of the branching filter has started • Debug(701) - branching is forced • Debug(702) - branching is suppressed • Debug(703) - branching is processed (i.e. passed to the filter) • Debug(900) - started check of Matrix Element (ME) calculation for the channel • Debug(901) - ME channel value obtained • Debug(902) - final ME channel value after checking all flags • Debug(2) - execution of the branching filter was completed • Debug(1000) - the number of particles sent to and retrieved from internal
PHOTOS eventrecord. 31he option
Log::SetWarningLimit(int limit) results in only the first ‘limit’ warningsbeing displayed. The default for limit is 100. If limit =0 is set, then there are no limits onthe number of warnings to be displayed.The memory leak tracking function allows checking of whether all memory allocated within
PHOTOS Interface is properly released. However, using the debug option significantly in-creases the amount of time needed for each run. Its use is therefore recommended for debug-ging purposes only. In order to use this option modify make.inc in the main directory byadding the line:
DEBUG = -D" LOG DEBUG MODE "
Recompile the interface. Now, whenever the program is executed a table will be printed atthe end of the run, listing all the pointers that were not freed, along with the memory theyconsumed. If the interface works correctly without any memory leaks, one should get anempty table.It is possible to utilize this tool within a user’s program; however there are a few limitations.The debugging macro from ”Log.h” can create compilation errors if one compiles it alongwith software which has its own memory management system (e.g.
ROOT ). To make themacro work within a user’s program, ensure that
Log.h is the last header file included inthe main program. It is enough to compile the program with the -D" LOG DEBUG MODE " directive added, or placed within the program before inclusionof the
Log.h file . C.6 Other User Configuration Methods
The following auxiliary methods are prepared. They are useful for initialization or are intro-duced for backward compatibility. • Photos::setRandomGenerator(double (*gen)()) installed in
PHOTOS 3.52
Replace random number generator used by
Photos . The user provided generator mustreturn a double between 0 and 1.
Photos::setRandomGenerator(NULL) will reset theprogram back to the default generator, which is a copy of
RANMAR [19, 20]. • Photos::setSeed(int iseed1, int iseed2)
Set the seed values for our copy of the random number generator
RANMAR [19, 20]. • Photos::maxWtInterference(double interference)
Set the maximum interference weight. The default, 2, is adopted to decays where atmost two charged decay products are present and no matrix element based kernel isused . • Photos::setInfraredCutOff(double cut off)
Set the minimal energy (in units of decaying particle mass) for photons to be explicitlygenerated. • Photos::setAlphaQED(double alpha)
Set the coupling constant, alpha QED. Note that
Log.h does not need to be included within the user’s program for the memory leak trackingtool to be used only for the
PHOTOS interface. For the decays like
J/ψ → π + π − a higher value, at least equal to the number of charged decay products,should be set. The algorithm performance will slow down linearly with the maximum interference weight butall simulation results will remain unchanged. Also in this case a higher than default 2 should be used. Photos::setInterference(bool interference)
A switch for interference, matrix element weight. • Photos::setDoubleBrem(bool doub)
Set double bremsstrahlung generation. • Photos::setQuatroBrem(bool quatroBrem)
Set bremsstrahlung generation up to a multiplicity of 4. • Photos::setExponentiation(bool expo)
Set the exponentiation mode. • Photos::setCorrectionWtForW(bool corr)
A switch for leading effects of the matrix element (in leptonic W decays) • Photos::setMeCorrectionWtForScalar(bool corr)
A switch for complete effects of the matrix element (in scalar to two scalar decays) installed in
PHOTOS 3.3 . • Photos::setMeCorrectionWtForW(bool corr)
A switch for complete effects of the matrix element (in leptonic decays of W ’s producedfrom anihilation of light fermions) installed in PHOTOS 3.2 • Photos::setMeCorrectionWtForZ(bool corr)
A switch for complete effects of the matrix element (in leptonic Z decays) installed in PHOTOS 3.1 • Photos::setTopProcessRadiation(bool top)
Set photon emission in top pair production in quark (gluon) pair annihilation and intop decay. • Photos::initializeKinematicCorrections(int flag)
Initialize kinematic corrections necessary to avoid consequences of rounding errors. • Photos::forceMassFrom4Vector(bool flag)
By default, for all particles used by
PHOTOS , mass is re-calculated and p E − p isused. If flag=false , the particle mass stored in the event record is used. The choicemay be important for the control of numerical stability in the case of very light stableparticles, but may be incorrect for decay products themselves of non-negligible width. • Photos::forceMass(int pdgid, double mass) installed in
PHOTOS 3.4
For particles of
PDGID (or -PDGID ) to be processed by
PHOTOS , the mass value at-tributed by the user will be used instead of the one calculated from the 4-vector. Notethat if both forceMass and forceMassFromEventRecord is used for the same
PDGID ,the last executed function will take effect. Up to version 3.51, the option is active if forceMassFrom4Vector = true (default). From version 3.52, the option works regard-less of the setting of forceMassFrom4Vector . • Photos::forceMassFromEventRecord(int pdgid) installed in
PHOTOS 3.4
For particles of
PDGID (or -PDGID ) to be processed by
PHOTOS , the mass value takenfrom the event record will be used instead of the one calculated from the 4-vector.Note that if both forceMass and forceMassFromEventRecord is used for the same
PDGID , the last executed function will take effect. Up to version 3.51, the option isactive if forceMassFrom4Vector = true (default). From version 3.52, the option worksregardless of the setting of forceMassFrom4Vector .33
Photos::createHistoryEntries(bool flag, int status) installed in
PHOTOS 3.4
If set to true , and if the event record format allows,
Photos will store history en-tries consisting of particles before processing . History entries will have status codesequal to status . The value of status will also be added to the list of status codesignored by Photos (see
Photos::ignoreParticlesOfStatus ). An example is providedin photos pythia example.cxx . • Photos::ignoreParticlesOfStatus(int status)
Decay products with the status code status will be ignored when checking momentum conservation and will not be passedto the algorithm for generating bremsstrahlung. • Photos::deIgnoreParticlesOfStatus(int status)
Removes status from the list ofstatus codes created with
Photos::ignoreParticlesOfStatus . • bool Photos::isStatusCodeIgnored(int status) Returns true if status is on thelist of ignored status codes. • Photos::setMomentumConservationThreshold(double momentum conservation threshold)
Threshold relative to the difference of the sum of the 4-momenta of incoming and out-going particles. The default value is 0.1. If larger energy-momentum non-conservationis found then photon generation is skipped in the vertex . • Photos::iniInfo()
The printout performed with
Photos::initialize() will exhibit outdated informationonce the methods listed above are applied. The reinitialized data can be printed usingthe
Photos::iniInfo() method. The same format as
Photos::initialize() will beused.
C.7 Creating Advanced Plots and Custom Analysis
In Section 5.2, we have presented results of a non-standard analysis performed by
MC-TESTER .Figure 4 has been obtained using a custom
UserTreeAnalysis located in the
ZeeAnalysis.C file residing in the examples/testing/Zee directory. This file serves as an example of howcustom analysis can be performed and how new plots can be added to the project with thehelp of
MC-TESTER .The basic
MC-TESTER analysis contains methods used by pre-set examples in the subdirectoriesof examples/testing to focus on at most one or two sufficiently hard photons from all thephotons generated by
PHOTOS . Its description and usage have already been documented in [7].The content of
ZeeAnalysis.C is identical to the default
UserTreeAnalysis of MC-TESTER with the only addition being a method to create the previously mentioned plot.In order to create the t ¯ t example, an additional routine had to be added to photos test.c .Since MC-TESTER is not designed to analyze processes involving multiple incoming particles, wehave used a method similar to that previously used in the
FORTRAN examples,
LC Analysis ,mentioned in [15], Section 6.1. This routine, fixForMctester , transforms the XY → t ¯ t process to the 100 → t ¯ t process, where the momentum of the special particle 100 is X + Y . In case of
HepMC , it creates copies of all particles on the list of outgoing particles in vertices where thephoton was added and will be added at the end of the list. In the past, momentum conservation was checked using the standard method of
HepMC . That effectivelymeant that only momentum, but not energy was checked. This turned out to be insufficient in some rarecases.
MC-TESTER can be set up to analyze the particle 100 in order to geta desirable result.For more details regarding the plots created for this documentation, see
README-plots locatedin the examples/testing/examples/testing/