Documentation / User's manual in Python :

From Uranie version 4.9, only Python greater than 3.8 can be used due to the use of ROOT version v6.32 (Python 2 is deprecated). Two words of caution about this:

ls -l `which python`  && ls -l `which python3`

lrwxrwxrwx. 1 root root 9  8 févr.  2023 /usr/bin/python -> ./python3
lrwxrwxrwx. 1 root root 10  8 févr.  2023 /usr/bin/python3 -> python3.11

Today's operating systems usually embed both versions of python and many of these still use the version 2 as a reference (see the block above with both python versions). Given the fact that one can have as many different python versions as possible, it should be possible to specify which one is of interest for the ongoing installation. The following lines should be used to specify the python version to be used, providing that the "dev" packages are indeed installed for this version:

 cmake ${PATH_TO_ROOT_SOURCES} -DPYTHON_EXECUTABLE=${PATH_TO_PYTHON_BIN} -DPYTHON_INCLUDE_DIR=${PATH_TO_PYTHON_INC}  -DPYTHON_LIBRARY=${PATH_TO_PYTHON_LIB} ...

These three specific python flags should be used both for ROOT and Uranie in a coherent way in order to install both platforms with a chosen Python's version. To get the recommended cmake line both for ROOT and Uranie see the README provided with the Uranie-sources.

In order to access ROOT and Uranie from Python, we need to ensure that some environment variables are properly set:

When the environment variables for Uranie and PyROOT are properly set, we can access to the classes as follows:

# Load the ROOT module
import ROOT

# Create a new data server object
tds=ROOT.URANIE.DataServer.TDataServer("myTDS","DataServer for python example")

# Add an attribute to the data server
tds.addAttribute( ROOT.URANIE.DataServer.TNormalDistribution("x", 0.0, 1.0) )

# Create a sampler object
sampler = ROOT.URANIE.Sampler.TSampling(tds, "lhs", 1000)

# Generate data
sampler.generateSample()

# Display the histogram of attribute x
tds.draw("x")

This code should produce a graphic as the one displayed in Figure I.2.

Figure I.2. Histogram produced using PyROOT

The instructions above can be executed either through the Python command line, or be written in a file (myscript.py in the example below) and run using the command:

python -i myscript.py

The -i option allows to stay in the Python environment at the end of the execution. This prevents the produced image to be automatically closed.

In the previous example, we can see that the access to Uranie's classes is somewhat tedious. In order to ease the process, a set of specific modules have been created. We call it the PyURANIE interface.

It is then possible to re-write the previous example using these specific modules:

# Load the URANIE module
from ROOT import URANIE

# Load the DataServer and Sampler modules
from URANIE import DataServer, Sampler

# Create a new data server object
tds = DataServer.TDataServer("myTDS","DataServer for the python example")

# Add an attribute to the data server
tds.addAttribute( DataServer.TNormalDistribution("x", 0.0, 1.0) )

# Create a sampler object
sampler = Sampler.TSampling(tds, "lhs", 1000)

# Generate data
sampler.generateSample()

# Display the histogram of attribute x
tds.draw("x")

The access to ROOT classes is provided through the ROOT module.

The PyURANIE interface also allows to use the command:

from URANIE.DataServer import *

This command loads all the classes of the DataServer module in Python and makes them directly accessible. It is similar to the C++ command using namespace URANIE::DataServer. However, in Python, using this command is not recommended. It can create name conflicts and use a large amount of memory.

Finally the equivalent of the rootlogon.C has been written for python, and is called rootlogon.py. It is composed of two parts, as for the one in C++, the second one being the exact equivalent. The first one, on the other hand, is a bit different and this difference arises from the way the language are dealing with loading modules. By doing

from rootlogon import DataServer

one can, for instance, directly creates a TDataServer by doing

toto=DataServer.TDataServer()

The example of rootlogon file for python is the following:

import ROOT

# Create shortcuts if uranie exists
urasys = ROOT.TString(ROOT.gSystem.Getenv("URANIESYS"))
if not urasys.EqualTo(""):
    from ROOT.URANIE import DataServer as DataServer
    from ROOT.URANIE import Sampler as Sampler
    from ROOT.URANIE import Launcher as Launcher
    from ROOT.URANIE import Relauncher as Relauncher
    from ROOT.URANIE import Reoptimizer as Reoptimizer
    from ROOT.URANIE import Sensitivity as Sensitivity
    from ROOT.URANIE import Optimizer as Optimizer
    from ROOT.URANIE import Modeler as Modeler
    from ROOT.URANIE import Calibration as Calibration
    from ROOT.URANIE import UncertModeler as UncertModeler
    from ROOT.URANIE import Reliability as Reliability
    from ROOT.URANIE import XMLProblem as XMLProblem
    from ROOT.URANIE import MpiRelauncher as MpiRelauncher
    pass

