This tutorial based on either the server @tau-neutrino.ps.uci.edu or @muon-neutrino.ps.uci.edu. The rest of this tutorial will use the tau server as example. For the tau server just change "tau" to "muon".
Welcome to the world of neutrinos! ⚛️ Neutrinos are tiny, fundamental particles that are all around us. They are produced in the sun, in distant exploding stars (supernovae), and right here on Earth in particle accelerators. However, they are famously difficult to study. Because they have no electric charge and very little mass, they rarely interact with other matter, earning them the nickname "ghost particles." Millions of them are passing through you right now without leaving a trace!
Despite being so elusive, neutrinos are crucial to our understanding of the universe. Studying them helps us unlock the secrets of stars, understand why there is more matter than antimatter, and search for new physics beyond our current theories.
The FASER (ForwArd Search ExpeRiment) at CERN has been a pioneer in studying particles that fly in the same direction as the main proton beams at the Large Hadron Collider (LHC). FORTUNE (FORward Two-arm UNiversal Experiment) is a proposed next-generation experiment designed to build on FASER's success with much greater sensitivity. More details about FASER
Since FORTUNE is not yet built, this tutorial uses highly realistic simulated data. Our goal is to develop a powerful machine learning workflow that can classify different types of neutrino interactions automatically.
From 3D Collision to 2D Image A particle interaction inside a detector is a complex, three-dimensional event. To make it easier for a computer to analyze, we simplify this 3D event by creating two 2D "pictures" of it, taken from different angles.
An x–z view (like a "top-down" view)
A y–z view (like a "side-on" view)
These two views are then combined into a single data object, much like a color photograph is made of channels for Red, Green, and Blue (RGB). Our "image" has two channels: the x-z view and the y-z view. This 2-channel image gives our model the spatial information it needs to recognize the unique patterns of each interaction type. These images are stored in HDF5 (H5) files, an efficient format for handling large scientific datasets.
Our main task is to teach a machine learning model to distinguish between different ways neutrinos can interact inside the detector. We will focus on three primary classes. Below, each image pair shows the same event from the two different camera angles (x-z and y-z).
NC (neutral-current interactions, any flavor)
νeCC (electron neutrino charged-current)
νμCC (muon neutrino charged-current)
ντCC (tau neutrino charged-current)
(Excluded from the default (3‑class) training because ντ CC events are experimentally scarce: producing a tau lepton requires a higher neutrino energy threshold (~3.5 GeV), the flux and effective cross section in the usable energy range are lower, and the short tau lifetime with many decay modes makes reconstruction and labeling more ambiguous. You can enable this class by setting num_classes=4, but expect reduced performance. No example image is shown for this class.)
Correctly identifying these interaction types is critical for our physics goals, such as measuring how neutrinos change from one type to another ("oscillations"). Traditionally, scientists wrote complex algorithms based on manually identified features, like the length of a track or the energy in a shower.
This is a perfect task for machine learning! Specifically, we'll use a Convolutional Neural Network (CNN), a type of AI model that excels at finding patterns in images. Our goal is to train a CNN to look at our 2-channel event "images" and automatically determine if the event is NC, νeCC, or νμCC.
This tutorial will guide you through the entire process: from loading and preprocessing the data to building, training, and evaluating your very own neutrino classification model with TensorFlow. Let's get started!
-
To connect the server, you must be on the UCI network. You can access the network with a VPN if you aren't on campus, info available here: https://www.oit.uci.edu/services/security/vpn/.
-
Contact maintainer of the server to get an account on the server such as you@tau-neutrino.ps.uci.edu, and an initial password.
-
Connect to the server with your initial password:
$ssh you@tau-neutrino.ps.uci.edu. -
Change your initial password and follow prompts:
$passwd.
- Note: Be sure your password is safe and correct. Your account will be locked when you input wrong password twice.
You are not entitled to run at root or sudo.
-
You need to be able to access github from the server. You can generate a personal token in GitHub Settings -> Developer settings -> Personal access tokens -> Tokens (classic) -> Generate new token -> Generate new token (classic). Remember to copy and save the generated token because it will only be displayed once.
-
Your directory path on the server is /home/you/, init your remote repo.
$ git clone url_to_repowhere url_to_repo ishttps://github.com/zhongyiwu/classifier-tensorflow.git, or that replacing "zhongyiwu" with your own username if you forked your own version (don't worry about that point if you're just starting though). You will be asked for your GitHub username and password. Your username should be your normal username, but the password should be the personal token you just generated. Now, this repo should appear as the directory "classifier-tensorflow". -
You can follow the same procedure to clone this repo to your local computer.
TensorFlow 2.x and Python 3.6 are required to run this tutorial. Load function is required to be used in tau-neutrino server in case that files are stored in the tau-neutrino server.
$ cd /home/you/classifier-tensorflow
$ mkdir h5
$ mkdir logs
$ mkdir plots
-classifier-tensorflow
\
-README.md
-default.conf
-train.py
-utils.py
-h5 (if using ROOT files)
-logs
-plots
If the data are stored as ROOT files, you will need to convert the ROOT files to H5 files before training. First open "default.conf" and change the dataset path to where your root files are stored. You can make a directory for the output H5 files, then obtain the TH2 Histogram from ROOT files, and convert them to 2 channel numpy array (size match) by running the command:
$ python3.6 train.py -c default.conf load
Note: If the files store in the tau-neutrino server, preprocessing can be done there.
Training should be directly done on H5 files. For this tutorial we have a preprocessed dataset that you can use directly, whose directory has already been written in "default.conf". You can change the model type in "default.conf".
Different ways to run the model
Choose the one you prefer. Here use nohup as a demonstration
$ nohup python3 train.py -c default.conf train > log_<name>.log 2>&1 &
where you can give the log file an arbitrary name by replacing with other strings. The command already enables a detached session, so feel free to turn off your laptop
nohup is a great way to keep your logs tidy. It ensures that the output from each training process gets its own file, which is perfect for when you're running different jobs on different GPUs at the same time and want to keep things separate.
Learn how to manage GPU (GPU Management)
You can check the training status in the output log file or using the command tail -f logs_name.log. Models will be saved in the "logs" directory.
Try to change the num_classes in "default.conf" from 3 to 4 after finishing the whole process and train again to see the differenes.
number of classes for classification
3 = three-class system: NueCC (0), NumuCC (1), NC (2)
4 = four-class system: NueCC (0), NumuCC (1), NutauCC (2), NC (3)
To check the accuracy and loss of the train, run the command:
$ python3 train.py -c default.conf loss
The loss curve will be saved in the "plots" directory.
Now that you have the models, you can use them to make predictions. You need to first uncommented the "modelfile" line in "default.conf" and then fill in the correct model file path and name. You are free to use any models, but the models with "best" are recommended when making predictions. Run the command:
$ nohup python3 train.py -c default.conf predict > predict.log 2>&1 &
The prediction file is saved in HDF5 format in the predictions directory with the filename structured as: predictions_(num_classes)model.h5, where the filename is composed of the prefix "predictions", the number of classes, the suffix "_model", and the ".h5" file extension.
To obtain the confusion matrix, PID distribution and Pur/Eff matrix, run the command:
python3 train.py -c default.conf plot
The plots will be saved in "plots" directory.
Learn more about the the classification evaluation metrics
You can open the output plots using your own method or using jupyter notebook:
Locally, run $ ssh -L 8888:localhost:8889 you@tau-neutrino.ps.uci.edu.
Remotely, run $ jupyter notebook --no-browser --port=8889.
Copy the url to your browser. In your browser, change http://localhost:8889/ to http://localhost:8888/.