User Guide#
Getting Started for Users#
Warning
The following guide is for users. If you want to contribute to CTLearn as a developer, see Developer Guide.
Installation for Users#
Inside an existing Pixi project, add the released CTLearn package:
$ pixi add --pypi ctlearn
$ pip install ctlearn
For working on the IT cluster, create a conda environment with the required build tools:
$ mamba create -n ctlearn-it-cluster -c conda-forge python==3.12 h5py scipy llvmlite gcc_linux-64 gxx_linux-64 openblas gfortran_linux-64
$ conda activate ctlearn-it-cluster
$ export CC=$(which x86_64-conda-linux-gnu-gcc)
$ export CXX=$(which x86_64-conda-linux-gnu-g++)
$ export FC=$(which x86_64-conda-linux-gnu-gfortran)
$ pip install ctlearn
Update LD_LIBRARY_PATH to include the necessary paths. For example, add the
following line to your .bashrc file:
$ export LD_LIBRARY_PATH=/path/to/your/conda/envs/ctlearn-it-cluster/lib:/path/to/cudnn/lib:$LD_LIBRARY_PATH
Replace /path/to/your/conda/envs/ctlearn-it-cluster/lib with the path to
your conda environment and /path/to/cudnn/lib with the path to the system’s
cuDNN libraries for CUDA 12.
Basic package usage#
The CTLearn package provides a set of command-line tools for training and predicting with deep learning models
using Keras or PyTorch. The tools are designed to work with data produced by the ctapipe package following
the CTAO data format. However, it also supports predicting on real observational data from the LST1 telescope
using the cta-lstchain package for the time being. Detail tutorials on how to use the CTLearn tools
are available in the CTLearn tutorials section of this documentation. Additionally, a high-level companion
python package to the CTLearn package is available for easy usage of the CTLearn tools.
The package is called CTLearnManager.
Training tools#
To train a model, choose the Keras or PyTorch training tool. Use --help-all
to display its available options. The examples below train a ResNet model for
particle classification:
$ ctlearn-train-keras-model --help-all
$ ctlearn-train-keras-model \
--signal=/path/to/signal_dir \
--pattern-signal="*gamma*.dl1.h5" \
--background=/path/to/background_dir \
--pattern-background="*proton*.dl1.h5" \
--config=/path/to/reader_config.json \
--output=/path/to/output_dir_keras \
--reco=type \
--TrainCTLearnModel.model_type=ResNet \
--TrainCTLearnModel.n_epochs=10 \
--TrainCTLearnModel.batch_size=64
$ ctlearn-train-pytorch-model --help-all
$ ctlearn-train-pytorch-model \
--signal=/path/to/signal_dir \
--pattern-signal="*gamma*.dl1.h5" \
--background=/path/to/background_dir \
--pattern-background="*proton*.dl1.h5" \
--config=/path/to/reader_config.json \
--output=/path/to/output_dir_pytorch \
--reco=type \
--TrainCTLearnModel.model_type=ResNet \
--TrainCTLearnModel.n_epochs=10 \
--TrainCTLearnModel.batch_size=64
View training progress in real time with TensorBoard:
$ tensorboard --logdir=/path/to/output_dir
Prediction tools#
To predict with a trained Keras or PyTorch model, use the ctlearn-predict-mono-model or ctlearn-predict-stereo-model command.
The following command will display all available options for predicting with a CTLearn model:
$ ctlearn-predict-mono-model --help-all
$ ctlearn-predict-stereo-model --help-all
Example: Predicting with a trained mono classification model
Use the same reader configuration as for training:
$ ctlearn-predict-mono-model \
--input_url=/path/to/input.dl1.h5 \
--output=/path/to/keras_prediction_output.dl2.h5 \
--config=/path/to/reader_config.json \
--type_model=/path/to/output_dir_keras/ctlearn_model.keras \
--PredictCTLearnModel.batch_size=64
$ ctlearn-predict-mono-model \
--input_url=/path/to/input.dl1.h5 \
--output=/path/to/pytorch_prediction_output.dl2.h5 \
--config=/path/to/reader_config.json \
--type_model=/path/to/output_dir_pytorch/ctlearn_model.pth \
--PredictCTLearnModel.batch_size=64
Caution
This tool expects the input data to be produced via the ctapipe package. The output file with the predictions follows the ctapipe DL2 data format.
View the predictions in a GUI with ViTables:
$ pip install vitables
$ vitables /path/to/*_prediction_output.dl2.h5
LST-1 prediction tool#
To predict on real observational data from the LST1 telescope, use the ctlearn-predict-LST1 command.
The following command will display all available options for predicting with a CTLearn model:
$ ctlearn-predict-LST1 --help-all
Example: Predicting on LST1 observational data
Use the same image channels and mapping as for training:
$ ctlearn-predict-LST1 \
--input_url=/path/to/lst1_input.dl1.h5 \
--output=/path/to/lst1_keras_prediction_output.dl2.h5 \
--type_model=/path/to/type/ctlearn_model.keras \
--energy_model=/path/to/energy/ctlearn_model.keras \
--LST1PredictionTool.channels=cleaned_image \
--LST1PredictionTool.channels=cleaned_relative_peak_time \
--LST1PredictionTool.image_mapper_type=BilinearMapper
$ ctlearn-predict-LST1 \
--input_url=/path/to/lst1_input.dl1.h5 \
--output=/path/to/lst1_pytorch_prediction_output.dl2.h5 \
--type_model=/path/to/type/ctlearn_model.pth \
--energy_model=/path/to/energy/ctlearn_model.pth \
--LST1PredictionTool.channels=cleaned_image \
--LST1PredictionTool.channels=cleaned_relative_peak_time \
--LST1PredictionTool.image_mapper_type=BilinearMapper
Caution
This tool expects the input data to be produced
via the cta-lstchain package. The output file with the predictions
follows the ctapipe DL2 data format.
For step-by-step examples from the different workflows, see the CTLearn tutorials.