Difference between revisions of "Monte Carlo and Smearing"

From Electron Ion Collider
Jump to: navigation, search
m (Overview: Links to summary presentation)
 
Line 1: Line 1:
''Note: developers should read the [[eic-smear Developer Notes]]''
+
''Note: developers should read the [[Eic-smear_Developer_Notes|eic-smear Developer Notes]]''
  
The Monte Carlo smearing package '''eic-smear''' is a collection of classes and routines for analysing Monte Carlo events and performing fast smearing to study the effects of detector resolution.
+
The Monte Carlo smearing package '''eic-smear''' is a collection of classes and routines for analysing Monte Carlo events and performing fast smearing to study the effects of detector resolution. It is designed for use with the [[ROOT|ROOT]] analysis framework.
It is designed for use with the [[ROOT]] analysis framework.
+
  
==Overview==
+
== Overview ==
  
 
There are two main elements to eic-smear:
 
There are two main elements to eic-smear:
# '''Monte Carlo''': A collection of classes describing events produced by various EIC [[Simulations | Monte Carlo generators]], and routines for [[BuildTree | building ROOT trees]] of these events from ASCII input.
+
 
# '''Smearing''': Classes and routines for applying fast detector [[smearing]] to the events produced by the Monte Carlo portion of the package.
+
#'''Monte Carlo''': A collection of classes describing events produced by various EIC [[Simulations|Monte Carlo generators]], and routines for [[BuildTree|building ROOT trees]] of these events from ASCII input.
 +
#'''Smearing''': Classes and routines for applying fast detector [[Smearing|smearing]] to the events produced by the Monte Carlo portion of the package.
 +
 
 
Being closely related, they are distributed as a single package.
 
Being closely related, they are distributed as a single package.
  
Please see the links above for details of how to use each portion of the package.
+
Please see the links above for details of how to use each portion of the package. There is also a summary talk [[Media:EicsmearOverview2014.pdf|here]]. The remainder of this page will deal primarily with installing the software.
There is also a summary talk [[Media:EicsmearOverview2014.pdf | here]].
+
The remainder of this page will deal primarily with installing the software.
+
  
