hepmc - Blame information for rev 433

Subversion Repositories:
Rev:
Rev Author Line No. Line
45 garren 1 \documentclass[11pt,letterpaper]{article}
198 garren 2 \usepackage{epsfig}
45 garren 3 \usepackage{graphicx}
4 \usepackage{graphics}  
5 \usepackage{cite}      % bibliographic sitations
6 \usepackage{floatflt}  
7 \usepackage{fancybox}  %allows for shadow boxes etc.
8 \usepackage{color}     %allows use of colors (RBG only, I think)
9 \usepackage{html}      % allows easy inclusion of links which are
10                        % interpretted properly by both latex and latex2html
11 \topmargin -0.5in
12 \setlength{\textwidth}{6.5in}
13 \setlength{\textheight}{8.75in}
14 \setlength{\oddsidemargin}{0in}
15 \setlength{\evensidemargin}{0in}
16  
17 %
18 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19 %
20  
21 \begin{document}
22  
23 %
24 %%%%%%%%%%%%%%%%%%%%%%%
25 % Define new commands %
26 %%%%%%%%%%%%%%%%%%%%%%%
27 %
28 % choose one of the following definitions of mycomment (second = good copy)
29 \newcommand{\mycomment}[1]{\marginpar{\it\tiny #1}} % used for margin comments
30 %\newcommand{\mycomment}[1]{\typeout{#1}}
31 \newcommand{\txt}[1]{{\mbox{\tiny #1}}} %facilitates sub/superscripts
32                                         % that aren't italicized
33 \newcommand{\order}{{\cal O}}
34  
35 \newenvironment{mylist}
36 {\begin{list}{}{
37   \setlength{\leftmargin}{0.5cm}
38   \setlength{\itemsep}{0pt}
39   \setlength{\parsep}{0pt}
40   \setlength{\topsep}{0pt}
41   \renewcommand{\makelabel}{}}}
42 {\end{list}}
43  
357 garren 44 %%%%  \vspace{-.2cm} {\bf \underline{\sc #1}} \vspace{-.2cm}
45 garren 45 \newenvironment{myitemize}[1]
46 { \begin{small}
357 garren 47   {\bf \underline{\sc #1}} \vspace{-.2cm}
45 garren 48   \begin{itemize}
49   \setlength{\itemsep}{-4pt}
50   \setlength{\parsep}{0pt}
51   \setlength{\topsep}{0pt}
52   \setlength{\partopsep}{0pt}
53 }
54 {\end{itemize}\end{small}}
55 \newcommand{\myitem}[2]{ \item {\bf #1}: {\it #2} }
56  
57 % from page 4 of fancybox.sty manual
58 \newenvironment{fminipage}%
59 {\begin{Sbox}\begin{minipage}}%
60 {\end{minipage}\end{Sbox}\fbox{\TheSbox}}
61 %
62 % use
63 % \begin{fminipage}{3in}
64 %     the text paragraph is 3 inchs wide
65 % \end{fminipage}
66 % to have a multi-line framed box
67 %
68 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
69 %
70 \begin{titlepage}
71 {\tiny \LaTeX-ed on \today.}
72  
198 garren 73 \vspace{2cm}
45 garren 74  
75 \begin{center}
76  
77 {\Huge\bf HepMC 2}
78  
79 \vspace{1cm}
80  
81 {\huge a C++ Event Record for Monte Carlo Generators }
82  
83 \vspace{2cm}
84  
85 \htmladdnormallink{http://savannah.cern.ch/projects/hepmc/}
86 {http://savannah.cern.ch/projects/hepmc/}
87  
198 garren 88 \vspace{1cm}
45 garren 89  
432 garren 90 {\Large User Manual Version 2.06} \\
433 garren 91 May 17, 2010
45 garren 92  
93 \vspace{2cm}
94  
198 garren 95 {\huge Matt Dobbs} \\
96 University of Victoria, Canada
97  
202 garren 98 \vspace{.2cm}
198 garren 99  
202 garren 100 {\Large J$\o$rgen Beck Hansen} \\
198 garren 101 CERN
102  
202 garren 103 \vspace{.2cm}
198 garren 104  
202 garren 105 {\Large Lynn Garren} \\
45 garren 106 Fermi National Accelerator Laboratory
107  
202 garren 108 \vspace{.2cm}
109  
110 {\Large Lars Sonnenschein} \\
391 garren 111 RWTH Aachen
202 garren 112  
45 garren 113 \vspace{1cm}
114  
115 \end{center}
116 \begin{abstract}
198 garren 117   The HepMC package is an object oriented event record written in C++
118   for High Energy Physics Monte Carlo Generators.  Many extensions
119   from HEPEVT, the Fortran HEP standard, are supported: the number of
120   entries is unlimited, spin density matrices can be stored with each
121   vertex, flow patterns (such as color) can be stored and traced,
122   integers representing random number generator states can be stored,
123   and an arbitrary number of event weights can be included.  Particles
124   and vertices are kept separate in a graph structure, physically
125   similar to a physics event.  The added information supports the
126   modularisation of event generators.  The package has been kept as
127   simple as possible with minimal internal/external dependencies.
128   Event information is accessed by means of iterators supplied with
129   the package.
130  
45 garren 131   HepMC 2 is an extension to the original HepMC written by Matt Dobbs.
132 \end{abstract}
133 \end{titlepage}
134  
198 garren 135 \setcounter{page}{1}
136 \tableofcontents
357 garren 137 \listoffigures
138 \listoftables
45 garren 139  
198 garren 140 \newpage
141  
45 garren 142 %
143 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
144 %
145  
146 \section{Introduction}
198 garren 147 This user manual is intended as a companion to the
45 garren 148 \htmladdnormallinkfoot{online documentation}
198 garren 149 {http://lcgapp.cern.ch/project/simu/HepMC/},
150 and together with the examples
45 garren 151 should provide a friendly introduction to the HepMC event record. A
152 general overview is available in Ref.~\cite{dobbs:2000CompPhysComm}.
153  
198 garren 154 The HEP community has moved towards Object-Oriented computing tools
155 (usually C++): most upcoming experiments are choosing OO software
213 garren 156 architecture, and Pythia 8~\cite{Torbjorn} and
157 Herwig++~\cite{Richardson}, written in C++, are available.  
198 garren 158 A standard event record must be simple for the end user to access information,
159 while maintaining the power and flexibility offered by OO design. The
160 HepMC event record has been developed to satisfy these criteria.
161  
162 HepMC is an object oriented event record written in C++ for Monte
163 Carlo Generators in High Energy Physics. It has been developed
164 independent of a particular experiment or event generator.  It is
165 intended to serve as both a ``container class'' for storing events after
166 generation and also as a ``framework'' in which events can be built up
167 inside a set of generators. This allows for the modularisation of
168 event generators---wherein different event generators could be
169 employed for different steps or components of the event generation
170 process (illustrated in Figure~\ref{modularisation}).
171 \footnote{
45 garren 172 %
198 garren 173 At the {\it Physics at TeV Colliders Workshop 2001} in Les
174 Houches, France, a group of Monte Carlo authors and experimentalists
175 produced a document~\cite{Boos:2001cv} which outlines the information
176 content necessary for two event generators to communicate information
177 about a hard process to the subsequent stages of event
178 generation. This was implemented in a set of Fortran common blocks,
179 and many ideas from HepMC were used, such as the scheme for handling
180 color flow information. Version 1.1 of HepMC supports the full event
181 information content of Ref.~\cite{Boos:2001cv} (run
182 information---pertaining to a collection of events---is also specified
183 in that document and is not addressed in HepMC).  }
184  
185 \begin{figure}[h]
186   \begin{center}
187     \Ovalbox{\begin{minipage}{5in}\begin{small}
188         \begin{tabular}{rcl}
189           $\overbrace{\mbox{Hard~Process~Generator}}^{
190             \mbox{\color{magenta}Specific NLO Generator}}$ &
191           $\stackrel{\rm \color{blue}Event~Record}{\rightarrow\rightarrow}$ &
192           $\overbrace{\mbox{Cascade~Package}}^{
193             \mbox{\color{magenta}ARIADNE}}$ \\
194           &
195           $\stackrel{\rm \color{blue}Event~Record}{\rightarrow\rightarrow}$ &
196           $\overbrace{\mbox{Hadronization~Package}}^{
197             \mbox{\color{magenta}Herwig}}$ \\
198           &
199           $\stackrel{\rm \color{blue}Event~Record}{\rightarrow\rightarrow}$ &
200           $\overbrace{\mbox{Decay~Package}}^{
201             \mbox{\color{magenta}EvtGen}}$ \\
202           &
203           $\stackrel{\rm \color{blue}Event~Record}{\rightarrow\rightarrow}$ &
204           $\overbrace{\mbox{Detector~Simulation}}^{
205             \mbox{\color{magenta}ATLfast}}$ \\
206         \end{tabular}\end{small}
207       \end{minipage}}\end{center}
357 garren 208   \caption[Modularised event generation]{\label{modularisation}
198 garren 209     HepMC supports the concept of modularised event generation
210     (illustrated above) by containing sufficient information within the
211     event record to act as a messenger between two modular steps in
212     the event generation process.  }
213 \end{figure}
214  
215  
216 Physics events are generally visualised using diagrams with a graph structure
217 (Figure~\ref{graph_structure}, left) which HepMC imitates by separating
218 out particles from vertices and representing them as the edges and
219 nodes respectively of a graph~\footnote{
220   Ref.~\cite{mc++} uses a similar structure.}
221 (Figure~\ref{graph_structure}, right). Each vertex maintains a listing of
222 its incoming and outgoing particles, while each particle points back
223 to its production vertex and decay vertex.
213 garren 224 The extension to  multiple collisions is natural - the
225 super-position of graphs from several different initial processes -
226 and so the event may contain an unlimited number
227 of (possibly interconnected) graphs.
228 The number of vertices/particles in each event is also open-ended.
198 garren 229 A subset of the event (such as one connected graph or a single vertex
230 and its descendants) may be examined or modified without having to
231 interpret complex parent/child relationship codes or re-shuffle the rest
232 of the event record.
233  
234 \begin{figure}[h]
235   \begin{center}
236      \parbox[c]{55mm}{\includegraphics[height=45mm,clip=]
237        {physicist_visualization.eps}}
238      \mbox{\huge ${\stackrel{\rm HepMC}{\rightarrow}}$}
239      \parbox[c]{45mm}{\includegraphics[height=45mm,clip=]
240        {graph_interpretation.eps}}
241   \end{center}
357 garren 242   \caption[Event visualization]
243    {\label{graph_structure} Events in HepMC are stored in a graph
198 garren 244     structure (right), similar to a physicist's visualisation of a
245     collision event (left).}
246 \end{figure}
247  
248 %
45 garren 249 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
250 %
251  
198 garren 252 \subsection{Features of the HepMC Event Record}
45 garren 253  
198 garren 254 \begin{itemize}\setlength{\itemsep}{0pt}
255 \item simple - easy access to information provided by iterators
432 garren 256       and range methods
198 garren 257 \item minimum dependencies
258 \item information is stored in a graph structure,
259   physically similar to a collision event
357 garren 260 \item allows specification of momentum and length units
198 garren 261 \item allows for the inclusion of spin density matrices
262 \item allows for the tracing of an arbitrary number of flow patterns
263 \item ability to store the state of random number generators (as
264   integers)
265 \item ability to store an arbitrary number of event weights
357 garren 266 \item ability to store parton distribution function information
267 \item ability to store heavy ion information
390 garren 268 \item ability to store generated cross section information on
269       an event by event basis
328 garren 270 \item strategies for conversion to/from HEPEVT (Ref.~\cite{Boos:2001cv})
271   which are easily extendible to support other event records
355 garren 272 \item strategies for input/output to/from Ascii files which
213 garren 273   are easily extendible to support other forms of persistency
390 garren 274 \item support for standard streaming I/O
198 garren 275 \end{itemize}
276  
277 %
278 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
279 %
280  
281 \section{HepMC 2}
282  
45 garren 283 Since January 2006, HepMC has been supported as an LCG external package.
284 The official web site is now \htmladdnormallink
285 {http://savannah.cern.ch/projects/hepmc/}
286 {http://savannah.cern.ch/projects/hepmc/},
287 and compiled libraries for supported platforms are available at
288 /afs/cern.ch/sw/lcg/external/HepMC.
289  
290 Historically, HepMC has used CLHEP (Ref.~\cite{clhep}) Lorentz vectors.  Some users wished to use
291 a more modern Lorentz vector package.  At the same time,
292 there was concern about allowing dependencies on any external package.  
293 Therefore, the decision was made to replace the CLHEP Lorentz vectors with
294 a minimal vector representation within HepMC.  
295  
357 garren 296 Because this is a major change, the versioning was changed
45 garren 297 from 1.xx.yy to 2.xx.yy.  Normally, a version number change in \emph{xx}
298 represents a change to the code and a version number change in \emph{yy}
299 represents a bug fix.
300  
198 garren 301 There have also been continuing requests for other features.
390 garren 302 Changes to HepMC must be approved by the LCG simulation project
303 (Ref.~\cite{lcgsim}).  
45 garren 304  
305 %
306 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
307 %
308  
198 garren 309 \subsection{Overview of Changes Since HepMC 1.26}
45 garren 310  
198 garren 311 See the HepMC ChangeLog~\cite{changelog} for a complete listing.
158 garren 312  
390 garren 313 GenEvent now contains pointers to a heavy ion class, a PDF information class,
314 and a generated cross section class.
328 garren 315 The pointers are null by default.  
316 In addition, GenEvent now has the capability to declare which
317 momentum and position units are used.
45 garren 318  
198 garren 319 GenParticle momentum and GenVertex position are represented by a simple FourVector
320 class instead of the CLHEP Lorentz vectors.  
45 garren 321 The SimpleVector.h header contains the FourVector and ThreeVector classes.
322 GenVertex will return the ThreeVector portion of the position.
323 Polarization will accept or return a ThreeVector representation
324 of the polarization.
325  
326 Both FourVector and ThreeVector have templated constructors.  
327 These constructors allow you to use the GenParticle and GenVertex constructors
328 with \emph{any} Lorentz vector, as long as the Lorentz vector has
329 \verb!x()!, \verb!y()!, \verb!z()!, and \verb!t()! methods.
330  
198 garren 331 The generated mass, which has always been part of the HEPEVT common block,
332 is now stored in GenParticle.  
45 garren 333 When a particle has large momentum and small mass,
334 calculating the mass from the momentum is unreliable.
335 Also, different machine representations and roundoff errors mean that
336 a calculated mass is not always consistent.
337 If no generated mass is set, then the mass is calculated from the momementum
338 and stored in GenParticle.
339  
198 garren 340 The IO\_AsciiParticles class provides output in the Pythia style.
341 This output is intended for ease of reading event output, not for persistency.
342  
390 garren 343 The IO\_Ascii output class has been replaced with of IO\_GenEvent,
328 garren 344 described in Section~\ref{iogenevent}.  
198 garren 345 IO\_GenEvent persists all information in the updated GenEvent object and
346 uses iostreams for greater flexibility.  IO\_GenEvent also has a
347 constructor taking a file name and mode type for backwards compatibility.
355 garren 348 Output remains in Ascii format.
198 garren 349  
390 garren 350 Streaming I/O of GenEvent objects may also be done without using IO\_GenEvent.
351  
352 The new HepMCDefs.h header allows users to query which features are
353 enabled.
354  
158 garren 355 %
356 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
357 %
49 garren 358  
198 garren 359 \section{Package Structure}
158 garren 360  
198 garren 361 Entries within the event record are separated into particles and
362 vertices. Each particle is composed of momentum, flow, and
363 polarization classes as well as id and status information.
364 The vertices are the connection nodes
365 between particles and are a container class for particles: thus each
366 particle within an event belongs to at least one vertex. In addition
367 the vertex is composed of position, id, and (spin density matrix)
368 weight information. Particles and vertices are uniquely identified by
369 an integer---referred to as a ``barcode''---which is meant to be a
213 garren 370 persistent label for a particular particle instance.
198 garren 371 The event is the container class for all (possibly
372 inter-connected) vertices in the event and contains process id, event
357 garren 373 number, unit information, weight, and random number state information.
158 garren 374  
403 garren 375 Please note that the barcodes are intended for internal use within HepMC
376 as a unique identifier for the particles and vertices.
377 Using the barcode to encode extra information is an abuse of
378 the barcode data member and causes confusion among users.
379  
198 garren 380 Iterators are provided as methods of the vertex and event classes
381 which allow easy directed access to information in the C++ Standard
432 garren 382 Template Library (STL) style.  
383 In addition, the GenRanges header contains several iterator
384 classes which explicity provide begin() and end() methods for the various
385 public iterator types, allowing the user to easily use such utilities as
386 Boost foreach.
45 garren 387  
357 garren 388 \begin{figure}[!ht]
198 garren 389   \begin{center}
202 garren 390     \includegraphics[width=\textwidth,clip=]{HepMC_basic_properties.eps}
198 garren 391   \end{center}
357 garren 392   \caption[HepMC class diagrams]
393     {\label{UML_diagrams} Class diagrams for the event record
202 garren 394     classes (GenEvent, GenVertex, and GenParticle) and the IO strategies
198 garren 395     are shown in the UML notation.}
396 \end{figure}
357 garren 397 \clearpage
158 garren 398  
390 garren 399 The event record class relationships are shown in Figure~\ref{UML_diagrams}.
357 garren 400  
198 garren 401 Several input/output strategies are provided. The interface for these
402 strategies is defined by an abstract base class, IO\_BaseClass.  These
403 strategies are capable of input/output of events and as such they depend
404 directly on the event record class.
158 garren 405  
198 garren 406 The package consists of about 5500~lines of code including
407 $\approx$1500~comments. There are 7 core classes (GenEvent,
408 GenVertex, GenParticle, Flow, Polarization, WeightContainer,
409 IO\_BaseClass) and several utility classes (i.e.\ IO\_HEPEVT, IO\_GenEvent,
410 HEPEVT\_Wrapper, PythiaWrapper, \ldots).
158 garren 411  
198 garren 412 \subsection{Dependencies}
158 garren 413  
198 garren 414 The HepMC 2 package  depends only on the C++ Standard
415 Template Library~\cite{stl} (STL).
416  
417 The HepMC 1 package dependencies were limited to STL
418 and the vector classes from the
328 garren 419 Class Library for High Energy Physics~\cite{clhep} (CLHEP).  
420  
421 Simple wrappers for the Fortran versions of Pythia~\cite{Sjostrand:2001yb}
422 and Herwig~\cite{herwig} are supplied with the
198 garren 423 package to allow the inclusion of event generation examples.
424  
425 \subsection{Namespace}
426  
427 The HepMC package is written within the HepMC:: namespace. Outside of
428 this namespace all class names will need to be prefixed by HepMC::.
429  
355 garren 430 The units methods and enums are in the HepMC::Units:: namespace.
431  
198 garren 432 \subsection{Performance}
433  
434 The CPU time performance of the HepMC event record has been quantified
435 by generating 1000 LHC $W\gamma$ production events using Pythia 5.7
436 and transferring the event record to HepMC using the IO\_HEPEVT
437 strategy. Results are summarised in Table~\ref{benchmarks}.
438 Generation of events in Pythia required 29 seconds of CPU time.
439 Generating the same events and transferring them into HepMC required
440 34 seconds.
441  
442 \begin{table}[h]
443 \begin{center}
444 \begin{tabular}{|l l l|c|c|} \hline
445 &&&CPU Time & File Size \\ \hline
446 Pythia &           &          & 29 sec & \\
447        & + {\color{red}HepMC}   &          & 34 sec & \\ \hline
448        & + {\color{red}HepMC} & + {\color{red}IO\_Ascii}
449        & 64 sec & 60.5 Mbytes \\
450        & + {\color{green}LCWRITE} &          
451        & 92 sec & 106 Mbytes \\
452 \multicolumn{3}{|l|}{HEPEVT raw size 1K events, 500K particles}
453 && 48.2 Mbytes \\ \hline
454 \end{tabular}
455 \end{center}
357 garren 456 \caption[Performance]{\label{benchmarks}
198 garren 457   CPU time performance and file size using a dedicated 450 MHz Pentium~III.}
458 \end{table}
459  
355 garren 460 The time to write HepMC events as Ascii files using the IO\_Ascii
198 garren 461 strategy was compared to \verb!LCWRITE!, a simple Fortran routine used
355 garren 462 in NLC studies to write the HEPEVT common block in formatted Ascii to file.
198 garren 463 Generating the events with Pythia, transferring them to HepMC, and
464 writing them to file took 64~seconds and produced a 60.5~Mbyte file.
465 Generating the events with Pythia and writing them to file using the
466 \verb!LCWRITE! subroutine took 92~seconds and produced a 106~Mbyte
467 file. Compression algorithms (such as \verb!gzip!) can reduce the file
468 sizes by a factor 3 or more.  The raw size of the HEPEVT common block
469 for these 1000~events (which in this case produced about 500K~particles) is
470 48.2~Mbytes.  In both cases most CPU time is spent writing to file.
471 HepMC benefits from added logic when interpreting the record and from
472 position information which is stored once for each vertex, rather than
473 with every particle.  
474  
475 CPU time savings will be realized when HepMC is
476 used inside event generators - since it is possible to target and
477 modify one area of the particle/vertex graph without re-shuffling the
478 rest of the event record.
479  
158 garren 480 %
481 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
482 %
198 garren 483 \section{Overview of Core Classes}
158 garren 484  
198 garren 485 \underline{\bf NOTE ABOUT UNITS}:
486 HepMC does not define which units are used for the information stored
487 in the event record.
488 The HEPEVT standard uses GeV/mm, and so the output from most Fortran
489 generators will normally be in these units.
328 garren 490 CLHEP and Geant4 use MeV/mm, and some collaborations such as ATLAS
198 garren 491 have adopted these units for their simulation.
337 garren 492 We also note that Fluka uses cm.
328 garren 493  
494 As of HepMC 2.04.00, GenEvent contains member data to store information
337 garren 495 about units used.  Default units are declared with configure switches
496 --with-momentum and --with-length.  
354 garren 497 These configure switches are required.
328 garren 498  
198 garren 499 HepMC users should refer to the code that fills the event record
500 to determine which units are being used.
501  
45 garren 502 %
503 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
504 %
505  
506 \subsection{HepMC::GenEvent}
507 \begin{myitemize}{Important Public Methods}
354 garren 508   \myitem{GenEvent(Units::MomentumUnit, Units::LengthUnit,...)}{As of
509     HepMC 2.04.00, additional constructors are available to enable
510     unit specification - see also use\_units below.}
45 garren 511   \myitem{add\_vertex}{adopts the specified vertex to the event and
512     assumes responsibility for deleting the vertex}
513   \myitem{remove\_vertex}{removes the specified vertex from the event,
514     the vertex is not deleted - thus use of this method is normally
515     followed directly by a delete vertex operation}
516   \myitem{vertex\_iterator}{iterates over all vertices in the event -
517     described in the iterator section}
518   \myitem{particle\_iterator}{iterates over all particles in the event
519     - described in the iterator section}
520   \myitem{vertex\_const\_iterator}{constant version of the vertex\_iterator}
521   \myitem{particle\_const\_iterator}{constant version of
522         the particle\_iterator}
432 garren 523   \myitem{vertex\_range}{provides begin() and end() for ease of use with
524           external fuctions, such as for\_each}
525   \myitem{particle\_range}{provides begin() and end() for ease of use with
526           external fuctions, such as for\_each}
45 garren 527   \myitem{print}{gives a formatted printout of the event to the
528     specified output stream}
529   \myitem{barcode\_to\_particle}{ returns a pointer to the particle
530         associated with the integer barcode argument }
531   \myitem{barcode\_to\_vertex}{ returns a pointer to the vertex
532         associated with the integer barcode argument }
337 garren 533   \myitem{use\_units}{set both momentum and position units, and scale FourVectors if necessary}
390 garren 534   \myitem{read}{read ascii input directly from an istream}
535   \myitem{write}{write ascii output directly to an ostream}
45 garren 536 \end{myitemize}
537 \begin{myitemize}{Relevant Data Members}
538   \myitem{signal\_process\_id}{an integer ID uniquely specifying the
539     signal process (i.e.\ MSUB in Pythia).}
540   \myitem{event\_number}{integer}
198 garren 541   \myitem{event\_scale}{(optional) the scale of this event.
45 garren 542         (-1 denotes unspecifed)}
543   \myitem{alphaQCD}{(optional) the value of the strong coupling
544     constant $\alpha_{QCD}$
545          used for this event. (-1 denotes unspecifed)}
546   \myitem{alphaQED}{(optional) the value of the electroweak coupling
547     constant $\alpha_{QED}$ (e.g.\ $\frac{1}{128}$)
548          used for this event. (-1 denotes unspecifed)}
549   \myitem{signal\_process\_vertex}{(optional) pointer to the vertex
550     defined as the signal process - allows fast navigation to the core
551     of the event}
198 garren 552   \myitem{beam\_particle\_1}{(optional) pointer to the first incoming beam particle }
553   \myitem{beam\_particle\_2}{(optional) pointer to the second incoming beam particle }
45 garren 554   \myitem{weights}{a container of an arbitrary number of 8 byte
432 garren 555     floating point event weights and their associated names}
198 garren 556   \myitem{random\_states}{a container of an arbitrary number of 4 byte
557     integers which define the random number generator state just
45 garren 558     before the event generation}
559   \myitem{heavy\_ion}{(optional) a pointer to a HeavyIon object
560                       (zero by default)}
561   \myitem{pdf\_info}{(optional) a pointer to a PdfInfo object
562                      (zero by default)}
390 garren 563   \myitem{cross\_section}{(optional) a pointer to a GenCrossSection object
564                      (zero by default)}
337 garren 565   \myitem{momentum\_unit}{momentum units (MEV or GEV)}
566   \myitem{length\_unit}{position units (MM or CM)}
45 garren 567 \end{myitemize}
390 garren 568 \begin{myitemize}{Important Free Functions}
569   \myitem{operator $>>$}{read ascii input directly from an istream}
570   \myitem{operator $<<$}{write ascii output directly to an ostream}
571 \end{myitemize}
45 garren 572 \begin{myitemize}{Notes and Conventions}
573   \item if hit and miss Monte Carlo integration is to be performed
574     with a single event weight, the first weight will be used by default
575   \item Memory allocation: vertex and particle objects will normally
576     be created by the user with the NEW operator. Once a vertex
577     (particle) is added to a event (vertex), it is "adopted" and
578     becomes the responsibility of the event (vertex) to delete that
579     vertex (particle).
354 garren 580   \item Although default units are specified with configure, the user
581     is strongly encouraged to explicitly set units with either the
582     appropriate constructor or a call to set\_units.
45 garren 583 \end{myitemize}
584  
585 The GenEvent is the container class for vertices.
586 A listing of all vertices is maintained with the event, giving fast
587 access to vertex information. GenParticles are accessed by means of the
588 vertices.
589  
390 garren 590 Extended event features
591 (weights, random\_states, heavy\_ion, pdf\_info, cross\_section)
45 garren 592 have been implemented such that if left empty/unused performance and memory
593 usage will be similar to that of an event without these features.
594  
198 garren 595 Iterators are provided as members of the GenEvent class
596 (described in Section~\ref{iterators}). Methods which fill containers of
597 particles or vertices are {\it not provided}, as the STL provides these
598 functionalities with algorithms such as \verb!copy! and iterator adaptors
599 such as \verb!back_inserter! giving a clean generic approach.
600 Using this functionality it is easy to obtain lists of
601 particles/vertices given some criteria - such as a list of all final
602 state particles. Classes which provide the criteria (called
603 predicates) are also {\it not provided}, as the number of
604 possibilities is open ended and specific to the application -
605 and would clutter the HepMC package. Implementing a predicate is
606 simple (about 4 lines of code).
607 Examples are given in the GenEvent header file and in
608 \verb!example_UsingIterators.cc! (Section~\ref{examples}).
432 garren 609 Useful examples can also be found in testHepMCIteration.cc.
45 garren 610  
611 The signal\_process\_id is packaged with each event (rather than being
612 associated with a run class for example) to handle the possibility of
613 many processes being generated within the same run. A container of
614 tags specifying the meaning of the weights and random\_states entries
615 is envisioned as part of a run class - which is beyond the scope of an
616 event record.
198 garren 617  
45 garren 618 %
619 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
620 %
621  
198 garren 622 \subsubsection{HepMC::PdfInfo}
623 \begin{myitemize}{Relevant Data Members}
624   \myitem{id1}{flavour code of first parton}
625   \myitem{id2}{flavour code of second parton }
289 garren 626   \myitem{pdf\_id1}{LHAPDF set id of first parton}
627   \myitem{pdf\_id2}{LHAPDF set id of second parton}
198 garren 628   \myitem{x1}{fraction of beam momentum carried by first parton ("beam side")}
629   \myitem{x2}{fraction of beam momentum carried by second parton ("target side")}
630   \myitem{scalePDF}{Q-scale used in evaluation of PDF's (in GeV)}
289 garren 631   \myitem{pdf1}{PDF (id1, x1, Q)  This should be of the form x*f(x)}
632   \myitem{pdf2}{PDF (id2, x2, Q)  This should be of the form x*f(x)}
198 garren 633 \end{myitemize}
289 garren 634 \begin{myitemize}{Notes and Conventions}
635   \item The LHAPDF\cite{lhapdf} set ids are the entries in the first column of
636         \htmladdnormallink
637         {http://projects.hepforge.org/lhapdf/PDFsets.index}
638         {http://projects.hepforge.org/lhapdf/PDFsets.index}.
639   \item The LHAPDF set ids pdf\_id1 and pdf\_id2 are zero by default.
640   \item IMPORTANT: The contents of pdf1 and pdf2 are expected to be x*f(x),
641         which is the quantity returned by LHAPDF.
332 garren 642   \item IMPORTANT: Input parton flavour codes id1 and id2 are expected to
643         obey the PDG code conventions, especially g = 21.
289 garren 644 \end{myitemize}
198 garren 645  
646 PdfInfo stores additional PDF information for a GenEvent.
647 Creation and use of this information is optional.
648  
649 %
650 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
651 %
652  
653 \subsubsection{HepMC::HeavyIon}
654 \begin{myitemize}{Relevant Data Members}
655   \myitem{Ncoll\_hard}{Number of hard scatterings}
656   \myitem{Npart\_proj}{Number of projectile participants}
657   \myitem{Npart\_targ}{Number of target participants}
658   \myitem{Ncoll}{Number of NN (nucleon-nucleon) collisions}
659   \myitem{N\_Nwounded\_collisions}{Number of N-Nwounded collisions}
660   \myitem{Nwounded\_N\_collisions}{Number of Nwounded-N collisons}
661   \myitem{Nwounded\_Nwounded\_collisions}{Number of Nwounded-Nwounded collisions}
662   \myitem{spectator\_neutrons}{Number of spectators neutrons}
663   \myitem{spectator\_protons}{Number of spectators protons}
664   \myitem{impact\_parameter}{Impact Parameter(fm) of collision}
665   \myitem{event\_plane\_angle}{Azimuthal angle of event plane}
666   \myitem{eccentricity}{eccentricity of participating nucleons
667          in the transverse plane (as in phobos nucl-ex/0510031)}
668   \myitem{sigma\_inel\_NN }{nucleon-nucleon inelastic
669                           (including diffractive) cross-section}
670 \end{myitemize}
671  
672 HeavyIon provides additional information storage in GenEvent for Heavy Ion
673 generators.  Creation and use of this information is optional.
674  
390 garren 675  
198 garren 676 %
677 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
678 %
679  
390 garren 680 \subsubsection{HepMC::GenCrossSection}
681 \begin{myitemize}{Relevant Data Members}
682   \myitem{cross\_section}{cross section in pb}
683   \myitem{cross\_section\_error}{error associated with this cross section in pb}
684 \end{myitemize}
685  
686 GenCrossSection provides additional storage in GenEvent for an event by event
687 snapshot of the cross section while events are being generated.
688 It is expected that the final cross section will be stored elsewhere.
689 Creation and use of this information is optional.
690  
691 %
692 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
693 %
694  
337 garren 695 \subsubsection{HepMC::Units}
696 \begin{myitemize}{Important Methods}
697   \myitem{enum MomentumUnit}{values are MEV or GEV}
698   \myitem{enum LengthUnit}{values are MM or CM}
699   \myitem{std::string name(MomentumUnit)}{return the unit designation as a string}
700   \myitem{std::string name(LengthUnit)}{return the unit designation as a string}
328 garren 701 \end{myitemize}
702 \begin{myitemize}{Notes and Conventions}
337 garren 703   \item Refer to a unit enum as, for instance, HepMC::Units::GEV
704   \item Whenever both unit types are passed, MomentumUnit always goes first.
328 garren 705 \end{myitemize}
706  
337 garren 707 Units is a namespace encapsulating methods used for unit manipulation.
708 Default units are set at compile time by the configure switches
709 --with-momentum and --with-length.  
328 garren 710  
711 %
712 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
713 %
714  
45 garren 715 \subsection{HepMC::GenVertex}
716 \begin{myitemize}{Important Public Methods}
717   \myitem{add\_particle\_in}{adds the specified particle to the
718     container of incoming particles}
719   \myitem{add\_particle\_out}{adds the specified particle to the
720     container of outgoing particles}
721   \myitem{remove\_particle}{removes the specified particle from
722     both/either of the incoming/outgoing particle containers, the
723     particle is not deleted - thus use of this method is normally
724     followed directly by a delete particle operation}
725   \myitem{vertex\_iterator}{iterates over vertices in the graph,
726     given a specified range - described in the iterator section}
727   \myitem{particle\_iterator}{iterates over particles in the graph,
728     given a specified range - described in the iterator section}
432 garren 729   \myitem{particles}{provides begin() and end() for ease of use with
730           external fuctions, such as for\_each}
731   \myitem{particles\_in}{provides begin() and end() for ease of use with
732           external fuctions, such as for\_each}
733   \myitem{particles\_out}{provides begin() and end() for ease of use with
734           external fuctions, such as for\_each}
45 garren 735 \end{myitemize}
736 \begin{myitemize}{Relevant Data Members}
737   \myitem{position}{$\vec{x},ct$ stored as FourVector}
738   \myitem{id}{integer id, may be used to specify a vertex type}
739   \myitem{weights}{a container of 8 byte floating point numbers of
740     arbitrary length, could be mapped in pairs into rows and columns to
741     form spin density matrices of complex numbers}
742   \myitem{barcode}{an integer which uniquely identifies the GenVertex
743     within the event. For vertices the barcodes are always negative integers.}
744 \end{myitemize}
745 \begin{myitemize}{Notes and Conventions}
746   \item no standards are currently defined for the vertex id
747   \item once a particle is added, the vertex becomes its owner and is
748     responsible for deleting the particle
749 \end{myitemize}
750  
751 The GenVertex is the container class for particles and forms the nodes
752 which link particles into a graph structure.
753  
198 garren 754 The weights container is included with each vertex with the intention
755 of storing spin density matrices. It is envisioned that a
756 generator package would assign spin density matrices to particle
757 production vertices and provide the functional form of the frame
758 definition for the matrix as a ``look-up'' method for interpreting
759 the weights. The generator package would also provide a boost method
760 to go from the frame of the density matrix to the lab frame and back
761 without destroying correlations. This gives maximum freedom to the
762 sub-generators - allowing for different form definitions.
763 This implementation is consistent with the EvtGen B-decay
764 package~\cite{evtgen} requirements.
765  
45 garren 766 %
767 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
768 %
769  
198 garren 770 \subsection{HepMC::WeightContainer}
771 \begin{myitemize}{Relevant Data Members}
772   \myitem{weights}{a vector of 8-byte floating point weights}
432 garren 773   \myitem{names}{a map of strings associated with a position in the weights vector}
198 garren 774 \end{myitemize}
775 \begin{myitemize}{Notes and Conventions}
776 \item methods are coded and names chosen in the spirit of the
777   STL vector class
778 \end{myitemize}
779  
432 garren 780 The WeightContainer is a storage area for double precision
781 weights used in GenEvent and GenVertex and their associated names.
782 WeightContainer mimics both a map class and the STL vector class,
783 and its member functions are chosen in that spirit.  
213 garren 784 You might, for instance, use the GenEvent weights to include
785 information about differential cross sections.
198 garren 786  
787 %
788 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
789 %
790  
45 garren 791 \subsection{HepMC::GenParticle}
792 \begin{myitemize}{Important Public Methods}
793   \myitem{operator FourVector}{conversion operator -
794     resolves the particle as a 4-vector according to its momentum}
795   \myitem{generatedMass}{generated mass}
796   \myitem{momentum().m()}{calculates mass from momentum}
432 garren 797   \myitem{particles\_in}{provides begin() and end() for ease of use with
798           external fuctions, such as for\_each}
799   \myitem{particles\_out}{provides begin() and end() for ease of use with
800           external fuctions, such as for\_each}
45 garren 801 \end{myitemize}
802 \begin{myitemize}{Data Members}
803   \myitem{momentum}{$\vec{p},cE$ stored as FourVector}
804   \myitem{generated\_mass}{generated mass for this particle}
805   \myitem{pdg\_id}{unique integer ID specifying the particle type}
806   \myitem{status}{integer specifying the particle's status
807   (i.e.\ decayed or not)}
808   \myitem{flow}{allows for the storage of flow patterns (i.e. color
809     flow), refer to Flow class}
810   \myitem{polarization}{stores the particle's polarization as
811   $(\theta,\phi)$, refer to Polarization class}
812   \myitem{production\_vertex}{pointer to the vertex where the particle
813     was produced, can only be set by the vertex}
814   \myitem{end\_vertex}{pointer to the vertex where the particle decays,
815     can only be set by the vertex}
816   \myitem{barcode}{an integer which uniquely identifies the GenParticle
817     within the event. For particles the barcodes are always positive integers.}
818 \end{myitemize}
819 \begin{myitemize}{Notes and Conventions}
820   \item the particle ID should be specified according to the
821     PDG standard~\cite{Yao:2006tx}
390 garren 822   \item the status code should be specified according to the clarified  
823      HEPEVT status codes
45 garren 824 \end{myitemize}
825  
826 The particle is the basic unit within the event record. The GenParticle
827 class is composed of the FourVector, Flow, and Polarization classes.
828  
829 Pointers to the particle's production and end vertex are included. In
830 order to ensure consistency between vertices/particles - these
831 pointers can only be set from the vertex. Thus adding a particle to
832 the particles\_in container of a vertex will automatically set the
833 end\_vertex of the particle to point to that vertex.
834  
198 garren 835 The definition of a HepLorentzVector scope resolution operator allows
836 for the use of 4-vector algebra with particles (i.e.\ preceding an
837 instance, \verb!particle!, of the HepMC::GenParticle class by
838 \verb!(HepLorentzVector)particle!  causes it to behave exactly like
839 its 4-vector momentum, examples are given in the particle header file).
840  
841 A second 4-vector for the particle's momentum at decay time has
842 {\it not} been included (as for example in~\cite{mc++}, where the
843 second momentum vector is included to facilitate tracking through
844 material). If this is desirable, one can simply add a decay vertex
845 with the same particle type going out. This is intuitive, since a
846 change in momentum cannot occur without an interaction (vertex).
847  
390 garren 848 After some discussion, the authors in MCnet~\cite{mcnet} have agreed to a
849 clarification of the HEPEVT~\cite{stdhep5.05} status codes.
850 The Fortran Monte Carlo generators will not change their behaviour,
851 but Sherpa, Pythia8, and Herwig++ will go to the newer usage.\newline
852 These are the accepted status code definitions:
853 \begin{myitemize}{}
854  \myitem{0     }{an empty entry with no meaningful information
855                     and therefore to be skipped unconditionally}
856  \myitem{1     }{a final-state particle, i.e. a particle that is not decayed
857  further by the generator (may also include unstable particles
858  that are to be decayed later, as part of the detector simulation).
859  Such particles must always be labelled '1'.}
860  \myitem{2     }{decayed Standard Model hadron or tau or mu lepton,
861  excepting virtual intermediate states thereof (i.e. the
862  particle must undergo a normal decay, not e.g. a
863  shower branching). Such particles must always be labelled '2'.
864  No other particles can be labelled '2'.}
865  \myitem{3     }{a documentation entry}
866  \myitem{4     }{an incoming beam particle}
867  \myitem{5-10  }{undefined, reserved for future standards}
868  \myitem{11-200}{an intermediate (decayed/branched/...) particle that
869        does not fulfill the criteria of status code 2,
870        with a generator-dependent classification of its nature.}
871  \myitem{201-  }{at the disposal of the user, in particular for event
872  tracking in the detector}
873 \end{myitemize}
874  
875  
45 garren 876 %
877 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
878 %
879  
198 garren 880 \subsubsection{HepMC::Flow}
881 \begin{myitemize}{Important Public Methods}
882   \myitem{connected\_partners}{returns a container of all particles
883     connected via the specified flow pattern}
884   \myitem{dangling\_connected\_partners}{returns a container of all
885     particles ``dangling'' from the ends of the specified flow
886     pattern}
887 \end{myitemize}
888 \begin{myitemize}{Relevant Data Members}
889   \myitem{particle\_owner}{points back to the particle to which
890     the flow object belongs}
891   \myitem{icode map}{container of integer flow codes - each entry has
892     an index and an icode}
893 \end{myitemize}
894 \begin{myitemize}{Notes and Conventions}
895   \item code indices 1 and 2 are reserved for color flow
896 \end{myitemize}
897  
898 The Flow class is a data member of the GenParticle---its use is
899 optional.  It stores flow
900 pattern information as a series of integer flow codes and indices.
901 This method features the possibility
902 of storing non-conserved flow patterns (such as baryon number
903 violation in SUSY models).
904 Some examples of integer flow code representation for several events
905 are provided in Ref.~\cite{Boos:2001cv}.
906  
907 The Flow class is used to keep track of flow patterns within a graph -
908 each pattern is assigned a unique integer code, and this code is
909 attached to each particle through which it passes. Different flow
910 types are assigned different flow indices, i.e.\ color flow uses index
911 1 and 2. Methods are provided to return a particle's flow partners. An
912 example is given at the top of the Flow header file.
913  
914 %
915 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
916 %
917  
45 garren 918 \subsubsection{HepMC::Polarization}
432 garren 919 \begin{myitemize}{Important Public Methods}
920   \myitem{is\_defined}{returns true if the Polarization has been defined}
921   \myitem{set\_undefined}{set this to undefined, resetting theta and phi
922           to their default values}
923 \end{myitemize}
45 garren 924 \begin{myitemize}{Relevant Data Members}
925   \myitem{theta}{$\theta$ angle in radians $0\leq\theta\leq\pi$}
926   \myitem{phi}{$\phi$ angle in radians $0\leq\phi<2\pi$}
927 \end{myitemize}
928 \begin{myitemize}{Notes and Conventions}
929   \item the angles are robust - if you supply an angle outside the
930     range, it is properly translated (i.e.\ $4\pi$ becomes 0)
931 \end{myitemize}
932  
933 Polarization is a data member of GenParticle - its use is
934 optional. It stores the $(\theta,\phi)$ polarization information which
935 can be returned as a ThreeVector as well.
936  
937 %
938 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
939 %
940  
213 garren 941 \subsubsection{HepMC::FourVector}
942 \begin{myitemize}{Important Public Methods}
943   \item A number of simple vector manipulations are available.
944           Check the reference manual for details.
945 \end{myitemize}
946 \begin{myitemize}{Relevant Data Members}
947   \myitem{x}{position x or momentum px}
948   \myitem{y}{position y or momentum py}
949   \myitem{z}{position z or momentum pz}
950   \myitem{t}{time or energy}
951 \end{myitemize}
952  
953 GenParticle momentum and GenVertex position are stored as FourVectors.
954 FourVector has a templated constructor that will automatically convert
955 any other vector with x(), y(), z(), and t() access methods to a FourVector.
956 This feature is used when converting from the HEPEVT common block.
957  
958 %
959 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
960 %
961  
45 garren 962 \subsection{HepMC::IO\_BaseClass}
963 \begin{myitemize}{Important Public Methods}
964   \myitem{write\_event}{writes out the specified event to the output
965     strategy}
966   \myitem{read\_next\_event}{reads the next event from the input
967     strategy into memory}
968   \myitem{operator$<<$,operator$>>$}{overloaded to give the
198 garren 969     same results as any of the above methods}
45 garren 970 \end{myitemize}
971  
972 IO\_BaseClass is the abstract base class defining the interface and
973 syntax for input and output strategies of events and particle data tables.
974  
975 Several IO strategies are supplied:
976 \begin{itemize}\setlength{\itemsep}{0pt}
158 garren 977   \item {\bf IO\_GenEvent} uses iostreams for input and output
978     thereby providing a form of persistency for the event record.
979     This class handles all information found in a GenEvent object.
198 garren 980     This class replaces IO\_Ascii and reads both formats.
45 garren 981     Events may be contained within the same file together with
982     an unlimited number of comments.
158 garren 983     The examples (Section~\ref{examples}) make use of this class.
198 garren 984   \item {\bf IO\_AsciiParticles} writes events in a format similar to
985      Pythia 6 output.  This is intended for human readability.
45 garren 986   \item {\bf IO\_HEPEVT} reads and writes events to/from the Fortran HEPEVT
987     common block. It relies on a helper class HEPEVT\_Wrapper which
988     is the interface to the common block
989     (which is defined in the header file HEPEVT\_Wrapper.h\footnote{
990       Different conventions exist for the fortran HEPEVT common
991       block. 4 or 8-byte floating point numbers may be used, and the
357 garren 992       number of entries is often taken as 4000 or 10000. To account for
45 garren 993       all possibilities the precision (float or double) and number of
994       entries can be set for the wrapper at run time,
995       \begin{tabbing}
996       i.e.\ \hspace{1cm} \= HEPEVT\_Wrapper::set\_max\_number\_entries(4000);\\
997                          \> HEPEVT\_Wrapper::set\_sizeof\_real(8);
998             \hspace{1cm} .
999       \end{tabbing}
1000       To interface properly to HEPEVT and avoid nonsensical
1001       results, it is essential to get these definitions right
198 garren 1002       {\it for your application}. See example\_MyPythia.cc
1003       (Section~\ref{examples}) for an example.
45 garren 1004       }).
1005     This IO strategy
1006     provides the means for interfacing to Fortran event
1007     generators. Other strategies which interface directly to the
1008     specific event record of a generator could be easily implemented
1009     in this style. An example of using IO\_HEPEVT to transfer events
198 garren 1010     from Pythia into HepMC is given in \verb!example_MyPythia.cc!
1011     (Section~\ref{examples}).
45 garren 1012 \end{itemize}
328 garren 1013  
390 garren 1014 Note that as of HepMC 2.05 it is possible to read and write events directly
1015 with streaming I/O operators instead of using IO\_GenEvent.  
1016  
198 garren 1017 %
1018 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1019 %
45 garren 1020  
198 garren 1021 \section{Overview of Iterators}
1022 \label{iterators}
45 garren 1023  
198 garren 1024 Examples of using the particle/vertex iterators are provided in
432 garren 1025 \verb!example_UsingIterators.cc! (Section~\ref{examples}).  
1026 Useful examples can also be found in testHepMCIteration.cc.
198 garren 1027  
432 garren 1028 As of HepMC 2.06.00, iterator range classes and methods are
1029 available for improved functionality.
1030  
80 garren 1031 %
1032 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1033 %
45 garren 1034  
198 garren 1035 \subsection{HepMC::GenEvent::vertex\_iterator}
1036  
1037 GenEvent::vertex\_iterator inherits from
1038 std::iterator<std::forward\_iterator\_tag,...>.
1039 It walks through all vertices in the event exactly once. It is robust and
1040 fast, and provides the best way to loop over all vertices in the
1041 event. For each event,
1042 vertices\_begin() and vertices\_end() define the beginning and
1043 one-past-the-end of the particle iterator respectively.
1044  
432 garren 1045 GenEventVertexRange( GenEvent\& ) is a wrapper for
1046 GenEvent::vertex\_iterator which provides begin() and end() for
1047 ease of use with external fuctions, such as Boost foreach.
1048 GenEvent::vertex\_range() also provides this functionality.
198 garren 1049  
1050 %
1051 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1052 %
1053  
1054 \subsection{HepMC::GenEvent::vertex\_const\_iterator}
1055  
1056 A constant version of HepMC::GenEvent::vertex\_iterator, otherwise identical.
1057  
432 garren 1058 ConstGenEventVertexRange is the constant version of GenEventVertexRange.
1059  
198 garren 1060 %
1061 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1062 %
1063  
1064 \subsection{HepMC::GenEvent::particle\_iterator}
1065  
1066 GenEvent::particle\_iterator inherits from
1067 std::iterator<std::forward\_iterator\_tag,...>.
1068 It walks through all particles in the
1069 event exactly once. It is robust and fast, and provides the best way
1070 to loop over all particles in the event. For each event,
1071 particles\_begin() and particles\_end() define the beginning and
1072 one-past-the-end of the particle iterator respectively.
1073  
432 garren 1074 GenEventParticleRange( GenEvent\& ) is a wrapper for
1075 GenEvent::particle\_iterator which provides begin() and end() for
1076 ease of use with external fuctions, such as Boost foreach.
1077 GenEvent::particle\_range() also provides this functionality.
198 garren 1078  
1079 %
1080 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1081 %
1082  
1083 \subsection{HepMC::GenEvent::particle\_const\_iterator}
1084  
1085 A constant version of HepMC::GenEvent::particle\_iterator, otherwise
1086 identical.
1087  
432 garren 1088 ConstGenEventParticleRange is the constant version of GenEventParticleRange.
1089  
198 garren 1090 %
1091 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1092 %
1093  
1094 \subsection{HepMC::GenVertex::vertex\_iterator}
1095 \begin{myitemize}{Notes and Conventions}
1096   \item the iterator range must be specified to instantiate -
1097     choices are: parents, children, family, ancestors, descendants,
1098     and relatives
1099   \item note: iterating over all ancestors and all descendents is {\it
1100       not} necessarily equivalent to all relatives - this is consitent
1101     with the range definitions
1102 \end{myitemize}
1103  
1104 GenVertex::vertex\_iterator differs from GenEvent::vertex\_iterator
1105 in that it has both a starting point and a range. The starting point
1106 is the vertex - called the root - from which the iterator was
1107 instantiated, and the range is defined relative to this point.
1108 The possible ranges are defined by an enumeration called
1109 HepMC::IteratorRange and the possibilities are:
1110 \begin{itemize}\setlength{\itemsep}{0pt}
1111   \myitem{parents}{walks over all vertices connected to the root via
1112     incoming particles}
1113   \myitem{children}{walks over all vertices connected to the root via
1114     outgoing particles}
1115   \myitem{family}{walks over all vertices connected to the root via
1116     incoming or outgoing particles}
1117   \myitem{ancestors}{walks over all vertices connected to the root via
1118     any number of incoming particle edges - i.e. returns the parents,
1119     grandparents, great-grandparents, \ldots}
1120   \myitem{descendants}{walks over all vertices connected to the root via
1121     any number of outgoing particle edges - i.e. returns the children,
1122     grandchildren, great-grandchildren, \ldots}
1123   \myitem{relatives}{walks over all vertices belonging to the same
1124     particle/vertex graph structure as the root}
1125 \end{itemize}
1126  
1127 The iterator algorithm traverses the graph by converting it to a tree
1128 (by ``chopping'' the edges at the point where a closed cycle connects
1129 to an already visited vertex) and returning the vertices in post
1130 order. The iterator requires more logic than the
1131 GenEvent::vertex\_iterator and thus access time is slower (the
1132 required to return one vertex goes like $\log n$ where $n$ is the
1133 number of vertices already returned by the iterator).
1134  
1135 GenVertex::vertex\_iterator allows the user to step into a specific part
1136 of a particle/vertex graph and obtain targetted information about it.
1137  
1138 %
1139 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1140 %
1141  
1142 \subsection{HepMC::GenVertex::particle\_iterator}
1143 \begin{myitemize}{Notes and Conventions}
1144   \item the iterator range must be specified to instantiate -
1145     choices are: parents, children, family, ancestors, descendants,
1146     and relatives
1147 \end{myitemize}
1148  
1149 GenVertex::particle\_iterator behaves exactly like
1150 GenVertex::vertex\_iterator, with the exception that it returns particles
1151 rather than vertices.  As a particle defines an edge or line (rather
1152 than a point) in the particle/vertex graph, it is intuitive to define
1153 the particle\_iterator relative to a vertex (point in the graph) - thus
1154 the starting point (root) is still a vertex, and the range is defined
1155 relative to this root.  The extension to particles can be made by
1156 using the particle's production or end vertex as the root.  Possible
357 garren 1157 ranges are defined by an enumeration called HepMC::IteratorRange.
1158 The possibilities are:
198 garren 1159 \begin{itemize}\setlength{\itemsep}{0pt}
1160   \myitem{parents}{walks over all particles incoming to the root}
1161   \myitem{children}{walks over all particles outgoing from the root}
1162   \myitem{family}{walks over all particles incoming or outgoing from
1163   the root}
1164   \myitem{ancestors}{walks over all incoming particles or particles
1165   incoming to ancestor vertices of the root - i.e. returns the parents,
1166     grandparents, great-grandparents, \ldots}
1167   \myitem{descendants}{walks over all outgoing particles or particles
1168     outgoing to descendant vertices of the root - i.e. returns the children,
1169     grandchildren, great-grandchildren, \ldots}
1170   \myitem{relatives}{walks over all particles belonging to the same
1171     particle/vertex graph structure as the root}
1172 \end{itemize}
1173  
1174 The class is composed of a GenVertex::vertex\_iterator -
1175 and the same considerations apply.
1176  
432 garren 1177 GenVertexParticleRange( GenVertex\&, IteratorRange ) is a wrapper for
1178 GenVertex::particle\_iterator which provides begin() and end() for
1179 ease of use with external fuctions, such as Boost foreach.
1180 If the HepMC::IteratorRange is unspecified, it defaults to "relatives".
1181 GenVertex::particles( IteratorRange ) also provides this functionality.
1182  
1183 Also provided, are GenParticleProductionRange( GenParticle\&, IteratorRange )
1184 and GenParticleEndRange( GenParticle\&, IteratorRange ),
1185 which iterate over the GenParticle's production or end vertex.  
1186 If the vertex is undefined, begin() and end() will throw a std::range\_error.
1187 If the HepMC::IteratorRange is unspecified, it defaults to "relatives".
1188 GenVertex::particles\_in( GenParticle\&, IteratorRange ),
1189 GenVertex::particles\_out( GenParticle\&, IteratorRange ),
1190 GenParticle::particles\_in( IteratorRange ), and
1191 GenParticle::particles\_out( IteratorRange ) also provide this functionality.
1192  
198 garren 1193 %
1194 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1195 %
1196  
328 garren 1197 \section{Ascii Output}
1198 \label{iogenevent}
1199  
1200 Ascii output uses begin and end keys to denote blocks of events.
1201 The HepMC version is written immediately before the begin key, but
1202 is not part of the event block.
1203  
1204 Within a block of events, each line of information begins with a
1205 single character key denoting the information found on the line.
1206  
1207 General GenEvent information is followed by a list of vertices
1208 and associated particles.  The count of vertices is expected to match the
1209 number of vertices specified in the general event information.
1210 Each vertex line specifies how many particle lines are associated
1211 with the vertex.
354 garren 1212  
390 garren 1213 As of HepMC 2.05, it is possible to read and write events directly
1214 with the streaming I/O operators $>>$ and $<<$ instead of using IO\_GenEvent.  
1215 However, the HepMC event block header and footer will not be written
1216 automatically if this method is used.  The user must call
1217 write\_HepMC\_IO\_block\_begin and write\_HepMC\_IO\_block\_end explicitly.
1218 IO\_GenEvent uses these operators internally.
1219  
1220 We describe the Ascii output here, which persists all information
354 garren 1221 contained in a HepMC GenEvent.
1222  
1223 %
1224 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1225 %
1226  
1227 \subsection{Basic IO\_GenEvent Structure}
1228  
328 garren 1229 \begin{myitemize}{Block Keys}
1230   \myitem{begin event block}{HepMC::IO\_GenEvent-START\_EVENT\_LISTING}
1231   \myitem{end event block}{HepMC::IO\_GenEvent-END\_EVENT\_LISTING}
1232 \end{myitemize}
1233 \begin{myitemize}{Line Keys}
1234   \myitem{E}{general GenEvent information}
432 garren 1235   \myitem{N}{named weights}
337 garren 1236   \myitem{U}{momentum and position units}
390 garren 1237   \myitem{C}{GenCrossSection information:
1238              This line will appear ONLY if GenCrossSection is defined.}
354 garren 1239   \myitem{H}{HeavyIon information:  
1240              This line will contain zeros if there is no associated HeavyIon object.}
1241   \myitem{F}{PdfInfo information:
1242              This line will contain zeros if there is no associated PdfInfo object.}
328 garren 1243   \myitem{V}{GenVertex information}
1244   \myitem{P}{GenParticle information}
1245 \end{myitemize}
1246  
432 garren 1247 Note that the E, N, U, C, H, and F lines contain event header information.
1248 There will be one and only one of these lines per event.
1249 Other lines with keys not specified above may be interspersed with the header
433 garren 1250 information.
1251 The N, U, C, H, and F lines must lie between the E line and the first V line
1252 for each event.  N, U, C, H, and F lines can appear in any order.
354 garren 1253 The header information is followed immediately by a V (vertex) line.
1254 Each vertex line is immediately followed by the P (particle) lines
1255 for particles associated with that vertex.  
1256 For purposes of IO, particles are associated with a vertex if they
1257 are in the list of outgoing particles.
1258 In addition, if an incoming particle is not an outgoing particle of
1259 some other vertex, then it is classified as an "orphan" incoming particle
1260 and associated with the vertex IO.
1261 In this way, each particle appears only once in the Ascii listing.
391 garren 1262 An example of the basic format written to a file is shown in Figure~\ref{ascii_format}.
1263 See Figure~\ref{ascii_stream} for an example of streaming ouput and
1264 Figure~\ref{ascii_cross} for an example with GenCrossSection information.
354 garren 1265  
357 garren 1266 \begin{figure}[h]
1267   \begin{center}
1268 {\tiny \begin{verbatim}
433 garren 1269 HepMC::Version 2.06.00
1270 HepMC::IO_GenEvent-START_EVENT_LISTING
1271 E 9 51 -1.0000000000000000e+00 -1.0000000000000000e+00 -1.0000000000000000e+00 20 0 309 1 2 0 4 2.3000000000000001e-01 3.4000000000000002e-01 1.1000000000000000e-01 6.5000000000000002e-02
1272 N 4 "0" "1" "2" "3"
1273 U GEV MM
1274 H 23 11 12 15 3 5 0 0 0 1.4499999582767487e-02 0 0 0
355 garren 1275 F 2 3 3.5000000000000003e-01 6.4999999999999991e-01 8.4499999999999993e+00 2.4499999779912355e+03 4.5499999591265787e+03 230 230
433 garren 1276 V -1 0 0 0 0 0 1 3 0
355 garren 1277 P 1 2212 0 0 6.9999999371178146e+03 7.0000000000000000e+03 9.3827000000000005e-01 3 0 0 -1 0
1278 P 3 21 -9.5802904850995474e-01 3.4892974578914365e-01 1.5677975928920182e+01 1.5711094833049845e+01 0 3 0 0 -3 0
433 garren 1279 P 12 2101 2.5787537037233477e-01 -1.1110299643709216e-01 1.2403958218239170e+03 1.2403959888942973e+03 5.7933000000000001e-01 2 0 0 -9 0
355 garren 1280 P 25 2 7.0015367813761997e-01 -2.3782674935205150e-01 2.3333682308044050e+00 2.4698753078332274e+00 3.3000000000000002e-01 2 0 0 -15 0
433 garren 1281 V -2 0 0 0 0 0 1 2 0
355 garren 1282 P 2 2212 0 0 -6.9999999371178146e+03 7.0000000000000000e+03 9.3827000000000005e-01 3 0 0 -2 0
1283 P 4 1 2.7745239600449745e-01 -1.8469236508822412e-01 -1.2668437617555701e+03 1.2668438056011901e+03 0 3 0 0 -4 0
1284 P 116 2203 -2.7745239600449745e-01 1.8469236508822412e-01 -1.8910900158159372e+03 1.8910902024916190e+03 7.7132999999999996e-01 2 0 0 -15 0
357 garren 1285 \end{verbatim}}
1286   \end{center}
1287   \caption[Example of ascii format]
1288           {\label{ascii_format} Example of the format written to a file.  
390 garren 1289            Only the first few lines are shown.
1290            Notice that this event has no GenCrossSection information. }
357 garren 1291 \end{figure}
355 garren 1292  
391 garren 1293 \begin{figure}[h]
1294   \begin{center}
1295 {\tiny \begin{verbatim}
433 garren 1296 HepMC::Version 2.06.00
391 garren 1297 HepMC::IO_GenEvent-START_EVENT_LISTING
432 garren 1298 E 1 65 -1.0000000000000000e+00 -1.0000000000000000e+00 -1.0000000000000000e+00 20 0 357 1 2 0 3 3.4560000000000002e-01 9.8595999999999995e-01 9.8563000000000001e-01
1299 N 3 "0" "second weight name" "weightName"
391 garren 1300 U GEV MM
432 garren 1301 C 3.3260000000000000e-03 1.0000000000000000e-04
391 garren 1302 V -1 0 0 0 0 0 1 3 0
1303 P 1 2212 0 0 6.9999999371178146e+03 7.0000000000000000e+03 9.3827000000000005e-01 3 0 0 -1 0
1304 P 3 -1 7.2521029125687850e-02 4.0916270130125820e-01 2.3327360517627892e+02 2.3327397528518750e+02 0 3 0 0 -3 0
1305 P 11 2214 -1.1686660480579378e-01 -8.5929732056936881e-03 6.3364496390829606e+02 6.3364619182056367e+02 1.2419302372801875e+00 2 0 0 -25 0
1306 P 91 1 4.4345575680105935e-02 -4.0056972809556451e-01 6.4508531915990204e+02 6.4508552945967551e+02 3.3000000000000002e-01 2 0 0 -26 0
1307 V -2 0 0 0 0 0 1 2 0
432 garren 1308 P 2 2212 0 0 -6.9999999371178146e+03 7.0000000000000000e+03 9.3827000000000005e-01 3 0 0 -2 0
1309 P 4 2 7.8470425410496383e-02 3.2223590540096692e-01 -1.4955117837986219e+01 1.4958794842314219e+01 0 3 0 0 -4 0
1310 P 95 2103 -7.8470425410496383e-02 -3.2223590540096692e-01 -3.0233822815549665e+03 3.0233823981369064e+03 7.7132999999999996e-01 2 0 0 -28 0
391 garren 1311 \end{verbatim}}
1312   \end{center}
1313   \caption[Example of ascii format]
1314           {\label{ascii_cross} Example of the format written to a file
432 garren 1315            when GenCrossSection and named weights are used.
1316            Only the first few lines are shown.
433 garren 1317            Notice that the HeavyIon line was not written because it contained
432 garren 1318            no information. }
391 garren 1319 \end{figure}
1320  
1321 \begin{figure}[h]
1322   \begin{center}
1323 {\tiny \begin{verbatim}
1324 E 1 65 -1.0000000000000000e+00 -1.0000000000000000e+00 -1.0000000000000000e+00 20 0 357 1 2 0 0
1325 U GEV MM
1326 F 2 3 3.5000000000000003e-01 6.4999999999999991e-01 8.4499999999999993e+00 2.4499999779912355e+03 4.5499999591265787e+03 230 230
1327 V -1 0 0 0 0 0 1 3 0
1328 P 1 2212 0 0 6.9999999371178146e+03 7.0000000000000000e+03 9.3827000000000005e-01 3 0 0 -1 0
1329 P 3 -1 7.2521029125687850e-02 4.0916270130125820e-01 2.3327360517627892e+02 2.3327397528518750e+02 0 3 0 0 -3 0
1330 P 11 2214 -1.1686660480579378e-01 -8.5929732056936881e-03 6.3364496390829606e+02 6.3364619182056367e+02 1.2419302372801875e+00 2 0 0 -25 0
1331 P 91 1 4.4345575680105935e-02 -4.0056972809556451e-01 6.4508531915990204e+02 6.4508552945967551e+02 3.3000000000000002e-01 2 0 0 -26 0
1332 V -2 0 0 0 0 0 1 2 0
1333 P 2 2212 0 0 -6.9999999371178146e+03 7.0000000000000000e+03 9.3827000000000005e-01 3 0 0 -2 0
1334 P 4 2 7.8470425410496383e-02 3.2223590540096692e-01 -1.4955117837986219e+01 1.4958794842314219e+01 0 3 0 0 -4 0
1335 P 95 2103 -7.8470425410496383e-02 -3.2223590540096692e-01 -3.0233822815549665e+03 3.0233823981369064e+03 7.7132999999999996e-01 2 0 0 -28 0
1336 V -3 0 0 0 0 0 0 1 0
1337 P 5 -1 4.5914398456298945e-02 2.5904843777716324e-01 1.4768981337590043e+02 1.4769004769866316e+02 0 3 0 0 -5 0
1338 \end{verbatim}}
1339   \end{center}
1340   \caption[Example of ascii format]
1341           {\label{ascii_stream} Example of the streaming output format.
1342            Only the first few lines are shown.
1343            Notice that the streaming output does not automatically
1344            write the IO\_GenEvent begin and end block lines.
1345            The user may optionally choose to add those "headers" to the
1346            output stream. }
1347 \end{figure}
1348  
1349 \clearpage
1350  
328 garren 1351 %
1352 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1353 %
1354  
354 garren 1355 \subsection{General Event Information}
1356  
1357 \begin{myitemize}{E - general GenEvent information}
1358   \myitem{int}{event number}
1359   \myitem{int}{number of multi paricle interactions}
1360   \myitem{double}{event scale}
1361   \myitem{double}{alpha QCD}
1362   \myitem{double}{alpha QED}
1363   \myitem{int}{signal process id}
1364   \myitem{int}{barcode for signal process vertex}
1365   \myitem{int}{number of vertices in this event}
1366   \myitem{int}{barcode for beam particle 1}
1367   \myitem{int}{barcode for beam particle 2}
1368   \myitem{int}{number of entries in random state list (may be zero)}
1369   \myitem{long}{optional list of random state integers}
1370   \myitem{int}{number of entries in weight list (may be zero)}
1371   \myitem{double}{optional list of weights}
1372 \end{myitemize}
432 garren 1373 \begin{myitemize}{N - weight names}
433 garren 1374   \myitem{int}{number of entries in weight name list.  
1375                Note that the number of entries here and on the E line are
1376                required to be exactly the same and in the same order.}
1377   \myitem{std::string}{list of weight names enclosed in quotes}
432 garren 1378 \end{myitemize}
354 garren 1379 \begin{myitemize}{U - momentum and position units}
1380   \myitem{std::string}{momentum units (MEV or GEV)}
1381   \myitem{std::string}{length units (MM or CM)}
1382 \end{myitemize}
390 garren 1383 \begin{myitemize}{C - GenCrossSection information}
1384   \myitem{double}{cross section in pb}
1385   \myitem{double}{error associated with this cross section in pb}
1386 \end{myitemize}
354 garren 1387 \begin{myitemize}{H - HeavyIon information}
1388   \myitem{int}{Number of hard scatterings}
1389   \myitem{int}{Number of projectile participants}
1390   \myitem{int}{Number of target participants}
1391   \myitem{int}{Number of NN (nucleon-nucleon) collisions}
1392   \myitem{int}{Number of spectator neutrons}
1393   \myitem{int}{Number of spectator protons}
1394   \myitem{int}{Number of N-Nwounded collisions}
1395   \myitem{int}{Number of Nwounded-N collisons}
1396   \myitem{int}{Number of Nwounded-Nwounded collisions}
1397   \myitem{float}{Impact Parameter(fm) of collision}
1398   \myitem{float}{Azimuthal angle of event plane}
1399   \myitem{float}{eccentricity of participating nucleons in the transverse plane}
1400   \myitem{float}{nucleon-nucleon inelastic cross-section}
1401 \end{myitemize}
1402 \begin{myitemize}{F - PdfInfo information}
1403   \myitem{int}{flavour code of first parton}
1404   \myitem{int}{flavour code of second parton}
1405   \myitem{double}{fraction of beam momentum carried by first parton}
1406   \myitem{double}{fraction of beam momentum carried by second parton}
1407   \myitem{double}{Q-scale used in evaluation of PDF's (in GeV)}
1408   \myitem{double}{x*f(x) for id1, x1, Q}
1409   \myitem{double}{x*f(x) for id2, x2, Q}
1410   \myitem{int}{LHAPDF set id of first parton (zero by default)}
1411   \myitem{int}{LHAPDF set id of second parton  (zero by default)}
1412 \end{myitemize}
1413  
1414 %
1415 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1416 %
1417  
1418 \subsection{Vertices and Particles}
1419  
1420 \begin{myitemize}{V - GenVertex information}
1421   \myitem{int}{barcode}
1422   \myitem{int}{id}
1423   \myitem{double}{x}
1424   \myitem{double}{y}
1425   \myitem{double}{z}
1426   \myitem{double}{ctau}
1427   \myitem{int}{number of "orphan" incoming particles}
1428   \myitem{int}{number of outgoing particles}
1429   \myitem{int}{number of entries in weight list (may be zero)}
1430   \myitem{double}{optional list of weights}
1431 \end{myitemize}
1432 \begin{myitemize}{P - GenParticle information}
1433   \myitem{int}{barcode}
1434   \myitem{int}{PDG id}
1435   \myitem{double}{px}
1436   \myitem{double}{py}
1437   \myitem{double}{pz}
1438   \myitem{double}{energy}
1439   \myitem{double}{generated mass}
1440   \myitem{int}{status code}
1441   \myitem{double}{Polarization theta}
1442   \myitem{double}{Polarization phi}
1443   \myitem{int}{barcode for vertex that has this particle as an incoming particle}
1444   \myitem{int}{number of entries in flow list (may be zero)}
1445   \myitem{int, int}{optional code\_index and code for each entry in the flow list}
1446 \end{myitemize}
1447  
1448 %
1449 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1450 %
1451  
198 garren 1452 \section{Building HepMC}
1453  
1454 Source code, binary and source code tarballs, bug tracking, etc. are
1455 all available from the HepMC web pages~\cite{LCGHepMC} at  
1456 \htmladdnormallink
1457 {https://savannah.cern.ch/projects/hepmc/}
1458 {https://savannah.cern.ch/projects/hepmc/}.
1459  
1460 Source code tarballs are on the download page:
1461 \htmladdnormallink
1462 {http://lcgapp.cern.ch/project/simu/HepMC/download/}
1463 {http://lcgapp.cern.ch/project/simu/HepMC/download/}.
357 garren 1464 Binary downloads are available for some releases.
1465 The following recipe is a guideline and should be modified according to taste.
198 garren 1466  
357 garren 1467 \begin{myitemize}{}
198 garren 1468   \myitem{download source code tarball}{}
1469   \myitem{mkdir cleanDIR}{Make a new directory to work in.}
1470   \myitem{cd cleanDIR}{}
1471   \myitem{tar -xzf HepMCtarball}{Unwind the tarball you downloaded.}
1472   \myitem{mkdir build install}{Define directories for building and installation.}
1473   \myitem{cd build}{This is your real working directory.}
357 garren 1474   \myitem{../../HepMC-release/configure --prefix=../install
1475           --with-momentum=XX --with-length=YY}
198 garren 1476     {--prefix tells the tools where to install the library and headers.
1477      The default install location is /usr/local.}
1478   \myitem{make}{Compile HepMC.}
1479   \myitem{make check}{Run the tests.  This is optional but strongly recommended.}
1480   \myitem{make install}{Install everything in your specified directory. }
1481 \end{myitemize}
1482  
1483 %
1484 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1485 %
1486  
80 garren 1487 \section{Examples}
1488 \label{examples}
198 garren 1489 Examples are provided in the examples directory of the package
80 garren 1490 and are installed in the installation directory under examples/HepMC.
158 garren 1491 Tests, found in the test directory of the package, also provide useful examples.
1492 The tests are not installed.
390 garren 1493 Most examples use IO\_GenEvent.
1494 However, example\_PythiaStreamIO.cc illustrates explicit use of the
1495 streaming I/O operators.
80 garren 1496  
1497 \begin{itemize}\setlength{\itemsep}{0pt}
1498   \item{\bf Using the HepMC vertex and particle iterators:}
1499        {example\_UsingIterators.cc}
198 garren 1500   \item{\bf Using HepMC with Pythia (Fortran):}
390 garren 1501       {example\_MyPythia.cc and example\_MyPythiaOnlyToHepMC.cc}
198 garren 1502   \item{\bf An Event Selection with Pythia Events:}
328 garren 1503       {example\_MyPythia.cc}
198 garren 1504   \item{\bf Event Selection and Ascii IO}
1505       {example\_EventSelection.cc}
80 garren 1506   \item{\bf Using HepMC with Herwig:}
1507      {example\_MyHerwig.cc}
198 garren 1508  \item{\bf Write an event file and then read it:}
328 garren 1509      {example\_MyPythia.cc}
390 garren 1510  \item{\bf Write an event file and then read it with the streaming I/O operators:}
1511      {example\_PythiaStreamIO.cc}
198 garren 1512   \item{\bf Building an Event from Scratch in the HepMC Framework:}
80 garren 1513      {example\_BuildEventFromScratch.cc}
256 garren 1514   \item{\bf Verify that copying generated events behaves as expected:}
1515      {testHerwigCopies.cc and testPythiaCopies.cc}
432 garren 1516   \item{\bf Using the iterator range classes and methods:}
1517      {HepMC/test/testHepMCIteration.cc}
80 garren 1518 \end{itemize}
1519  
390 garren 1520 I/O examples are shown in Figures
1521 \ref{read_ascii}, \ref{write_ascii}.
1522 \ref{read_stream}, and \ref{write_stream}.
80 garren 1523  
357 garren 1524 \begin{figure}[h]
390 garren 1525 \caption[IO\_GenEvent example]{\label{read_ascii}
1526          Reading HepMC events from a file. }
1527     {\small \begin{verbatim}
1528     // specify an input file
1529     HepMC::IO_GenEvent ascii_in("example.dat",std::ios::in);
1530     // get the first event
1531     HepMC::GenEvent* evt =  ascii_in.read_next_event();
1532     // loop until we run out of events
1533     while ( evt ) {
1534         // analyze the event
1535         ...
1536         // delete the created event from memory
1537         delete evt;
1538         // read the next event
1539         ascii_in >> evt;
1540     }
1541     \end{verbatim}}
1542 \end{figure}
1543  
1544 \begin{figure}[h]
1545 \caption[Streaming input example]{\label{read_stream}
1546            Reading HepMC events from an input stream. }
357 garren 1547 {\small \begin{verbatim}
390 garren 1548     // specify an input stream
1549     std::ifstream is( "example_PythiaStreamIO_write.dat" );
1550     // create an empty event
1551     HepMC::GenEvent evt;
1552     // loop over the input stream
1553     while ( is ) {
1554         // read the event
1555         evt.read( is );
1556         // make sure we have a valid event
1557         if( evt.is_valid() ) {
1558             // analyze the event
1559             ...
1560         }
1561     }
357 garren 1562 \end{verbatim}}
1563 \end{figure}
355 garren 1564  
357 garren 1565 \begin{figure}[h]
390 garren 1566 \caption[IO\_HEPEVT and IO\_GenEvent example]
357 garren 1567 {\label{write_ascii} Convert events from the HEPEVT common block
1568           to HepMC format and write them to a file. }
1569 {\small \begin{verbatim}
390 garren 1570     // common block conversion methods
1571     HepMC::IO_HEPEVT hepevtio;
1572     // specify an output file
1573     HepMC::IO_GenEvent ascii_out("example.dat",std::ios::out);
1574     for ( int i = 1; i <= maxEvents; i++ ) {
1575         // convert an event
1576         HepMC::GenEvent* evt = hepevtio.read_next_event();
1577         // analyze the event
1578         ...
1579         // write the HepMC event
1580         ascii_out << evt;
1581         // delete the created event from memory
1582         delete evt;
1583     }
1584     \end{verbatim}}
1585 \end{figure}
1586  
1587 \begin{figure}[h]
1588 \caption[IO\_HEPEVT and streaming output example]
1589 {\label{write_stream} Convert events from the HEPEVT common block
1590           to HepMC format and write them to streaming output. }
1591     {\small \begin{verbatim}
1592     // common block conversion methods
1593     HepMC::IO_HEPEVT hepevtio;
1594     // specify an output stream
1595     std::ofstream os( "example_PythiaStreamIO_write.dat" );
1596     for ( int i = 1; i <= maxEvents; i++ ) {
1597         // generate the event with Pythia, Herwig, etc.
1598         ...
1599         // convert an event
1600         HepMC::GenEvent* evt = hepevtio.read_next_event();
1601         // analyze the event
1602         ...
1603         // write the HepMC event
1604         evt->write(os);
1605         // delete the created event from memory
1606         delete evt;
1607     }
357 garren 1608 \end{verbatim}}
1609 \end{figure}
355 garren 1610  
390 garren 1611 \clearpage
1612  
45 garren 1613 %
1614 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1615 %
198 garren 1616  
1617 \section{Deprecated Classes}
355 garren 1618 \label{deprecated}
198 garren 1619  
1620 Two major classes have been deprecated: IO\_Ascii and ParticleData.
391 garren 1621 IO\_Ascii was deprecated in 2.02.00 and was removed as of HepMC 2.05.00.
1622 IO\_Ascii has been replaced by IO\_GenEvent,
390 garren 1623 which uses iostreams instead of files.
198 garren 1624  
391 garren 1625 The ParticleData classes, deprecated since HepMC 2.02.00,
1626 had become outmoded and would need a lot of work.  
432 garren 1627 The ParticleData classes were removed as of HepMC 2.06.00.
391 garren 1628 Instead, we recommend using packages already developed for this
198 garren 1629 purpose, such as HepPDT~\cite{heppdt}.
1630  
391 garren 1631 IO\_ExtendedAscii, introduced in 1.28.00, was deprecated in 2.02.00
1632 and removed as of HepMC 2.04.00.
328 garren 1633  
391 garren 1634 IO\_GenEvent and the streaming input operator can read old files written by
1635 either IO\_Ascii or IO\_ExtendedAscii.
328 garren 1636  
198 garren 1637  
1638 %
1639 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1640 %
1641  
1642 \section{Acknowlegements}
1643  
1644 We would like to acknowlege useful suggestions, consultations, and
1645 comments from: Ian Hinchliffe, Pere Mato, H.T. Phillips, Anders Ryd,
1646 Maria Smizanska, and Brian Webber.  R.D.\ Schaffer and Lassi
1647 Tuura provided many useful suggestions on the package architecture.
1648 Thanks to Witold Pokorski and Pere Mato for providing the fixes that
1649 make HepMC compile and run on Windows with Microsoft Visual C++.
1650  
1651  
1652 %
1653 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1654 %
1655  
45 garren 1656 \begin{thebibliography}{99}
1657  
1658 \bibitem{dobbs:2000CompPhysComm}
1659   M.~Dobbs and J.B.~Hansen, ``The HepMC C++ Monte Carlo Event Record for
1660   High Energy Physics'', Computer Physics Communications (to be
1661   published) \htmladdnormallink{[ATL-SOFT-2000-001]}
1662   {http://weblib.cern.ch/}.  
1663  
198 garren 1664 \bibitem{Torbjorn}
1665   Pythia 8.1 available at \htmladdnormallink
1666   {http://www.thep.lu.se/~torbjorn/pythiaaux/present.html}
1667   {http://www.thep.lu.se/~torbjorn/pythiaaux/present.html}.
158 garren 1668  
198 garren 1669 \bibitem{Richardson}
1670   Herwig++ 2.1 available at \htmladdnormallink
1671   {http://projects.hepforge.org/herwig/}
1672   {http://projects.hepforge.org/herwig/}.
45 garren 1673  
198 garren 1674 \bibitem{Boos:2001cv}
1675 E.~Boos {\it et al.},
1676 ``Generic user process interface for event generators,''
1677 arXiv:hep-ph/0109068.
1678  
1679 \bibitem{mc++}
1680   S.~Protopopescu, ``MC++ Interface''.
1681   Available from \htmladdnormallink
1682   {http://ox3.phy.bnl.gov/\~serban/mcpp/index.html}
1683   {http://ox3.phy.bnl.gov/\~serban/mcpp/index.html}.
1684  
45 garren 1685 \bibitem{clhep}
1686   ``A Class Library for High Energy Physics,'' (CLHEP).
1687   Available from
1688   \htmladdnormallink
1689   {http://wwwasd.web.cern.ch/wwwasd/lhc++/clhep/}
1690   {http://wwwasd.web.cern.ch/wwwasd/lhc++/clhep/}.
1691  
390 garren 1692 \bibitem{lcgsim}
1693    Generator Services Subproject information available at
1694    \htmladdnormallink
1695   {http://lcgapp.cern.ch/project/simu/generator/}
1696   {http://lcgapp.cern.ch/project/simu/generator/}.
1697  
198 garren 1698 \bibitem{changelog}
1699   Latest HepMC ChangeLog available at  \htmladdnormallink
1700   {http://simu.cvs.cern.ch/cgi-bin/simu.cgi/simu/HepMC/ChangeLog?view=markup}
1701   {http://simu.cvs.cern.ch/cgi-bin/simu.cgi/simu/HepMC/ChangeLog?view=markup}.
1702  
1703 \bibitem{stl}
1704   A.A.~Stepanov, M.~Lee, ``The Standard Template Library,''
1705   Hewlett-Packard Laboratories Technical Report HPL-94-34, April 1994,
1706   revised July 7, 1995.
1707   %%``Public domain implementation of the standard template library'',
1708   Available from \htmladdnormallink{ftp://butler.hpl.hp.com/stl/}
1709   {ftp://butler.hpl.hp.com/stl/}.
1710  
1711 \bibitem{Sjostrand:2001yb}
1712   T.~Sjostrand {\it et al.},
1713   ``High-energy physics event generation with PYTHIA 6.1,''
1714   Comput.\ Phys.\ Commun.\  {\bf 135}, 238 (2001).
1715  
328 garren 1716 \bibitem{herwig}
1717    G. Corcella {\it et al.},
1718   ``Herwig 6: an event generator for Hadron Emission Reactions
1719   With Interfering Gluons (including supersymmetric processes)''
1720   JHEP {\bf 0101}, 010 (2001) [hep-ph/0011363]; hep-ph/0210213.
1721  
289 garren 1722 \bibitem{lhapdf}
1723   ``the Les Houches Accord PDF Interface,'' (LHAPDF).
1724   Available from
1725   \htmladdnormallink
1726   {http://projects.hepforge.org/lhapdf/}
1727   {http://projects.hepforge.org/lhapdf/}.
1728  
198 garren 1729 \bibitem{evtgen}
1730   A.~Ryd, D.~Lange,
1731   ``The EvtGen package for simulating particle decays,''
1732   Computing in High Energy Physics, Chicago, Illinois, USA (1998).
1733  
45 garren 1734 \bibitem{Yao:2006tx}
1735   W.-M.~Yao {\it et al.}, ``Review of particle physics,''
1736   Journal\ of\ Physics {\bf G33}, 1 (2006).
1737   Available from \htmladdnormallink{http://pdg.lbl.gov/}{http://pdg.lbl.gov/}.
1738  
213 garren 1739  
198 garren 1740 \bibitem{stdhep5.05}
1741   L.~Garren, ``StdHep 5.05 Monte Carlo Standardization at FNAL,''
1742   Fermilab PM0091. Available from
1743   \htmladdnormallink
1744   {http://cepa.fnal.gov/psm/stdhep/}
1745   {http://cepa.fnal.gov/psm/stdhep/}.
1746  
1747 \bibitem{LCGHepMC}
1748   ``a C++ Event Record for Monte Carlo Generators,'' (HepMC).
1749   Available from
1750   \htmladdnormallink
1751   {https://savannah.cern.ch/projects/hepmc/}
1752   {https://savannah.cern.ch/projects/hepmc/}.
1753  
1754 \bibitem{heppdt}
1755   HepPDT is available at \htmladdnormallink
1756   {http://savannah.cern.ch/projects/heppdt/}
1757   {http://savannah.cern.ch/projects/heppdt/}.
1758  
390 garren 1759 \bibitem{mcnet}
1760   MCnet is available at \htmladdnormallink
1761   {http://www.montecarlonet.org/}
1762   {http://www.montecarlonet.org/}.
1763  
45 garren 1764 \end{thebibliography}
1765  
1766 %
1767 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1768 %
1769  
1770 \end{document}
1771