SHOE (Software for Hadrontherapy Optimization Experiment) - The FOOT software page

Tasks & Organization

Here you can find the full list and description of the software tasks.

Getting started with the FOOT software

SHOE is made available to users through the git INFN server.

The SHOE software is formed by Simulation code and a Reconstruction code.

The software is organized in folders.

• G4Simulation: contains everything is needed to run the simulation with Geant4. Details can be found in the Simulation page.
• Simulation folder: contains everything is needed to run the simulation with FLUKA. Details can be found in the Simulation page.
• libs folder: contains the framework and all the classes needed to handle the reconstruction of all the subdetectors, the event display and the global event reconstruction.
• Reconstruction folder: contains the executables and macros to run the events reconstruction.

Before downloading the software you have to:

• register on the git lab portal (baltig).
• ask to the SHOE mantainer ( Alessio Sarti) the right to download the software package.

Once you have both a baltig account and the download privileges , you can start the real download.

Download

You can download the software from shell using the following commands (using the account and pwd that you use to access the baltig site):

git clone https://xxxx@baltig.infn.it/asarti/shoe.git

where xxxx has to be replaced with the username registered in the baltig site.

Or you can download the zip file directily from the baltig page using the download button on the right hand side.

A stable version of the external GenFit software will be also downloaded.

A quickstart guide to git can be found here.

Prerequisites

In short:

• gcc >= 8
• properly installed & working ROOT

See below for the details...

The only real pre-requisiteis for the shoe installation is to have a working/fully equipped ROOT installation available. Different 'setup up' procedures are needed depending on the machine you are using. Detailed instructions are given below for the Trie-3 setting up. Here-after you can find the instructions for setting up your personal/local machine.

A pre-requisite to compile the latest versions of the Master and NewGeom branches is related to the gcc compiler version. gcc versions from 8, onwards have been succesfully tested and are capable to compile the code. Check, before starting, that your local installation / machine, provides you a compiler with version >= 8.

The code can be also downloaded and installed on a local machine. As a pre-requisite you need to check that you have a proper ROOT configuration. This can be checked by issuing the command

root-config --features

If the eve libs and the minuit2 libs are not installed (not the default if you have a custom ROOT installation) you can go in the build dir and enable them via:

cmake  pathtoroot  -Drpath=ON -Dminuit2=ON -Dcxx14=ON -DCMAKE_BUILD_TYPE=Debug

This command takes also care of setting the standard c++14 in Root dictionary building, as needed by the Master and development branches.

Once ROOT is properly installed, go above and follow the 'with cmake' steps to compile.

Few users, reported so far, different problems with missing libraries in the standard ROOT pre-configuration. In that case we strongly advise the people to write to the foot-software mailing list rreporting the problem and asking for help (debugging ROOT missing libraries can be difficult and time consuming). As an example we show how to fix the missing GLew libraries on BigSur and ROOT 6.24/06:

"-Dbuiltin_glew=ON" and "-Druntime_cxx_modules=OFF" 

had to be added. This is System, Installation, and Software dependent so, do not refer to that as a general solution for all evil. If you find problems during the installation, write to the mailing list!

Compile and Run

To compile and run the simulation and reconstruction code, you need to refer to the dedicated Simulation and Reconstruction software pages.

Some preliminary information on how to run is provided at this link FOOT_HowTo.pdf... For more detailed instructions, see below.

The shoe software is organized in branches. First of all you need to identify the branch that you want to start with and activate it. For example, if you want to start with the master branch, you can do the following (inside the shoe directory):

git checkout master

Once the branch has been activated, you can proceed with the following installations.

The shoe software can be compiled and installed using cmake.

Inside the shoe folder, it is possible to compile the code using the following syntax

mkdir build
cd build
cmake /path/to/shoe/ -DCMAKE_BUILD_TYPE=Debug
make

Cmake will compile all the software and create, inside the build folder, the executables needed to process the data and simulation files.

Attention: starting from the latest release of the NewGeom branch (Aug 2020), the cmake behaviour has changed a little (since the amount of files that have to be copied around is increasing): the files in config, geomaps, calib, data and macros folder are NOT copied anymore unless the option FILECOPY is set on ( default wise being off). To switch on the option you need to add :

cmake path/to/shoe -D FILECOPY=ON

Before compiling it is needed to setup a proper environment, in order to have cmake working properly.

Decode raw data and MC within Shoe

After the compilation of a working Shoe installation you're ready to decode data and MC to perform a local or global reconstruction

Some preliminary information on how to run is provided at this link. On the same link Doxygen Documentation for Shoe is present.

For more detailed instructions, see the FOOT software tutorial page.

Download the code and run it on the Bologna Tier-1

The code can be downloaded installed and run on the CNAF machines through the following steps.

Get a CNAF account. To do that get in contact with Roberto Spighi and follow the instructions on the CNAF site (compiling the form that can be downloaded from here).

Access the Tier-1 and Tier-3

Access the Tier-1 and Tier-3 machine with your CNAF account (userXXX).

Log into the gateway (bastion):

ssh -X -Y -C userXXX@bastion.cnaf.infn.it

Access the Tier-1 machine with:

ssh -X -Y -C userXXX@ui01-foot.cr.cnaf.infn.it

(check which login has been assigned to you on the machine, in principle same as in bastion)

Access the Tier-3 machine with:

ssh -X -Y -C userXXX@uibo-foot-01.cr.cnaf.infn.it

