C++ Interface to Tauola
mainpage.h
1 /**
2 
3  @mainpage C++ Interface to Tauola
4  @brief Description of Tauola Interface in C++. WARNING for Doxygen sub-pages: Namespaces, Data Structures, Files, Directorises. All describe the development version. For the release of particular choice, its doxygen documentation is included in the corresponding distribution tar-ball.
5 
6  @authors Nadia Davidson, Gizo Nanava, Tomasz Przedzinski, Elzbieta Richter-Was, Zbigniew Was
7 
8 
9 
10  @section download1 New release
11 
12  The source code and documentation for Tauola release 1.1.9 (and of TauSpinner release 2.1.2)
13  - <a href="resources/TAUOLA.1.1.9/Tauola_interface_design.1.1.9.pdf">Tauola_interface_design.1.1.9.pdf</a> full software documentation includes updates with respect to
14 the preprint version.
15  - <a href="resources/TAUOLA.1.1.9/TAUOLA.1.1.9-LHC.tar.gz">TAUOLA source code for the LHC</a>
16 (or <a href="resources/TAUOLA.1.1.9/TAUOLA.1.1.9.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
17  enabling changes of code/models for tau decay hadronic currents)
18 tarball and its <a href="resources/TAUOLA.1.1.9/svn_info_tauola.1.1.9.txt">revision info</a> SVN tag, tarball
19 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.9/changelog.1.1.9.txt">changelog.txt</a>, for Tauspinner technical documentation see also arXiv:1802.05459 2407.17282
20 
21  <b>IMPORTANT NOTE:</b> Starting from release v1.1.8 we have added HepMC3 support (HepMC3 is avialble on the official <a href="https://hepmc.web.cern.ch/hepmc/">HepMC website</a>).
22  HEPEVT and HepMC libraries are now separated, which means <b>changes to the list of linked libraries are necessary</b>.
23 
24  @section developement Developement version
25 
26  The source code and documentation are updated daily from the repository as well. The following files are provided for download of the developement version:
27  - <a href="resources/TAUOLA.development.version/Tauola_interface_design.development.version.pdf">Tauola_interface_design.pdf</a> full software documentation.
28  - <a href="resources/TAUOLA.development.version/TAUOLA.development.version-LHC.tar.gz">TAUOLA source code for the LHC</a>
29 (or <a href="resources/TAUOLA.development.version/TAUOLA.development.version.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>) tarball and its <a href="resources/TAUOLA.development.version/svn_info_tauola.development.version.txt">revision info</a> SVN tag, tarball creation date/time, etc.
30 For updates with respect to release 1.0 see <a href="resources/TAUOLA.development.version/changelog.development.version.txt">changelog.txt</a>, for Tauspinner technical documentation on electroweak corrections see also arXiv:1808.08616 .
31 
32  @section download Older releases
33 
34 
35  The source code and documentation for release 1.0. The following files are provided for download:
36  - <a href="http://arxiv.org/abs/1002.0543">arXiv:1002.0543</a> full software documentation.
37  - <a href="resources/TAUOLA.1.0.tar.gz">TAUOLA source code </a> tarball.
38 
39  The source code and documentation for release 1.0.2
40  - <a href="resources/TAUOLA.1.0.2/Tauola_interface_design.1.0.2.pdf">Tauola_interface_design.1.0.2.pdf</a> full software documentation includes updates with respect to
41 the preprint version.
42  - <a href="resources/TAUOLA.1.0.2/TAUOLA.1.0.2-LHC.tar.gz">TAUOLA source code for LHC</a>
43 (or <a href="resources/TAUOLA.1.0.2/TAUOLA.1.0.2.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
44  enabling changes of code/models for tau decay hadronic currents)
45 tarball and its <a href="resources/TAUOLA.1.0.2/svn_info_tauola.1.0.2.txt">revision info</a> SVN tag, tarball
46 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.0.2/changelog.1.0.2.txt">changelog.txt</a>.
47 
48  The source code and documentation for release 1.0.4
49  - <a href="resources/TAUOLA.1.0.4/Tauola_interface_design.1.0.4.pdf">Tauola_interface_design.1.0.4.pdf</a> full software documentation includes updates with respect to
50 the preprint version.
51  - <a href="resources/TAUOLA.1.0.4/TAUOLA.1.0.4-LHC.tar.gz">TAUOLA source code for the LHC</a>
52 (or <a href="resources/TAUOLA.1.0.4/TAUOLA.1.0.4.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
53  enabling changes of code/models for tau decay hadronic currents)
54 tarball and its <a href="resources/TAUOLA.1.0.4/svn_info_tauola.1.0.4.txt">revision info</a> SVN tag, tarball
55 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.0.4/changelog.1.0.4.txt">changelog.txt</a>.
56 
57  The source code and documentation for release 1.0.5
58  - <a href="resources/TAUOLA.1.0.5/Tauola_interface_design.1.0.5.pdf">Tauola_interface_design.1.0.5.pdf</a> full software documentation includes updates with respect to
59 the preprint version.
60  - <a href="resources/TAUOLA.1.0.5/TAUOLA.1.0.5-LHC.tar.gz">TAUOLA source code for the LHC</a>
61 (or <a href="resources/TAUOLA.1.0.5/TAUOLA.1.0.5.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
62  enabling changes of code/models for tau decay hadronic currents)
63 tarball and its <a href="resources/TAUOLA.1.0.5/svn_info_tauola.1.0.5.txt">revision info</a> SVN tag, tarball
64 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.0.5/changelog.1.0.5.txt">changelog.txt</a>.
65 
66  The source code and documentation for release 1.0.6
67  - <a href="resources/TAUOLA.1.0.6/Tauola_interface_design.1.0.6.pdf">Tauola_interface_design.1.0.6.pdf</a> full software documentation includes updates with respect to
68 the preprint version.
69  - <a href="resources/TAUOLA.1.0.6/TAUOLA.1.0.6-LHC.tar.gz">TAUOLA source code for the LHC</a>
70 (or <a href="resources/TAUOLA.1.0.6/TAUOLA.1.0.6.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
71  enabling changes of code/models for tau decay hadronic currents)
72 tarball and its <a href="resources/TAUOLA.1.0.6/svn_info_tauola.1.0.6.txt">revision info</a> SVN tag, tarball
73 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.0.6/changelog.1.0.6.txt">changelog.txt</a>.
74 
75  The source code and documentation for release 1.0.7
76  - <a href="resources/TAUOLA.1.0.7/Tauola_interface_design.1.0.7.pdf">Tauola_interface_design.1.0.7.pdf</a> full software documentation includes updates with respect to
77 the preprint version.
78  - <a href="resources/TAUOLA.1.0.7/TAUOLA.1.0.7-LHC.tar.gz">TAUOLA source code for the LHC</a>
79 (or <a href="resources/TAUOLA.1.0.7/TAUOLA.1.0.7.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
80  enabling changes of code/models for tau decay hadronic currents)
81 tarball and its <a href="resources/TAUOLA.1.0.7/svn_info_tauola.1.0.7.txt">revision info</a> SVN tag, tarball
82 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.0.7/changelog.1.0.7.txt">changelog.txt</a>.
83 
84  The source code and documentation for release 1.1.0
85  - <a href="resources/TAUOLA.1.1.0/Tauola_interface_design.1.1.0.pdf">Tauola_interface_design.1.1.0.pdf</a> full software documentation includes updates with respect to
86 the preprint version.
87  - <a href="resources/TAUOLA.1.1.0/TAUOLA.1.1.0-LHC.tar.gz">TAUOLA source code for the LHC</a>
88 (or <a href="resources/TAUOLA.1.1.0/TAUOLA.1.1.0.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
89  enabling changes of code/models for tau decay hadronic currents)
90 tarball and its <a href="resources/TAUOLA.1.1.0/svn_info_tauola.1.1.0.txt">revision info</a> SVN tag, tarball
91 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.0/changelog.1.1.0.txt">changelog.txt</a>. Starting from this version <a href="http://arxiv.org/abs/1201.0117">TauSpinner </a>was merged into TAUOLA source code.
92 
93  The source code and documentation for release 1.1.1
94  - <a href="resources/TAUOLA.1.1.1/Tauola_interface_design.1.1.1.pdf">Tauola_interface_design.1.1.1.pdf</a> full software documentation includes updates with respect to
95 the preprint version.
96  - <a href="resources/TAUOLA.1.1.1/TAUOLA.1.1.1-LHC.tar.gz">TAUOLA source code for the LHC</a>
97 (or <a href="resources/TAUOLA.1.1.1/TAUOLA.1.1.1.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
98  enabling changes of code/models for tau decay hadronic currents)
99 tarball and its <a href="resources/TAUOLA.1.1.1/svn_info_tauola.1.1.1.txt">revision info</a> SVN tag, tarball
100 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.1/changelog.1.1.1.txt">changelog.txt</a>.
101 
102 - \b NOTE: this version was erroneously made public for three days (Nov 20-22) and lacks numerical protecting code against rounding errors for TauSpinner operation on events with bremsstrahlung in leptonic decays.
103 Version 1.1.1a should be used instead.
104 For the period of time Nov 23 - Nov 27 this (1.1.1) version number was attributed to the code of version 1.1.1a but svn label was not updated at that time.
105 
106  The source code and documentation for release 1.1.1a
107  - <a href="resources/TAUOLA.1.1.1a/Tauola_interface_design.1.1.1a.pdf">Tauola_interface_design.1.1.1a.pdf</a> full software documentation includes updates with respect to
108 the preprint version.
109  - <a href="resources/TAUOLA.1.1.1a/TAUOLA.1.1.1a-LHC.tar.gz">TAUOLA source code for the LHC</a>
110 (or <a href="resources/TAUOLA.1.1.1a/TAUOLA.1.1.1a.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
111  enabling changes of code/models for tau decay hadronic currents)
112 tarball and its <a href="resources/TAUOLA.1.1.1a/svn_info_tauola.1.1.1a.txt">revision info</a> SVN tag, tarball
113 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.1a/changelog.1.1.1a.txt">changelog.txt</a>.
114 
115  - \b NOTE: for downloads Nov 20-27 2012 please check note for version 1.1.1.
116 
117  The source code and documentation for release 1.1.3
118  - <a href="resources/TAUOLA.1.1.3/Tauola_interface_design.1.1.3.pdf">Tauola_interface_design.1.1.3.pdf</a> full software documentation includes updates with respect to
119 the preprint version.
120  - <a href="resources/TAUOLA.1.1.3/TAUOLA.1.1.3-LHC.tar.gz">TAUOLA source code for the LHC</a>
121 (or <a href="resources/TAUOLA.1.1.3/TAUOLA.1.1.3.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
122  enabling changes of code/models for tau decay hadronic currents)
123 tarball and its <a href="resources/TAUOLA.1.1.3/svn_info_tauola.1.1.3.txt">revision info</a> SVN tag, tarball
124 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.3/changelog.1.1.3.txt">changelog.txt</a>.
125 
126  The source code and documentation for release 1.1.4
127  - <a href="resources/TAUOLA.1.1.4/Tauola_interface_design.1.1.4.pdf">Tauola_interface_design.1.1.4.pdf</a> full software documentation includes updates with respect to
128 the preprint version.
129  - <a href="resources/TAUOLA.1.1.4/TAUOLA.1.1.4-LHC.tar.gz">TAUOLA source code for the LHC</a>
130 (or <a href="resources/TAUOLA.1.1.4/TAUOLA.1.1.4.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
131  enabling changes of code/models for tau decay hadronic currents)
132 tarball and its <a href="resources/TAUOLA.1.1.4/svn_info_tauola.1.1.4.txt">revision info</a> SVN tag, tarball
133 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.4/changelog.1.1.4.txt">changelog.txt</a>.
134 
135  The source code and documentation for release 1.1.5
136  - <a href="resources/TAUOLA.1.1.5/Tauola_interface_design.1.1.5.pdf">Tauola_interface_design.1.1.5.pdf</a> full software documentation includes updates with respect to
137 the preprint version.
138  - <a href="resources/TAUOLA.1.1.5/TAUOLA.1.1.5-LHC.tar.gz">TAUOLA source code for the LHC</a>
139 (or <a href="resources/TAUOLA.1.1.5/TAUOLA.1.1.5.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
140  enabling changes of code/models for tau decay hadronic currents)
141 tarball and its <a href="resources/TAUOLA.1.1.5/svn_info_tauola.1.1.5.txt">revision info</a> SVN tag, tarball
142 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.5/changelog.1.1.5.txt">changelog.txt</a>.
143 
144  The source code and documentation for Tauola release 1.1.6 (and of TauSpinner release 2.0.0)
145  - <a href="resources/TAUOLA.1.1.6/Tauola_interface_design.1.1.6.pdf">Tauola_interface_design.1.1.6.pdf</a> full software documentation includes updates with respect to
146 the preprint version.
147  - <a href="resources/TAUOLA.1.1.6/TAUOLA.1.1.6-LHC.tar.gz">TAUOLA source code for the LHC</a>
148 (or <a href="resources/TAUOLA.1.1.6/TAUOLA.1.1.6.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
149  enabling changes of code/models for tau decay hadronic currents)
150 tarball and its <a href="resources/TAUOLA.1.1.6/svn_info_tauola.1.1.6.txt">revision info</a> SVN tag, tarball
151 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.6/changelog.1.1.6.txt">changelog.txt</a>.
152 
153  The source code and documentation for Tauola release 1.1.6b (and of TauSpinner release 2.0.1)
154  - <a href="resources/TAUOLA.1.1.6b/Tauola_interface_design.1.1.6b.pdf">Tauola_interface_design.1.1.6b.pdf</a> full software documentation includes updates with respect to
155 the preprint version.
156  - <a href="resources/TAUOLA.1.1.6b/TAUOLA.1.1.6b-LHC.tar.gz">TAUOLA source code for the LHC</a>
157 (or <a href="resources/TAUOLA.1.1.6b/TAUOLA.1.1.6b.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
158  enabling changes of code/models for tau decay hadronic currents)
159 tarball and its <a href="resources/TAUOLA.1.1.6b/svn_info_tauola.1.1.6b.txt">revision info</a> SVN tag, tarball
160 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.6b/changelog.1.1.6b.txt">changelog.txt</a>.
161 
162  The source code and documentation for Tauola release 1.1.6c (and of TauSpinner release 2.0.3)
163  - <a href="resources/TAUOLA.1.1.6c/Tauola_interface_design.1.1.6c.pdf">Tauola_interface_design.1.1.6c.pdf</a> full software documentation includes updates with respect to
164 the preprint version.
165  - <a href="resources/TAUOLA.1.1.6c/TAUOLA.1.1.6c-LHC.tar.gz">TAUOLA source code for the LHC</a>
166 (or <a href="resources/TAUOLA.1.1.6c/TAUOLA.1.1.6c.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
167  enabling changes of code/models for tau decay hadronic currents)
168 tarball and its <a href="resources/TAUOLA.1.1.6c/svn_info_tauola.1.1.6c.txt">revision info</a> SVN tag, tarball
169 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.6c/changelog.1.1.6c.txt">changelog.txt</a>.
170  - Note: on some platforms the cpp pre-compiler which we use for archiving versions of fortran add into the code gnu licence in c++ comment format. This issue started with gcc 4.8.2. It has been fixed in new release.
171  - Solution: in TAUOLA/make.inc set: CPPFLAGS= -C -P -traditional-cpp -nostdinc
172 
173 
174  The source code and documentation for Tauola release 1.1.8 (and of TauSpinner release 2.0.6)
175  - <a href="resources/TAUOLA.1.1.8/Tauola_interface_design.1.1.8.pdf">Tauola_interface_design.1.1.8.pdf</a> full software documentation includes updates with respect to
176 the preprint version.
177  - <a href="resources/TAUOLA.1.1.8/TAUOLA.1.1.8-LHC.tar.gz">TAUOLA source code for the LHC</a>
178 (or <a href="resources/TAUOLA.1.1.8/TAUOLA.1.1.8.tar.gz">TAUOLA source code with full TAUOLA FORTRAN</a>
179  enabling changes of code/models for tau decay hadronic currents)
180 tarball and its <a href="resources/TAUOLA.1.1.8/svn_info_tauola.1.1.8.txt">revision info</a> SVN tag, tarball
181 creation date/time, etc. For updates with respect to release 1.0 see <a href="resources/TAUOLA.1.1.8/changelog.1.1.8.txt">changelog.txt</a>, for Tauspinner technical documentation see also arXiv:1802.05459.
182 
183  <b>IMPORTANT NOTE:</b> Starting from release v1.1.8 we have added HepMC3 support (HepMC3 is avialble on the official <a href="https://hepmc.web.cern.ch/hepmc/">HepMC website</a>).
184  HEPEVT and HepMC libraries are now separated, which means <b>changes to the list of linked libraries are necessary</b>.
185 
186  @section intro Introduction/Status
187 
188  At present (since Feb 2 2010) the C++ interface functionality for TAUOLA is complete.
189  Longitudinal spin correlation are checked using <a href="http://mc-tester.web.cern.ch/MC-TESTER/">
190  MC-TESTER</a> now. Transverse spin correlations and full functionality of TAUOLA Universal Interface
191  are coded. Genuine electroweak corrections for processes mediated by Z/gamma are implemented as well.
192 
193  The tar file contains the C++ interface along with the source code for tauola itself (as available from <a href="http://wasm.web.cern.ch/wasm/goodies.html">old web page</a>; version Oct 11 2005).
194  The developement version contains the latest source code for the interface from our subversion repository. Note that
195  revision numbers, dates and other info for this development version can be found in the revision information file listed above.
196 
197  At present, the tar ball includes everything that is needed for installation. The user is advised to use HepMC 2.04+ libraries as described below.
198 
199  @section setup Requirements
200 
201  For compilation, and to run the simple example, the interface requires:
202  - <a href="http://lcgapp.cern.ch/project/simu/HepMC/">HepMC v2.04</a> or later.
203 
204  For further examples, one need to also install:
205  - <a href="http://root.cern.ch/drupal/">ROOT v5.18</a> or later
206  - <a href="http://home.thep.lu.se/~torbjorn/Pythia.html">PYTHIA 8.1</a> or later. PYTHIA must be compiled with HepMC 2 so that the PYTHIA library hepmcinterface exists.
207  - <a href="http://mc-tester.web.cern.ch/MC-TESTER/">MC-TESTER v1.24</a> or later. Do not forget to compile the additional HepMC library libHepMCEvent as well.
208 
209  Examples of TAUOLA C++ combined with PHOTOS and its C++ interface are available from:
210 - <a href="http://photospp.web.cern.ch/">
211 PHOTOS C++</a> official webpage.
212 
213 
214 
215  @section compile Configuration and Compilation
216 
217  In order to compile the TAUOLA C++ interface:
218  - Execute './configure' with additional command line options:
219  - '--with-hepmc=<path> ' provides the path to HepMC installation directory. One can set HEPMCLOCATION variable instead of using this directive. This options is required for interface to compile. To compile without HepMC use '--without-hepmc'
220  - '--prefix=<path>' provides the installation path. The 'include' and 'lib' directories will be copied there if 'make install' is executed later. If none has been provided, the default directory for installation is '/usr/local'.
221  - Execute 'make'
222  - Optionally, execute 'make install' to copy files to the directory provided during configuration.
223 
224  After compiling the 'tauola-fortran' part, the TAUOLA C++ interface will be compiled and the '/lib' and '/include' directories will contain the appropriate library and include files.
225 
226  In order to compile the examples, enter the 'examples' directory, and:
227  - execute './configure' to determine which examples can be compiled. Additional paths can be provided as command line options:
228  - '--with-pythia8=<path>' provides the path to the Pythia8 installation directory. One can set the PYTHIALOCATION variable instead of using this directive. This path is required for all additional examples and tests.
229  - '--with-mc-tester=<path>' provides the path to the MC-Tester installation directory (libHepMCEvent must be compiled as well, check MC-Tester documentation for more details). One can set the MCTESTERLOCATION variable instead of using this directive. This path is required for all additional examples and tests. It is assumed that using this option also implies that ROOT has already been installed (since it's required by MC-TESTER). The location of its binaries should be listed in the PATH variable.
230  - execute 'make'
231 
232  Note that for examples working with PYTHIA 8.1, the PYTHIA8DATA global variable must be set (refer to instructions provided during configuration).
233  Similarly, for examples in the examples/testing directory to work, the MCTESTERLOCATION global variable must be set.
234  If neither PYTHIA nor MC-TESTER are present, only the simple example will be provided. The '/examples' directory will contain the compiled example files.
235 
236  If you prefer not to use configuration scripts,
237  you may find <a href="resources/doxygen/README-NO-CONFIG.txt">README-NO-CONFIG.txt</a> useful.
238 
239  @section testing Testing
240 
241  In order to run some more specific tests both PYTHIA and MC-TESTER must be installed.
242  - Compile TAUOLA C++ interface as well as examples.
243  - Check that the appropriate system variables are set: normally set by the script
244  configure.paths.sh [.csh] (the configuration step mentions this script).
245  - Enter the /examples/testing directory. Modify test.inc if needed.
246  - Enter the selected directory and execute 'make'.
247 
248  The appropriate .root files as well as .pdf files generated by MC-TESTER will be created inside the chosen directory. You can execute 'make clobber' to clean the directory. You can also execute 'make' inside the 'TAUOLA/examples/testing' directory to run all available tests one after another.
249 
250  @section sanc SANC
251  Electroweak corrections may affect spin correlations between tau+ and tau- in a significant way. This is the case at high energies,
252 far above WW threshold. At present we use the alpha scheme for electroweak calculations, this choice may not be optimal for the
253 cross section weight aiming at implementation of electroweak corrections. For this, the end scheme should be consistent with the choice
254 of the host generator. On the other hand this is not the problem for spin correlations, our prime interest. In addition, if tables are used, transverse spin correlations for processes mediated by Z and gamma are taken into account.
255 
256 Changes to the tables generated by the SANC module can be implemented by modifying the interface located in the '/SANC' directory. Details regarding the structure and initialization variables of the interface are described in the documentation. In order to generate new tables:
257  - execute 'make' in the '/SANC' directory to compile the library and tools.
258  - Adjust the initialization in the SANC tables calculation if needed.
259  - execute 'make tables' in the '/SANC' directory to generate the tables.
260  - move tables to the directory from which your main program is executed.
261 
262  <hr>
263  @section description Description of the code
264 
265  @image html tauola_interface_design.png "Design of Interface. Components are described in more detail below."
266 
267  @subsection outline Algorithm Outline
268 
269  The simplified version of the main program structure including the tauola decay routines would consist of:
270  - initialize the Monte Carlo generator and all other generators / analysis tools.
271  - set the appropriate parameters for the Tauola interface.
272  - invoke the Tauola::initialize() routine.
273  - for each event to be generated:
274  - generate an event using any Monte Carlo generator
275  - convert a generated event to the HepMC event record
276  - create a TauolaHepMCEvent from a HepMC event object
277  - invoke decayTaus() for the TauolaHepMCEvent object. If a tau has already been decayed by a MC generator, use undecayTaus() first.
278  - the HepMC event is now prepared and can be used in the analysis
279  - finalize the analysis
280  - print any summary output if needed and exit
281 
282  @subsection flow Flow of Control
283 
284  The following is a more detailed example point by point of how a tau, or set of taus, are decayed using the interface with the HepMC event record implementation.
285 
286  Starting from the main program:
287  - At the initialization step, appropriate configuration routines via the 'Tauola' class methods can be executed.
288  - The Tauola::initialize() method must be invoked, which calls the Initialize() methods in f_Init, which in turn calls the initilization routines of TAUOLA.
289 
290  In the main event loop, after the HepMC event is filled by a Monte Carlo generator:
291  - An appropriate implementation of the abstract class TauolaEvent - TauolaHepMCEvent object must be created, taking a HepMC::GenEvent object as its parameter.
292  - The method decayTaus() for the created TauolaHepMCEvent object must be invoked. If the Monte Carlo generator has already performed the decays of a tau, the undecayTaus() method can be executed just before the decayTaus() method.
293 
294  After executing decayTaus(), the following procedure takes place:
295  - The HepMC event record is traversed and a list of stable taus in the event is created.
296  - the taus from the list are paired with other decay products (e.g. tau neutrino or second tau). If the pair consists of two taus, the second tau is removed from the previous list.
297  - TauolaParticlePairs are then created from these pairings.
298  - For each pair, the spin density matrix is calculated using information about the production process.
299  - The decayTauPairs() method is called for each pair. Within this method:
300  - For each tau in the pair, decay() is called.
301  - the decay method in TauolaParticle is responsible for adding itself
302  (the tau) to the DecayList in the first position. It then calls
303  decay() in f_Decay which in turn calls the dekay_() routine of TAUOLA.
304  - dekay_() in TAUOLA generates a set of daughter particles with
305  momentum as though the tau was decayed in its rest frame.
306  - The dekay_() also provides a polarimetric vector, which is used in combination with spin density matrix to calculate the spin weight. It is used to determine whether the decay is accepted or not.
307  - If rejected, the list of decay products is cleared and the pair is decayed anew. This way unweighting of spin effects is performed.
308  - Once accepted, for each tau in the pair the routine addDecayToEventRecord() is executed, which in turn calls TAUOLA dekay_() with an option set to write to the event record.
309  - For each daughter TAUOLA calls filhep_() in the file f_FilHep.c.
310  - filhep_() adds a new TauolaHepMCParticle to DecayList with all necessary information taken from TAUOLA.
311  - The DecayList data structure translates the parent index given by TAUOLA to a pointer to the TauolaParticle(TauolaHepMCParticle) object.
312  - The parents are set via the TauolaParticle methods (setMother, etc.) By setting the mothers it is automatically assigned a barcode and added to the HepMC event.
313  - The particle is boosted by the tau's momentum.
314  - The position of the vertex of the particle is modified accordingly to the tau lifetime.
315  - Control is then returned to TauolaHepMCEvent which proceeds onto the next pair.
316  - When all pairs are decayed, the TauolaHepMCEvent converts the HepMC::GenEvent to the units selected by the user (GeV/MeV mm/cm) and finalizes execution. The loop in the main program proceeds to the next event.
317 
318 <!--
319  @section event_rec Notes About the Event Record
320  This section in future will describe examples of events, particularly unusual ones,
321  which the TAUOLA Interface will nonetheless need to be able to handle, but which were not discussed at the time
322 of writing the documentation. At present this point is basically empty, except one example. Such type of events is already discussed in
323 the documentation.
324  - <a href="resources/pythia_event.pdf">example of a pythia event</a> with
325  non-conservation of momentum and tau->tau type vertices.
326 
327  @section to_do Things to do
328 
329 See software documentation in pdf form.
330 -->
331 
332  <hr>
333 Last update; usually last night by the robot, see the doxygen time below and revision info of the development version.
334 */
Generated by doxygen 1.9.1