This repository hosts code examples that use uproot, awkward array, and other core python packages to load and analyse FCC simulation.
The simplest way to access the notebooks is using the CERN Swan service, which provides access via web browser to a CERN machine with a full LCG Python 3 setup. You can find details of Swan here. Using Swan, it is easy to open Jupyter notebooks on the CERN machine and interact with them using your browser.
Once you are in Swan, a few more Python packages are required. This can be done by clicking the terminal icon in Swan, which will open a new page with a terminal. You will be placed in /eos/user/j/jbloggs, your EOS user area (if your name is Joe Bloggs!). In the terminal, do:
pip install --user awkward1 particle
At the moment, we need the master release of the uproot4 package (eventually we can also just install the stable release with pip). To get the master and install it, do:
git clone https://github.com/scikit-hep/uproot4.git
cd uproot4
python setup.py install --user
To donwload the fcc_python_tools project code in Swan, click on the cloud icon with an arrow on the right of your My Projects screen. In the box which appears, paste this link:
https://github.com/donalrinho/fcc_python_tools.git
This will place fcc_python_tools into /eos/user/j/jbloggs/SWAN_projects/fcc_python_tools.
Once you have downloaded fcc_python_tools, you need to reconfigure Swan to source the fcc_python_tools/setup/setup.sh script. This script adds the fcc_python_tools module to PYTHONPATH, and makes the base directory of the project (ANAROOT) known. To do this, click the three dots in the top right of your Swan browser window. Select the Change configuration option. This will let you redefine your Swan session login, where you can specify the path the the setup script in the Environment script box. Type the following into this box:
$CERNBOX_HOME/SWAN_projects/fcc_python_tools/setup/setup.sh
to point to the setup script in your copy of fcc_python_tools.
User ROOT files produced with FCCSW can be placed in the data/ directory in the main project folder. Python code to perform specific tasks is housed in fcc_python_tools/, and example notebooks for running analysis can be found in examples/. Plots produced with matplotlib are stored in the output/plots folder, and LaTeX tables in the output/tables folder. Users can store analysis results in dictionaries and persist them to .json files, and write the output to the output/json folder.
Shortcuts for these various locations are defined in the fcc_python_tools/locations.py script. Here, users can change the default data directory and output locations if desired, and also add additional shortucts. These shortcuts can be accessed with:
from fcc_python_tools.locations import loc
where loc.ROOT for example gives the home directory of the project, and loc.DATA points to the data folder where you can put your ROOT files.
This project is intended as an example analysis framework, to demonstrate how to load and analyse FCC simulation data and produce some useful output. Users are free to extend the code by adding their own functions into the fcc_python_tools folder and writing their own dedicated analysis scripts.
Generated events produced in FCCSW are stored in ROOT files. In this project, these files are loaded using the uproot package, which provides fast, ROOT-independent file loading into python. The events are handled using awkward array, which provides numpy-like access to jagged data (different numbers of particles in each event). This enables analysis at array-level, where all events are analysed with a single command without the use of loops.
Example Jupyter notebooks are provided in the examples directory. If you are working with the fcc_python_tools package on your own local mahcine (laptop or desktop with a Python environmet including the required packages), you can do:
jupyter notebook
to launch Jupyter in your local browser. You can then run notebooks from there and point to files on your own machine. However, the example notebooks provided use files stored on EOS. To access these files, you should use Swan as described above.
A summary of exclusive decay modes generated via EvtGen is provided here.
| Decay mode | DecFile name | Z decay | Events required |
|---|---|---|---|
| B+ -> (D0 -> K+ pi-) pi+ | Bu2D0Pi.dec | bb | 250k |
| B0 -> (K*0 -> K- pi+) tau+ tau-, tau -> 3pi nu | Bd2KstTauTau.dec | bb | 250k |
| B0 -> mu mu | Bd2MuMu.dec | bb | 250k |
| B0 -> (D*- -> (D0b -> K+ pi-) pi-) tau+ nu, tau -> 3pi nu | Bd2DstTauNu.dec | bb | 250k |
| B0 -> (D- -> K+ pi- pi-) tau+ nu, tau -> 3pi nu | Bd2DTauNu.dec | bb | 250k |
| B0 -> (K*0 -> K- pi+) e+ e- | Bd2KstEE.dec | bb | 250k |
| B0 -> (K*0 -> K- pi+) nu nu | BdKstNuNu.dec | bb | 250k |
| B0 -> (Ks0 -> pi pi) pi0 | Bd2KsPi0.dec | bb | 250k |
| Bs0 -> (phi -> K+ K-) gamma | Bs2PhiGamma.dec | bb | 1M |
| Bs0 -> tau+ tau-, tau -> 3pi nu | Bs2TauTau.dec | bb | 1M |
| Bc+ -> tau+ nu, tau -> 3pi nu | Bc2TauNu.dec | bb | 25M |
| tau -> 3mu | Tau2MuMuMu.dec | tautau | 100k |
| tau -> mu gamma | Tau2MuGamma.dec | tautau | 100k |
| D+ -> pi+ pi0 | D2PiPi0.dec | cc | 250k |