Muograph: muon tomography library

This repository provides a library for muon scattering tomography and muon transmission tomography data analysis.

Overview

As a disclaimer, this library is more of an aggregate of muon tomography algorithms used throughtout PhD research rather than a polished product for the general public. As such, this repo targets mostly muon tomography reaserchers and enthousiasts.

Users can find ready to use scattering density algorihms as well as samples of simulated data.

While currently being at a preliminary stage, this library is designed to be extended by users, whom are invited to implement their favorite reconstruction, material inference or image processing algorithms.

If you are interested in using this library seriously, please contact us; we would love to hear if you have a specific use-case you wish to work on.

Installation

As a dependency

For a dependency usage, muograph can be instaled with pip within a Conda environment:

conda create -n muograph python=3.10
conda activate muograph
pip install muograph

Make sure everythings works by running:

pytest path_to_muograph/test

You can check the location where muograph is installed:

pip show muograph

For development

Clone the repository locally:

git clone [email protected]:MaximeLagrange/muograph.git
cd muograph

For development usage, we use poetry to handle dependency installation:

curl -sSL https://install.python-poetry.org | python3 -

To get started, you need Poetry's bin directory in your PATH environment variable. Add the export command to your shell's configuration file. For bash, add it to the ~/.bashrc file. For zsh, add it to the ~/.zshrc file.

export PATH="$HOME/.local/bin:$PATH"

then reload the configuration file:

source ~/.bashrc # or source ~/.zshrc

Poetry should now be accessible:

poetry self update

Muograph requires python >= 3.10. This can be installed with e.g pyenv.

curl https://pyenv.run | bash
pyenv update
pyenv install 3.10
pyenv local 3.10

Install the dependencies:

poetry install
poetry self add poetry-plugin-export
poetry config warnings.export false
poetry run pre-commit install

Finally, make sure everything is working as expected by running the tests:

poetry run pytest muograph/test/

For those unfamiliar with poetry, basically just prepend commands with poetry run to use the stuff installed within the local environment, e.g. poetry run jupyter notebook to start a jupyter notebook server. This local environment is basically a python virtual environment. To correctly set up the interpreter in your IDE, use poetry run which python to see the path to the correct python executable.

How-to: jupyter notebooks

You can run notebooks both on a remote gateway node and on compute nodes. In the following, we will use this convention:

• head node is a remote gateway machine (for instance ingrid-ui in Louvain, or gaeui01 in Oviedo)
• compute node is a computing node (more powerful computing CPUs) that is usually not accessible from outside (hence requires tunnelling through the head node). In Louvain, it is e.g. the whatever it is called (I forgot), in Louvain the gae machines. On the head node, run it on port 8889:

jupyter notebook --no-browser --port=8889

On computing nodes, run it on port 8890 instead:

jupyter notebook --no-browser --port=8890

If the notebook runs on a compute node, run port forwarding on ingrid:

ssh -N -f -L localhost:8889:localhost:8890 gpunode

If it runs on the ingrid head node, it is enough to just run port forwarding locally (also needed if running the notebook on a compute node):

ssh -N -f -L localhost:8888:localhost:8889 ucl

with an appropriate ~/.ssh/config defining the hosts ucl and gpunode. The notebooks can be viewed locally at http://localhost:8888/tree.

Tutorials

A few tutorials to introduce users to the package can be found in the tutorial/ folder. They are provied as Jupyter notebooks:

• 00_Volume_of_interest.ipynb shows how to define a voxelized volume of interest, later used by the reconstruction algorithms.
• 01_Hits.ipynb demonstrates how to load muon hits, and simulate detector spatial resolution and/or efficiency effects.
• 02_Tracking.ipynb shows how to convert muon hits into muon tracks usable for image reconstruction purposes.
• 03_Tracking_muon_Scattering_tomography.ipynb combines incoming and ougoing tracks to compute features relevant to muon scatering tomography.
• 04_POCA.ipynb takes the user through the computation of voxel-wise density predictions based on the Point of Closest Approach.
• 05_Binned_clustered_algorithm.ipynb demonstrates the Binned Clustered Algorithm, with and without muon momentum information.
• 06_Angle_statistical_reconstruction.ipynb shows the Angle Statistical Reconstruction algorithm, with and without muon momentum information.

You can run the tutorials using poetry command:

poetry run jupyter notebook muograph/tutorials/05_Binned_clustered_algorithm.ipynb

Examples

More advanced examples are provided in the muograph/examples:

poetry run jupyter notebook muograph/examples/00_scattering_small_size_statue.ipynb