POLAR background prediction
Stéphane Nguyen, Nicolas Produit*
* Denotes supervisor
Physicists from the POLAR collaboration are interested in detecting Gamma Ray Bursts (GRBs).
Based on past data collected from the POLAR detector mounted on the Tiangong-2 spacelab, this project aims to build a model of the background and use it to extract potentially meaningful time intervals for further analysis by experts. These time intervals are extracted based the magnitude of the difference between the target and predicted photon rates (photon counts per second) for different energy bins.
These time intervals might include moments in which the detector was turned off or had problems which caused our predictions to be significantly higher or lower than the target rates. They might also include solar events such as solar flares.
tl;dr
- Built a model of the background (light curve) using data collected from the POLAR detector
- Used the residuals (target-prediction) to extract time intervals
- Brief peek at model interpretability by using partial derivatives of output wrt input
Related links
- https://www.astro.unige.ch/polar/
- https://www.unige.ch/dpnc/fr/groups/xin-wu/experiences/polar/
- https://www.astro.unige.ch/polar/grb-light-curves
nf1rate.root
dataset (ROOT-CERN format)
Contact
Please contact Prof. Nicolas Produit if you need any information on the dataset or anything related to physics as I'm not an expert in the field.
- Install pytorch:
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
- And other dependencies:
pip3 install -r requirements.txt
- Download the
nf1rate.root
dataset in ROOT-CERN format from my Dropbox and place it under the./data
directory.
The code was developed for Python 3.10.12
and 3.10.6
with torch==2.0.1 and torchvision==0.15.2. Using a different Python version might cause problems. As for the ROOT-CERN tool, I used ROOT 6.26/06.
I also used Jupyter v2023.7.1002162226
and Remote-SSH v0.102.0
extensions of VSCode 1.81.1
to remotely edit and run codes on raidpolar (POLAR research group's Linux machine).
python src/main.py
to run the training phase (usepython src/main.py wandb.mode=disabled
if you don't want to use weights and biases)python src/visualizer.py
to load pretrained model, plot loss and predicted photon rates (for validation set if not specified).python src/export.py
to export into .root format (ROOT CERN), our predictions over the whole dataset with the 25 known GRBs.python src/export_cluster_intersections.py
to export into .root format, the same aspython src/export.py
but also the cluster intersections for different sets of energy bins or conditions. Moreover, it also exports in .pkl a few tables used in our documentation (incl. number of clusters).- Run the different cells of
./notebooks/results.ipynb
to show the rest of our (interactive) plots (clusters, cluster intersections, etc.).
I want to use a different model architecture, hyperparameters, features etc. What can I do?
You can change the config/trainer.yaml
. However, your possiblities are limited to what I've implemented. Please refer to the documentation for more information.
Can I run src/main.py, src/visualizer.py, src/export.py and src/export_cluster_intersections.py remotely?
Yes, you can. To remotely run our Python scripts without keeping an opened SSH connection for the whole execution duration, you can use tmux
and detach the session.
Can I run the Jupyter notebooks remotely?
Yes, you can. You can use Jupyter and Remote-SSH VSCode extensions. They allow you to edit and run codes on your remote Linux machine.
If you don't want to use VSCode, you can take a look at the following link: https://docs.anaconda.com/free/anaconda/jupyter-notebooks/remote-jupyter-notebook/
The execution crashed. What happened?
The crash is likely due to memory usage as we sometimes create/store data structures with over 3 million entries.
- You can change
verbose: False
toverbose: True
inconfig/trainer.yaml
to see more information (our prints). - You can check
cfg.common.device
inconfig/trainer.yaml
, you might need to change it tocpu
if you don't have a GPU (you can check that usingtorch.cuda.is_available()
in Python). - You can use
nvidia-smi
to see the VRAM usage (if you're using a GPU) - You can use
htop
(or another command) to see the RAM usage. - I sometimes create tensors containing the whole dataset to perform a single forward pass on all the examples instead of many. In terms of memory usage, this is not great. Instead, you can try to work with mini-batches despite the fact that you will have to perform multiple forward passes.
Can I run the codes on CPU?
-
src/main.py
: I recommend using the GPU for model training because it's faster and because I mostly trained my model using the GPU. However, if you want to continue with the CPU, you can swapcfg.common.device: cuda
withcfg.common.device: cpu
. -
src/visualizer.py
,src/export.py
,src/export_cluster_intersections.py
andnotebooks/results.ipynb
work by default on GPU if available; if not, they work on CPU. Although this behavior overridescfg.common.device
, you can still manually change it by replacing in the code:
cfg.common.device = "cuda" if torch.cuda.is_available() else "cpu"
to
cfg.common.device = "cpu" # "cuda" if torch.cuda.is_available() else "cpu"
before trainer = Trainer(cfg)
.
Why results using CPU are different than when using GPU?
Operations execution order is most likely the cause of these differences.
See the following links:
The interactive plots in results.ipynb don't work
You can try to re-run the corresponding Jupyter notebook cell.
-
Code and project structure: https://github.com/eloialonso/iris
-
LSTM to predict GRB occurrences from past photon counts and energy info: https://cernbox.cern.ch/pdf-viewer/public/X1OvZ4iY19vewcV/HAGRID_in_Space.pdf
-
55 GRBs: https://www.researchgate.net/publication/326811280_Overview_of_the_GRB_observation_by_POLAR
-
Technologies
- Weights & biases: https://wandb.ai/site
- Pytorch:
- Hydra: https://hydra.cc/docs/intro/
- ReviewNB ("git diff but for Jupyter notebooks"): https://www.reviewnb.com/
- VSCode Remote SSH: https://code.visualstudio.com/docs/remote/ssh-tutorial
- Diff with colors by using
diff <file1> <file2> --color
: https://man7.org/linux/man-pages/man1/diff.1.html - TMux detach/reattach session: https://www.redhat.com/sysadmin/introduction-tmux-linux
- Rsync