usersGuide.html
No OneTemporary
Actions

Size

21 KB

Subscribers

None

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">  </td>
	<td align="left" valign="middle" class="postheader"><a href="index.html"><font color="#004faf">Home</font></a> ·
	<a href="overview.html"><font color="#004faf">Overview</font></a> · <font color="#004faf">Users
	Guide</font><a href="generator.html"><font color="#004faf"></font></a> ·
	<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> </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> </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 ρ, φ, and J/ψ 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>σ/(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 "Sartre.h"
	2
	3 int main() {
	4 Sartre sartre;
	5 bool ok = sartre.init("myRuncard.txt");
	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 "Sartre.h"
	2 #include "EventGeneratorSettings.h"
	3
	4 int main() {
	5 Sartre sartre;
	6
	7 EventGeneratorSettings* settings = sartre.runSettings();
	8
	9 settings->setVerbose(true); <br />10 settings->setNumberOfEvents(10000); <br />11 settings->setVectorMesonId(333); <br />12 settings->setElectronBeamEnergy(20.); <br />13 settings->setHadronBeamEnergy(100); <br />14 settings->setDipoleModelType(bSat); <br />15 settings->setA(197); // Au <br />16 settings->setEnableNuclearBreakup(false); <br />17 settings->setQ2min(0.5);
	18 // possibly more ...<br />19
	20 bool ok = sartre.init();
	21
	22 settings->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->numberOfEvents(); <br />2 <br />3 for (unsigned long iEvent = 0; iEvent < 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 < 4) event->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 <<em>A</em>> and
	the mean amplitude squared <<em>A</em><sup>2</sup>>, 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 (γ/DVCS)</th>
	<td align="center">yes</td>
	<td align="center">yes</td>
	</tr>
	<tr>
	<th align="left" bgcolor="#999999" scope="row">113 (ρ)</th>
	<td align="center">yes</td>
	<td align="center">yes</td>
	</tr>
	<tr>
	<th align="left" bgcolor="#999999" scope="row">333 (φ)</th>
	<td align="center">yes</td>
	<td align="center">yes</td>
	</tr>
	<tr>
	<th align="left" bgcolor="#999999" scope="row">443 (J/ψ)</th>
	<td align="center">yes</td>
	<td align="center">yes</td>
	</tr>
	</table>
	<p> </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 (γ/DVCS)</th>
	<td align="center">yes</td>
	<td align="center">no</td>
	</tr>
	<tr>
	<th align="left" bgcolor="#999999" scope="row">113 (ρ)</th>
	<td align="center">yes</td>
	<td align="center">no</td>
	</tr>
	<tr>
	<th align="left" bgcolor="#999999" scope="row">333 (φ)</th>
	<td align="center">yes</td>
	<td align="center">no</td>
	</tr>
	<tr>
	<th align="left" bgcolor="#999999" scope="row">443 (J/ψ)</th>
	<td align="center">yes</td>
	<td align="center">no</td>
	</tr>
	</table>

	<p> </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 (γ/DVCS)</th>
	<td align="center">yes</td>
	<td align="center">yes</td>
	</tr>
	<tr>
	<th align="left" bgcolor="#999999" scope="row">113 (ρ)</th>
	<td align="center">yes</td>
	<td align="center">yes</td>
	</tr>
	<tr>
	<th align="left" bgcolor="#999999" scope="row">333 (φ)</th>
	<td align="center">yes</td>
	<td align="center">yes</td>
	</tr>
	<tr>
	<th align="left" bgcolor="#999999" scope="row">443 (J/ψ)</th>
	<td align="center">yes</td>
	<td align="center">yes</td>
	</tr>
	</table>
	<p> </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 λ) that is
	needed to calculate the skewedness and real amplitude corrections.
	λ 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 λ 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> </p>


	<address><div align="center">
	<table border="0" cellspacing="0" width="100%"><tbody><tr class="address">
	<td align="left" width="40%"> </td>
	<td align="center" width="20%"> </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 (19 h, 19 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 3994148
Default Alt Text: usersGuide.html (21 KB)

usersGuide.htmlNo OneTemporaryActions

usersGuide.htmlView Options

File Metadata

Event Timeline

usersGuide.html
No OneTemporary
Actions

usersGuide.html
View Options