User's Guide


Table of Contents

Preface
1. Introduction
The ROOT Mailing Lists
Contact Information
Conventions Used in This Book
The Framework
What Is a Framework?
Why Object-Oriented?
Installing ROOT
The Organization of the ROOT Framework
$ROOTSYS/bin
$ROOTSYS/lib
$ROOTSYS/tutorials
$ROOTSYS/test
$ROOTSYS/include
$ROOTSYS/<library>
How to Find More Information
Class Reference Guide
2. Getting Started
Setting the Environment Variables
Start and Quit a ROOT Session
Using the GUI
Main Menus and Toolbar
The Editor Frame
Classes, Methods and Constructors
User Interaction
Building a Multi-pad Canvas
Saving the Canvas
Printing the Canvas
The ROOT Command Line
Multi-line Commands
CINT Extensions
Helpful Hints for Command Line Typing
Regular Expression
Conventions
Coding Conventions
Machine Independent Types
TObject
Global Variables
gROOT
gFile
gDirectory
gPad
gRandom
gEnv
Environment Setup
Logon and Logoff Scripts
History File
Tracking Memory Leaks
Memory Checker
Converting from PAW to ROOT
Converting HBOOK/PAW Files
3. Histograms
The Histogram Classes
Creating Histograms
Fixed or Variable Bin Size
Bin Numbering Convention
Re-binning
Filling Histograms
Automatic Re-binning Option
Random Numbers and Histograms
Adding, Dividing, and Multiplying
Projections
Drawing Histograms
Setting the Style
Draw Options
Drawing a Sub-range of a 2-D Histogram
Superimposing Histograms with Different Scales
Statistics Display
Setting Line, Fill, Marker, and Text Attributes
Setting Tick Marks on the Axis
Giving Titles to the X, Y and Z Axis
Making a Copy of an Histogram
Normalizing Histograms
Saving/Reading Histograms to/from a File
Miscellaneous Operations
Alphanumeric Bin Labels
Option 1: SetBinLabel
Option 2: Fill
Option 3: TTree::Draw
Sort Options
Histogram Stacks
TH2Poly
Profile Histograms
Build Options
Drawing a Profile without Error Bars
Create a Profile from a 2D Histogram
Create a Histogram from a Profile
Generating a Profile from a TTree
2D Profiles
Iso Surfaces
3D Implicit Functions
TPie
The User Interface for Histograms
TH1Editor
TH2Editor
4. Graphs
TGraph
Graph Draw Options
Superimposing Two Graphs
Graphs with Error Bars
Graphs with Asymmetric Error Bars
Graphs with Asymmetric Bent Errors
TGraphPolar
TGraph Exclusion Zone
TGraphQQ
Two Datasets
One Dataset
TMultiGraph
TGraph2D
TGraph2DErrors
Fitting a Graph
Setting the Graph's Axis Title
Zooming a Graph
The User Interface for Graphs
5. Fitting Histograms
The Fit Method
Fit with a Predefined Function
Fit with a User-Defined Function
Creating a TF1 with a Formula
Creating a TF1 with Parameters
Creating a TF1 with a User Function
Fixing and Setting Parameters’ Bounds
Fitting Sub Ranges
The Fit Panel
Function Choice and Settings
Fitter Settings
Draw Options
Print Options
Command Buttons
Fitting Multiple Sub Ranges
Adding Functions to the List
Combining Functions
Associated Function
Access to the Fit Parameters and Results
Associated Errors
Fit Statistics
The Minimization Package
Basic Concepts of Minuit
The Transformation of Limited Parameters
How to Get the Right Answer from Minuit
Reliability of Minuit Error Estimates
FUMILI Minimization Package
Neural Networks
Introduction
The MLP
Learning Methods
Using the Network
Examples
6. A Little C++
Classes, Methods and Constructors
Inheritance and Data Encapsulation
Method Overriding
Data Encapsulation
Creating Objects on the Stack and Heap
7. CINT the C++ Interpreter
What is CINT?
The ROOT Command Line Interface
The ROOT Script Processor
Un-named Scripts
Named Scripts
Executing a Script from a Script
Resetting the Interpreter Environment
A Script Containing a Class Definition
Debugging Scripts
Inspecting Objects
ROOT/CINT Extensions to C++
ACLiC - The Automatic Compiler of Libraries for CINT
Usage
Setting the Include Path
Dictionary Generation
Intermediate Steps and Files
Moving between Interpreter and Compiler
Reflex
Overview
Selecting Types And Members
Genreflex and Templates
GCCXML Installation
Reflex API
Cintex
8. Object Ownership
Ownership by Current Directory (gDirectory)
Ownership by the Master TROOT Object (gROOT)
The Collection of Specials
Access to the Collection Contents
Ownership by Other Objects
Ownership by the User
The kCanDelete Bit
The kMustCleanup Bit
9. Graphics and the Graphical User Interface
Drawing Objects
Interacting with Graphical Objects
Moving, Resizing and Modifying Objects
Selecting Objects
Context Menus: the Right Mouse Button
Executing Events when a Cursor Passes on Top of an Object
Graphical Containers: Canvas and Pad
The Global Pad: gPad
The Coordinate Systems of a Pad
Converting between Coordinate Systems
Dividing a Pad into Sub-pads
Updating the Pad
Making a Pad Transparent
Setting the Log Scale
WaitPrimitive method
Locking the Pad
Graphical Objects
Lines, Arrows and Polylines
Circles and Ellipses
Rectangles
Markers
Curly and Wavy Lines for Feynman Diagrams
Text and Latex Mathematical Expressions
Greek Letters
Mathematical Symbols
Text in a Pad
The TeX Processor TMathText
Axis
Axis Title
Axis Options and Characteristics
Setting the Number of Divisions
Zooming the Axis
Drawing Axis Independently of Graphs or Histograms
Orientation of Tick Marks on Axis
Labels
Axis with Time Units
Axis Examples
Graphical Objects Attributes
Text Attributes
Line Attributes
Fill Attributes
Color and Color Palettes
The Graphics Editor
TAxisEditor
TPadEditor
Copy and Paste
Using the GUI
Programmatically
Legends
The PostScript Interface
Special Characters
Writing Several Canvases to the Same PostScript File
Create or Modify a Style
3D Viewers
Invoking a 3D viewer
The GL Viewer
The X3D Viewer
Common 3D Viewer Architecture
10. Folders and Tasks
Folders
Why Use Folders?
How to Use Folders
Creating a Folder Hierarchy
Posting Data to a Folder (Producer)
Reading Data from a Folder (Consumer)
Tasks
Execute and Debug Tasks
11. Input/Output
The Physical Layout of ROOT Files
The File Header
The Top Directory Description
The Histogram Records
The Class Description List (StreamerInfo List)
The List of Keys and the List of Free Blocks
File Recovery
The Logical ROOT File: TFile and TKey
Viewing the Logical File Contents
The Current Directory
Objects in Memory and Objects on Disk
Saving Histograms to Disk
Histograms and the Current Directory
Saving Objects to Disk
Saving Collections to Disk
A TFile Object Going Out of Scope
Retrieving Objects from Disk
Subdirectories and Navigation
Streamers
Automatically Generated Streamers
Transient Data Members (//!)
The Pointer to Objects (//->)
Variable Length Array
Double32_t
Prevent Splitting (//|| )
Streamers with Special Additions
Writing Objects
Ignore Object Streamers
Streaming a TClonesArray
Pointers and References in Persistency
Streaming C++ Pointers
Motivation for the TRef Class
Using TRef
How Does It Work?
Action on Demand
Array of TRef
Schema Evolution
The TStreamerInfo Class
The TStreamerElement Class
Example: TH1 StreamerInfo
Optimized StreamerInfo
Automatic Schema Evolution
Manual Schema Evolution
Building Class Definitions with the StreamerInfo
Example: MakeProject
Migrating to ROOT 3
Compression and Performance
Remotely Access to ROOT Files via a rootd
TNetFile URL
Remote Authentication
A Simple Session
The rootd Daemon
Starting rootd via inetd
Command Line Arguments for rootd
Reading ROOT Files via Apache Web Server
Using the General Open Function of TFile
XML Interface
12. Trees
Why Should You Use a Tree?
A Simple TTree
Show an Entry with TTree::Show
Print the Tree Structure with TTree::Print
Scan a Variable the Tree with TTree::Scan
The Tree Viewer
Creating and Saving Trees
Creating a Tree from a Folder Hierarchy
Tree and TRef Objects
Autosave
Trees with Circular Buffers
Size of TTree in the File
User Info Attached to a TTree Object
Indexing a Tree
Branches
Adding a Branch to Hold a List of Variables
Adding a TBranch to Hold an Object
Setting the Split-level
Exempt a Data Member from Splitting
Adding a Branch to Hold a TClonesArray
Identical Branch Names
Adding a Branch with a Folder
Adding a Branch with a Collection
Examples for Writing and Reading Trees
Example 1: A Tree with Simple Variables
Writing the Tree
Viewing the Tree
Reading the Tree
Example 2: A Tree with a C Structure
Writing the Tree
Analysis
Example 3: Adding Friends to Trees
Adding a Branch to an Existing Tree
TTree::AddFriend
Example 4: A Tree with an Event Class
The Event Class
The EventHeader Class
The Track Class
Writing the Tree
Reading the Tree
Example 5: Import an ASCII File into a TTree
Trees in Analysis
Simple Analysis Using TTree::Draw
Using Selection with TTree:Draw
Using TCut Objects in TTree::Draw
Accessing the Histogram in Batch Mode
Using Draw Options in TTree::Draw
Superimposing Two Histograms
Setting the Range in TTree::Draw
TTree::Draw Examples
Using TTree::Scan
TEventList and TEntryList
Filling a Histogram
Using TTree::MakeClass
Creating a Class with MakeClass
MyClass.h
MyClass.C
Modifying MyClass::Loop
Loading MyClass
Using TTree::MakeSelector
Performance Benchmarks
Impact of Compression on I/O
Chains
TChain::AddFriend
13. Math Libraries in ROOT
TMath
Random Numbers
TRandom
TRandom1
TRandom2
TRandom3
Seeding the Generators
Examples of Using the Generators
Random Number Distributions
UNURAN
Performances of Random Numbers
MathCore Library
Generic Vectors for 2, 3 and 4 Dimensions (GenVector)
Main Characteristics
Example: 3D Vector Classes
Example: 3D Point Classes
Example: LorentzVector Classes
Example: Vector Transformations
Example with External Packages
MathMore Library
Mathematical Functions
Special Functions in MathCore
Special Functions in MathMore
Probability Density Functions (PDF)
Cumulative Distribution Functions (CDF)
Linear Algebra: SMatrix Package
Example: Vector Class (SVector)
Example: Matrix Class (SMatrix)
Example: Matrix and Vector Functions and Operators
Matrix and Vector Functions
Minuit2 Package
ROOT Statistics Classes
Classes for Computing Limits and Confidence Levels
Specialized Classes for Fitting
Multi-variate Analysis Classes
14. Linear Algebra in ROOT
Overview of Matrix Classes
Matrix Properties
Accessing Properties
Setting Properties
Creating and Filling a Matrix
Matrix Operators and Methods
Arithmetic Operations between Matrices
Arithmetic Operations between Matrices and Real Numbers
Comparisons and Boolean Operations
Matrix Norms
Miscellaneous Operators
Matrix Views
View Operators
View Examples
Matrix Decompositions
Tolerances and Scaling
Condition number
LU
Bunch-Kaufman
Cholesky
QRH
SVD
Matrix Eigen Analysis
Speed Comparisons
15. Adding a Class
The Role of TObject
Introspection, Reflection and Run Time Type Identification
Collections
Input/Output
Paint/Draw
Clone/DrawClone
Browse
SavePrimitive
GetObjectInfo
IsFolder
Bit Masks and Unique ID
Motivation
Template Support
The Default Constructor
rootcint: The CINT Dictionary Generator
Dictionaries for STL
Adding a Class with a Shared Library
The LinkDef.h File
Adding a Class with ACLiC
16. Collection Classes
Understanding Collections
General Characteristics
Determining the Class of Contained Objects
Types of Collections
Ordered Collections (Sequences)
Iterators: Processing a Collection
Foundation Classes
A Collectable Class
The TIter Generic Iterator
The TList Collection
Iterating Over a TList
The TObjArray Collection
TClonesArray – An Array of Identical Objects
The Idea Behind TClonesArray
Template Containers and STL
17. Physics Vectors
The Physics Vector Classes
TVector3
Declaration / Access to the Components
Other Coordinates
Arithmetic / Comparison
Related Vectors
Scalar and Vector Products
Angle between Two Vectors
Rotation around Axes
Rotation around a Vector
Rotation by TRotation Class
Transformation from Rotated Frame
TRotation
Declaration, Access, Comparisons
Rotation around Axes
Rotation around Arbitrary Axis
Rotation of Local Axes
Inverse Rotation
Compound Rotations
Rotation of TVector3
TLorentzVector
Declaration
Access to Components
Vector Components in Non-Cartesian Coordinates
Arithmetic and Comparison Operators
Magnitude/Invariant mass, beta, gamma, scalar product
Lorentz Boost
Rotations
Miscellaneous
TLorentzRotation
Declaration
Access to the Matrix Components/Comparisons
Transformations of a Lorentz Rotation
Transformation of a TLorentzVector
Physics Vector Example
18. The Geometry Package
Quick Start: Creating the “world”
Example 1: Creating the World
Example 2: A Geometrical Hierarchy Look and Feel
Materials and Tracking Media
Elements, Materials and Mixtures
Radionuclides
Tracking Media
User Interface for Handling Materials and Media
Shapes
Units
Primitive Shapes
Composite Shapes
Navigation Methods Performed By Shapes
Creating Shapes
Dividing Shapes
Parametric Shapes
Geometry Creation
The Volume Hierarchy
Creating and Positioning Volumes
Geometrical Transformations
Ownership of Geometry Objects
Navigation and Tracking
TGeoNavigator Class
Initializing the Starting Point
Initializing the Direction
Initializing the State
Checking the Current State
Saving and Restoring the Current State
Navigation Queries
Creating and Visualizing Tracks
Checking the Geometry
The Overlap Checker
Graphical Checking Methods
The Drawing Package
Drawing Volumes and Hierarchies of Volumes
Visualization Settings and Attributes
Ray Tracing
Representing Misalignments of the Ideal Geometry
Physical Nodes
Geometry I/O
GDML
Navigation Algorithms
Finding the State Corresponding to a Location (x,y,z)
Finding the Distance to Next Crossed Boundary
Geometry Graphical User Interface
Editing a Geometry
The Geometry Manager Editor
Editing Existing Objects
Creation of New Objects
Editing Volumes
How to Create a Valid Geometry with Geometry Editors
19. Python and Ruby Interfaces
PyROOT Overview
Glue-ing Applications
Access to ROOT from Python
Access to Python from ROOT
Installation
Using PyROOT
Memory Handling
Performance
Use of Python Functions
Working with Trees
Using Your Own Classes
How to Use ROOT with Ruby
Building and Installing the Ruby Module
20. The Tutorials and Tests
$ROOTSYS/tutorials
$ROOTSYS/test
Event – An Example of a ROOT Application
stress - Test and Benchmark
guitest – A Graphical User Interface
21. Example Analysis
Explanation
Script
22. Networking
Setting-up a Connection
Sending Objects over the Network
Closing the Connection
A Server with Multiple Sockets
23. Threads
Threads and Processes
Process Properties
Thread Properties
The Initial Thread
Implementation of Threads in ROOT
Installation
Classes
TThread for Pedestrians
TThread in More Details
Advanced TThread: Launching a Method in a Thread
Known Problems
The Signals of ROOT
Glossary
24. PROOF: Parallel Processing
25. Writing a Graphical User Interface
The ROOT GUI Classes
Widgets and Frames
TVirtualX
A Simple Example
A Standalone Version
Widgets Overview
TGObject
TGWidget
TGWindow
Frames
Layout Management
Event Processing: Signals and Slots
Widgets in Detail
Buttons
Text Entries
Number Entries
Menus
Toolbar
List Boxes
Combo Boxes
Sliders
Triple Slider
Progress Bars
Static Widgets
Status Bar
Splitters
TGCanvas, ViewPort and Container
Embedded Canvas
The ROOT Graphics Editor (GED)
Object Editors
Editor Design Elements
Drag and Drop
Drag and Drop Data Class
Handling Drag and Drop Events
26. ROOT/Qt Integration Interfaces
Qt-ROOT Implementation of TVirtualX Interface (BNL)
Installation
Applications
TQtWidget Class, Qt Signals / Slots and TCanvas Interface
GSI QtROOT
Create a New Project in the Designer
main()
27. Automatic HTML Documentation
Reference Guide
Product and Module Documentation
Converting Sources (and Other Files) to HTML
Special Documentation Elements: Directives
Latex Directive
Macro Directive
Customizing HTML
Referencing Documentation for other Libraries
Search Engine
ViewCVS
Wiki Pages
Tutorial
28. Appendix A: Install and Build ROOT
License
Installing ROOT
Choosing a Version
Installing Precompiled Binaries
Installing the Source
Installing and Building the Source from a Compressed File
More Build Options
File system.rootrc
TCanvas Specific Settings
THtml Specific Settings
GUI Specific Settings
TBrowser Settings
TRint Specific Settings
ACLiC Specific Settings
PROOF Related Variables
Documentation to Download
Index

List of Figures

1.1. ROOT framework directories
1.2. ROOT framework directories
1.3. ROOT libraries dependencies
2.1. A canvas with drawing
2.2. A context menu
2.3. The SaveAs... dialog
3.1. The class hierarchy of histogram classes
3.2. The "E1" bars' option
3.3. Different draw options
3.4. The TEXT option
3.5. Different contour options
3.6. The earth.C macro output
3.7. "LEGO" and "SURF" options
3.8. Different surface options
3.9. Vertical bar charts
3.10. Horizontal bar charts
3.11. The picture produced by spectrumpainter.C macro
3.12. The picture produced by fit2a.C macro
3.13. Superimposed histograms with different scales
3.14. Histograms with alphanumeric bin labels
3.15. Using a *char variable type in TTree::Draw
3.16. Stacked histograms
3.17. A TH2Poly histogram example
3.18. A profile histogram example
3.19. A TProfile2D histogram example
3.20. Iso surfaces
3.21. 3D implicit function
3.22. The picture generated by tutorial macro piechart.C
4.1. A graph drawn with axis, * markers and continuous line (option AC*)
4.2. A graph drawn with axis and bar (option AB)
4.3. A graph drawn with axis and fill (option AF)
4.4. Graph markers created in different ways
4.5. Superimposing two graphs
4.6. Graphs with different draw options of error bars
4.7. A graph with asymmetric error bars
4.8. A graph with asymmetric bent error bars
4.9. A polar graph
4.10. Graphs with exclusion zones
4.11. Examples of qq-plots of 2 datasets
4.12. Examples of qq-plots of 1 dataset
4.13. A multigraph example
4.14. Delaunay triangles and Voronoi diagram
4.15. Graph2D drawn with option "surfl" and "tril p0"
4.16. Output of macro graph2dfit.C
4.17. A graph with axis titles
4.18. A zoomed graph
5.1. The function x*sin(x)
5.2. Fitting a histogram with several Gaussian functions
5.3. The output of the FittingDemo() example
5.4. The neural net output
5.5. The original and the neural net for Br
7.1. ROOT object inspector of TFile
7.2. The object inspector of fKeys, the list of keys in the memory
8.1. The ROOT Object Browser
9.1. Context menus of different objects in a canvas
9.2. A histogram drawn in a pad
9.3. Pad coordinate systems
9.4. The status bar
9.5. Dividing a pad into 6 sub-pads
9.6. Different arrow formats
9.7. Different types of ellipses
9.8. A rectangle with a border
9.9. Markers
9.10. Different marker sizes
9.11. The use of non-symmetric markers
9.12. The picture generated by the tutorial macro feynman.C
9.13. The picture generated by the tutorial macro latex.C
9.14. The picture generated by the tutorial macro latex2.C
9.15. The picture generated by the tutorial macro latex3.C
9.16. PaveLabels drawn with different options
9.17. PaveText examples
9.18. A PaveText example
9.19. A TMathText example
9.20. Y-axis with and without exponent labels
9.21. Time axis examples
9.22. A histogram with time axis X
9.23. The first axis example
9.24. The second axis example
9.25. An axis example with time display
9.26. Font’s examples
9.27. The various patterns
9.28. The basic ROOT colors
9.29. Different draw options
9.30. A legend example
9.31. Invoking external 3D viewers from canvas menus
9.32. The GL 3D Viewer
9.33. GL Viewer camera interactions
9.34. GL Viewer draw styles
9.35. GL Viewer interactive box clipping
9.36. GL Viewer object manipulators
9.37. Overview of 3D viewer architecture
9.38. TBuffer3D class hierarchy
10.1. Tasks in the ROOT browser
11.1. The browser with 15 created histograms
11.2. ROOT File/Directory/Key description
11.3. The structure of TFile
11.4. The file before and after the call to Write
11.5. Compression and precision of Double32_t
11.6. A diagram of a streamed TH1F in the buffer
11.7. Streaming object pointers
11.8. The ROOT schema evolution
11.9. The schema evolution for objects written on disk and in memory
12.1. Activating the tree viewer
12.2. The TreeViewer
12.3. A couple of graphs
12.4. The TTree class
12.5. The tree1.root file and its tree in the browser
12.6. A leaf histogram
12.7. The tree viewer
12.8. The tree viewer with tree4 example
12.9. Using draw options in trees
13.1. Math libraries and packages
13.2. PDF, CDF and quantiles in the case of the normal distribution
14.1. Overview of matrix classes
14.2. Speed comparison between the different matrix packages
16.1. The inheritance hierarchy of the primary collection classes
16.2. The internal data structure of a TList
16.3. The internal data structure of a TObjArray
16.4. The internal data structure of a TClonesArray
18.1. Concentration of C14 derived elements
18.2. Concentracion of elements derived fromCa53+Sr78
18.3. Primitive Shapes - the general inheritance scheme
18.4. TGeoBBox class
18.5. TGeoPara class
18.6. TGeoTrd1 class
18.7. TGeoTrd2 class
18.8. TGeoTrap Class
18.9. TGeoGtra class
18.10. TGeoArb8 class
18.11. TGeoTube Class
18.12. TGeoTubeSeg Class
18.13. TGeoCtub Class
18.14. TGeoEltu Class
18.15. TGeoHype Class
18.16. TGeoCone Class
18.17. TGeoConeSeg Class
18.18. TGeoSphere Class
18.19. TGeoTorus Class
18.20. TGeoParaboloid Class
18.21. TGeoPcon Class
18.22. TGeoPgon Class
18.23. TGeoXtru Class
18.24. The composite shapes structure
18.25. Representation of A+B+C
18.26. Internal representation for composite shapes
18.27. A composite shape example
18.28. A geometry hierarchy in memory
18.29. Assemblies of volumes
18.30. Extruding volumes
18.31. Overlap checking
18.32. Safety computation checking
18.33. Random points
18.34. Random rays
18.35. Ray-traced view in a pad
18.36. Ray-tracing example with box-clipping
18.37. Navigation in the geometry hierarchy
18.38. Finding the location of a point in the geometry hierarchy
18.39. Finding the distance to the next crossed boundary
18.40. The geometry manager editor
18.41. Accessing/creating different categories of editable objects
18.42. Selection dialogs for different TGeo objects
18.43. Editors for shapes, materials, media, matrices
18.44. Setting volume properties and modifying volume hierarchy
18.45. Volume visualisation settings and division interface for volumes
20.1. Native GUI widgets
22.1. Server - Client setting-up and closing the connection
24.1. The Multi-tier structure of a PROOF cluster
25.1. Widgets created by ROOT GUI classes
25.2. The GUI classes hierarchy
25.3. The layout classes hierarchy
25.4. Histogram, pad and axis editors