Example 3 Getting ROOT Output With Fluka -------------------------------------------------------- UPDATED===10.10.2008.09.13.19 TITLE===Getting ROOT Output With Fluka TYPE===database -------------------------------------------------------- --------------------------------------------------------

Riccardo Brunetti (INFN, Italy); 9 May 2003
Vasilis Vlachoudis (CERN, Geneve); 6 March 2008

--------------------------------------------------------

R. Brunetti
Last Updated by Vasilis Vlachoudis

Overview ::::::::::::

In this document we describe a possible approach to the problem of obtaining the output of a FLUKA simulation in the form of a ROOT file, like a ROOT tree.

The FLUKA program comes to the users as a huge library of routines entirely written in FORTRAN and is originally designed to provide an output in its own format, that can be manipulated with special tools provided with the code.

Recently, however, a number of users changed their frameworks to the C/C++ environment and started to use ROOT as the main analysis tool, hence a simple method to merge the two packages could be useful.

On the other hand the FLUKA package, as it is now, is the result of many years of development and to rewrite it in some OO language, in order to completely integrate it in the ROOT framework, (even it is possible in principle) could be very dangerous.

The procedure we will describe reduces as much as possible the changes in the FLUKA fortran routines, simply adding calls to external library functions where needed inside the original FLUKA users routines.

The standard scoring mechanisms of FLUKA are strongly recommended for most of the cases, sometimes a custom scoring is needed. While it can be convinient to create customised histograms and n-tuples in ROOT one has to pay special attention on how to interpret the information he is scorring.

The use of an External C/C++ Library ::::::::::::

Instead of rewriting the FLUKA users routine in some language other than FORTRAN, the simplest approach is the one of calling from inside them user C/C++ functions from a custom external library.

In doing this, the main problem is the one of passing the needed variables to the external function. Some of them are locally available inside the FORTRAN user subroutine or entry point, while others are placed inside global COMMON BLOCKS.

In the first case, it's very simple to pass the variables to the C/C++ function; this operation can be performed through the function's arguments, provided to follow some simple rule.

In the second case one has to include some header files in the C/C++ code, that make the FORTRAN COMMON BLOCKS available through C/C++ globally defined structures.

Once the problem of the variables has been solved, the C/C++ library and the FLUKA FORTRAN user routines can be compiled separately, to obtain the required object files to be linked into the FLUKA executable.

