FPaDsoft (software for “Future Particle Detector” studies), or FPad, is a package for future detector studies for circular colliders. It is designed to work “out-of-the box” for physics analysis of LCIO files after full detector simulations. The Monte Carlo files for this package are posted to HepSim in the “slcio” data format. It can also process the original PROMC files with the truth-level information.

The package does not require installation, nor platform-dependent libraries. It is a merge of several open-source Java projects, such as lcsim.org [(Simulator for the linear collider (SLIC): A tool for ILC detector simulations. N. Graf and J. McCormick, http://inspirehep.net/record/736286?ln=en)], LCIO event model, FreeHep, DMelt (community edition) for histogramming and plotting, hs-tools of HepSim. It also supports Java-implemented anti-KT jets. The package is designed to work using the Python language (it includes Jython 2.7), or using the standard Java.

You can find Monte Carlo samples in the LCIO format using the rfull001 search link. This link prints all event samples after full detector simulations (“tag rfull001”). Select “info” and then find the tag “rfull001” which prints LCIO files for a given MC sample. You can download such samples as discussed in HepSim manual.

The installation does not have external dependencies besides Java. Make sure Java7 and above is installed. Then run these commands to install the package (on Linux)

wget http://atlaswww.hep.anl.gov/hepsim/soft/fpadsoft-1.2.tgz -O - | tar -xz;
cd fpadsoft/
source setup.sh # takes 5 sec for first-time optimization

The last command optimizes Java packages for the Python language. Now you are ready to run over any file with truth-level and datector-simulation files, such as LCIO and ProMC. You can also use Windows.

All examples are publicly available from examples public directory. They are also located in the “examples” directory of the downloaded package. Many examples are based on gev250ee_pythia6_zpole_ee data sample (Z→e+e-). We assume that the working directory is “examples”. Do not forget to run “setup.sh” before running the examples.

Let's calculate Z peak from thuth-level electrons. Get 4 files (in 2 threads) and copy all files to the directory “gev250ee_pythia6_zpole”:

source setup.sh
cd examples
hs-get gev250ee_pythia6_zpole_ee%rfull001 gev250ee_pythia6_zpole_ee 2 4 # download 4 files
../fpad mc_truth.py

Alternatively, run this example in the FPad editor:

../fpad_edit mc_truth.py

It will pop-up an editor to edit the script. Then press “Run”. You can use also Windows and run “fpad.bat”. The result of this file is:

Let's calculate Z peak from particle-flow objects after full reconstruction using Pandora. You do not run “hs-get” command if you have done this before.

hs-get gev250ee_pythia6_zpole_ee%rfull001 gev250ee_pythia6_zpole_ee 2 4 # download 4 files
../fpad mc_pflow.py

you can also make a simple fit:

../fpad mc_pflow_fit.py

Let's calculate Z peak from reconstructed tracks (no Pandora and no particle identification) You do not run “hs-get” command if you have done this before.

hs-get gev250ee_pythia6_zpole_ee%rfull001 gev250ee_pythia6_zpole_ee 2 4 # download 4 files
../fpad mc_tracks.py

Let's calculate the Higgs peak from reconstructed photons after the PFA algorithm. This time you will need H→ gamma+gamma sample gev250ee_pythia6_higgs_gamgam: We set pT(γ)>10 GeV.

hs-get gev250ee_pythia6_higgs_gamgam%rfull001 gev250ee_pythia6_higgs_gamgam 2 10 # get 10 files in 2 threads
../fpad mc_gammagamma.py

Let's calculate Z peak from reconstructed b-jets. Jets are reconstructed using the Durham kT algorithm with ycut=0.05. This time we will download Z→ bbar sample. Look at gev250ee_pythia6_zpole_bbar. We assume pT(jet)>20 GeV.

hs-get gev250ee_pythia6_zpole_bbar%rfull001 gev250ee_pythia6_zpole_bbar  2 4 # download 4 files
../fpad mc_jets.py

No any optimization for jet reconstruction was used. Consider other approaches to make more realistic dijet mass.

Let's calculate Z peak from two Durham jets as in the previous example, but using Z→tau+tau sample. Should see shift from 90 GeV (neutrino).

hs-get gev250ee_pythia6_zpole_tautau%rfull001 gev250ee_pythia6_zpole_tautau 2 50 # download 50 files
../fpad mc_tautau.py

No any optimization for jet reconstruction was used. Consider other approaches to make more realistic tau reconstruction..

Let's calculate Higgs peak from reconstructed leptons in the channel H(125)→ ZZ* → 4L (electrons and muons). We will use particle flow objects to reconstruct and identify electrons and muons. This time we will download Higgs→ 4 lepton sample. Look at gev250ee_pythia6_higgs_zz_4l.

hs-get gev250ee_pythia6_higgs_zz_4l%rfull001 gev250ee_pythia6_higgs_zz_4l 2 100 # download 100 files in 2 threads
../fpad mc_higgs_zz.py

You can also look at some exotic configurations. For example, let's reconstruct Higgs at 100 TeV using SLIC:

hs-get tev100_pythia6_higgs_zz_4l%rfull001 tev100_pythia6_higgs_zz_4l # get 100 TeV sample
../fpad mc_higgs_zz_100tev.py

This example uses the Jade algorithm to force 2 jets, and uses H→ bbar sample:

hs-get gev250ee_pythia6_higgs_bbar%rfull001 gev250ee_pythia6_higgs_bbar  2  15 
../fpad mc_higgs_bbar.py

This example shows the jet energy resolution in 2 pT(truth) regions. It is based on inclusive jet sample gev250ee_pythia6_qcd_all. We use Durham jets with pT(truth)>20 GeV. Jet are constructed from PFA objects. Truth jet and reco jets are matched using dR<0.05 in phi and rapidity.

One can also visualize calorimter-level objects, such as hits. For example, here are calorimeter hits for Z→ bbar event (only one event is shown)

../fpad mc_hits3D.py # hits in 3D for 1 events
../fpad mc_hits.py   # phi distribution of hits

Location of calorimeter hits for 1 event:

Phi angle of calorimeter hits for all events:

Use the HepSim manual. You do not need to “hs-tools” since it is already installed. You can list and download files for Z to e+e- automatically as

hs-ls  gev250ee_pythia6_zpole_ee%rfull001 # list all files
hs-get gev250ee_pythia6_zpole_ee%rfull001 # download all files (can be large sample!)

Here “gev250ee_pythia6_zpole_ee” is the dataset name, and “rfull001” is the reconstruction tag.

To find event samples with full simulations, use the full search and the string “rfull”. For example, use the http://atlaswww.hep.anl.gov/hepsim/list.php?find=rfull link that lists all samples that have been processed with a full detector simulation.

The standard set of containers is available from the LCIO files posted on HepSim. Read Manual. The API is described in LCIO Java API description.

Look the Java API definition of the needed objects in org.lcsim.lcio

BeamCalHits
CalorimeterHitRelations
EM_BARREL
EM_ENDCAP
EcalBarrelHits
EcalEndcapHits
HAD_BARREL
HAD_ENDCAP
HcalBarrelHits
HcalEndcapHits
HelicalTrackHitRelations
HelicalTrackHits
HelicalTrackMCRelations
LumiCalHits
MCParticle
MUON_BARREL
MUON_ENDCAP
MuonBarrelHits
MuonEndcapHits
PandoraPFOCollection
ReconClusters
SiTrackerBarrelHits
SiTrackerEndcapHits
SiTrackerForwardHits
SiVertexBarrelHits
SiVertexEndcapHits
StateAtECal
StateAtEnd
StateAtStart
TKR_RawTrackerHits
TKR_TrackerHits
Tracks
VXD_RawTrackerHits
VXD_TrackerHits

The Monte Carlo files located in rfull001 link are done using the sidloi3 detector: http://lcsim.org/detectors/sidloi3.html. The XML geometry is given in http://lcsim.org/detectors/sidloi3.zip.

The SiD detector is shown here

You can view detector geometries posted in http://lcsim.org/detectors/ as this. Download zip file and extract it. Find file “compact.xml”, and then run geometry converter as:

./gconverter -o heprep compact.xml  sidloi3.heprep

Now you can open this file in the Jas and view it. Look at other options by running “./gconverter_gui”.

Here are a few links to the description of this detector.

SiD detector description

SiD detector description (older version)

FPadSoft uses histogram packages supported by both DMelt (community edition) or JAIDA (FreeHep). DMelt provides programming API similar to PyROOT and with classes named conveniently to reduce code verbosity.

Here are a few most common classes:

• HPlot - canvas to show X-Y data and histograms in 2D
• HPlot3D - canvas to show X-Y-Z data and histograms in 3D
• H1D - 1D histogram
• H2D - 2D histogram
• P1D - X-Y container with support of 2-level errors

The main canvas to show histograms H1D and data points P1D is HPlot. To process scripts in a background without a pop-up HPlot, use method “visible(False)”, and set sys.exit(0) at the end of the scripts. You can also use the JAIDA to make histograms (Histogram1D or Histogram2D). In addition, data are saved in the form of XML (with the extension “.jdat”) files. Look the manual DatMelt IO.

• PromcUtil convenient method to fill arrays with particles from ProMC files
• LParticle a HEP particle with the Lorentz transformations
• FastParticle a HEP particles with precomputed Et2,Eta,Phi for jet algorithms.
• Physics vectors typical HEP physics vectors the Lorentz transformations
• JetN2 recommended kt-type jet clustering ng algorithms (kT, anti-kT, CA) implemented in Java using N^2 approach, similar to the FastJet algorithm. Recommended for hadron collisions
• SCJet traditional kt-type jet clustering algorithms (kT, anti-kT) for pp implemented in Java using N^3 approach (slow)
• Jets and event shapes traditional jet algorithms and event shapes for e+e- from FreeHep (Geneva, Jade, Durham jets)

Java implementation of the longitudinally invariant kT and anti-kT clustering algorithms uses the E-scheme to combine particles (p1+p2) and Eta-Phi space (not Rapidity-Phi). Also, Cambridge/Aachen jets are supported. HepJet on github shows benchmarks of the Java implementation of the anti-KT with the original FastJet package.

You can build the standard kt-jets using PromcUtil, followed by the KTjet class.

To work with ProMC files, look at the ProMC Java API that is used to store data on the HepSim web page

• ProMCHeader for MC and ProMCHeader for NLO
• Event for MC and Event for NLO
• Particles for MC and Particles for NLO
• ProMCStat for MC and ProMCStat for NLO

It is simplified compared to full MC simulations, and also includes additional arrays “idata” and “fdata” to store information on event weights and uncertainties.

The project uses the community edition of DMelt project and the FreeHEP Java Libraries.

If you need to read LCIO files in C++ code with ROOT/FastJet, use this example package:

wget http://atlaswww.hep.anl.gov/hepsim/soft/lcio-cpp.tgz -O - | tar -xz;
cd lcio-cpp; make 

It will compile “example.cpp” file linking FastJet package. Look at README file to see how to install the “LCIO” package required by this example. Your LCIO“ files from HepSim should be in the directory “data”.

You can run over the original truth-level files from HepSim:

 wget http://mc.hep.anl.gov/asc/hepsim/events/ee/250gev/pythia6_zpole_tautau/macros/pythia6_zpole_tautau.py
../fpad pythia6_zpole_tautau.py

This example prints the pT distribution of e, mu, taus. Typically, HepSim contains validation files with the extension py that can check the validity of truth-level samples. See the description in HepSim documentation and HepSim API

You can run Jas+Wired to visualize the simulated events. Run this program included in fpadsoft as:

./fjas

Then copy the detector geometry file to the local directory where the file “jas” is:

wget http://atlaswww.hep.anl.gov/hepsim/soft/detectors/sidloi3_heprep.tgz -O - | tar -xz;

This will create a directory “detector”. This detector corresponds to “rfull001” tag used for the reconstruction of pythia6_zpole_ee (Z→e+e-).

Now we can visualize the detector as [File]-[Open data source]-[HepRep] XML and select the file “detector/sidloi3/sidloi3.heprep”. This is how to do this using the command line:

./fjas detector/sidloi3/sidloi3.heprep

You will see the detector layout:

Now, we will read the event: Open any *.slcio file you copied from HepSim as [File]-[Open data source]-[LCIO] file. Then click a small button [Go] (top menu bar). It will process events. Then select again [File]-[New]-[Wired 4 view]. You will get an image in the Wired4 display as this:

Now press [Go] again to look at next event.

If you want to see how data records are organized inside the slcio file, do this [File]-[New]-[LCSim Event browser]

This collection of tools for future collider studies was developed at ANL (S.Chekanov, [email protected]) in collaboration with Jan Strube (PNNL) ([email protected]) and Ashutosh Kotwal (Duke U) [email protected]. The Java part of the simulator for the linear collider was designed N. Graf, J. McCormick, T.Jonson

For some help with SLIC, read:

https://confluence.slac.stanford.edu/display/ilc/ILC+Detector+Simulation+FAQ

https://confluence.slac.stanford.edu/display/ilc/LCSim+Tutorials

~~REFNOTES~~

— Sergei Chekanov 2015/10/08 09:31