Release 0.3.4 bring interactive help to all types and methods of ROOT.jl.
Starting from release 0.3.3, the built-in Julia package manager is used to install the C++ ROOT framework. This mechansim replace the Conda one, which was introduced as an interim solution and rapidly showed its limits. The ROOT libraries (and also also executables) are package in the ROOT_jll JLL package.
📝 Automatic installation of the ROOT libraries is currently not supported for MacOS. It was supported for a short time by the Conda mechanism, before an update of the Conda forge repository broke the dependencies. On MacOS, the C++ ROOT framework must be installed separately using one of the method supported by ROOT.
ROOT.jl is a Julia interface to the C++ ROOT Data analysis framework used in the high energy physics community.
It is a work-in-progress package. It targets persons used to the ROOT framework and wishing to access it from Julia.
The project aims to provide access to the complete ROOT C++ API with a one-to-one mapping. Several ROOT classes are currently supported. Simplification of the API is not in the scope of the package. The API is already very convenient for some functionalities, like histogramming, histogram fit and plotting. The C++ interface to read and write TTree does not map well in Julia. A simplification of the API for I/O with a better Julia integration will be provided by a front end package in the contact of the ROOTIO project.
Function documentation for the Julia help command is not available yet. Please refer to the C++ ROOT reference guide for API documentation.
Since release 0.3.0, ROOT.jl uses CxxWrap to interface to the C++ libraries and the wrappers were generated using WrapIt!. Releases 0.1.0 and 0.2.0 were based on Cxx.jl, providing an access to the full ROOT C++ API, while release 0.3.0+ covers a subset of classes, but requiring use of the outdated Julia version 1.3.
Linux and MacOS.
To install the latest release, type from the Julia REPL, type ] to enter in the package manager and then,
add ROOT
If you are on MacOS, read the MacOS part of the next section.
The development version (github HEAD) can be installed using,
dev https://github.com/JuliaHEP/ROOT.jl
build ROOT
On Linux, the C++ ROOT framework used as backend is bundled in the ROOT_jll Julia package that is installed automatically. This is the default and recommended option on Linux.
Use of C++ ROOT framework software installed outside of Julia is also possible. For this, the ROOTprefs.jl should be used to change the default backend installation mode. This has to be done before the ROOT module is imported. Each ROOT.jl package is tight to one or few C++ ROOT versions: see the list in section Backend versions.
The ROOT_jll package does not include yet the libraries for MacOS (*). Therefore, the user needs to take care of installing the C++ ROOT framework of the proper release: see next section for the required or do import ROOT, which will show a message specifying the required release if not accessible yet.
Once the C++ ROOT framework installed, first run root-config --version to make sure it is accessible from the shell environment and the release is correct, then start Julia and import the ROOT module. The library providing the Julia bindings will be compiled.
If after an upgrade of ROOT.jl, you needed to also upgrade the C++ framework installation and the installation path changed, then run using ROOTprefs; set_ROOTSYS() in Julia before importing the ROOT module in order to update the path.
(*)The package ROOT.jl will still be installed, but be essentially empty on this platform.
| Julia package version |
Default ROOT version |
Other supported version(s) |
|---|---|---|
| 0.4.0 | 6.32.08 | 6.32.06 |
| 0.3.1—0.3.2 | 6.32.02 | |
| 0.3.0 | 6.30.04 |
The Julia ROOT package version uses ROOT release 6.32.08. If a ROOT installation is found in the default binary search paths (PATH environment variable) with this version, then it will be used. Otherwise, ROOT will be installed using [Conda](https://github.com/JuliaPy/Conda.jl) into `$HOME/.julia/Conda/3`.
C++ classes are mapped to Julia struct with the same name. Non-static class methods are mapped to Julia methods, with the same name, taking the class instance as first argument followed by the arguments of the C++ methods. The double column :: used for C++ namespace and for static fields in C++ is mapped to the ! symbol: static function f of class A, A::f() becomes A!f() in Julia.
Non-static methods of C++ classes are exported, the other symbols (classes, global functions, etc) are not.
import ROOT
ROOT.demo()#Import the module.
using ROOT
# An alias for ROOT
const R = ROOT
# Create a ROOT histogram, fill it with random events, and fit it.
h = R.TH1D("h", "Normal distribution", 100, -5., 5.)
R.FillRandom(h, "gaus")
#Draw the histogram on screen
c = R.TCanvas()
R.Draw(h)
#Fit the histogram wih a normal distribution
R.Fit(h, "gaus")
#Save the Canvas in an image file
R.SaveAs(c, "demo_ROOT.png")
#Save the histogram and the graphic canvas in the demo_ROOT_out.root file.
f = R.TFile!Open("demo_ROOT_out.root", "RECREATE")
R.Write(h)
R.Write(c)
Close(f)More examples can be found in the examples directory.
See input list in misc/ROOT.wit
-
I/O and general classes:
TROOT,TBrowser,TSystem,TApplication,Rtypes,TNamed,TObject,TTree,TBranchPtr,TLeaf,TBranch,TTreeReader,TTreeReaderValue,TTreeReaderArray,TCanvas,TRandom,TDirectory,TDirectoryFile,TFile,TEntryList,TKey,TObjArray,TVectorD,TVectorF -
The complete set of classes of the Histogram library (except
TMultiGraph):
`Foption`, `HFitInterface`, `TAxis`, `TAxisModLab`,, `TBackCompFitter`, `TBinomialEfficiencyFitter`, `TConfidenceLevel`, `TEfficiency`, `TF12`, `TF1AbsComposition`, `TF1Convolution`, `TF1`, `TF1NormSum`, `TF2`, `TF3`, `TFitResult`, `TFitResultPtr`, `TFormula`, `TFractionFitter`, `TGraph2DAsymmErrors`, `TGraph2DErrors`, `TGraph2D`, `TGraphAsymmErrors`, `TGraphBentErrors`, `TGraphDelaunay2D`, `TGraphDelaunay`, `TGraphErrors`, `TGraph`, `TGraphMultiErrors`, `TGraphSmooth`, `TGraphTime`, `TH1C`, `TH1D`, `TH1F`, `TH1`, `TH1I`, `TH1K`, `TH1S`, `TH2C`, `TH2D`, `TH2F`, `TH2`, `TH2I`, `TH2Poly`, `TH2S`, `TH3C`, `TH3D`, `TH3F`, `TH3`, `TH3I`, `TH3S`, `THistRange`, `THLimitsFinder`, `THnBase`,, `THnChain`, `THn`, `THnSparse`, `THnSparse_Internal`, `THStack`,, `TKDE`, `TLimitDataSource`, `TLimit`, `TMultiDimFit`, `TMultiGraph`, `TNDArray`, `TPolyMarker`, `TPrincipal`, `TProfile2D`,, `TProfile2Poly`, `TProfile3D`, `TProfile`, `TScatter`, `TSpline`, `TSVDUnfold`, `TVirtualFitter`, `TVirtualGraphPainter`, `TVirtualHistPainter`, `TVirtualPaveStats`
- The classes from the Geometry library:
`TGDMLMatrix`, `TGeant4PhysicalConstants`, `TGeant4SystemOfUnits`, `TGeoArb8`, `TGeoAtt`, `TGeoBBox`, `TGeoBoolNode`, `TGeoBranchArray`, `TGeoBuilder`, `TGeoCache`, `TGeoCompositeShape`, `TGeoCone`, `TGeoElement`, `TGeoEltu`, `TGeoExtension`, `TGeoGlobalMagField`, `TGeoHalfSpace`, `TGeoHelix`, `TGeoHype`, `TGeoManager`, `TGeoMaterial`, `TGeoMatrix`, `TGeoMedium`, `TGeoNavigator`, `TGeoNode`, `TGeoOpticalSurface`, `TGeoParaboloid`, `TGeoPara`, `TGeoParallelWorld`, `TGeoPatternFinder`, `TGeoPcon`, `TGeoPgon`, `TGeoPhysicalConstants`, `TGeoPhysicalNode`, `TGeoPolygon`, `TGeoRCPtr`, `TGeoRegion`, `TGeoScaledShape`, `TGeoShapeAssembly`, `TGeoShape`, `TGeoSphere`, `TGeoStateInfo`, `TGeoSystemOfUnits`, `TGeoTessellated`, `TGeoTorus`, `TGeoTrd1`, `TGeoTrd2`, `TGeoTube`, `TGeoTypedefs`, `TGeoUniformMagField`, `TGeoVector3`, `TGeoVolume`, `TGeoVoxelFinder`, `TGeoXtru`, `TVirtualGeoConverter`, `TVirtualGeoPainter`, `TVirtualGeoTrack`, `TVirtualMagField`
Complete list of bound ROOT types, including classes whose methods are not exposed to Julia and list of wrapped methods
See list in misc/jlROOT-report.txt.
If you miss a ROOT class and have a minimum of programming skills, we invite you to check out the code from the ROOTjl-generator repository. The generate.jl script of ROOTjl-generator is used to generate the contents of the src directory, deps directory and Project.toml file of the ROOT.jl package.
The class should be added in the list defined by the input parameter of the src/ROOT.wit.in configuration file. At best, it will work out of the box. With a bit less luck, it will fail but it can be fixed by adding few methods in the src/jlROOT-veto.h to exclude them from the Julia binding. At worst, it will require changes in the Wrapit! wrapper generator.
A wish list will also be added in the ROOTjl-generator to prioritize the ROOT classes to add.
New contribution is welcome. Here is a list of contributions ideas:
- Add support for a not-yet-supported ROOT class: see previous section.
- Develop a Julia script that converts the ROOT Doxygen API documentation into Julia documentation (docstring. The xml output format of Doxygen, designed to be parsed by a program, will be used. Contact @grasph if you are interested in this project or send a message to Julia discourse - HEP category
- Contribute to WrapIt!, the engine that generates the wrapping code needed by CxxWrap C++/Julia interface.
- Port a ROOT tutorial into Julia to be be added to the examples.