It is important to remember that, in order to avoid problems of undefined symbols when linking (the symbol's names follow different rules for C++ and fortran compilers), all the external C/C++ functions must be declared inside external "C" blocks.

Compiling and Linking ::::::::::::

The FORTRAN and C/C++ code can be compiled separately. For the modified FLUKA user routines the script fff can be simply used without any modifications, while for the C/C++ library a Makefile can be prepared.

The Makefile should produce an object file containing the library part of the code and a ROOT shared object that can be loaded dynamically inside the ROOT CINT environment, containing the information about the custom classes used in the program.

To finally link everything to the FLUKA executable, the lfluka is used, including the required ROOT libraries and the custom shared object previously created.

A Simple Example ::::::::::::

We give here a simple example of an external C++ library which allows to obtain the output of the a simple example root.inp input file in the form of a ROOT tree, that can be saved on file and then opened and analyzed. The main steps are the following:

Define a class Results, containing the information we want to extract from FLUKA and to save on the tree.
The class header shown below contains the same information saved in the original example. It must be pointed out that this first step is not mandatory. A ROOT tree can also be filled with simple variables.

#ifndef ROOT_Results
#define ROOT_Results

#include "TObject.h"

class Results : public TObject {

 private:

  Int_t ij;
  Double_t econtr, xa, ya, za, txx, tyy, tzz;

 public:

  Results() : ij(0), econtr(0), xa(0), ya(0),
    za(0), txx(0), tyy(0), tzz(0) {}
  Results(Int_t ijj, Double_t econtrr, Double_t xaa,
	  Double_t yaa, Double_t zaa,
	  Double_t txxx, Double_t tyyy, Double_t tzzz);
  virtual ~Results();

  ClassDef(Results,1);

};

#endif

Write a C++ library of functions which acts as the interface between FLUKA and ROOT.

The library functions will allow to open the ROOT file, to create the ROOT tree and to fill it with objects of class "Results". The library used in this example is shown below.

All the functions are defined inside extern "C" blocks, to avoid undefined symbols when linking. The first function myusrini opens the ROOT file and creates the ROOT tree to be filled, the second function treefill fills the tree with objects of class "Results", after creating them, and the last function fileclose closes the ROOT file. It must be noted that the include directives concerning the ROOT classes have been added and that the way the values are passed to the function treefill follows the requirements mentioned in 0.2.

#ifndef __CFORTRAN_LOADED
#include "cfortran.h"
#endif

#include 

#include 
#include "Results.h"
#include 
#include 

#ifndef WIN32
#define myusrini myusrini_
#else
#define myusrini MYUSRINI
#endif

static TFile *RootFile = 0;
static TTree *RootTree = 0;
static Results *TheResults = 0;

extern "C" {
  void myusrini (Double_t &pluto)
  {
    printf("Executing MYUSRINI\n");
    RootFile = new TFile("Out.root","recreate");
    RootTree = new TTree("ResultsTree","Protons");
    RootTree->Branch("Results", "Results", &TheResults, 64000, 1);

    printf("%f\n", pluto);

  }
}

#ifndef WIN32
#define treefill treefill_
#else
#define treefill TREEFILL
#endif

extern "C" {
  void treefill(Int_t &ij, Double_t &econtr, Double_t 
, Double_t &ya, Double_t &za,
		Double_t &txx, Double_t &tyy, Double_t &tzz)
  {
    if (TheResults) {
      delete TheResults;
      TheResults = 0;
    }

    TheResults = new Results(ij, econtr, xa, ya, za,
			     txx, tyy, tzz);
    RootTree->Fill();
  }
}

#ifndef WIN32
#define fileclose fileclose_
#else
#define fileclose FILECLOSE
#endif

extern "C" {
  void fileclose()
  {
    if (TheResults) {
      delete TheResults;
      TheResults = 0;
    }
    RootTree->Write();
    RootFile->Close();
  }
}

Place the needed function calls inside the FORTRAN user routines.

Now, the fortran user routines: usrini.f, usrout.f and mgdraw.f can be edited and modified as shown below

As can be seen, in this case the values to be stored in the ROOT tree are passed as a calling arguments of the function treefill(....).

usrini

...
      LUSRIN = .TRUE.
* *** Write from here on *** *
      PIPPO = 2.5D0
      CALL myusrini(PIPPO);
...

usrout


...
      CALL FILECLOSE
...

mgdraw

...
*
*======================================================================*
*                                                                      *
*     Boundary-(X)crossing DRAWing:                                    *
*                                                                      *
*     Icode = 1x: call from Kaskad                                     *
*             19: boundary crossing                                    *
*     Icode = 2x: call from Emfsco                                     *
*             29: boundary crossing                                    *
*     Icode = 3x: call from Kasneu                                     *
*             39: boundary crossing                                    *
*     Icode = 4x: call from Kashea                                     *
*             49: boundary crossing                                    *
*     Icode = 5x: call from Kasoph                                     *
*             59: boundary crossing                                    *
*                                                                      *
*======================================================================*
*                                                                      *
      ENTRY BXDRAW ( ICODE, MREG, NEWREG, XSCO, YSCO, ZSCO )
      IF(MREG.EQ.3.AND.NEWREG.EQ.2) THEN
         IF( JTRACK.EQ.1) THEN
            IF(ETRACK.GT.AM(JTRACK)) THEN
               XTUP(1) = JTRACK
               XTUP(2) = ETRACK-AM(JTRACK)
               XTUP(3) = XSCO
               XTUP(4) = YSCO
               XTUP(5) = ZSCO
               XTUP(6) = CXTRCK
               XTUP(7) = CYTRCK
               XTUP(8) = CZTRCK
               CALL treefill(JTRACK,
     +                       (ETRACK-AM(JTRACK)),XSCO,YSCO,ZSCO,
     +                       CXTRCK,CYTRCK,CZTRCK)
            ENDIF
         ENDIF
      ENDIF
      RETURN
...

Compile the fortran routines with the usual fff script.
- $FLUPRO/flutil/fff usrini.f
- $FLUPRO/flutil/fff usrout.f
- $FLUPRO/flutil/fff mgdraw.f
Compile the C++ part of the code using a Makefile. Actually the Makefile contains also the compilation of the fluka routines and the linking.

The result of the compilation will be a file FluLib.o with the external library symbols, and a shared library libResults.so containing the information on the class Results, it's attributes and (if present) it's methods. This shared library can be dynamically linked inside the root interactive environment.
Link everything together in the FLUKA executable using the modified lfluka script.

In order to link the custom shared object libResults.so> and the ROOT libraries, it is sufficient to add the last line to the final command (provided the ROOT packages is correctly installed).

Finally, the executable can be produced as usual:

$FLUPRO/flutil/lfluka -m fluka usrini.o usrout.o histin.o mgdraw.o FluLib.o libResults.so -o rootfluka

WARNING: Please be sure you have the root library directory defined in the dynamic libraries path. To do so please add the path in the LD_LIBRARY_PATH variable, and the CURRENT directory:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/root-path/lib:`pwd`

The `pwd` is used to add the current directory which will be needed later for FLUKA to find the libResults.so library.

As obvious, the libraries FluLib.o and libResults.so must also be linked. All the above steps are included inside the Makefile. Type:
- make clean
- make
to get all modules compiled and the rootfluka executable linked
Run the program using the usual rfluka script. Now, the executable is ready to run. The usual command:

FLUTIL/rfluka -e rootfluka -N0 -M1 inp-file

starts the fluka run, which proceeds in the standard way. It is important to remember to set the environmental variable in order to include the path to the directory in which the program is running.
(Finally) Open the root file browse the tree and make some plots of the physical variables saved. The ROOT tree can be analyzed inside the ROOT interactive environment, after loading the shared object libResults.so. The content can be scanned through the ROOT tree browser (as in Figure 1 or using an apposite CINT macro. Start root and give the command new TBrowser(). Select in the files the root001_Out.root file and inspect in "ROOT Files" branch the contents of the ntuple we just created with FLUKA.

Figure 2 shows the proton energy distribution from the FLUKA simulation.

Figure 1: ROOT tree browser showing the variables retrieved from FLUKA run

Figure 2: Example of a distribution of an output variable

Example Files:

Conclusions ::::::::::::

Using an external library it is possible to merge piece of codes written in C/C++ with the FLUKA package. This allows to build custom functions which act as interfaces with the ROOT framework, in order, for example, to obtain the output of the simulation in the form of ROOT files.

The changes in the original fortran code are minimal, and simply consist in adding some external function calls where needed, without touching the core of the FLUKA program.

This approach can thus be considered as an alternative to the h2root method and can give more flexibility for those people who want to write custom pieces of code in C or C++ and to use ROOT for the following data analysis.