Page Menu
Home
HEPForge
Search
Configure Global Search
Log In
Files
F19251518
rivet-manual.tex
No One
Temporary
Actions
Download File
Edit File
Delete File
View Transforms
Subscribe
Award Token
Flag For Later
Size
21 KB
Referenced Files
None
Subscribers
None
rivet-manual.tex
View Options
\documentclass
{
JHEP3
}
%\JHEP{00(2007)000}
\usepackage
{
xspace,graphicx,mparhack,amsmath,amssymb,url,underscore,fancyvrb
}
\usepackage
{
hepnicenames,hepunits
}
\usepackage
{
picinpar,fancybox
}
%\usepackage{xcolor}
%\usepackage{palatino,mathpazo}
\DeclareRobustCommand
{
\TODO
}
[1]
{
\ensuremath
{
\bigstar
}{
#1
}
\xspace
}
%\DeclareRobustCommand{\TODO}[1]{\textcolor{red!20!black}{\ensuremath{\bigstar}{#1}}\xspace}
%\DeclareRobustCommand{\TOCHECK}[1]{\textcolor{blue!20!black}{\ensuremath{\bigcircle}{#1}}\xspace}
\newenvironment
{
snippet
}{
\Verbatim
}{
\endVerbatim
}
\newcommand
{
\kbd
}
[1]
{
\texttt
{
#1
}
\xspace
}
\newcommand
{
\inp
}
[1]
{
\textsf
{
\textdollar
}
\hspace
{
1mm
}
\texttt
{
#1
}
\xspace
}
\newcommand
{
\outp
}
[1]
{
\textsf
{
#1
}
\xspace
}
\newcommand
{
\code
}
[1]
{
\texttt
{
#1
}
\xspace
}
\newcommand
{
\var
}
[1]
{
\texttt
{
\textdollar
{}
#1
}
\xspace
}
\newcommand
{
\val
}
[1]
{
\textit
{
\ensuremath
{
\langle\text
{
\textrm
{
#1
}
\/
}
\rangle
}}
\xspace
}
\newcommand
{
\home
}{
\texttt
{
\ensuremath
{
\sim
}}
\xspace
}
\newcommand
{
\RGnegate
}{
\texttt
{
\ensuremath
{
\sim
}}}
\newcommand
{
\cmdbreak
}{
\textbackslash\newline
}
\newcommand
{
\SectionRef
}
[1]
{
section~
\ref
{
#1
}}
\newcommand
{
\SubsectionRef
}
[1]
{
sub-section~
\ref
{
#1
}}
\let\oldmarginpar\marginpar
\renewcommand\marginpar
[1]
{
\-\oldmarginpar
{
\footnotesize
\textit
{
#1
}}}
%\renewcommand\marginpar[1]{\-\oldmarginpar[\raggedleft\footnotesize \textit{#1}]%
%{\raggedright\footnotesize \textit{#1}}}
\newcommand
{
\coneimg
}{
\includegraphics
[height=11mm]
{
cone
}}
\newcommand
{
\bendimg
}{
\includegraphics
[height=11mm]
{
bend
}}
\newcommand
{
\dblbendimg
}{
\bendimg\hspace
{
0.5mm
}
\bendimg
}
\setlength
{
\fboxsep
}{
5mm
}
\setlength
{
\linewidth
}{
5pt
}
\newenvironment
{
change
}
%
{
\begin
{
Sbox
}
%
\begin
{
minipage
}{
0.9
\textwidth
}
%
\begin
{
window
}
[0,l,
{
\coneimg
}
,
{}
]
\noindent\hspace
{
-0.8ex
}}
%
{
\par\end
{
window
}
%
\end
{
minipage
}
%
\end
{
Sbox
}
%
\vspace
{
5mm
}
%
\noindent
%
\begin
{
center
}
%
\fbox
{
\TheSbox
}
%
\end
{
center
}
%
\vspace
{
5mm
}
%
\ignorespacesafterend
}
% \newenvironment{change}{%
% \begin{window}[0,l,{\coneimg},{}] \noindent\hspace{-0.8ex}}{\par%
% % \showthe\prevgraf%
% % \showthe\prevdepth%
% % \ifnum\prevgraf<2\rule{1pt}{1.2cm}\fi%
% \end{window}\ignorespacesafterend}
\newenvironment
{
detail
}{
\begin
{
window
}
[0,l,
{
\bendimg
}
,
{}
]
}{
\end
{
window
}
\ignorespacesafterend
}
\newenvironment
{
dbldetail
}{
\begin
{
window
}
[0,l,
{
\dblbendimg
}
,
{}
]
}{
\end
{
window
}
\ignorespacesafterend
}
\title
{
Rivet and AGILe manual
}
\author
{
Andy Buckley
\\
IPPP, Durham University, UK.
\\
E-mail:
\email
{
andy.buckley@durham.ac.uk
}}
\author
{
James Monk
\\
HEP Group, Dept. of Physics and Astronomy, UCL, London, UK.
\\
E-mail:
\email
{
jmonk@fnal.gov
}}
\author
{
Lars Sonnenschein
\\
CERN, Gen
\`
eve 1206, Switzerland.
\\
E-mail:
\email
{
sonne@cern.ch
}}
\author
{
Jon Butterworth
\\
HEP Group, Dept. of Physics and Astronomy, UCL, London, UK.
\\
E-mail:
\email
{
jmb@hep.ucl.ac.uk
}}
\author
{
Leif L
\"
onnblad
\\
Theoretical Physics, Lund University, Sweden.
\\
E-mail:
\email
{
lonnblad@thep.lu.se
}}
\preprint
{}
%\preprint{\hepth{9912999}}
\abstract
{
This is the manual and user guide for the Rivet system for the
validation and tuning of Monte Carlo event generators. As well as the core
Rivet library, this manual describes the usage of the
\kbd
{
rivetgun
}
program
and the AGILe generator interface library. The level of description is
generally intended for users of the system, starting with the basics of using
validation code written by others, and then covering all the details you need
to know to write your own Rivet components.
}
\keywords
{
Event generator, simulation, validation, tuning, QCD
}
\begin
{
document
}
\section
{
Introduction
}
This manual is a users' guide to using the Rivet generator validation
system. Rivet itself is a C++ class library, with classes to represent
observable calculations, analyses and their data objects, and a collection of
infrastructure/management objects which you hopefully won't have to worry about
very much. The simplest way to use Rivet is via the
\kbd
{
rivetgun
}
command line
tool, which can run a generator using the AGILe interface library, analyse the
events as they are generated, and produce output distributions in your format of
choice. For those who wish to embed their analyses in some larger framework,
Rivet can also be run programmatically on HepMC event objects with no special
executable being required.
Before we get started, a declaration of intent: this manual is intended to be a
guide to using Rivet,
\emph
{
not
}
a comprehensive and painstakingly maintained
reference to the application programming interface (API) of the Rivet and AGILe
libraries. For that purpose, you will hopefully find the online generated
documentation at
\url
{
http://projects.hepforge.org/rivet
}
and
\url
{
http://projects.hepforge.org/agile
}
to be ideal.
\subsection
{
Typographic conventions
}
As is normal in computer user manuals, the typography in this manual is used to
indicate whether we are describing source code elements, commands to be run in a
terminal, the output of a command etc.
The main such clue will be the use of
\kbd
{
typewriter-style
}
text: this
indicates the name of a command or code element --- class names, function names
etc. Typewriter font is also used for commands to be run in a terminal, but in
this case it will be prefixed by a dollar sign, as in
\inp
{
echo ''Hello'' |
cat
}
. The output of such a command on the terminal will be typeset in
\outp
{
sans-serif
}
font. When we are documenting a code feature in detail (which
is not the main point of this manual), we will use square brackets to indicate
optional arguments, and italic font between angle brackets to represent an
argument name which should be replaced by a value,
e.g.
\code
{
Event::applyProjection(
\val
{
proj
}
)
}
.
Following the example of Donald Knuth in his books on
\TeX
{}
, in this document
we will indicate paragraphs of particular technicality or esoteric nature with a
``dangerous bend''
\marginpar
{
\bendimg\\
Dangerous bend
}
sign. These will typically be about the
internals of Rivet which most people will be lucky enough never to need know
about, but for detail obsessives, the inordinately curious and Rivet hackers
they may be useful. You can almost certainly skip them on a first
reading. Similarly, you may see double bend signs
\marginpar
{
\dblbendimg\\
Double bend
}
--- the same rules apply for
these, but even more strongly.
\section
{
Quickstart
}
The point of this section is to get you up and running with Rivet as soon as
possible. Doing this by hand may be rather frustrating, as Rivet depends on
several external libraries --- you'll get bored downloading and building them by
hand in the right order.
To make life more pleasant, we have written a bootstrapping script which will
download tarballs of Rivet, AGILe and the other required libraries, expand them
and build them in the right order. This is generally nicer than doing it all by
hand, and virtually essential if you want to use the existing versions of
FastJet, HepMC, generator libraries, and so on from CERN AFS: there are issues
with these versions which the script works around, which you won't find easy to
do yourself.
You can get this script from the following Web address:
\url
{
http://svn.hepforge.org/rivet/bootstrap/rivet-bootstrap
}
To run the script, we recommend that you choose a personal installation
directory. Personally, I make a
\kbd
{
\home
/local
}
directory for this purpose, to
avoid polluting my home directory with a lot of files. If you already use a
directory of the same name, you might want to use a separate one, say
\kbd
{
\home
/rivetlocal
}
. You'll need to add
\kbd
{
\val
{
localdir
}
/bin
}
to your
\var
{
PATH
}
environment variable and
\kbd
{
\val
{
localdir
}
/lib
}
to your
\var
{
LD
_
LIBRARY
_
PATH
}
.
Now, change directory to your build area (you may also want to make this,
e.g.
\kbd
{
\home
/build
}
), and download the script:
\\
\inp
{
wget
\url
{
http://svn.hepforge.org/rivet/bootstrap/rivet-bootstrap
}}
\\
Now run it, specifying the install area as the argument:
\\
\inp
{
chmod a+x rivet-bootstrap
}
\\
\inp
{
./rivet-bootstrap
\val
{
localdir
}}
\\
If you are running on a system where the CERN AFS area is mounted as
\path
{
/afs/cern.ch
}
, then the bootstrap script will attempt to use the pre-built
HepMC, LHAPDF, FastJet and GSL libraries from the LCG software area. Either way,
you'll see a large amount of build output, and finally a message telling you
what changes to your environment variables will make the system useable. Set the
variables as instructed, if you've not already done so, and check that it works
by issuing
\\
\inp
{
rivetgun -g FPythia:6413
}
\\
which should make 10 LHC events for you, using the Fortran Pythia 6.4.13
generator. You're on your way!
You now have a working, installed copy of the Rivet and AGILe libraries, and the
\kbd
{
rivetgun
}
and
\kbd
{
rivet-config
}
executables.
\kbd
{
rivet-config
}
is a
simple script which can be used to determine useful paths when compiling against
Rivet.
\kbd
{
rivetgun
}
is the main executable used to run generators and process
their output with Rivet analyses. We'll discuss it in detail
in
\SectionRef
{
sec:rivetgun
}
.
One last thing before continuing, though: the generators themselves. Again, if
you're running on a system with the CERN LCG AFS area mounted, then
\kbd
{
rivetgun
}
will attempt to automatically use the generators packaged by the
LCG Genser team. Otherwise, you'll have to build your own mirror of the LCG
generators. This process is not standardised at the moment (this will hopefully
change), so we've provided a script,
\kbd
{
mkGenserArea
}
, in the
\kbd
{
bin
}
directory of the AGILe source distribution (this will have been downloaded by
the
\kbd
{
rivet-bootstrap
}
script. We recommend getting the latest version from
SVN, though:
\\
\inp
{
wget
\url
{
http://svn.hepforge.org/agile/trunk/bin/mkGenserArea
}}
\\
Now make yourself a Genser installation directory, e.g.
\kbd
{
\var
{
HOME
}
/genser
}
,
and
\kbd
{
cd
}
into it. Then run the
\kbd
{
mkGenserArea
}
script, and wait for it
all to build. Finally, set the
\var
{
AGILE
_
GEN
_
PATH
}
path variable to contain the
\kbd
{
\val
{
genserDir
}
/liblinks
}
directory: you should now have a few Fortran
generators to play with.
\section
{
Running
\kbd
{
rivetgun
}}
\label
{
sec:rivetgun
}
The
\kbd
{
rivetgun
}
executable is the easiest way to use Rivet, and will be our
example throughout this manual. To get started, just run the command
\inp
{
rivetgun
}
with no arguments. You should get a short usage message, looking
something like this:
%
\begin
{
snippet
}
buckley@d65:~/proj/cedar/agile
\$
rivetgun
PARSE ERROR:
One or more required arguments missing!
Brief USAGE:
rivetgun
{
-g <FHerwig:6510|FPythia:6413>|-G <genfile>
}
[-R]
[-o <filename>] [-n <num>] [--nocolor] [-l <name=level>]
[--histotype <AIDA|FLAT|ROOT>] [-H <name>]
[-A] [-a <ALEPH
_
1991
_
S2435284|~ALEPH
_
1991
_
S2435284
|CDF
_
1994
_
S2952106|~CDF
_
1994
_
S2952106|CDF
_
2001
_
S4751469...]
[-P <paramfile>] ... [-p <param=value>] ... [--mom2 <mom>]
[--mom1 <mom>] [--beam2 <ANTIPROTON|PIMINUS|NU
_
TAUBAR|...]
[--beam1 <ANTIPROTON|PIMINUS|NU
_
TAUBAR|...]
[-i <filename>] [-s <seed>] [--] [--version] [-h]
For complete USAGE and HELP type:
rivetgun --help
\end
{
snippet
}
The message obtained with
\kbd
{
rivetgun --help
}
is much more explicit about the
meanings of these options, but we'll survey a few of them here with concrete examples.
\begin
{
itemize
}
\item
\paragraph
{
Simple run:
}{
\kbd
{
rivetgun -g~FHerwig:6510 -P~lep1.params
-n~1000
}
will use the Fortran Herwig 6.5.10 generator (the
\kbd
{
-g
}
option
switch) to generate 1000 events (the
\kbd
{
-n
}
switch) in LEP1 mode,
i.e.
$
\Ppositron\Pelectron
$
collisions at
$
\sqrt
{s}
=
\unit
{
90
}{
\GeV
}
$
. The
\kbd
{
-P
}
switch is actually the way of specifying a
\kbd
{
rivetgun
}
parameters file: in this case, the file
\kbd
{
lep1.params
}
is loaded from the
\kbd
{
\val
{
installdir
}
/share/RivetGun
}
directory, if it isn't first found in
the current directory.
}
\item
\paragraph
{
Parameter changes:
}{
\kbd
{
rivetgun -g~FPythia:6413
-P~lep1.params -n~1000
\cmdbreak
-p~"PARJ(82)=5.27"
}
will generate 1000
events using the Fortran Pythia 6.4.13 generator, again in LEP1 mode. The
difference this time is that we've used the
\kbd
{
-p
}
(lower-case) switch to
change a named generator parameter, here Pythia's PARJ(82), which sets the
parton shower cutoff scale. Being able to change parameters on the command
line is useful for scanning parameter ranges from a shell loop, or rapid
testing of parameter values without needing to write a parameters file for
use with~
\kbd
{
-P
}
.
}
\item
\paragraph
{
Writing out HepMC events:
}{
\kbd
{
rivetgun -g~FPythia:6413
-P~lhc.params -n~50 -o~out.hepmc -R
}
will generate 50 LHC events with
Pythia. The~
\kbd
{
-o
}
switch is being used here to tell
\kbd
{
rivetgun
}
to
write the generated events to the
\kbd
{
out.hepmc
}
file. This file will be a
plain text dump of the HepMC event records in the ``GenEvent''
format. The~
\kbd
{
-R
}
flag is used to disable running Rivet at all: in this
instance,
\kbd
{
rivetgun
}
will produce no histogram output file and is
basically just a flexible steering program for several generators.
}
\item
\paragraph
{
Choosing analyses:
}{
\kbd
{
rivetgun -g~FHerwig:6510
-P~lep1.params
\cmdbreak
-a~DELPHI
_
1996
_
S3430090
}
will again generate LEP1
events using Pythia. This time, since the
\kbd
{
-n
}
switch is not present,
\kbd
{
rivetgun
}
will fall back to its default run of 10 events. We're here
running a Rivet analysis for the first time --- in the above runs, even
when~
\kbd
{
-R
}
wasn't specified, we weren't actually running any analyses. In
this case, we're running the DELPHI analysis most used for Monte Carlo
tuning.
}
\item
\paragraph
{
Using all analyses:
}{
\kbd
{
rivetgun -g~FHerwig:6510
-P~tevatron1800.params
\cmdbreak
-n~ 50000 -A
-a~
\RGnegate
{}
CDF
_
1994
_
S2952106
}
will generate 50k Tevatron events at
$
\sqrt
{s}_{
\Pproton\Pproton
}
=
\unit
{
1
.
8
}{
\TeV
}
$
. The~
\kbd
{
-A
}
switch says
that
\kbd
{
rivetgun
}
should try to run all the analyses that it can: it will
automatically disable any analyses not compatible with the Tevatron beam
particles. The~
\kbd
{
-a
}
switch is being used here for the opposite of its
usual reason: prefixing the analysis name with a tilde (
\kbd
{
\RGnegate
}
)
\emph
{
removes
}
that analysis. Here, all Tevatron analyses
\emph
{
other than
}
CDF
_
1994
_
S2952106 will run.
}
\item
\paragraph
{
Histogramming:
}{
\kbd
{
rivetgun -g~FPythia:6413
-P~tevatron1800.params
\cmdbreak
-H~foo --histotype~ROOT
}
will make 10
Tevatron events. The new features are the
\kbd
{
-H
}
and
\kbd
{
--histotype
}
switches, which influence the output data file. The
\kbd
{
-H
}
chooses the
base name of the output file, by default ``Rivet'' and
\kbd
{
--histotype
}
chooses the format, here set to ROOT. So the output file, which in the above
examples was
\kbd
{
Rivet.aida
}
, will here be
\kbd
{
foo.root
}
.
}
\item
\paragraph
{
Log level:
}{
\kbd
{
rivetgun -g~FPythia:6413 -P~lep1.params
-l~Rivet.Analysis=DEBUG~
\cmdbreak
-l~Rivet.Projection=TRACE -l~RivetGun=WARN
}
will again generate LEP1 events using Pythia. The~
\kbd
{
-l
}
flags are being
used to change the level of the logging coming from the various analysis
classes. The first tells all Rivet analyses and associated handlers to show
any messages at log level ``debug'' --- more than usual --- and above. The
second tells Rivet's projections to log at ``trace'' level --- very detailed
debug information --- and above. The last controls the log levels of the
\kbd
{
rivetgun
}
executable itself: this can be used to suppress or enhance
information like the event number. The default level is ``info'', which lies
between ``debug'' and ``warning''.
}
\item
\paragraph
{
More on logging:
}{
\kbd
{
rivetgun -g~FPythia:6413 -P~lep1.params
\cmdbreak
-l~Rivet.Analysis.Handler=WARN -l~Rivet.Analysis.Test=TRACE
}
is another demo of Rivet's logging capabilities. The logging system is
hierarchical, so the examples above applied to
\emph
{
all
}
analyses,
\emph
{
all
}
projections, and so on. It is possible, indeed desirable, to be
more specific, as in this example, where the log levels of most classes in
the
\kbd
{
Rivet.Analysis
}
log hierarchy is the default ``info'' level, but
\kbd
{
Analysis.Handler
}
and
\kbd
{
Analysis.Test
}
are set to different levels.
}
\end
{
itemize
}
\TODO
{
Using the output AIDA/other format data files.
}
As with most software, the best way to learn it is to try and use it ---
preferably starting with relatively modest aims and then progressing to more
ambitious things as your familiarity increases. And give feedback to the authors
if the design seems a bit screwy!
\section
{
How Rivet works
}
Hopefully by now you've run Rivet a few times and got the hang of the command
line interface and viewing the resulting analysis data files. Maybe you've got
some ideas of analyses that you would like to see in Rivet's library. If so,
then you'll need to know a little about Rivet's internal workings before you can
start coding: with any luck by the end of this section that won't seem
particularly intimidating.
The core objects in Rivet are ``projections'' and ``analyses''. Hopefully
``analyses'' isn't a surprise --- that's just the collection of routines that
will make histograms to compare with reference data, and the only things that
might differ there from experieces with HzTool are the new histogramming system
and the fact that we've used some OO features to make life a bit easier. The
meaning of ``projections'', as applied to event analysis, will probably be less
obvious. We'll discuss them now.
\section
{
Projections
}
The name ``projection'' is meant to evoke thoughts of
projection operators, low-dimensional slices/views of high-dimensional spaces,
and other things that might appeal to physicists who view the world through
quantum-tinted lenses. A more mundane, but equally applicable, name would be
``observables'', but since they all inherit from the
\kbd
{
Projection
}
base
class, we'll stick to that name. Projections can be relatively simple things
like event shapes (i.e. scalar, vector or tensor quantities), or arbitrarily
complex things like lossy or selective views of the event final
state.
\footnote
{
The ability for projections to return arbitrarily complex objects
constructed from the event record is why we chose a slightly vague term like
``projection'' rather than ``observable'', which many people take to be
``something I can plot.''
}
\subsection
{
Projection caching
}
Aside from semantic issues of how we're dividing the computational work of
analysing events, projections are important computationally because they live
within a framework which automatically stores (``caches'') their results between
events.
A concrete example may help here: let's say we have two analyses which
have the same run conditions, i.e. incoming beam types, beam energies, etc. Each
also uses the thrust event shape measure to define a set of basis vectors for
their analysis. For each event that gets passed to Rivet, whichever analysis
gets called first will first call a final state projection to get a list of
stable, physical particles (filtering out the intermediate and book-keeping
entries in the HepMC event record). That final state projection is then
``attached'' to the event. The analysis will then call a thrust projection which
has been told to use the same final state projection to define the momentum
vectors used in the thrust calculation, and similarly the thrust projection will
be registered with the event.
So far, projections have offered no benefits! However, when the second analysis
runs, it will similarly apply its final state and thrust projections to the
event, but the infrastructure will detect that an equivalent calculation has
already been done and will return references to the already-run
projections. Since projections can actually contain each other (``nesting''),
this model allows some substantial computational savings, without the analysis
author even needing to be particularly aware of what is going on.
\begin
{
change
}
The projection model is very likely to change in Rivet version 2.0, to protect
analysis authors further from the issues of managing projection object
lifecycles. This will take the form of centralising projection object
ownership, but won't affect the overall principle of projection caching.
\end
{
change
}
Observant readers may have noticed a problem with all this projection caching
cleverness: what if the final states aren't defined the same way? One might
provide charged final state particles only, or the acceptances (defined in
rapidity range and a IR
$
p_
\perp
$
cutoff) might differ. Rivet handles this by
making each projection provide a comparison operator which is used to decide
whether the cached version is acceptable or if the calculation must be re-run
with different settings. Because projections can be nested, applying a top-level
projection to an event can spark off a cascade of comparisons, calculations and
cache accesses, making use of existing results wherever possible.
% \begin{detail}
% How projection caching \emph{really} works
% (skippable, but useful as a reference)
% This section is super-hardcore
% \end{detail}
\subsection
{
Standard projection summary
}
\subsection
{
Example projection
}
\subsection
{
Cuts and constraints
}
\section
{
Analyses
}
\subsection
{
Histogramming
}
\TODO
{
Histo interfaces, AIDA and YODA. Formats.
}
\subsection
{
Analysis histo autobinning
}
\subsection
{
Pluggable analyses
}
\subsection
{
Example analysis
}
\section
{
Viewing output data files
}
\section
{
Comparing with reference data
}
% \begin{thebibliography}{999}
% \end{thebibliography}
\end
{
document
}
File Metadata
Details
Attached
Mime Type
text/x-tex
Expires
Tue, Sep 30, 6:02 AM (1 d, 22 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
6566414
Default Alt Text
rivet-manual.tex (21 KB)
Attached To
Mode
rRIVETHG rivethg
Attached
Detach File
Event Timeline
Log In to Comment