Pluto extensions to ROOT functions

Pluto extensions to ROOT functions adminuser

This feature will come with Pluto 5.41

What?

The Pluto functions (at the moment only for the 2-dimensional case) offer an extension to the ROOT functions TF1/TF2/TF3. They combine the classical ROOT functions with the Pluto batch scripting which itself connects with objects like TH1/TH2/TH3 and TGraph/TGraph2D. It therefore allows to combine histogram(s) with graphs and calculations. The number of combinations which are possible by these features is almost endless. Therefore the following examples can only sketch the possibilites.

The problem

The Pluto functions should serve as a general interface for Pluto models whereever 2rd party data should be included. One common example is the class PAngularDistributions, where one can add TF1/TF2, or a TGraph. While keeping this methods to ensure backward compatibility, the aim is to provide a more general interface.

The solution

The Pluto functions are costructed like the ROOT functions with the difference that no pointer to a function or a TFormula is used. The latter feature is already included in the Pluto script language, which is based on TFormula. The function is replaced by one (or more) methods which can be optionally extended with the histogram of graph objects. The axes of the function can be read via the variables _x, _y and _z, and the output _f as the function value must be provided. The access to the histogram/graph object is done via the Eval command.

All examples are based on this macro which contains some dummy histograms and TGraphs.

Interface to a TGraph2D

PF2 * only_tgraph = new PF2("Only TGraph2D", 0, 0.8, 0, 0.8); 
only_tgraph->Add(gra, "_f = Eval(_x,_y)");

 

Mixing a histogram with a graph

PF2 * tgraph_and_hist1 = new PF2("TGraph2D mixed with a TH1", 0, 0.8, 0, 0.8);
tgraph_and_hist1->Add(gra, "_f = Eval(_x,_y)"); 
tgraph_and_hist1->Add(hist1, "if (_x < 0.3) _f = Eval(_y)");

Mixing a histogram with a graph and some dummy calculations (here a rotation)

PF2 * tgraph_and_hist1a = new PF2("TGraph2D mixed with a TH1 and some dummy calculations", 0, 0.8, 0, 0.8); 
tgraph_and_hist1a->Add(gra, "_f = Eval(_x,_y)"); 
tgraph_and_hist1a->Add("my_x = _x - _y; my_y = (_x + _y) * 0.5; ");
tgraph_and_hist1a->Add(hist1, "if (my_x > 0.1 && my_x < 0.35) _f = Eval(my_y)");

Merger of a histogram with a graph (here a multiplication)

PF2 * tgraph_and_hist2 = new PF2("TGraph2D merged with a TH2", 0, 0.8, 0, 0.8); 
tgraph_and_hist2->Add(gra, "_f = Eval(_x,_y)"); 
tgraph_and_hist2->Add(hist2, "_f = _f * Eval(_x, _y)");

Scripted inline particle filter

Scripted inline particle filter adminuser

What?

PlutoScript is an in-line scripting language which is designed to operate inside the event loop in order to modify particles and variables. Observables can be calculated on-the-fly and projected to histograms and ntuples. This feature allows also to connect data objects (like acceptance or resolution TH1,2,3 matrices) with the Pluto event loop and develop high-level detector description ROOT-files which can be distributed and expanded by Pluto users with one single command.

The problem

One very common mission in event generation is to filter the produced events with an acceptance matrix and to smear the particle momenta with the detector resolution. The normal way is that for this purpose a collaboration provides a software package which included data (matrices) and software (handling of the matrices and smearing). But sometimes also ROOT macros together with ROOT files are provided. This means that the ROOT file and the analysis macro should be provided in a common package. This is unconvinient and can be even a source of mistakes (inconsistencies). Moreover, if the file format or the meaning of the axes of the matrices changes, also the analysis macro has to changed. Also, multi-particle correlations can be hardly described with matrices.

The solution

Starting with Pluto v5.35 the packing of ROOT objects with PlutoScript is possible. In order to fulfill the above-mentioned aim the script language provides the following features:

  • One can call all methods (also Set-methods) of the PParticle-object.
  • One can access the PUtilsREngine to do random sampling (flat, Gaus, ...)
  • The script provides loops, jumps and sub-programs features.
  • The "packed" ROOT file can be attached to the data base, script and matrices are extracted automatically.

Example

Download our dummy detector and put the ROOT file in your working directory (where Pluto is installed, e.g. the macro dir)

//Load and extract the demo detector:
makeDistributionManager()->Unpack("pluto_demo_filter.root")
//Setup the reaction as usual:
PReaction my_reaction("3.5","p","p", "p p eta [g dilepton [e+ e-]]","eta_dalitz");
//Run the event loop:
my_reaction.Loop(100000);