==Documentation==
+
== Documentation ==
  
 
Full class documentation is provided [http://www.star.bnl.gov/~tpb/eic-smear/index.html here].
 
Full class documentation is provided [http://www.star.bnl.gov/~tpb/eic-smear/index.html here].
  
 
The ''scripts'' subdirectory of the distribution contains a number of examples of how to use the code, including:
 
The ''scripts'' subdirectory of the distribution contains a number of examples of how to use the code, including:
* Building ROOT trees from generator output.
 
* Reading trees for analysis.
 
  
Class documentation for the out-of-date original version of the code is preserved [http://www.star.bnl.gov/~tpb/erhicRoot here].
+
*Building ROOT trees from generator output.
This version does not provide fast smearing functionality.
+
*Reading trees for analysis.
  
==Obtaining the code==
+
Class documentation for the out-of-date original version of the code is preserved [http://www.star.bnl.gov/~tpb/erhicRoot here]. This version does not provide fast smearing functionality.
 +
 
 +
== Obtaining the code ==
  
 
There are three ways to access the smearing package.
 
There are three ways to access the smearing package.
# For those with an EIC RCF account, it can be accessed via the EIC AFS region. The code is located at <code>/afs/rhic.bnl.gov/eic/PACKAGES/eic-smear</code>.
 
# Download a source distribution (see below) and build it yourself.
 
# For those wanting to develop the code themselves, check out the a version from [http://svn.racf.bnl.gov/svn/eic/Utilities/eic-smear/ svn]. Stable releases can be found under <code>tags</code>, while the latest developments (albeit with the possibility of instabilities) are located under <code>trunk</code>.
 
  
If using the EIC AFS version, make sure to run it with the correct EIC ROOT installation.
+
#For those with an EIC RCF account, it can be accessed via the EIC AFS region. The code is located at <code>/afs/rhic.bnl.gov/eic/PACKAGES/eic-smear</code>.
The simplest way to ensure this is to use the standard EIC [[Computing#EIC_logon | logon scripts]] to configure your environment.
+
#Download a source distribution (see below) and build it yourself.
It can then be run immediately with no further setup.
+
#For those wanting to develop the code themselves, check out the a version from [http://svn.racf.bnl.gov/svn/eic/Utilities/eic-smear/ svn]. Stable releases can be found under <code>tags</code>, while the latest developments (albeit with the possibility of instabilities) are located under <code>trunk</code>.
If you want to run with a different version of ROOT you should compile your own version of the library.
+
  
===Source distributions===
+
If using the EIC AFS version, make sure to run it with the correct EIC ROOT installation. The simplest way to ensure this is to use the standard EIC [[Computing#EIC_logon|logon scripts]] to configure your environment. It can then be run immediately with no further setup. If you want to run with a different version of ROOT you should compile your own version of the library.
* [[Media:Eic-smear-1.0.3.tar.bz2 | Version 1.0.3]]
+
* [[Media:Eic-smear-1.0.2.tar.bz2 | Version 1.0.2]]
+
* [[Media:Eic-smear-1.0.1.tar.bz2 | Version 1.0.1]]
+
* [[Media:Eic-smear-1.0.0.tar.bz2 | Version 1.0.0]]
+
  
==Compiling==
+
=== Source distributions ===
 +
 
 +
*[[Media:Eic-smear-1.0.3.tar.bz2|Version 1.0.3]]
 +
*[[Media:Eic-smear-1.0.2.tar.bz2|Version 1.0.2]]
 +
*[[Media:Eic-smear-1.0.1.tar.bz2|Version 1.0.1]]
 +
*[[Media:Eic-smear-1.0.0.tar.bz2|Version 1.0.0]]
 +
 
 +
== Compiling ==
 +
 
 +
The package can be built using either configure/make or (as of version 1.0.3) CMake. The most up-to-date build instructions and other information can be found in the accompanying README. Out-of-source builds are recommended to avoid polluting your source directory e.g. from the eic-smear directory:
  
The package can be built using either configure/make or (as of version 1.0.3) CMake.
 
The most up-to-date build instructions and other information can be found in the accompanying README. Out-of-source builds are recommended to avoid polluting your source directory e.g. from the eic-smear directory:
 
 
  mkdir build
 
  mkdir build
 
  cd build
 
  cd build
 +
 
Create a Makefile using either configure:
 
Create a Makefile using either configure:
 +
 
  ../configure [arguments]
 
  ../configure [arguments]
 +
 
or CMake:
 
or CMake:
 +
 
  cmake [arguments] ..
 
  cmake [arguments] ..
 +
 
See the README for relevant arguments. Finally make and, optionally, install:
 
See the README for relevant arguments. Finally make and, optionally, install:
 +
 
  make
 
  make
 
  make install
 
  make install
 +
 
If you don't do an install then the generated library can be found in the <code>.libs</code> directory (note the '.') in the build directory.
 
If you don't do an install then the generated library can be found in the <code>.libs</code> directory (note the '.') in the build directory.
  
===PYTHIA 6 support===
+
=== PYTHIA 6 support ===
 +
 
 +
For most generators eic-smear only accepts ASCII files as input for tree generation (see the [[Simulations|generator]] pages for an explanation of the format). However it is possible to run PYTHIA 6 from within ROOT and directly process the output into a tree, without the intermediate step of an ASCII file. This can save significant time and disk space associated with storing and reading the ASCII files, as well as allowing user-defined manipulation (such as event filtering) between generation and writing of events. For this, one must have
 +
 
 +
*[ftp://root.cern.ch/root/pythia6.tar.gz PYTHIA 6] compiled as a shared library named libPythia6.so.
 +
*A version of ROOT compiled against PYTHIA 6 (see the ROOT installation instructions)
  
For most generators eic-smear only accepts ASCII files as input for tree generation (see the [[Simulations | generator]] pages for an explanation of the format).
 
However it is possible to run PYTHIA 6 from within ROOT and directly process the output into a tree, without the intermediate step of an ASCII file.
 
This can save significant time and disk space associated with storing and reading the ASCII files, as well as allowing user-defined manipulation (such as event filtering) between generation and writing of events.
 
For this, one must have
 
* [ftp://root.cern.ch/root/pythia6.tar.gz PYTHIA 6] compiled as a shared library named libPythia6.so.
 
* A version of ROOT compiled against PYTHIA 6 (see the ROOT installation instructions)
 
 
To enable PYTHIA 6 support in eic-smear, the user must pass the following option to <code>configure</code>:
 
To enable PYTHIA 6 support in eic-smear, the user must pass the following option to <code>configure</code>:
 +
 
  ../configure --with-pythia6-libdir=/path/to/pythia6dir
 
  ../configure --with-pythia6-libdir=/path/to/pythia6dir
 +
 
or to CMake:
 
or to CMake:
 +
 
  cmake -DPYTHIA6_LIBDIR=/path/to/pythia6dir ..
 
  cmake -DPYTHIA6_LIBDIR=/path/to/pythia6dir ..
where pythia6dir is the directory containing libPythia6.so.
 
To run PYTHIA 6 from within ROOT, the erhic::Pythia6 utility class is provided.
 
All PYTHIA configuration is done via ROOT's own TPythia6 class.
 
See the documentation for that class for details of how to use it.
 
  
==Loading==
+
where pythia6dir is the directory containing libPythia6.so. To run PYTHIA 6 from within ROOT, the erhic::Pythia6 utility class is provided. All PYTHIA configuration is done via ROOT's own TPythia6 class. See the documentation for that class for details of how to use it.
 +
 
 +
== Loading ==
  
 
Load the shared library into ROOT via
 
Load the shared library into ROOT via
 +
 
  root [0] gSystem->Load("/path/to/eic-smear/.libs/libeicsmear");
 
  root [0] gSystem->Load("/path/to/eic-smear/.libs/libeicsmear");
or whatever library path was used if it was installed in another location.
+
 
If you include this path in your (DY)LD_LIBRARY_PATH you can just do
+
or whatever library path was used if it was installed in another location. If you include this path in your (DY)LD_LIBRARY_PATH you can just do
 +
 
 
  root [0] gSystem->Load("libeicsmear");
 
  root [0] gSystem->Load("libeicsmear");
Note that if you are an EIC RCF user, and follow the EIC [https://wiki.bnl.gov/eic/index.php/Computing#EIC_logon logon] instructions, the package is automatically loaded when you start ROOT.
+
 
Depending on what is loaded already, you may need to load other ROOT libraries before loading eic-smear.
+
Note that if you are an EIC RCF user, and follow the EIC [https://wiki.bnl.gov/eic/index.php/Computing#EIC_logon logon] instructions, the package is automatically loaded when you start ROOT. Depending on what is loaded already, you may need to load other ROOT libraries before loading eic-smear. Specifically, if you compile ''without'' PYTHIA 6 support you may need to load libEGPythia6 first, followed by eic-smear:
Specifically, if you compile ''without'' PYTHIA 6 support you may need to load libEGPythia6 first, followed by eic-smear:
+
 
 
  root [0] gSystem->Load("libEGPythia6");
 
  root [0] gSystem->Load("libEGPythia6");
 
  root [1] gSystem->Load("libeicsmear");
 
  root [1] gSystem->Load("libeicsmear");
  
===A note to Mac users===
+
=== A note to Mac users ===
Depending on the version of ROOT you use, it may not recognise the libeicsmear.dylib file produced by make.
+
 
A simple workaround is to create a symbolic link to the .dylib with suffix .so:
+
Depending on the version of ROOT you use, it may not recognise the libeicsmear.dylib file produced by make. A simple workaround is to create a symbolic link to the .dylib with suffix .so:
 +
 
 
  cd /path/to/eic-smear/librarydir
 
  cd /path/to/eic-smear/librarydir
 
  ln -s libeicsmear.dylib libeicsmear.so
 
  ln -s libeicsmear.dylib libeicsmear.so
 +
 
Recent versions of ROOT recognise and accept .dylib files without issue.
 
Recent versions of ROOT recognise and accept .dylib files without issue.
  
==Running==
+
== Running ==
 +
 
 +
Converting ASCII output from the EIC event generators to ROOT events is handled by the routine [[BuildTree|BuildTree]].
  
Converting ASCII output from the EIC event generators to ROOT events is handled by the routine [[BuildTree]].
+
The first step to smearing is to write a script defining the detector volumes one wants to use. The routine SmearTree() is then used to apply the smearing defined by this script to a Monte Carlo tree. A detailed overview of how to perform both these steps can be found [[Smearing|here]].
  
The first step to smearing is to write a script defining the detector volumes one wants to use.
+
[[Category:Smearing]]
The routine SmearTree() is then used to apply the smearing defined by this script to a Monte Carlo tree.
+
A detailed overview of how to perform both these steps can be found [[Smearing | here]].
+

Latest revision as of 21:24, 13 August 2019

Note: developers should read the eic-smear Developer Notes

The Monte Carlo smearing package eic-smear is a collection of classes and routines for analysing Monte Carlo events and performing fast smearing to study the effects of detector resolution. It is designed for use with the ROOT analysis framework.

Overview

There are two main elements to eic-smear:

  1. Monte Carlo: A collection of classes describing events produced by various EIC Monte Carlo generators, and routines for building ROOT trees of these events from ASCII input.
  2. Smearing: Classes and routines for applying fast detector smearing to the events produced by the Monte Carlo portion of the package.

Being closely related, they are distributed as a single package.

Please see the links above for details of how to use each portion of the package. There is also a summary talk here. The remainder of this page will deal primarily with installing the software.

Documentation

Full class documentation is provided here.

The scripts subdirectory of the distribution contains a number of examples of how to use the code, including:

  • Building ROOT trees from generator output.
  • Reading trees for analysis.

Class documentation for the out-of-date original version of the code is preserved here. This version does not provide fast smearing functionality.

Obtaining the code

There are three ways to access the smearing package.

  1. For those with an EIC RCF account, it can be accessed via the EIC AFS region. The code is located at /afs/rhic.bnl.gov/eic/PACKAGES/eic-smear.
  2. Download a source distribution (see below) and build it yourself.
  3. For those wanting to develop the code themselves, check out the a version from svn. Stable releases can be found under tags, while the latest developments (albeit with the possibility of instabilities) are located under trunk.

If using the EIC AFS version, make sure to run it with the correct EIC ROOT installation. The simplest way to ensure this is to use the standard EIC logon scripts to configure your environment. It can then be run immediately with no further setup. If you want to run with a different version of ROOT you should compile your own version of the library.

Source distributions

Compiling

The package can be built using either configure/make or (as of version 1.0.3) CMake. The most up-to-date build instructions and other information can be found in the accompanying README. Out-of-source builds are recommended to avoid polluting your source directory e.g. from the eic-smear directory:

mkdir build
cd build

Create a Makefile using either configure:

../configure [arguments]

or CMake:

cmake [arguments] ..

See the README for relevant arguments. Finally make and, optionally, install:

make
make install

If you don't do an install then the generated library can be found in the .libs directory (note the '.') in the build directory.

PYTHIA 6 support

For most generators eic-smear only accepts ASCII files as input for tree generation (see the generator pages for an explanation of the format). However it is possible to run PYTHIA 6 from within ROOT and directly process the output into a tree, without the intermediate step of an ASCII file. This can save significant time and disk space associated with storing and reading the ASCII files, as well as allowing user-defined manipulation (such as event filtering) between generation and writing of events. For this, one must have

  • PYTHIA 6 compiled as a shared library named libPythia6.so.
  • A version of ROOT compiled against PYTHIA 6 (see the ROOT installation instructions)

To enable PYTHIA 6 support in eic-smear, the user must pass the following option to configure:

../configure --with-pythia6-libdir=/path/to/pythia6dir

or to CMake:

cmake -DPYTHIA6_LIBDIR=/path/to/pythia6dir ..

where pythia6dir is the directory containing libPythia6.so. To run PYTHIA 6 from within ROOT, the erhic::Pythia6 utility class is provided. All PYTHIA configuration is done via ROOT's own TPythia6 class. See the documentation for that class for details of how to use it.

Loading

Load the shared library into ROOT via

root [0] gSystem->Load("/path/to/eic-smear/.libs/libeicsmear");

or whatever library path was used if it was installed in another location. If you include this path in your (DY)LD_LIBRARY_PATH you can just do

root [0] gSystem->Load("libeicsmear");

Note that if you are an EIC RCF user, and follow the EIC logon instructions, the package is automatically loaded when you start ROOT. Depending on what is loaded already, you may need to load other ROOT libraries before loading eic-smear. Specifically, if you compile without PYTHIA 6 support you may need to load libEGPythia6 first, followed by eic-smear:

root [0] gSystem->Load("libEGPythia6");
root [1] gSystem->Load("libeicsmear");

A note to Mac users

Depending on the version of ROOT you use, it may not recognise the libeicsmear.dylib file produced by make. A simple workaround is to create a symbolic link to the .dylib with suffix .so:

cd /path/to/eic-smear/librarydir
ln -s libeicsmear.dylib libeicsmear.so

Recent versions of ROOT recognise and accept .dylib files without issue.

Running

Converting ASCII output from the EIC event generators to ROOT events is handled by the routine BuildTree.

The first step to smearing is to write a script defining the detector volumes one wants to use. The routine SmearTree() is then used to apply the smearing defined by this script to a Monte Carlo tree. A detailed overview of how to perform both these steps can be found here.