(check which login has been assigned to you on the machine, in principle same as in bastion)

Setup the environment and install SHOE on Tier-1

Guidelines from Roberto Zarrella for the usage of the Tier1 resources.

1) When you login to the local machine ( ui01-foot.cr.cnaf.infn.it, accessible from bastion), you will be located in you home directory

/home/FOOT-T3/<USER>

This directory is NOT meant to store processed data since the "home" storage is limited and shared by all foot users. Please, use this directory only to store minor files, e.g. your software installation (SHOE, macros, etc.).

2) Processed data MUST be stored inside the directory:

/storage/gpfs_data/foot/

Make sure to create your own directory inside this space:

/storage/gpfs_data/foot/<USER>

and put your processed files inside it.

3) A shared installation of ROOT 6.28.00 is available for everybody in the folder:

/opt/exp_software/foot/root

4) A shared file located in:

/opt/exp_software/foot/root_shoe_foot.sh

can be used to setup your work environment. You can launch the command:

 $ source /opt/exp_software/foot/root_shoe_foot.sh 

This will load the correct versions of gcc, cmake, python and ROOT needed to correctly compile SHOE on the Tier1.

5) SHOE has to be installed in /storage/gpfs_data/foot/ under your own directory:

cd /opt/exp_software/foot/
mkdir /opt/exp_software/foot/<USER>

Now you are ready to install SHOE according to the Getting started with the FOOT software session.

6) A bash script located in shoe in:

shoe/Reconstruction/scripts/runShoeBatchT1.sh

can be used to process data in parallel using the condor resources. Information on how to run the script and correctly handle the cleanup needed afterwards is given at the beginning of the file. A Shoe Installation guide is also included in the script information in order to have a proper environment setup to run shoe on Tier-1. READ CAREFULLY the info in the script before running it.

7) A bash script located shoe in:

shoe/Reconstruction/scripts/runShoeBatchT1_MC.sh

can be used to run SHOE on Monte Carlo simulated data using the HTCondor suite on Tier1. It is conceived to run on MC FILES. The script processes a single MC file launching a number of jobs in condor so that each of them processes ~20k events.

Information on how to run the script and correctly handle the cleanup needed afterwards is given at the beginning of the file. A Shoe Installation guide is also included in the script information in order to have a proper environment setup to run shoe on Tier-1. READ CAREFULLY the info in the script before running it.

The campaign manager

In order to properly configure the software to handle different data and MC relative to different campaigns/test beams and to use the proper calibration and configuration files when processing a given subset of runs in a given campaign, a campaign manager has been developed.

Documentation

• The first (Jun 2020 version) slides documenting the implementation can be found here. (Consider that wrt the slides, the ForceSync flag has been not implemented as discussed during the meeting).
• An updated version is available here: CampManager_upd.pdf (Jul 2020)
• Further updates are documented here: CampManager_upd1.pdf (Aug 2020)

Informations

The campaign manager implementation has been performed inside TAGbase:

The implementation is done inside:

 Libraries/TAGbase/TAGcampaignManager.cxx
 Libraries/TAGbase/TAGcampaignManager.hxx    

The relevant files, for each campaign are kept inside the folder

Reconstruction/cammaps

Here you can find the master file: FOOT_cam.map

I have made several changes in the classes that load the files to avoid local versioning, now the versioning is done by the campaign manager. I’ve also change name and location of files, mainly calibration files that has been moved to the calib folder and with an .cal extension (accordingly to last the SW meeting).
The versioning of the file, if needed, is done with respect to the run number.

For the moment the campaign manager is able to handle 4 main “experiments” (see FOOT_cam.cam file) :

 [[CamName][]]CamName:    "12C_200"
CamDataMC:    1
CamSum: "Simulation data for 12C on 12C (5mm target) @ 200MeV/u"

CamName:    "16O_200"
CamDataMC:    1
CamSum: "Simulation data for 16O on 12C (run 6) or C2H4 (run 1-5) for 5mm target thickness @ 200MeV/u"

CamName:    "GSI"
CamDataMC:    0
CamDate: "5-8 April 2019"
CamSum: "Test experiment with ST+BM+VTX+TW?"

CamName:   "HE_MC"
CamDataMC:    1
CamSum: "Simulation data for 4He on 12C (5mm target) @ 700MeV/u?

The master file refers to the campaign files for each campaign already available

• Gsi 2019 : Reconstruction/level0/cammaps/GSI.cam

• MC (He) : Reconstruction/level0/cammaps/HE_MC.cam

• MC (Standard) : Reconstruction/level0/cammaps/STD.cam

For each campaign the decision about which detectors have to be reconstructed is left to the user!

The detectors that have to be included are listed in the config/FootGlobal.par file.

The files needed by the campaign manager are provided in each subfolder and should follow the convention described hereafter.

- geo files:
./geomaps/TAXXanyname.geo

- configuration files:
./config/TAXXanyname.cfg

- mapping files:
./config/TAXXanyname.map

- calibration files:
./calib/TAXXanyname.cal

where XX = ST, BM, TG, VT, IT, MSD, TW, CA

Currently the CampaignManager is available only under the NewGeom branch. Once the tests will be finalised, it will be merged in the Master branch.

Contributing to the software development.

To contribute using the git framework you need the proper rights: youcan ask for them to the FOOT project administrators.

A dedicated page for the software developers has been setup.