{"id":24871602,"url":"https://github.com/maximelagrange/muography_workshop_bnd_2023","last_synced_at":"2026-06-14T21:34:10.548Z","repository":{"id":180094738,"uuid":"659626792","full_name":"MaximeLagrange/Muography_Workshop_BND_2023","owner":"MaximeLagrange","description":"Muography framework installation guide","archived":false,"fork":false,"pushed_at":"2023-08-14T08:04:51.000Z","size":17937,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T22:47:02.521Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MaximeLagrange.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-28T08:19:47.000Z","updated_at":"2023-07-10T12:05:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"403197c0-cf94-4dc1-b848-78422475cd09","html_url":"https://github.com/MaximeLagrange/Muography_Workshop_BND_2023","commit_stats":null,"previous_names":["maximelagrange/muography_workshop_bnd_2023"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MaximeLagrange/Muography_Workshop_BND_2023","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaximeLagrange%2FMuography_Workshop_BND_2023","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaximeLagrange%2FMuography_Workshop_BND_2023/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaximeLagrange%2FMuography_Workshop_BND_2023/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaximeLagrange%2FMuography_Workshop_BND_2023/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MaximeLagrange","download_url":"https://codeload.github.com/MaximeLagrange/Muography_Workshop_BND_2023/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaximeLagrange%2FMuography_Workshop_BND_2023/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34339195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-01T04:32:41.664Z","updated_at":"2026-06-14T21:34:10.529Z","avatar_url":"https://github.com/MaximeLagrange.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Muon scattering tomography end-to-end simulation framework\n\nThis repository aims at guiding the user for the installation of an end-to-end muon scattering tomography framework required for the BND School 2023, held in Wuppertal, Germany. For more information, please have look at the [introductory slides] (not available yet).\n\n*N.B: The full installation might take some time. Please make sure that you **install the framework prior to the workshop**! If you run into issues you cannot solve by yourself, please use the [dedicated slack chanel](https://join.slack.com/t/bndschoolmuog-b2x9179/shared_invite/zt-1y9t2l2h0-zxvZcvoVf1YD0iqp7_3EPg) or contact us at maximelagrange98@gmail.com*.\n\n## Installation\n\nDebuging GEANT4 code can be a painful experience. In order to make this workshop a succes, one need every participant to run the same **Operating System** (OS) so that everybody is on the same page. A \"simple\" solution is the use of a **Virtual Machine** (VM),  a compute resource that uses software instead of a physical computer to run programs and deploy apps. Using it, every participant will be able to run the same OS, in our case **Ubuntu 22.04**.\n\n*N.B: If you already run Ubuntu, please get the 22.04 and create a new user account to make sure that our installations do not create any conflicts with your existing working environement. In case you do not want to update, you can create a virtual machine like the others.*\n\n### I - Virtual machine\n\n#### A - VirtualBox\n\nFirst, you want to install the VirtualBox software. The installation guide can be found [here](https://www.virtualbox.org/manual/ch02.html). Depending on your OS, you can also checkout these youtube tutorials where is installation is done step by step.\n\n- [MacOS with Apple silicon M1/M2 processors](https://www.youtube.com/watch?v=KV90vu3tpjI)\n- [MacOS with Intel processor](https://www.youtube.com/watch?v=hd0Lbtly41Y)\n- [Windows 11](https://www.youtube.com/watch?v=b866-7Y_0KQ)\n- [Windows 10](https://www.youtube.com/watch?v=8mns5yqMfZk)\n- [Ubuntu](https://www.youtube.com/watch?v=SUPoqRPn9to)\n\nOnce VirtualBox is installed, you can go to the next step and create the virtual machine which will host the Ubuntu OS.\n\n#### B - Creating a virtual machine\n\n\nFirst, download the Ubuntu 22.04 iso file from the [ubuntu website](https://ubuntu.com/download/desktop).\n\nDepending on your initial OS, checkout these videos which detail how to create an Ubuntu virtual machine:\n\n- [Windows](https://www.youtube.com/watch?v=zHwFtyxJsog)\n- [Mac](https://www.youtube.com/watch?v=b_tOialCSXE)\n\n*N.B Make sure you assign enough disk to the virtual machine. At least **35 GB**.*\n\n#### C - Virtual machine testing\n\nNow that your virtual machine is created, you have to **make sure** that you can connect the machine to **internet via Wi-Fi**, and that you are able to **open the terminal**. \n\nIn case you run into issues, you can check these links:\n\n- [Unable to access Wi-Fi](https://windowsreport.com/wifi-error-virtualbox/)\n- [Unable to open terminal](https://askubuntu.com/questions/1435918/terminal-not-opening-on-ubuntu-22-04-on-virtual-box-7-0-0)\n\n ### II - GEANT4 - Root installation\n\nUsing the freshly created Ubuntu virtual machine, we will proceed to the installation of both Root ad GEANT4.\n\n#### A - Micromamba installation\n\nConda is a very useful tool for packages and dependecies installation and updates. We will use `micromamba` (https://mamba.readthedocs.io/en/latest/installation.html) which is a tiny version of the `mamba` package manager, itself being a reimplementation of `conda`.\n\nUsing `micromamba` allows for a straighforward installation of both GEANT4 and Root, as well as all the required packages and libraries.\n\nOpen a terminal in your `/home/user/` directory and run:\n\n```\nwget -qO- https://micromamba.snakepit.net/api/micromamba/linux-64/latest | tar -xvj bin/micromamba\n./bin/micromamba shell init -s bash -p ~/micromamba\nsource ~/.bashrc\n```\n#### B - GEANT4 - Root installation\nNow download the `geant-root.yml` and move it to `/home/user/`. Go in the `/home/usr/` directory (replace `usr` by your actual user name) and run:\n\n```\n./bin/micromamba create -f geant-root.yml\n```\n\nInstall cmake:\n\n```\nsudo apt install cmake\n```\n\nLet's check if the installation worked:\n\n```\nmicromamba activate geant-root\ncd micromamba/envs/geant-root/share/Geant4-11.0.3/examples/basic/B1/\nmkdir build\ncd build\n```\n\nWe will now run the `cmake ../` command. BEFORE CONTINUING, MAKE SURE YOU ARE IN THE `build/` DIRECTORY!\n\n```\ncmake ../\nmake\n```\n\nNow is the moment of truth! Try to run the exampleB1 by running:\n\n```\n./exampleB1\n```\n\nYou should see a window poping, which displays the structure of the detector (if you run into errors, please report it in the dedicated Slack channel). Once you it is working properly, you can delete the build directory. Another one will be created during the installation of CRY.\n\nThe exampleB1 will be used as base for the activities of this workshop, so do not modify it, neither any other file in the B1 directory (unless we ask you to do so)!\n\n### III - CRY installation\n\n[CRY](https://nuclear.llnl.gov/simulation/doc_cry_v1.7/cry.pdf) is cosmic-ray shower librairy used to generate correlated cosmic-ray particle shower distributions. Installing it and linking it to GEANT4 will allow us to simulate cosmic muons and propagate them through our detector and volume of interest.\n\n#### A - Download\n\nCRY can be downloaded [here](https://nuclear.llnl.gov/simulation/). Download it, open a terminal window an run:\n\n```\ncd Downloads/\ntar -xvf cry_v1.7.tar.gz\nmv cry_v1.7 ../micromamba/envs/geant-root/\n```\n\n#### B - Make\n\nNow we will go in the cry_directory (`micromamba/envs/geant-root/`) and make CRY. This will create a `libCRY.a` file in `cry_v1.7/lib`.\n\n```\ncd ../micromamba/envs/geant-root/cry_v1.7/\nmake\n```\n\n#### C - Modify CMakeLists.txt\n\nIt is now possible to link CRY to exampleB1. In order to do so, we must modify the CMakeLists.txt so that GEANT4 knows how to access the CRY library (Replace `usr` by your username in the path). Since we are here, we will also link Root with GEANT4.\n\n```\ncd /home/usr/micromamba/envs/geant-root/share/Geant-4-11.0.3/examples/basic/B1/\n```\n\nOpen the `CMakeLists.txt` file and after `project(B1)` add the following lines:\n\n```\nset(CRY_PATH /home/usr/micromamba/envs/geant-root/cry_v1.7)\nset(CRY_LIB -L${CRY_PATH}/lib libCRY.a)\ninclude_directories(${CRY_PATH}/src)\n\n# Find ROOT (required package)\n\nlist(APPEND CMAKE_PREFIX_PATH $ENV{ROOTSYS})\nfind_package(ROOT REQUIRED COMPONENTS RIO)\ninclude(${ROOT_USE_FILE})\ninclude_directories(${ROOT_INCLUDE_DIRS})\nfind_package(ROOT REQUIRED)\ninclude_directories(${ROOT_INCLUDE_DIRS})\n```\n\nSearch for `target_link_libraries(exampleB1 ${Geant4_LIBRARIES})` and replace it by `target_link_libraries(exampleB1 ${Geant4_LIBRARIES} ${CRY_LIB} ${ROOT_LIBRARIES})` .\n\nFinally, at line ~60 you should see `set(EXAMPLEB1_SCRIPTS ...)`. Simply add `cmd.file` as follow:\n\n```\nset(EXAMPLEB1_SCRIPTS\nexampleb1.in\nexampleb1.out\ninit_vis.mac\nrun1.mac\nrun2.mac\nvis.mac\ncmd.file\n)\n```\n\n#### D - Create cmd.file\n\nWe need to create the file used to drive the cosmic shower generation. Run the following:\n\n```\ncd /home/usr/micromamba/envs/geant-root/share/Geant-4-11.0.3/examples/basic/B1/\nnano cmd.file\n```\n\nPaste the following in the file:\n\n```\n/run/initialize\n/CRY/input returnNeutrons 0\n/CRY/input returnProtons 0\n/CRY/input returnGammas 0\n/CRY/input returnPions 0\n/CRY/input returnKaons 0\n/CRY/input returnElectrons 0\n/CRY/input returnMuons 1\n/CRY/input date 7-1-2012\n/CRY/input latitude 48.0\n/CRY/input altitude 0\n/CRY/input subboxLength 1.2\n/CRY/input nParticlesMin 1\n/CRY/input nParticlesMax 2\n/CRY/update\n\n/control/execute vis.mac\n/vis/viewer/set/viewpointThetaPhi 90. 0.\n/vis/filtering/trajectories/create/particleFilter\n/vis/filtering/trajectories/particleFilter-0/add mu+\n\n/run/beamOn 1000\n```\n\nSave and exit.\n\n#### E - Import generator files from CRY\n\nWe need to import a few files from the CRY GEANT4 examples in the `src/` and `include/` directories of our exampleB1 by running:\n\n```\ncd /home/usr/micromamba/envs/geant-root/share/Geant-4-11.0.3/examples/basic/B1/src/\nrm PrimaryGeneratorAction.cc\ncd ..\ncd include/\nrm PrimaryGeneratorAction.hh\n\ncd /home/usr/micromamba/envs/geant-root/cry_v1.7/geant/src/\ncp PrimaryGeneratorAction.cc RNGWrapper.cc PrimaryGeneratorMessenger.cc /home/usr/micromamba/envs/geant-root/share/Geant-4-11.0.3/examples/basic/B1/src/\n\ncd /home/usr/micromamba/envs/geant-root/cry_v1.7/geant/include/\ncp PrimaryGeneratorAction.hh RNGWrapper.hh PrimaryGeneratorMessenger.hh /home/usr/micromamba/envs/geant-root/share/Geant-4-11.0.3/examples/basic/B1/include/\n```\n\n#### F - Modifying B1 files\n\n##### Removing namespace B1\n\nTo make things work, we still have to modify files. All files in `/B1/src/` and `/B1/include/` start with:\n\n```\nnamespace B1{\n\n    ...\n}\n```\nOpen all those files and remove it *(Do not forget to also remove the brackets!)*.\n\n##### PrimaryGeneratorAction.cc\n\nWe must tell GEANT4 where the CRY data is located. Using search and replace (ctrl + h), search all instances of `../data` in the `B1/src/PrimaryGeneratorAction.cc` file and replace them by the actual path to cry_v1.7 data, which should be:\n\n```\n/home/usr/micromamba/envs/geant-root/cry_v1.7/data\n```\n\nYou must also include the `G4SystemOfUnits.hh` file by adding `#include \"G4SystemOfUnits.hh\"`.\n\n##### ActionInitialization.cc\n\nOpen the `B1/src/ActionInitialization.cc` file and replace `SetUserAction(new PrimaryGeneratorAction);` by `SetUserAction(new PrimaryGeneratorAction(\"\"));`\n\n##### RunAction.cc\n\n\nOpen the `B1/src/RunAction.cc` file and comment lines from 105 to 150. (Within `void RunAction::EndOfRunAction(const G4Run* run){}`).\n\n##### exampleB1.cc\n\nOpen the `B1/exampleB1.cc` file, and replace line 90 `if ( ! ui ){` by `if (argc\u003e1){`.\n\n#### G - Testing\n\nNow is the moment of truth! Run the modified exampleB1:\n\n```\ncd B1/\nmkdir build\ncd build\n```\n\n**Before running **`cmake ../`**, make sure you are in the `build/` directory!**\n\n```\ncmake ../\nmake\n./exampleB1 cmd.file\n```\n\nYou should see a window poping, which displays the structure of the detector (if you run into errors, please report it in the dedicated Slack channel).\n\n\n ### V - Python environment\n\n We will use python to analyse the simulated data. We need to create an environment with all the required libraries. Once again, `micromamba` can do that with just one command line:\n\n```\nmicromamba create -n muograph_env jupyterlab pandas scikit-spatial scikit-learn pyqt joblib qt fastprogress -c conda-forge\nmicromamba activate muograph_env\n```\n\nAfter downloading the repositoy, open a terminal window and run:\n\n```\njupyter lab\n```\n\nTry to run a few cells from the Tutorial_0 to see if everything is running smoothly (if you run into errors, please report it in the dedicated Slack channel).\n\nNow the framework is finally ready to go! Apologies for this painful installation prcedures and see you at the workshop!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximelagrange%2Fmuography_workshop_bnd_2023","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximelagrange%2Fmuography_workshop_bnd_2023","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximelagrange%2Fmuography_workshop_bnd_2023/lists"}