Page MenuHomeHEPForge
Files F8308831

usersGuide.html
No OneTemporary
Actions

usersGuide.html
View Options

<!--
//==============================================================================
// usersGuide.html
//
// Copyright (C) 2010-2013 Tobias Toll and Thomas Ullrich
//
// This file is part of Sartre version: 1.1
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation.
// This program is distributed in the hope that it will be useful,
// but without any warranty; without even the implied warranty of
// merchantability or fitness for a particular purpose. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
//
// Author: Thomas Ullrich
// Last update:
// $Date: 2013-05-29 21:25:21 +0100 (Wed, 29 May 2013) $
// $Author: thomas.ullrich@bnl.gov $
//==============================================================================
-->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<title>Sartre - Users Guide</title>
<meta http-equiv="Content-type" content="text/html; charset=UTF-8" /> <link href="sartre.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="120" align="left" valign="top"><img src="images/sartreLogo.png" alt="" border="0" align="right" /></td>
<td width="10">&nbsp;&nbsp;</td>
<td align="left" valign="middle" class="postheader"><a href="index.html"><font color="#004faf">Home</font></a>&nbsp;&middot;
<a href="overview.html"><font color="#004faf">Overview</font></a>&nbsp;&middot; <font color="#004faf">Users
Guide</font><a href="generator.html"><font color="#004faf"></font></a>&nbsp;&middot;
<a href="referenceGuide.html"><font color="#004faf">Reference Guide</font> </a></td></tr>
</table>
<h1 class="title">Users Guide</h1>
<p>Sar<em>t</em>re is a class library that lets you easily assemble a program
that fits your needs. Typically your setup will consist of a main program
and a <a href="runcardRef.html">
runcard</a>, <em>i.e.</em>, a text file with instruction read by Sar<em>t</em>re,
that defines various parameters such as beam energies, what model to
use, what vector meson species to generate, the number of events, and
much more. Sar<em>t</em>re has a built-in mechanism to take care of
this. The main class the user has to deal with is
<a href="refSartre.html">Sartre</a>.
Necessary subclasses can be obtained via access functions of <a href="refSartre.html">Sartre</a>.
The class <a href="refEventGeneratorSettings.html">EventGeneratorSettings</a> deals
with the setup parameters and the complete structure of the generated
event is returned in an instance of the <a href="refEvent.html"> Event</a> class. Sar<em>t</em>re
has no predefined output format. The provided example program <code>sartreMain.cpp</code> contains
an example on how to store the generated events in a ROOT file for later
processing. </p>
<p>In this Users Guide we discuss the general idea of Sartre, how it functions,
and how to use it. For detailed information
on classes please see the <a href="referenceGuide.html">Reference Guide</a>.</p>
<p>&nbsp;</p>
<h2>Content</h2>
<ol>
<li><a href="#TheBigPicture">The big picture</a></li>
<li><a href="#FinalStateParticles">Final state particles</a></li>
<li><a href="#ConventionsAndUnitsInSartre">Conventions and units
in Sar<em>t</em>re</a></li>
<li><a href="#EnvironmentVariables">Environment variables</a></li>
<li><a href="#GettingStarted">Getting started</a></li>
<li><a href="#Tables">Tables</a></li>
</ol>
<h2>&nbsp;</h2>
<h2><a name="TheBigPicture" id="TheBigPicture"></a>1. The big picture</h2>
<p>It is helpful to understand the basics of how Sar<em>t</em>re actually
works, The figure below illustrate (in a very schematic fashion) the
inner working of the Sar<em>t</em>re event generator. </p>
<p align="center"><img src="images/scheme.png" /></p>
<p>The user provides the energies of the incoming beams, the hadron beam
mass (A), sets the range in<i> t</i>,
<i>W<sup> </sup></i>, and <i>Q<sup>2</sup></i> he or she wants to generate,
defines which dipole model to use, what vector meson to generate,
and much more. The values are typically defined in a so called <a href="runcardRef.html">runcard</a>,
a user provided text file, that is passed to Sartre during initialization.
From the given parameters Sar<em>t</em>re
first determines which amplitude (mean and variance) tables are to be
used. Table exist for the bSat and the bNonSat models, for the three
vector mesons &rho;, &phi;, and J/&psi; s well as for DCVS. Sartre
currently contains tables for several nuclei reaching from light to
heavy. The beam energies, the table range and the user requested limits
determine the kinematic range in <i>W<sup> </sup></i>,<i>Q<sup>2</sup></i>,
and t. Sartre used the tables to calculate a 3-dimensional
probability density function (pdf)
that is essentially the triple differential
cross-section <em>d<sup>3</sup>&sigma;/(dt
dW<sup>2</sup> dQ<sup>2</sup>)</em>. This pdf is used in UNU.RAN,
a random generation package that provides a random generatos for
multivariate continuous distributions, which then generates random
number triplets for <i>t</i>, <i>W<sup>2 </sup></i>, and <i>Q<sup>2</sup></i> accordingly.
This triplet is then fed into a final state generator that calculates
the final state particles, <em>i.e</em>., the scattered electron
and proton/nuclei, the vector meson, and the virtual photon. Note
that<i> t</i>,
<em>W</em>, and <i>Q<sup>2</sup></i> completely <a href="finalState.html">determine
the final state</a> with the exception of the azimuthal angles
which are chosen randomly. In case the event is incoherent a
diffractive mass is generated and converted into an excitation
energy that is used to breakup the nucleus. We use the evaporation
and fragmentation model Gemini to do that for us. The output,
the event record, is available in full for the user for further
processing.</p>
<p><strong>Why <i>t</i>, <em>W</em>, and <i>Q<sup>2</sup></i> ?</strong> There
are 3 independent variables needed. Since Sar<em>t</em>re deals with
diffractive events <em>t</em> is
a given. The other two can be any combination of <em>x, W, Q, y</em>. <i>Q<sup>2</sup></i> seems
rather obvious and intuitive. Since in the case of photoproduction <em>x</em> loses
its importantance, <em>W</em> was picked as the 3rd variable. It is also
the parameter that is easiest accessible in the experiment and it is
numerically somewhat easier to handle. The static <a href="refKinematics.html">class
Kinematics</a>
provides tools that let you easily (and correctly) transform one into
the other if needed. The generated event records contains them all. Sar<em>t</em>re
</p>
<h2><a name="FinalStateParticles" id="FinalStateParticles"></a>2. Final state particles</h2>
<p>The final state particles are the scattered electron, the scattered
proton/nucleus, and the created vector meson. For incoherent events
the fragments of the broken nucleus are also provided. The vector
mesons are not decayed in Sar<em>t</em>re.
This can be easily done at a later stage, e.g. in Geant. The <a href="refEvent.html">Event</a> class
that contains the event record also holds information on the virtual
photon. </p>
<h2><a name="ConventionsAndUnitsInSartre" id="ConventionsAndUnitsInSartre"></a>3.
Conventions and units in Sar<em>t</em>re</h2>
<p>The beam electron comes from the right meaning it has negative p<sub>z</sub>,
the proton beam is coming from the left meaning it has positive p<sub>z</sub>.
Energy, momenta, and masses are given in GeV, GeV/<em>c</em>, and GeV/<em>c</em><sup>2</sup>,
respectively. Lengths, such as impact parameter or dipole radii, are in fm
(fermi/ femtometer), cross-sections are given in nb (nanobarn). </p>
<h2><a name="EnvironmentVariables" id="EnvironmentVariables"></a>4.
Environment variables</h2>
<p>Sar<em>t</em>re requires only one environment variable to be set: <code>$SARTRE_DIR</code>.
This variable should point to the directory where Sar<em>t</em>re
is installed. It is used to locate the <a href="#Tables">amplitude
lookup tables</a> needed
in Sartre as well as the many tables required by Gemini to handle
the nuclear breakup for incoherent events. Since Sar<em>t</em>re
is using ROOT libraries it is advisable to also have the environment
<code>$ROOTSYS</code> defined. </p>
<h2><a name="GettingStarted" id="GettingStarted"></a>5. Getting Started</h2>
<p>Most programs have a similar structure:</p>
<ol>
<li>Create an instance of <a href="refSartre.html">Sartre</a></li>
<li>Pass setup parameters to the created object</li>
<li>Initialize</li>
<li>Loop and generate events</li>
</ol>
<p>Typically you only need one instance of <a href="refSartre.html">Sartre</a> that
you can initialize multiple times if needed. There are two ways of
passing the setup parameters to <a href="refSartre.html">Sartre</a>:
(i) using a runcard or (ii) programmatically. The advantage of a
runcard is that you can change the setup without re-compiling the
program; it also makes batch processing easier. Here's the example
with a runcard:</p>
<pre class="code">1 #include &quot;Sartre.h&quot;
2
3 int main() {
4 Sartre sartre;
5 bool ok = sartre.init(&quot;myRuncard.txt&quot;);
6
7 // generate events if ok == true
8 // ....
9
10 return 0;
11 }</pre>
<p>For details on runcard syntax and available commands see the <a href="runcardRef.html">
runcard reference.</a> To setup the run programmatically you need to
define every parameter through an
instance of <a href="refEventGeneratorSettings.html">EventGeneratorSettings</a> that
can be obtained from the instance of <a href="refSartre.html">Sartre</a>
as shown here:</p>
<pre class="code">1 #include &quot;Sartre.h&quot;
2 #include &quot;EventGeneratorSettings.h&quot;
3
4 int main() {
5 Sartre sartre;
6
7 EventGeneratorSettings* settings = sartre.runSettings();
8
9 settings-&gt;setVerbose(true); <br />10 settings-&gt;setNumberOfEvents(10000); <br />11 settings-&gt;setVectorMesonId(333); <br />12 settings-&gt;setElectronBeamEnergy(20.); <br />13 settings-&gt;setHadronBeamEnergy(100); <br />14 settings-&gt;setDipoleModelType(bSat); <br />15 settings-&gt;setA(197); // Au <br />16 settings-&gt;setEnableNuclearBreakup(false); <br />17 settings-&gt;setQ2min(0.5);
18 // possibly more ...<br />19
20 bool ok = sartre.init();
21
22 settings-&gt;list(); // good habit: print all settings
23
24 // generate events if init() was successful (ok == true)
25 // ....
26
27 return 0;
28 }</pre>
<p>Note that you have to setup <a href="refSartre.html">Sartre</a> before calling <code>init()</code>. For
several parameters, changes afterwards have no effect. Some, however, you
can change throughout the rest of the program. See <a href="refEventGeneratorSettings.html">EventGeneratorSettings </a> reference
page for details.</p>
<p>Once <a href="refSartre.html">Sartre</a> is setup we are ready to generate events. This
typically looks like this:</p>
<pre class="code">1 unsigned long maxEvents = settings-&gt;numberOfEvents(); <br />2 <br />3 for (unsigned long iEvent = 0; iEvent &lt; maxEvents; iEvent++) { <br />4
5 // Generate one event <br />6 Event *event = sartre.generateEvent(); <br />7
8 // Print out (here only for the first few events) <br />9 if (iEvent &lt; 4) event-&gt;list(); <br />14 } </pre>
<p>Note, that in the example above we use the number of events to generate (<code>maxEvents</code>)
from the setting parameter (line 1). If you use a runcard the referring variable
would be <code>numberOfEvents</code>. You are of course free to use any number
you want but it is a good habit to do as shown in the example since then
the number of events can then be controlled through a runcard. <a href="refSartre.html#generateEvent">Sartre::generateEvent() </a>generates
a full event and returns a pointer to the object that holds the event (line
6).</p>
<p>The <a href="refEvent.html">Event</a> class contains the complete event structure. In the above
example (line 9) we use <a href="refEvent.html#list">Event::list()</a> to show the complete event record for
the first 4 events. Here is an example of how such a print-out looks like: </p>
<pre class="code">
evt = 1 Q2 = 0.209 x = 1.259e-04
W = 40.793 y = 0.208
t = -0.010 xpom = 5.898e-03
pol = T diff = coherent
# id name status parents daughters px py pz E m
0 11 e- 4 - - 2 3 0.000 0.000 -20.000 20.000 5.110e-04
1 1000791970 Au(197) 4 - - 6 - 0.000 0.000 99.996 100.000 0.938
2 11 e- 1 0 - - - 0.014 -0.407 -15.839 15.844 5.110e-04
3 22 gamma 2 0 - 4 5 -0.014 0.407 -4.161 4.156 -0.458
4 443 J/psi 1 3 - - - -0.113 0.396 -3.572 4.745 3.097
5 990 pomeron 2 3 3 6 - 0.099 0.011 -0.589 -0.589 -0.100
6 1000791970 Au(197) 1 1 5 - - 0.099 0.011 99.406 99.411 0.938 </pre>
<p>The print-out starts with a block of general event properties, where <code>pol</code> is
the polarization of the virtual photon and <code>diff</code> indicates
if the event was coherent or incoherent. <a href="refSartre.html">Sartre</a> follows
the PDG numbering scheme to identify particles. All energies are in GeV,
all momenta in GeV/<em>c</em>, and masses in GeV/c<sup>2</sup>.</p>
<p>For a detail description of the event record we refer to the <a href="eventRecord.html">Event
Record</a> documentation.</p>
<h2><a name="Tables" id="Tables"></a>6. Tables</h2>
<p>The Sar<em>t</em>re event generator requires a set of lookup tables in
order to work. These tables are kept in the <code>$SARTRE_DIR/tables</code> directory,
where <code>$SARTRE_DIR</code> is
an environment variable that needs to be defined and points to the Sar<em>t</em>re
installation directory. Internally the tables are kept in ROOT 3D histograms.
Each setup requires at least 4 tables to hold the mean amplitude &lt;<em>A</em>&gt; and
the mean amplitude squared &lt;<em>A</em><sup>2</sup>&gt;, each for longitudinally
and transversely polarized photons. Each set of tables is kept in a subdirectory
following the following scheme: <var>A/model/VM_ID</var>, where <var>A</var> is
the hadron beam mass, <var>model</var> the name of the used dipole model
(bSat, bNonSat, or bCGC), and <em>VM_ID</em> is the PDG particle ID
of the vector meson or photon.</p>
<p>Generating these tables is rather CPU extensive. So far only the following
tables are available:</p>
<table border="1" cellpadding="5">
<tr>
<th scope="col">p (A=1)</th>
<th bgcolor="#999999" scope="col">bSat</th>
<th bgcolor="#999999" scope="col">bNonSat</th>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">22 (&gamma;/DVCS)</th>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">113 (&rho;)</th>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">333 (&phi;)</th>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">443 (J/&psi;)</th>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>
</table>
<p>&nbsp;</p>
<table border="1" cellpadding="5">
<tr>
<th scope="col">Ca (A=40)</th>
<th bgcolor="#999999" scope="col">bSat</th>
<th bgcolor="#999999" scope="col">bNonSat</th>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">22 (&gamma;/DVCS)</th>
<td align="center">yes</td>
<td align="center">no</td>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">113 (&rho;)</th>
<td align="center">yes</td>
<td align="center">no</td>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">333 (&phi;)</th>
<td align="center">yes</td>
<td align="center">no</td>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">443 (J/&psi;)</th>
<td align="center">yes</td>
<td align="center">no</td>
</tr>
</table>
<p>&nbsp;</p>
<table border="1" cellpadding="5">
<tr>
<th scope="col">Au (A=197)</th>
<th bgcolor="#999999" scope="col">bSat</th>
<th bgcolor="#999999" scope="col">bNonSat</th>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">22 (&gamma;/DVCS)</th>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">113 (&rho;)</th>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">333 (&phi;)</th>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>
<tr>
<th align="left" bgcolor="#999999" scope="row">443 (J/&psi;)</th>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>
</table>
<p>&nbsp;</p>
<p>There are several tools to inspect and query these tables. They are located
in the<code> $SARTRE_DIR/bin</code> directory. While they are mostly
meant for experts to verify the integrity of the tables one might be
of general interest: <code>tableInspector</code>. All table tools are
automatically build together with the Sar<em>t</em>re library during
installation. The command takes one or several tables as argument and
prints the content type as well as the kinematic range in<em> t</em>,
Q<sup>2</sup>,
and W (W<sup>2</sup>), the latter being the most useful item for the
user. They typically have a set of useful options: <var>-s</var> to print
additional statistics or <var>-a</var> to print the content of the whole
table. </p>
<p>Starting with Sar<em>t</em>re version 1.1 we also include a set of lookup
tables for the logarithmic derivative of the amplitude along <em>x</em> (typically
called &lambda;) that is
needed to calculate the skewedness and real amplitude corrections.
&lambda; values are derived from the referring ep table (also when
running eA). If the kinematic range is not sufficient, that is if
the amplitude table range used is larger than that of the &lambda; table,
we fallback to calculating the value on the fly from the referring
ep table. If the latter is not large enough corrections are switched
off. In any case the user is informed about what is happening. </p>
<p>&nbsp;</p>
<address><div align="center">
<table border="0" cellspacing="0" width="100%"><tbody><tr class="address">
<td align="left" width="40%">&nbsp;</td>
<td align="center" width="20%">&nbsp;</td>
<td align="right" width="40%"><div align="right"><br>Last Update:
<!-- #BeginDate format:Am1 -->May 29, 2013<!-- #EndDate -->
</div></td>
</tr></tbody></table></div></address>
</body></html>

File Metadata

Mime Type
text/html
Expires
Sat, Dec 21, 1:17 PM (1 d, 1 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
3994148
Default Alt Text
usersGuide.html (21 KB)

Event Timeline