# General graphical style
white = 0

# PlotStyle
ROOT.gStyle.SetPalette(1)
ROOT.gStyle.SetOptDate(21)

# Legend
ROOT.gStyle.SetLegendBorderSize(0)
ROOT.gStyle.SetFillStyle(0)

# Pads
ROOT.gStyle.SetPadColor(white)
ROOT.gStyle.SetTitleFillColor(white)
ROOT.gStyle.SetStatColor(white)

#  ====================  Hint ====================
#
#    Might be practical to store this in a convenient place (for instance
#    the ".python" folder in your home directory) or any other place where
#    your $PYTHONPATH is pointing.
#
#    example : export PYTHONPATH=$PYTHONPATH:${HOME}/.mypython/
#
#    It should then be called as "from rootlogon import " + the list of module
#    This would replace the shortcuts created and import done in the rest of
#    the scripts
#
#    Many style issue can be set once and for all here.
#    toto=DataServer.TDataServer()
#

This section introduces some frequently asked methods to help handling data and objects (as many objects proposed are either ROOT or C++-based). Some of these methods are used throughout the examples in the macros in Chapter XIV, but the aim here is to gather everything that might be of use for a python user that would like to put his hand on Uranie. Most of this methods rely on ROOT version being greater than 6.20 but the modification are small if one uses older versions (as long as it is greater than6).

"""
Example of TDataServer into numpy array converter
"""
import numpy as np
from rootlogon import DataServer

# import data into a dataserver
tds = DataServer.TDataServer("tds", "pouet")
tds.fileDataRead("myData.dat")
print("Dumping tds")
tds.scan()

# Define the list of variable to be read
VarList = "x:y"

# Create an array by defining the shape and the type (this array is a matrix)
TdsData = np.empty(shape=(tds.getNPatterns(), len(VarList.split(":"))),
                   dtype=np.float64)
# Dump the data into the created array (the last field empty unless a select is done on the sample)
tds.getTuple().extractData(TdsData, TdsData.size, VarList, tds.getCut().GetTitle())

# Check the content
print("Dumping the array")
print(TdsData)

# Create a new Dataserver and feed it
tds2 = DataServer.TDataServer("brandnew", "pouet")
# Add the attribute in the dataserver and create the tuple
for name in VarList.split(":"):
    index = VarList.split(":").index(name)
    VarData = np.ascontiguousarray(TdsData.transpose()[index])
    tds2.addAttributeUsingData(name, VarData, VarData.size)

print("Dumping new tds")
tds2.Scan("*")

"""
Example of TMatrix into numpy array conversion
"""
import numpy as np
import ROOT

# define the number of rows and columns
nrow = 3
ncol = 5

# Initialise and fill a TMatrixD
InMat = ROOT.TMatrixD(nrow, ncol)
for i in range(nrow):
    for j in range(ncol):
        InMat[i][j] = ROOT.gRandom.Gaus(0, 1)

print("Original TMatrixD")
InMat.Print()

# Create the ndarray with the good shape
mat_version = np.frombuffer(InMat.GetMatrixArray(), dtype=np.float64,
                            count=nrow*ncol).reshape(nrow, ncol)
print("Numpy array transformation")
print(mat_version)

# Back to another TMatrixD
OutMat = ROOT.TMatrixD(nrow, ncol)
OutMat.SetMatrixArray(mat_version)
print("\nRecreated TMatrixD")
OutMat.Print()

"""
Example of C++ function in python
"""
import numpy as np
import ROOT

# Loading a function
ROOT.gROOT.LoadMacro("UserFunctions.C")

# Preparing inputs and outputs
inp = np.array([1.2, 0.8])  # input values
out = np.zeros(4)  # output values initialise with 4 zeros

# Call the method, through the ROOT interface
ROOT.operation(inp, out)

# Print the result
print("Results are")
print(out)

"""
Example of C++style reference usage
"""
from ctypes import c_double  # for ROOT version greater or equal to 6.20
from rootlogon import DataServer

# create a dataserver and read data
tds = DataServer.TDataServer("pouet", "foo")
tds.fileDataRead("myData.dat")

# compute quantile (this method get the results 'by reference')
proba = 0.9  # ROOT.Double(0.9) for ROOT version lower than 6.20
quant = c_double(0.0)  # ROOT.Double(0.0) for ROOT version lower than 6.20

# Compute the quantile and dump the value returned by reference
tds.computeQuantile("x", proba, quant)
print("Result is ")
print(quant.value)

The PyROOT environment has a few specificities which it is preferable to be aware of (the rest being discussed already in Section I.2.6). The following websites help to learn about them:

Finally, reference [PyUranie] introduces (in French) some of these problems and shows examples on how to use Uranie with PyROOT.