Each filter is dumping a readme during extraction. Since a filter can be configured (by means of global variables), the readme should provide information about the handling of the filter file.

 

Examples for Pluto as a quick converter

Examples for Pluto as a quick converter adminuser

All examples can be combined and adapted.

Output of a reaction to ASCII

This can be done by the echo-command:

PReaction my_reaction("_T1=2.2","p","p","p p eta [dilepton [e+ e-] g]"); 
my_reaction.Output("eta_dalitz.lst","px=[eta]->Px(); py=[eta]->Py(); pz=[eta]->Pz(); echo $px,$py,$pz"); 
my_reaction.Print(); 
my_reaction.Loop(100);

Reading of an ASCII file and conversion to a TNtuple

Text files can be read with the readline-command. The pattern in the curly brackets is similar to scanf. The target variables are defined with the @-prefix.
Keep in mind that the variables in the ntuple are filled automatically if the branches match the defined variables by name.

TFile *f = new TFile("ntuple.root", "RECREATE"); 
TNtuple *ntuple = new TNtuple("ntuple", "data", "px:py:pz"); 
PReaction my_reaction;     
my_reaction.Input("eta_dalitz.lst", "readline{@px,@py,@pz};"); 
my_reaction.Output(ntuple); 
cout << my_reaction.Loop() << " events converted" << endl; 
ntuple->Write(); 
f->Close();

Reading of an ASCII file and projection of the content to a histogram

The text file can be read, new variables can be calculated and projected to histograms:

TH1F *pt = new TH1F("pt","",20,0,1); 
PReaction my_reaction;     
my_reaction.Input("eta_dalitz.lst","readline{@px,@py,@pz};"); 
my_reaction.Do(pt,"_x = sqrt(px*px + py*py)"); 
cout << my_reaction.Loop() << " events projected" << endl; 
pt->Draw();

Reading of an ASCII file and conversion to PParticles

PReaction my_reaction("eta_file");     
my_reaction.Input("eta_dalitz.lst","readline{@px,@py,@pz};"); 
my_reaction.Do("myeta = P3M(px,py,pz,eta.mass); myeta->SetID(eta.pid); push(myeta)"); 
cout << my_reaction.Loop() << " events converted" << endl;

Conversion of a TNtuple to ASCII

This is quite simple, as the branches in the input ntuple are used as variables.

TFile *f = new TFile("ntuple.root"); 
PReaction my_reaction;     
my_reaction.Input(ntuple); 
my_reaction.Output("eta.lst","echo $px,$py,$pz"); 
cout << my_reaction.Loop() << " events converted" << endl;

Conversion of an UniGen file to a TNtuple

This is a more complex example, how Pluto can be used to read UniGen files. UniGen has a lot of converters for (e.g.) UrQMD and HSD, therefore these files can be feed into Pluto by the UniGen input.

TFile *f = new TFile("dileptons.root", "RECREATE"); 
TNtuple *ntuple = new TNtuple("dileptons", "data", "ee_mass"); 
PReaction my_reaction;     
my_reaction.AddBulk(new PUniGenInput("eta_dalitz_unigen.root")); 
my_reaction.Do("ee_mass = ([e+] + [e-] )->M();"); 
my_reaction.Output(ntuple); 
cout << my_reaction.Loop() << " events converted" << endl; 
f->cd(); 
ntuple->Write(); 
f->Close();

*Version 5.37.4 (dev),

Download archive

Download archive adminuser

 

Version 6.01 of 11/06/2018

Version 6.00 of 17/05/2017

The following versions are only available inside GSI

Version 5.02 of 03/07/2007

Class Index Release notes

Version 5.11 of 11/11/2007

Class Index Tutorials Release notes

Version 5.12 of 27/11/2007

Class Index Tutorials Release notes

Version 5.13 of 29/01/2008
(branched)

Class Index Tutorials Release notes

Version 5.14 of 18/02/2008 (branched)

Class Index Tutorials Release notes

Version 5.14.1 of 19/02/2008
(branched, last 5.1x version)

Class Index Tutorials Release notes

Version 5.21 of 21/01/2009

Class Index Tutorials Roadmap Release notes Contributing authors References

Version 5.22 of 27/02/2009

Class Index Tutorials Roadmap Release notes Contributing authors References

Version 5.23 of 17/04/2009

Class Index Tutorials Roadmap Release notes Contributing authors References

Version 5.24 of 18/05/2009

Class Index Tutorials Roadmap Release notes Contributing authors References

Version 5.25 of 12/06/2009

Class Index Tutorials Roadmap Release notes Contributing authors References

