In late 1994, we decided to learn and investigate Object Oriented programming and C++ to better judge the suitability of these relatively new techniques for scientific programming. We knew that there is no better way to learn a new programming environment than to use it to write a program that can solve a real problem. After a few weeks, we had our first histogramming package in C++. A few weeks later we had a rewrite of the same package using the, at that time, very new template features of C++. Again, a few weeks later we had another rewrite of the package without templates since we could only compile the version with templates on one single platform using a specific compiler. Finally, after about four months we had a histogramming package that was faster and more efficient than the well-known FORTRAN based HBOOK histogramming package. This gave us enough confidence in the new technologies to decide to continue the development. Thus was born ROOT. Since its first public release at the end of 1995, ROOT has enjoyed an ever-increasing popularity. Currently it is being used in all major High Energy and Nuclear Physics laboratories around the world to monitor, to store and to analyse data. In the other sciences as well as the medical and financial industries, many people are using ROOT. We estimate the current user base to be around several thousand people. In 1997, Eric Raymond analysed in his paper 「The Cathedral and the Bazaar」 the development method that makes Linux such a success. The essence of that method is: 「release early, release often and listen to your customers」. This is precisely how ROOT is being developed. Over the last five years, many of our 「customers」 became co-developers. Here we would like to thank our main co-developers and contributors:
Masaharu Goto wrote the C++ interpreter CINT that was an essential part of ROOT before ROOT 6. Despite being 8 time zones ahead of us, we have the feeling he has been sitting in the room next door since 1995.
Andrei and Mihaela Gheata (Alice collaboration) are co-authors of the ROOT geometry classes and Virtual Monte-Carlo. They have been working with the ROOT team since 2000.
Olivier Couet, who after a successful development and maintenance of PAW, has joined the ROOT team in 2000 and has been working on the graphics sub-system.
Ilka Antcheva has been working on the Graphical User Interface classes. She is also responsible for this latest edition of the Users Guide with a better style, improved index and several new chapters (since 2002).
Bertrand Bellenot has been developing and maintaining the Win32GDK version of ROOT. Bertrand has also many other contributions like the nice RootShower example (since 2001).
Valeriy Onoutchin has been working on several ROOT packages, in particular the graphics sub-system for Windows and the GUI Builder (since 2000).
Gerri Ganis has been working on the authentication procedures to be used by the root daemons and the PROOF system (since 2002).
Maarten Ballintijn (MIT) is one of the main developers of the PROOF sub-system (since 1995).
Valeri Fine (now at BNL) ported ROOT to Windows and contributed largely to the 3-D graphics. He is currently working on the Qt layer of ROOT (since 1995).
Victor Perevoztchikov (BNL) worked on key elements of the I/O system, in particular the improved support for STL collections (1997-2001).
Nenad Buncic developed the HTML documentation generation system and integrated the X3D viewer inside ROOT (1995-1997).
Suzanne Panacek was the author of the first version of this User's Guide and very active in preparing tutorials and giving lectures about ROOT (1999-2002).
Axel Naumann has been developing further the HTML Reference Guide and helps in porting ROOT under Windows (cygwin/gcc implementation) (since 2000).
Anna Kreshuk has developed the Linear Fitter and Robust Fitter classes as well as many functions in TMath, TF1, TGraph (since 2005).
Richard Maunder has contributed to the GL viewer classes (since 2004).
Timur Pocheptsov has contributed to the GL viewer classes and GL in pad classes (since 2004).
Sergei Linev has developed the XML driver and the TSQLFile classes (since 2003).
Stefan Roiser has been contributing to the reflex and cintex packages (since 2005).
Lorenzo Moneta has been contributing the MathCore, MathMore, Smatrix & Minuit2 packages (since 2005).
Wim Lavrijsen is the author of the PyRoot package (since 2004).
Further we would like to thank all the people mentioned in the
$ROOTSYS/README/CREDITS file for their contributions, and finally, everybody who gave comments, reported bugs and provided fixes.
Rene Brun & Fons Rademakers
Geneva, July 2007
In the mid 1990』s, René Brun and Fons Rademakers had many years of experience developing interactive tools and simulation packages. They had lead successful projects such as PAW, PIAF, and GEANT, and they knew PAW the twenty-year-old FORTRAN libraries had reached their limits. Although still very popular, these tools could not scale up to the challenges offered by the Large Hadron Collider, where the data is a few orders of magnitude larger than anything seen before.
At the same time, computer science had made leaps of progress especially in the area of Object Oriented Design, and René and Fons were ready to take advantage of it.
ROOT was developed in the context of the NA49 experiment at CERN. NA49 has generated an impressive amount of data, around 10 Terabytes per run. This rate provided the ideal environment to develop and test the next generation data analysis.
ROOT was, and still is, developed in the 「Bazaar style」, a term from the book 「The Cathedral and the Bazaar」 by Eric S. Raymond. It means a liberal, informal development style that heavily relies on the diverse and deep talent of the user community. The result is that physicists developed ROOT for themselves; this made it specific, appropriate, useful, and over time refined and very powerful. The development of ROOT is a continuous conversation between users and developers with the line between the two blurring at times and the users becoming co-developers.
When it comes to storing and mining large amount of data, physics plows the way with its Terabytes, but other fields and industry follow close behind as they acquiring more and more data over time. They are ready to use the true and tested technologies physics has invented. In this way, other fields and industries have found ROOT useful and they have started to use it also.
In the bazaar view, software is released early and frequently to expose it to thousands of eager co-developers to pound on, report bugs, and contribute possible fixes. More users find more bugs, because they stress the program in different ways. By now, after ten years, the age of ROOT is quite mature. Most likely, you will find the features you are looking for, and if you have found a hole, you are encouraged to participate in the dialog and post your suggestion or even implementation on the ROOT forum.
If you have a question, it is likely that it has been asked, answered, and stored in the ROOT Forum. Please use the search engine to see if your question has already been answered before posting a topic in the Forum.
You can access the ROOT forum at: https://root-forum.cern.ch.
Several authors wrote this book and you may see a 「change of voice」 from one chapter to the next. We felt we could accept this in order to have the expert explain what they know best. If you would like to contribute a chapter or add to a section, please contact firstname.lastname@example.org. We count on you to send us suggestions on additional topics or on the topics that need more documentation. Please send your comments, corrections, questions, and suggestions to the
rootdoc list: email@example.com
We attempt to give the user insight into the many capabilities of ROOT. The book begins with the elementary functionality and progresses in complexity reaching the specialized topics at the end. The experienced user looking for special topics may find these chapters useful: see 「Networking」, 「Writing a Graphical User Interface」, 「Threads」, and 「PROOF: Parallel Processing」.
We tried to follow a style convention for the sake of clarity. The styles in used are described below.
To show source code in scripts or source files:
To show the ROOT command line, we show the ROOT prompt without numbers. In the interactive system, the ROOT prompt has a line number (
root); for the sake of simplicity, the line numbers are left off.
Italic bold monotype font indicates a global variable, for example
When a variable term is used, it is shown between angled brackets. In the example below the variable term <library> can be replaced with any library in the
ROOT is an object-oriented framework aimed at solving the data analysis challenges of high-energy physics. There are two key words in this definition, object oriented and framework. First, we explain what we mean by a framework and then why it is an object-oriented framework.
Programming inside a framework is a little like living in a city. Plumbing, electricity, telephone, and transportation are services provided by the city. In your house, you have interfaces to the services such as light switches, electrical outlets, and telephones. The details, for example, the routing algorithm of the phone switching system, are transparent to you as the user. You do not care; you are only interested in using the phone to communicate with your collaborators to solve your domain specific problems.
Programming outside of a framework may be compared to living in the country. In order to have transportation and water, you will have to build a road and dig a well. To have services like telephone and electricity you will need to route the wires to your home. In addition, you cannot build some things yourself. For example, you cannot build a commercial airport on your patch of land. From a global perspective, it would make no sense for everyone to build their own airport. You see you will be very busy building the infrastructure (or framework) before you can use the phone to communicate with your collaborators and have a drink of water at the same time. In software engineering, it is much the same way. In a framework, the basic utilities and services, such as I/O and graphics, are provided. In addition, ROOT being a HEP analysis framework, it provides a large selection of HEP specific utilities such as histograms and fitting. The drawback of a framework is that you are constrained to it, as you are constraint to use the routing algorithm provided by your telephone service. You also have to learn the framework interfaces, which in this analogy is the same as learning how to use a telephone.
If you are interested in doing physics, a good HEP framework will save you much work. Next is a list of the more commonly used components of ROOT: Command Line Interpreter, Histograms and Fitting, Writing a Graphical User Interface, 2D Graphics, Input/Output , Collection Classes, Script Processor.
There are also less commonly used components, as: 3D Graphics, Parallel Processing (PROOF), Run Time Type Identification (RTTI), Socket and Network Communication, Threads.
The benefits of frameworks can be summarized as follows:
Less code to write - the programmer should be able to use and reuse the majority of the existing code. Basic functionality, such as fitting and histogramming are implemented and ready to use and customize.
More reliable and robust code - the code inherited from a framework has already been tested and integrated with the rest of the framework.
More consistent and modular code - the code reuse provides consistency and common capabilities between programs, no matter who writes them. Frameworks make it easier to break programs into smaller pieces.
More focus on areas of expertise - users can concentrate on their particular problem domain. They do not have to be experts at writing user interfaces, graphics, or networking to use the frameworks that provide those services.
Object-Oriented Programming offers considerable benefits compared to Procedure-Oriented Programming:
Encapsulation enforces data abstraction and increases opportunity for reuse.
Sub classing and inheritance make it possible to extend and modify objects.
Class hierarchies and containment containment hierarchies provide a flexible mechanism for modeling real-world objects and the relationships among them.
Complexity is reduced because there is little growth of the global state, the state is contained within each object, rather than scattered through the program in the form of global variables.
Objects may come and go, but the basic structure of the program remains relatively static, increases opportunity for reuse of design.
To install ROOT you will need to go to the ROOT website at: http://root.cern.ch/root/Availability.html. You have a choice to download the binaries or the source. The source is quicker to transfer since it is only ~22 MB, but you will need to compile and link it. The binaries compiled with no debug information range from ~35 MB to ~45 MB depending on the target platform.
The installation and building of ROOT is described in Appendix A: Install and Build ROOT. You can download the binaries, or the source. The GNU g++ compiler on most UNIX platforms can compile ROOT.
Before downloading a binary version make sure your machine contains the right run-time environment. In most cases it is not possible to run a version compiled with, e.g., gcc4.0 on a platform where only gcc 3.2 is installed. In such cases you'll have to install ROOT from source.
ROOT is currently running on the following platforms: supported platforms
GNU/Linux x86-32 (IA32) and x86-64 (AMD64)(GCC,Intel/icc, Portland/PGCC,KAI/KCC)
Intel Itanium (IA64) GNU/Linux (GCC, Intel/ecc, SGI/CC)
FreeBSD and OpenBSD (GCC)
HP HP-UX 10.x (IA32) and 11 (IA64) (HP CC, aCC, GCC)
IBM AIX 4.1 (xlC compiler, GCC)
Sun Solaris for SPARC (SUN C++ compiler, GCC)
Sun Solaris for x86 (SUN C++ compiler, KAI/KCC)
Compaq Alpha (GCC, KAI/KCC, DEC/CXX)
SGI Irix 32 and 64 bits (GCC, KAI/KCC, SGI C++ compiler)
Windows >= 95 (Microsoft Visual C++ compiler, Cygwin/GCC)
MacOS X PPC, x86-32, x86-64 (GCC, Intel/ICC, IBM/xl)
PowerPC with GNU/Linux and GCC, Debian v2
PowerPC64 with GNU/Linux and GCC
ARM with GNU/Linux and GCC
Now after we know in abstract terms what the ROOT framework is, let us look at the physical directories and files that come with the ROOT installation. You may work on a platform where your system administrator has already installed ROOT. You will need to follow the specific development environment for your setup and you may not have write access to the directories. In any case, you will need an environment variable called
ROOTSYS, which holds the path of the top ROOT directory.
ROOTSYS directory are examples, executables, tutorials, header tutorials files, and, if you opted to download it, the source is here. The directories of special interest to us are
include. The next figure shows the contents of these directories.
bin directory contains several executables.
||shows the ROOT splash screen and calls
||the executable that
||is the utility ROOT uses to create a class dictionary for Cling|
||a modified version of
||a script returning the needed compile flags and libraries for projects that compile and link with ROOT|
||a small daemon used to authenticate a user of ROOT parallel processing capability (PROOF)|
||the actual PROOF process, which is started by
||is the daemon for remote ROOT file access (see the
There are several ways to use ROOT, one way is to run the executable by typing
root at the system prompt another way is to link with the ROOT libraries and make the ROOT classes available in your own program.
Here is a short description of the most relevant libraries, the ones marked with a * are only installed when the options specified them.
libAsImage is the image manipulation library
libCling is the C++ interpreter (Cling)
libCore is the Base classes
libEG is the abstract event generator interface classes
libEGPythia is the Pythia5 event generator interface
libEGPythia6 is the Pythia6 event generator interface
libFitPanel contains the GUI used for fitting
libGed contains the GUI used for editing the properties of histograms, graphs, etc.
libGeom is the geometry package (with builder and painter)
libGpad is the pad and canvas classes which depend on low level graphics
libGraf is the 2D graphics primitives (can be used independent of libGpad)
libGraf3d is the 3D graphics primitives
libGui is the GUI classes (depend on low level graphics)
libGuiBld is the GUI designer
libGuiHtml contains the embedded HTML browser
libGX11 is the low level graphics interface to the X11 system
libGX11TTF is an add-on library to libGX11 providing TrueType fonts
libHbook is for interface ROOT - HBOOK
libHist is the histogram classes (with accompanying painter library)
libHtml is the HTML documentation generation system
libMatrix is the matrix and vector manipulation
libMathCore contains the core mathematics and physics vector classes
libMathMore contains additional functions, interfacing the GSL math library
libMinuit is the MINUIT fitter
libNet contains functionality related to network transfer
libNew is the special global new/delete, provides extra memory checking and interface for shared memory (optional)
libPhysics contains the legacy physics classes (TLorentzVector, etc.)
libPostscript is the PostScript interface
libProof is the parallel ROOT Facility classes
libPython provides the interface to Python
libRFIO is the interface to CERN RFIO remote I/O system.
libRGL is the interface to OpenGL.
libReflex is the runtime type database library used by Cling
libRint is the interactive interface to ROOT (provides command prompt)
libRIO provides the functionality to write and read objects to and from ROOT files
libRooFit is the RooFit fitting framework
libRuby is the interface to Ruby
libSpectrum provides functionality for spectral analysis
libThread is the interface to TThread classes
libTMVA contains the multivariate analysis toolkit
libTree is the TTree object container system
libTreePlayer is the TTree drawing classes
libTreeViewer is the graphical TTree query interface
The libraries are designed and organized to minimize dependencies, such that you can load just enough code for the task at hand rather than having to load all libraries or one monolithic chunk. The core library (
libCore.so) contains the essentials; it is a part of all ROOT applications. In the Figure 1-2 you see that libCore.so is made up of base classes, container classes, meta information classes, operating system specific classes, and the ZIP algorithm used for compression of the ROOT files.
The Cling library (
libCling.so) is also needed in all ROOT applications, and even by
libCore. A program referencing only
TObject only needs
libCling will be opened automatically. To add the ability to read and write ROOT objects one also has to load
libRIO. As one would expect, none of that depends on graphics or the GUI.
Library dependencies have different consequences; depending on whether you try to build a binary, or you just try to access a class that is defined in a library.
When building your own executable you will have to link against the libraries that contain the classes you use. The ROOT reference guide states the library a class is reference guide defined in. Almost all relevant classes can be found in libraries returned by
root-config -glibs; the graphics libraries are retuned by
root-config --libs. These commands are commonly used in
root-config instead of enumerating the libraries by hand allows you to link them in a platform independent way. Also, if ROOT library names change you will not need to change your Makefile.
A batch program that does not have a graphic display, which creates, fills, and saves histograms and trees, only needs to link the core libraries (
libTree. If ROOT needs access to other libraries, it loads them dynamically. For example, if the
TreeViewer is used,
libTreePlayer and all libraries
libTreePlayer depends on are loaded also. The dependent libraries are shown in the ROOT reference guide's library dependency graph. The difference between reference guide
libHistPainter is that the former needs to be explicitly linked and the latter will be loaded automatically at runtime when ROOT needs it, by means of the Plugin Manager. plugin manager
In the Figure 1-2, the libraries represented by green boxes outside of the core are loaded via the plugin manager plugin manager or equivalent techniques, while the white ones are not. Of course, if one wants to access a plugin library directly, it has to be explicitly linked. An example of a plugin library is
libMinuit. To create and fill histograms you need to link
libHist.so. If the code has a call to fit the histogram, the 「fitter」 will dynamically load libMinuit if it is not yet loaded.
plugin manager The Plugin Manager
TPluginManager allows postponing library dependencies to runtime: a plugin library will only be loaded when it is needed. Non-plugins will need to be linked, and are thus loaded at start-up. Plugins are defined by a base class (e.g.
TFile) that will be implemented in a plugin, a tag used to identify the plugin (e.g.
^rfio: as part of the protocol string), the plugin class of which an object will be created (e.g.
TRFIOFile), the library to be loaded (in short
libRFIO.so to RFIO), and the constructor to be called (e.g. 「
TRFIOFile()」). This can be specified in the
.rootrc which already contains many plugin definitions, or by calls to
When using a class in Cling, e.g. in an interpreted source file, ROOT will automatically load the library that defines this class. On start-up, ROOT parses all files ending on
.rootmap rootmap that are in one of the
Windows). They contain class names and the library names that the class depends on. After reading them, ROOT knows which classes are available, and which libraries to load for them.
TSystem::Load("ALib") is called, ROOT uses this information to determine which libraries
libALib.so depends on. It will load these libraries first. Otherwise, loading the requested library could cause a system (dynamic loader) error due to unresolved symbols.
tutorials The tutorials directory contains many example example scripts. They assume some basic knowledge of ROOT, and for the new user we recommend reading the chapters: 「Histograms」 and 「Input/Output」 before trying the examples. The more experienced user can jump to chapter 「The Tutorials and Tests」 to find more explicit and specific information about how to build and run the examples.
$ROOTSYS/tutorials/ directory include the following sub-directories:
fft: Fast Fourier Transform with the fftw package
fit: Several examples illustrating minimization/fitting
foam: Random generator in multidimensional space
geom: Examples of use of the geometry package (
gl: Visualisation with OpenGL
graphics: Basic graphics
graphs: Use of
gui: Scripts to create Graphical User Interface
image: Image Processing
math: Maths and Statistics functions
matrix: Matrices (
mlp: Neural networks with
net: Network classes (client/server examples)
physics: LorentzVectors, phase space
pyroot: Python tutorials
pythia: Example with
quadp: Quadratic Programming
smatrix: Matrices with a templated package
spectrum: Peak finder, background, deconvolutions
splot: Example of the
TSplot class (signal/background estimator)
sql: Interfaces to SQL (mysql, oracle, etc)
thread: Using Threads
tmva: Examples of the MultiVariate Analysis classes
tree: Creating Trees, Playing with Trees
unuran: Interface with the unuram random generator library
xml: Writing/Reading xml files
You can execute the scripts in
$ROOTSYS/tutorials (or sub-directories) by setting your current directory in the script directory or from any user directory with write access. Several tutorials create new files. If you have write access to the tutorials directory, the new files will be created in the tutorials directory, otherwise they will be created in the user directory.
The test directory contains a set of examples example that represent all areas of the framework. When a new release is cut, the examples in this directory are compiled and run to test the new release's backward compatibility. The list of source files is described in chapter 「The Tutorials and Tests」.
$ROOTSYS/test directory is a gold mine of ROOT-wisdom nuggets, and we encourage you to explore and exploit it. We recommend the new users to read the chapter 「Getting Started」. The chapter 「The Tutorials and Tests」 has instructions on how to build all the programs and it goes over the examples
include directory contains all header files. It is especially important because the header files contain the class definitions.
The directories we explored above are available when downloading the binaries. When downloading the source you also get a directory for each library with the corresponding header and source files, located in the
src subdirectories. To see what classes are in a library, you can check the
<library>/inc directory for the list of class definitions. For example, the physics library
libPhysics.so contains these class definitions:
website The ROOT web site has up to date documentation. The ROOT source code automatically generates this documentation, so each class is explicitly documented on its own web page, which is always up to date with the latest official release of ROOT.
The ROOT Reference Guide web pages can be found at class index reference guide http://root.cern.ch/root/html/ClassIndex.html. Each page contains a class description, and an explanation of each method. It shows the class inheritance tree and lets you jump to the parent class page by clicking on the class name. If you want more details, you can even see the source. There is a help page available in the little box on the upper right hand side of each class documentation page. You can see on the next page what a typical class documentation web page looks like. The ROOT web site also contains in addition to this Reference Guide, 「How To's」, a list of publications and example applications.
The top of any class reference page lets you jump to different parts of the documentation. The first line links to the class index and the index for the current module (a group of classes, often a library). The second line links to the ROOT homepage and the class overviews. The third line links the source information - a HTML version of the source and header file as well as the CVS (the source management system used for the ROOT development) information of the files. The last line links the different parts of the current pages.
We begin by showing you how to use ROOT interactively. There are two examples to click through and learn how to use the GUI. We continue by using the command line, and explaining the coding conventions, global variables and the environment setup. If you have not installed ROOT, you can do so by following the instructions in the appendix, or on the ROOT web site: http://root.cern.ch/root/Availability.html
Before you can run ROOT you need to set the environment variable
ROOTSYS and change your path to include
root/bin and library path variables to include
root/lib. Please note: the syntax is for
bash, if you are running
tcsh you will have to use
setenv instead of
$ export ROOTSYS=$HOME/root
$ export PATH=$PATH:$ROOTSYS/bin
On HP-UX, before executing the interactive module, you must set the library path:
$ export SHLIB_PATH=$SHLIB_PATH:$ROOTSYS/lib
On AIX, before executing the interactive module, you must set the library path:
$ [ -z "$LIBPATH" ] && export LIBPATH=/lib:/usr/lib $ export LIBPATH=$LIBPATH:$ROOTSYS/lib
On Linux, Solaris, Alpha OSF and SGI, before executing the interactive module, you must set the library path:
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ROOTSYS/lib
On Solaris, in case your LD_LIBRARY_PATH is empty, you should set it:
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ROOTSYS/lib:/usr/dt/lib
If you use the
afs version you should set (vers = version number, arch = architecture):
$ export ROOTSYS=/afs/cern.ch/sw/lcg/external/root/vers/arch/root
If ROOT was installed in
$HOME/myroot directory on a local machine, one can do:
cd $HOME/myroot . bin/thisroot.sh // or source bin/thisroot.sh
$ROOTSYS/bin/thisroot.[c]sh scripts will set correctly the
LD_LIBRARY_PATH or other paths depending on the platform and the
MANPATH. To run the program just type:
$ root ------------------------------------------------------------------------- | Welcome to ROOT 6.10/01 http://root.cern.ch | | (c) 1995-2017, The ROOT Team | | Built for macosx64 | | From heads/v6-10-00-patches@v6-10-00-25-g9f78c3a, Jul 03 2017, 11:39:44 | | Try '.help', '.demo', '.license', '.credits', '.quit'/'.q' | ------------------------------------------------------------------------- root 
To start ROOT you can type
root at the system prompt. This starts up Cling, the ROOT command line C/C++ interpreter, and it gives you the ROOT prompt (
It is possible to launch ROOT with some command line options, as shown below:
% root -? Usage: root [-l] [-b] [-n] [-q] [dir] [[file:]data.root] [file1.C ... fileN.C] Options: -b : run in batch mode without graphics -n : do not execute logon and logoff macros as specified in .rootrc -q : exit after processing command line macro files -l : do not show splash screen -x : exit on exception dir : if dir is a valid directory cd to it before executing -? : print usage -h : print usage --help : print usage -config : print ./configure options -memstat : run with memory usage monitoring
-b ROOT session runs in batch mode, without graphics display. This mode is useful in case one does not want to set the DISPLAY or cannot do it for some reason.
-n usually, launching a ROOT session will execute a logon script and quitting will execute a logoff script. This option prevents the execution of these two scripts.
it is also possible to execute a script without entering a ROOT session. One simply adds the name of the script(s) after the ROOT command. Be warned: after finishing the execution of the script, ROOT will normally enter a new session.
-q process command line script files and exit.
For example if you would like to run a script
myMacro.C in the background, redirect the output into a file
myMacro.log, and exit after the script execution, use the following syntax:
root -b -q myMacro.C > myMacro.log
If you need to pass a parameter to the script use:
root -b -q 'myMacro.C(3)' > myMacro.log
Be mindful of the quotes, i.e. if you need to pass a string as a parameter, the syntax is:
root -b -q 'myMacro.C("text")' > myMacro.log
You can build a shared library with ACLiC and then use this shared library on the command line for a quicker execution (i.e. the compiled speed rather than the interpreted speed). See also 「Cling the C++ Interpreter」.
root -b -q myMacro.so > myMacro.log
ROOT has a powerful C/C++ interpreter giving you access to all available ROOT classes, global variables, and functions via the command line. By typing C++ statements at the prompt, you can create objects, call functions, execute scripts, etc. For example:
To exit the ROOT session, type
The basic whiteboard on which an object is drawn in ROOT is called a canvas (defined by the class
TCanvas). Every object in the canvas is a graphical object in the sense that you can grab it, resize it, and change some characteristics using the mouse. The canvas area can be divided in several sub areas, so-called pads (the class
TPad). A pad is a canvas sub area that can contain other pads or graphical objects. At any one time, just one pad is the so-called active pad. Any object at the moment of drawing will be drawn in the active pad. The obvious question is: what is the relation between a canvas and a pad? In fact, a canvas is a pad that spans through an entire window. This is nothing else than the notion of inheritance. The
TPad class is the parent of the
TCanvas class. In ROOT, most objects derive from a base class
TObject. This class has a virtual method
Draw() such as all objects are supposed to be able to be 「drawn」. If several canvases are defined, there is only one active at a time. One draws an object in the active canvas by using the statement:
This instructs the object 「
object」 to draw itself. If no canvas is opened, a default one (named 「
c1」) is created. In the next example, the first statement defines a function and the second one draws it. A default canvas is created since there was no opened one. You should see the picture as shown in the next figure.
The following components comprise the canvas window:
Menu bar - contains main menus for global operations with files, print, clear canvas, inspect, etc.
Tool bar - has buttons for global and drawing operations; such as arrow, ellipse, latex, pad, etc.
Canvas - an area to draw objects.
Status bar - displays descriptive messages about the selected object.
Editor frame - responds dynamically and presents the user interface according to the selected object in the canvas.
At the top of the canvas window are File, Edit, View, Options, Inspect, Classes and Help menus.
New Canvas: creates a new canvas window in the current ROOT session.
Open…: popup a dialog to open a file.
Close Canvas: close the canvas window.
Save: save the drawing of the current canvas in a format selectable from the submenu. The current canvas name is used as a file name for various formats such as PostScript, GIF, JPEG, C macro file, root file.
Save As…: popup a dialog for saving the current canvas drawing in a new filename.
Print: popup a dialog to print the current canvas drawing
Quit ROOT: exit the ROOT session
There is only one active menu entry in the Edit menu. The others menu entries will be implemented and will become active in the near future.
Editor: toggles the view of the editor. If it is selected activates and shows up the editor on the left side of the canvas window. According to the selected object, the editor loads the corresponding user interface for easy change of the object's attributes.
Toolbar: toggles the view of the toolbar. If it is selected activates and shows up the toolbar. It contains buttons for easy and fast access to most frequently used commands and for graphics primitive drawing. Tool tips are provided for helping users.
Status Bar: toggles the view of the status bar. If it is selected, the status bar below the canvas window shows up. There the identification of the objects is displayed when moving the mouse (such as the object's name, the object's type, its coordinates, etc.).
Colors: creates a new canvas showing the color palette.
Markers: creates a new canvas showing the various marker styles.
Iconify: create the canvas window icon, does not close the canvas
View With…: If the last selected pad contains a 3-d structure, a new canvas is created with a 3-D picture according to the selection made from the cascaded menu: X3D or OpenGL. The 3-D image can be interactively rotated, zoomed in wire-frame, solid, hidden line or stereo mode.
Auto Resize Canvas: turns auto-resize of the canvas on/off:
Resize Canvas: resizes and fits the canvas to the window size.
Move Opaque: if selected, graphics objects are moved in opaque mode; otherwise, only the outline of objects is drawn when moving them. The option opaque produces the best effect but it requires a reasonably fast workstation or response time.
Resize Opaque: if selected, graphics objects are resized in opaque mode; otherwise, only the outline of objects is drawn when resizing them.
Interrupt: interrupts the current drawing process.
Refresh: redraws the canvas contents.
Pad Auto Exec: executes the list of
TExecs in the current pad.
Statistics: toggles the display of the histogram statistics box.
Histogram Title: toggles the display of the histogram title.
Fit Parameters: toggles the display of the histogram or graph fit parameters.
Can Edit Histogram: enables/disables the possibility to edit histogram bin contents.
ROOT: inspects the top-level
gROOT object (in a new canvas).
Start Browser: starts a new object browser (in a separate window).
GUI Builder: starts the GUI builder application (in a separate window).
Canvas: help on canvas as a whiteboard area for drawing.
Menus: help on canvas menus.
Graphics Editor: help on primitives' drawing and objects' editor.
Browser: help on the ROOT objects' and files' browser.
Objects: help on DrawClass, Inspect and Dump context menu items.
PostScript: help on how to print a canvas to a PostScript file format.
About ROOT: pops up the ROOT Logo with the version number.
The following menu shortcuts and utilities are available from the toolbar:
Create a new canvas window.
Popup the Open File dialog.
Popup the Save As… dialog.
Popup the Print dialog.
Interrupts the current drawing process.
Redraw the canvas.
Create a new objects' browser.
You can create the following graphical objects using the toolbar buttons for primitive drawing. Tool tips are provided for helping your choice.
An Arc or circle: Click on the center of the arc, and then move the mouse. A rubber band circle is shown. Click again with the left button to freeze the arc.
A Line: Click with the left button at the point where you want to start the line, then move the mouse and click again with the left button to freeze the line.
An Arrow:Click with the left button at the point where you want to start the arrow, then move the mouse and click again with the left button to freeze the arrow.
A Diamond: Click with the left button and freeze again with the left button. The editor draws a rubber band box to suggest the outline of the diamond.
An Ellipse: Proceed like for an arc. You can grow/shrink the ellipse by pointing to the sensitive points. They are highlighted. You can move the ellipse by clicking on the ellipse, but not on the sensitive points. If, with the ellipse context menu, you have selected a fill area color, you can move a filled-ellipse by pointing inside the ellipse and dragging it to its new position.
A Pad: Click with the left button and freeze again with the left button. The editor draws a rubber band box to suggest the outline of the pad.
A PaveLabel: Proceed like for a pad. Type the text of label and finish with a carriage return. The text will appear in the box.
A Pave Text: Proceed like for a pad. You can then click on the
TPaveText object with the right mouse button and select the option
Paves Text: Proceed like for a
A Poly Line: Click with the left button for the first point, move the moose, click again with the left button for a new point. Close the poly-line with a double click. To edit one vertex point, pick it with the left button and drag to the new point position.
A Curly Line: Proceed as for the arrow or line. Once done, click with the third button to change the characteristics of the curly line, like transform it to wave, change the wavelength, etc.
A Curly Arc: Proceed like for an ellipse. The first click is located at the position of the center, the second click at the position of the arc beginning. Once done, one obtains a curly ellipse, for which one can click with the third button to change the characteristics, like transform it to wavy, change the wavelength, set the minimum and maximum angle to make an arc that is not closed, etc.
A Text/Latex string: Click with the left button where you want to draw the text and then type in the text terminated by carriage return. All
TLatex expressions are valid. To move the text or formula, point on it keeping the left mouse button pressed and drag the text to its new position. You can grow/shrink the text if you position the mouse to the first top-third part of the string, then move the mouse up or down to grow or shrink the text respectively. If you position the mouse near the bottom-end of the text, you can rotate it.
A Marker: Click with the left button where to place the marker. The marker can be modified by using the method
A Graphical Cut: Click with the left button on each point of a polygon delimiting the selected area. Close the cut by double clicking on the last point. A
TCutG object is created. It can be used as a selection for a
::Draw. You can get a pointer to this object with:
Once you are happy with your picture, you can select the
Save as canvas.C item in the canvas File menu. This will automatically generate a script with the C++ statements corresponding to the picture. This facility also works if you have other objects not drawn with the graphics editor (histograms for example).
The ROOT graphics editor loads the corresponding object editor
objEditor according to the selected object
obj in the canvas respecting the class inheritance. An object in the canvas is selected after the left mouse click on it. For example, if the selected object is
TAxisEditor will shows up in the editor frame giving the possibility for changing different axis attributes. The graphics editor can be:
Embedded - connected only with the canvas in the application window that appears on the left of the canvas window after been activated via View menu / Editor. It appears on the left side if the canvas window allowing users to edit the attributes of the selected object via provided user interface. The name of the selected object is displayed on the top of the editor frame in red color. If the user interface needs more space then the height of the canvas window, a vertical scroll bar appears for easer navigation.
Global - has own application window and can be connected to any created canvas in a ROOT session. It can be activated via the context menu entries for setting line, fill, text and marker attributes for backward compatibility, but there will be a unique entry in the near future.
The user interface for the following classes is available since ROOT v.4.04:
TPaveStats. For more details, see 「The Graphics Editor」, 「The User Interface for Histograms」, 「The User Interface for Graphs」.
Object oriented programming introduces objects, which have data members and methods. The next line creates an object named
f1 of the class
TF1 that is a one-dimensional function. The type of an object is called a class. The object itself is called an instance of a class. When a method builds an object, it is called a constructor.
In our constructor the function sin(x)/x is defined for use, and 0 and 10 are the limits. The first parameter,
func1 is the name of the object
f1. Most objects in ROOT have a name. ROOT maintains a list of objects that can be searched to find any object by its given name (in our example
The syntax to call an object's method, or if one prefers, to make an object to do something is:
The dot can be replaced by 「
object is a pointer. In compiled code, the dot MUST be replaced by a 「
->」 if object is a pointer.
So now, we understand the two lines of code that allowed us to draw our function.
f1.Draw() stands for 「call the method
Draw() associated with the object
f1 of the class
TF1」. Other methods can be applied to the object
f1 of the class
TF1. For example, the evaluating and calculating the derivative and the integral are what one would expect from a function.
By default the method
TF1::Paint(), that draws the function, computes 100 equidistant points to draw it. The number of points can be set to a higher value with:
Note that while the ROOT framework is an object-oriented framework, this does not prevent the user from calling plain functions.
Now we will look at some interactive capabilities. Try to draw the function
sin(x)/x again. Every object in a window (which is called a canvas) is, in fact, a graphical object in the sense that you can grab it, resize it, and change its characteristics with a mouse click. For example, bring the cursor over the x-axis. The cursor changes to a hand with a pointing finger when it is over the axis. Now, left click and drag the mouse along the axis to the right. You have a very simple zoom.
When you move the mouse over any object, you can get access to selected methods by pressing the right mouse button and obtaining a context menu. If you try this on the function
TF1, you will get a menu showing available methods. The other objects on this canvas are the title, a
; the x and y-axis,
TAxis objects, the frame, a
TFrame object, and the canvas a
TCanvas object. Try clicking on these and observe the context menu with their methods.
For example try selecting the
SetRange() method and putting
10 in the dialog box fields. This is equivalent to executing
f1.SetRange(-10,10) from the command line, followed by
f1.Draw(). Here are some other options you can try.
Once the picture suits your wishes, you may want to see the code you should put in a script to obtain the same result. To do that, choose Save /
canvas.C entry of the File menu. This will generate a script showing the options set in the current canvas. Notice that you can also save the picture into various file formats such as PostScript, GIF, etc. Another interesting possibility is to save your canvas into the native ROOT format (
.rootfile). This will enable you to open it again and to change whatever you like. All objects associated to the canvas (histograms, graphs) are saved at the same time.
Let us now try to build a canvas with several pads.
Once again, we call the constructor of a class, this time the class
TCanvas. The difference between this and the previous constructor call (
TF1) is that here we are creating a pointer to an object. Next, we call the method
Divide() of the
TCanvas class (that is
TCanvas::Divide()), which divides the canvas into four zones and sets up a pad in each of them. We set the first pad as the active one and than draw the function
All objects will be drawn in that pad because it is the active one. The ways for changing the active pad are:
Click the middle mouse button on a pad will set this pad as the active one.
Use the method
TCanvas::cd() with the pad number, as was done in the example above:
Pads are numbered from left to right and from top to bottom. Each new pad created by
TCanvas::Divide() has a name, which is the name of the canvas followed by _1, _2, etc. To apply the method
cd() to the third pad, you would write:
TPad::cd()for the object
MyC_3. ROOT will find the pad that was named
MyC_3when you typed it on the command line (see ROOT/Cling Extensions to C++).