Pluto

Pluto adminuser


Pluto
A Monte Carlo simulation tool for hadronic physics

 

The package at a glance

Pluto is a simulation framework for heavy ion and hadronic-physics reactions. It provides a library of C++ classes such as particles, reactions but also interface classes. The reactions can be set up with a few lines of ROOT macro code without detailed knowledge of programming. Different physics models can be selected via a manager class, while experts can use various template classes (see latest tutorials) for defining and attaching their own models. A build-in scripting language (see full reference manual) which was in particular designed for this purpose can handle in-line histogram filling, event filtering and particle modifications. The input and output file format can be adjusted, and an Unigen and FAIRROOT interface allows for a smooth inclusion in 3rd party code.

Discussion and Support

Download (Pluto6)

Non-HADES users are kindly asked to cite the package as described below.

Latest bugfix release: Version 6.02 of 11/07/2023

Latest stable release: Version 6.01 of 11/06/2018

Older release: Version 6.00 of 17/05/2017

The development version is available via Github and GSI Gitlab

 

Publications

Citation rules for users

For version 5+6 (in general) cite:

Pluto: A Monte Carlo Simulation Tool for Hadronic Physics. [Inspire]

If you use the new interface you can cite the paper which deals more with technical aspects:

Design of the Pluto Event Generator. [Inspire]

If you use the new bremsstrahlung and Delta descriptions:

A versatile method for simulating pp -> ppe+e- and dp -> pne+e-p_spec reactions. [Inspire]

Other documents

Related Topics

Contact

A snapshot of Pluto

A snapshot of Pluto adminuser

What?

Pluto is a collection of C++ classes, adding up to the framework of a simulation package for hadronic-physics reactions.  It is launched interactively from within the ROOT environment, and makes use of ROOT only, without requiring additional packages. The focus is on streamlining particle generators by providing the tools to set up and manipulate particles, reaction channels, and complex reactions, as well as apply experimental filters on the reaction products, such as geometrical acceptance and kinematical conditions. Typical simulations may be executed with a few lines of input, with no expertise required on the part of the user. The output  may be analyzed on line, or further processed with GEANT. The package includes models for resonance and Dalitz decays, resonance spectral functions with mass-dependent widths, and anisotropic angular distributions for selected channels. A decay-manager interface enables multi-step ("cocktail") calculations. An extensive particle data base is available, with capabilities to support up to 999 particles, including user-defined ones. Particle properties and decay modes are included in the data base. Thermal distributions are implemented, enabling multi-hadron decays of hot fireballs.


The general philosophy of Pluto is that on one hand the users should be able to drive the package in a very easy way, but on the other hand are allowed to customize it without any restiction. This means that the user can gain control to add new decays/paticles among with new models up to the writing of plugins/mods.  

Figure 1:  PLUTO structure

pluto_at_a_glance.png (88128 bytes)

The structure and design of Pluto is sketched in the figure above: the orange boxes show the user classes to set up and handle reaction (and decay channels), they start and control the event loop. The yellow box is the interface for accessing the particle stream while the event loop is running, providing a lot of useful features. The boxes shaded in blue represent the data base for the particles and dacays among with a user interface for customization. The light blue boxes are the distribution interface and the physics models, the first one allows to add and/or select physics cases, the models can be either build-in models and runtime replacements. This area of Pluto works even outside the event loop for the calculation of parameters (mass distributions, decay widths,...)

Why?

Pluto is designed as an experimentalist's tool (not only) for the HADES Collaboration. It standardizes simulations by providing a common platform that is accessible via the analysis environment (ROOT), with a straightforward user interface that does not inhibit non-experts in simulations. It is a modular and reusable package that can support additional features. A common tool for simulations may facilitate acceptance studies for the detectors comprising the HADES spectrometer, and make feasible comparisons of results obtained by different detector groups. At the same time it is a high-level analysis tool, that, after tracking and particle identification, is useful in the recognition of the physical processes in experimental spectra.

How?

To illustate a simulation with Pluto, a proton-proton reaction with a kinetic energy T=3.5 GeV is considered as an example, the decay steps (channels ) are created with the decay parser in background. In the conventions of Pluto a Channel is a step in a reaction, and a Reaction is a complete process. The output will be written to the file "eta_dalitz", which might be further analyzed. To show some the (optional) features, a TNtuple, a filter and a histrogram are created in addition. A Filter applies physical constraints on any Particle of a Reaction, before the event tree is written to disk. In our case, an event is accepted if both the electron and the positron are produced with polar angles in the range of 18 to 85 degree. The used batch language is based on the ROOT TFormula class, combined with some additional features like the creation of (composite) particles, the access to their getter methods and conditional executions.

The sequence shown below, executed from an interactive ROOT session on a typical linux PC, generates 100k events in around 10 seconds (CPU time). Output is stored for the decay products in a ROOT files (ASCII optional for use as input to GEANT). Some comments sketch the actions induced by the command lines. Details may be found in the Pluto tutorials. 


//Create a file for the NTuple: 
TFile *f = new TFile("ntuple.root", "RECREATE"); 
//Create an NTuple with several variables: 
TNtuple *ntuple = new TNtuple("ntuple", "data from Pluto events", "eta_px:eta_py:eta_pz:opang"); 
//Create a control histo: 
TH1F * histo1 = new TH1F ("histo1","dilepton mass with opening angle < 9deg",100,0.0,0.7); //Define the reaction: pp -> pp eta at 3.5 kinetic beam energy: 
PReaction my_reaction("3.5","p","p", "p p eta [g dilepton [e+ e-]]","eta_dalitz"); 
//Inline calculating of a variable (here: Theta of e+ in degree): 
my_reaction.Do("theta_ep = ([e+]->Theta() * 180.)/TMath::Pi()"); 
//...same for e-: my_reaction.Do("theta_em = ([e-]->Theta() * 180.)/TMath::Pi()"); 
//Example of a reaction filter: Put a # in front of the variable name: my_reaction.Do("#filter = 1; if theta_ep < 18 || theta_ep > 85 || theta_em < 18 || theta_em > 85; #filter = 0"); 
//Calculate the variables for the NTuple: my_reaction.Do("eta_px = [eta]->Px() ; eta_py = [eta]->Py() ; eta_pz = [eta]->Pz();"); 
//Opening angle in lab frame: 
my_reaction.Do("opang = [e+]->Angle([e-])"); 
//The NTuple should be written here: 
my_reaction.Output(ntuple); 
//The (conditional) histogram. Prepare the axis (_x) 
my_reaction.Do(histo1,"if opang &g (9./180.)*TMath::Pi(); _x = ([e+] + [e-])->M()"); 
//Run event loop: 
my_reaction.Loop(100000); 

 

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