Version 5.25.1 of 29/06/2009
(last 5.2x version)

Class Index Tutorials Roadmap Release notes Contributing authors References

Version 5.31 of 28/09/2009

Class Index Tutorials Roadmap Release notes Contributing authors References
News:

  • Many plugins (some of them are still in development)
  • New makefile
  • Some changes for quasi-free reactions
  • Changed standard seed to the systime

Known problems:

  • pd → He η does not work
  • Bulk decay sometimes overwrites parent

Version 5.32 of 14/10/2009

Class Index Tutorials Roadmap Contributing authors References
News: (for details see Release notes)

  • Adding instream particles via batch command (see new demo macro)
  • General purpose file format for acceptance filters (demo macro still missing)
  • Added more strangeness particles
  • New aliases (e.g. Delta0(1232) for D0)
  • Added fairroot plugin (see README)

Known problems (fixed in 5.33):

  • Bulk classes in the pdm are not working
  • Embedded particle still shows problems

Version 5.33 of 04/11/2009

Class Index Tutorials Roadmap Contributing authors References

Version 5.34 of 19/01/2010

Class Index QA-plots Tutorials Contributing authors References
News: (for details see Release notes)

  • Many plugins (e.g. pn scattering)

Version 5.35 of 09/07/2010

Class Index QA-plots Tutorials Contributing authors References
News: (for details see Release notes)

  • Many plugins (e.g. pn scattering)
  • Changed standard seed to the systime
  • N-body phase space (N>3) with 1 unstable hadron
  • PlutoScript has been finalized

Version 5.36 of 24/09/2010

Class Index QA-plots Tutorials Contributing authors References
News: (for details see Release notes)

  • Correct phase space for Resonance to N + gamma
  • Moved some variables to batch space
  • Added demo FF models in eta_decays
  • Fixed some bugs, in particular the slow omega bug in the fireball macro

Version 5.37 of 04/01/2011

Class Index QA-plots Tutorials Contributing authors References
News: (for details see Release notes)

  • Collider experiments are working
  • New reaction parser (supports beam tilt)
  • Fixed some severe problems with PBatch
  • Link from data base values to PBatch
  • Added PSimpleVMDFF with customized vmd-equations
  • Added mass correlator to genbod
  • Finished basic work for the rare eta decays

Version 5.38 of 15/07/2011

Class Index QA-plots Tutorials Contributing authors References
News: (for details see Release notes)

  • PDalitzDistribution can use histograms as input
  • Batch script enhanced by multi-purpose ASCII input (readline command) and output (echo)
  • New plugin: pdg code and unigen input (reading UniGen events, see converter link above)
  • Added more Dalitz decays of resonances
  • Standard dilepton rho shape changed to hard cut at 2-pion threshold

Version 5.40 of 03/11/2011

Class Index QA-plots Tutorials
News: (for details see Release notes)

  • Added PAnyDistribution which works as a general purpose rejection distribution using batch script equations.
  • Fixed bug: _w was not written back to the stream particles.
  • Added build-in ->GetBeam() and ->GetTarget() methods in PBatch

Version 5.41 of 13/11/2012

Class Index QA-plots Tutorials

News: (for details see Release notes)

  • Added new resonances in pdg-plugin
  • Added SetRapidityDistribution(TF1 *) to PFireball
  • Added Set/GetEnhanceChannelBR which allows to scale the "branching ratio" for bulk decays.
  • Added else command for the script language
  • Added new PScatterCrossSection class for q vs. cos(theta) sampling
  • Added PF1/PF2/PF3 Pluto functions.

Version 5.42 of 13/03/2013

Class Index * QA-plots * Tutorials

News (since v5.41): (for details see Release notes)

  • Bug fixes

Version 5.43 of 21/07/2015

Class Index * QA-plots * Tutorials

News (since v5.42): (for details see Release notes)

  • Bug fixes, in particular:
    • Fixed bug for thermal photons, and enabled 1-dimension thermal sampling functions in PFireball.
    • Fixed bug in omega -> mu+mu-pi0 decay
  • Added bulk interface to PChannelsSee demo macro.
  • Added PDensityMatrix to convert densities (from ASCII file, like HSD) to particles. See demo macro.
  • Added plugin for transport simulation of particles through a beamline including beam detectors
  • Added GetRandom(X,Y) methods

Version 5.44.4 of 17/05/2017

Class Index * QA-plots * Tutorials

News (since v5.43): (for details see Release notes)

  • Bug fixes only

Version 6.00 of 17/05/2017

Class Index * QA-plots * Tutorials

News (since v5.xx): (for details see Release notes)

  • Changed to ROOT6
  • Switched to cmake
  • New directory structure and code cleanup