├── logo.png ├── .gitignore ├── run.mac ├── detector.tg ├── mingle.bat ├── drawE.py ├── mesh.mac ├── LICENSE ├── CMakeLists.txt ├── gui.mac ├── vis.mac ├── mingle.cc └── README.md /logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jintonic/mingle/HEAD/logo.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # ignore executable 2 | mingle 3 | mingle.exe 4 | 5 | # ignore build directory 6 | *build* 7 | .vs 8 | 9 | # ignore backup files 10 | \#* 11 | .swp 12 | *~ 13 | 14 | # ignore visualization output 15 | *.prim 16 | *.jpeg 17 | *.png 18 | *.pdf 19 | *.heprep 20 | *.wrl 21 | 22 | # ignore data output 23 | *.root 24 | *.csv 25 | *.tab 26 | *.txt 27 | 28 | # ignore cmake generated files 29 | .qt 30 | CMakeCache.txt 31 | CMakeFiles 32 | Makefile 33 | cmake_install.cmake 34 | 35 | # ignore others 36 | macro 37 | -------------------------------------------------------------------------------- /run.mac: -------------------------------------------------------------------------------- 1 | # display applied commands on screen 2 | /control/verbose 3 | 4 | # construct detector geometry and physics processes 5 | /run/initialize 6 | 7 | # 2.6 MeV gamma-rays shot to x direction from (-20,0,0) cm 8 | /gps/particle gamma 9 | /gps/energy 2.6 MeV 10 | /gps/pos/centre -20 0 0 cm 11 | /gps/direction 1 0 0 12 | 13 | # save energy deposition in volume named CsI 14 | /score/create/realWorldLogVol CsI 15 | /score/quantity/energyDeposit e 16 | /score/close 17 | /score/list 18 | 19 | /run/verbose 2 20 | /run/printProgress 1000 21 | /run/beamOn 10000 22 | 23 | -------------------------------------------------------------------------------- /detector.tg: -------------------------------------------------------------------------------- 1 | // define a 10x10x10 m3 cubic hall filled with air 2 | :volu hall BOX 200 200 200 G4_AIR 3 | :vis hall OFF 4 | 5 | // define a cylindrical vacuum chamber made of stainless steel 6 | :volu chamber TUBE 0 10*cm 15*cm G4_STAINLESS-STEEL 7 | :color chamber 0.5 0.5 0.5 8 | 9 | // default length unit: mm 10 | :volu vacuum TUBE 0 99 149 G4_Galactic 11 | :color vacuum 0.5 0.5 0.5 12 | 13 | :rotm r000 0 0 0 14 | :place chamber 3 hall r000 0 0 0 15 | :place vacuum 2 chamber r000 0 0 0 16 | 17 | :volu CsI TUBE 0 50 100 G4_CESIUM_IODIDE 18 | :color CsI 0.3 0.7 0.9 19 | :place CsI 1 vacuum r000 0 0 0 20 | 21 | -------------------------------------------------------------------------------- /mingle.bat: -------------------------------------------------------------------------------- 1 | :: Add mingle folder to user PATH 2 | 3 | :: Disable printing commands on screen 4 | @echo OFF 5 | 6 | if not exist mingle.exe ( 7 | if not exist ..\mingle.exe ( 8 | echo cannot find mingle.exe, please compile mingle.cc first 9 | pause & exit /b 10 | ) 11 | ) 12 | 13 | :: Get curernt user PATH from the registry 14 | :: https://stackoverflow.com/questions/46712814 15 | :: https://stackoverflow.com/questions/14509652 16 | for /f "skip=2 tokens=1-2*" %%G in ('Reg Query HKCU\Environment /V PATH 2^>nul') do set user_path=%%I 17 | 18 | :: check if current folder is already in PATH 19 | echo %user_path% | findstr /i /c:%~dp0 > nul 20 | if %errorlevel% neq 0 ( 21 | echo add "%~dp0" to user PATH 22 | echo setx path "%user_path%%~dp0;" 23 | ) else ( 24 | echo %~dp0 & echo is already in your user PATH: 25 | echo %user_path:;=&echo.% 26 | ) 27 | 28 | echo mingle.exe can be executed anywhere now 29 | :: keep terminal open to show result if the script is run manually 30 | pause & exit /b 31 | -------------------------------------------------------------------------------- /drawE.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python3 2 | # open a root file using uproot 3 | import uproot 4 | f = uproot.open('scoring.root') 5 | # check what's in the file 6 | f.keys() 7 | 8 | # get ROOT tree (https://root.cern/manual/trees/) named 'CsI_e' 9 | t = f['CsI_e'] 10 | # list branches in the tree 11 | t.keys() 12 | # get branch 'CsI_e_score' 13 | b = t['CsI_e_score'] 14 | # get values in the branch as an awkward array 15 | e = b.array() 16 | 17 | # draw energy (e) distribution 18 | import matplotlib.pyplot as p 19 | p.hist(e, bins=100) 20 | p.xlabel('Energy deposition in CsI [MeV]') 21 | p.ylabel('Entries') 22 | p.title('Linear scale') 23 | p.text(1.63, 4020, r'Full-absorption peak $\rightarrow$') 24 | p.grid(True) 25 | 26 | # draw e in log scale 27 | p.figure() 28 | p.hist(e, bins=100, log=True) 29 | p.xlabel('Energy deposition in CsI [MeV]') 30 | p.ylabel('Entries') 31 | p.title('Log scale') 32 | p.text(1.18, 250, r'Single-escape peak $\rightarrow$') 33 | p.text(0.63, 6.2, r'Compton continuum', color='white') 34 | p.grid(True) 35 | 36 | # show canvas 37 | p.show() 38 | 39 | -------------------------------------------------------------------------------- /mesh.mac: -------------------------------------------------------------------------------- 1 | # display applied commands on screen 2 | /control/verbose 3 | # print output of threads separately 4 | /control/cout/useBuffer 5 | 6 | # construct detector geometry and physics processes 7 | /run/initialize 8 | 9 | # shoot 6.5 MeV alpha to positive x direction 10 | /gps/particle alpha 11 | /gps/energy 6.5 MeV 12 | /gps/pos/centre -19 0 0 cm 13 | /gps/direction 1 0 0 14 | 15 | # print every step of simulation on screen 16 | /tracking/verbose 2 17 | # simulate a few events 18 | /run/beamOn 1 19 | # disable verbose output for a large quantity of events 20 | /tracking/verbose 0 21 | 22 | /score/create/boxMesh mesh 23 | /score/mesh/boxSize 40 1 1 mm 24 | /score/mesh/nBin 40 1 1 25 | /score/mesh/translate/xyz -16 0 0 cm 26 | 27 | /score/quantity/nOfStep nOfStepEMinus 28 | /score/filter/particle eMinusFilter e- 29 | /score/quantity/nOfStep nOfStepAlpha 30 | /score/filter/particle AlphaFilter alpha 31 | /score/close 32 | /score/list 33 | 34 | /run/printProgress 100 35 | /run/beamOn 1000 36 | 37 | /score/dumpQuantityToFile mesh nOfStepEMinus nOfStepEMinus.csv 38 | /score/dumpQuantityToFile mesh nOfStepAlpha nOfStepAlpha.csv 39 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 Jing Liu 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /CMakeLists.txt: -------------------------------------------------------------------------------- 1 | cmake_minimum_required(VERSION 3.16) # CMake quits without it 2 | 3 | project(mingle) # project name 4 | 5 | # http://geant4-userdoc.web.cern.ch/geant4-userdoc/UsersGuides/InstallationGuide/html/buildtools.html 6 | find_package(Geant4 REQUIRED ui_all vis_all) # search for Geant4Config.cmake 7 | include(${Geant4_USE_FILE}) # Linux cannot find Geant4 header files without it 8 | 9 | if(WIN32) # set config type for multi-configuration generators, e.g. Visual Studio, Xcode 10 | set(CMAKE_CONFIGURATION_TYPES Release CACHE STRING "Release;Debug;..." FORCE) 11 | else() # set default build type for single-configuration generators, e.g. Makefile 12 | if(NOT CMAKE_BUILD_TYPE) # if not defined by the user 13 | set(CMAKE_BUILD_TYPE Release CACHE STRING "Release;Debug;..." FORCE) 14 | endif() 15 | endif() # executable of Release type is leaner & faster than that of Debug type 16 | 17 | if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT) # if not defined by the user 18 | set(CMAKE_INSTALL_PREFIX "${Geant4_DIR}/../../.." CACHE PATH "Installation prefix" FORCE) 19 | endif() # set default installation prefix 20 | 21 | if(APPLE) # https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling 22 | set(CMAKE_INSTALL_RPATH "${Geant4_DIR}/../..") 23 | endif() # set RPATH in executable on Mac (must be before add_executable(...)) 24 | 25 | add_executable(${PROJECT_NAME} ${PROJECT_NAME}.cc) 26 | target_link_libraries(${PROJECT_NAME} ${Geant4_LIBRARIES}) 27 | install(TARGETS ${PROJECT_NAME}) # enable cmake --install -------------------------------------------------------------------------------- /gui.mac: -------------------------------------------------------------------------------- 1 | /gui/addMenu window Window 2 | /gui/addButton window Close exit 3 | 4 | /gui/addMenu verb Verbosity 5 | /gui/addButton verb /run/verbose /run/verbose 6 | /gui/addButton verb /control/verbose /control/verbose 7 | /gui/addButton verb /tracking/verbose /tracking/verbose 8 | /gui/addButton verb /globalField/verbose "/globalField/verbose 2" 9 | 10 | /gui/addMenu list List 11 | /gui/addButton list Materials "/material/nist/listMaterials all" 12 | /gui/addButton list Particles "/particle/list all" 13 | /gui/addButton list Processes "/process/list all" 14 | /gui/addButton list Units "/units/list all" 15 | 16 | /gui/addMenu run Run 17 | /gui/addButton run "beamOn 1" "/run/beamOn 1" 18 | /gui/addButton run "beamOn 10" "/run/beamOn 10" 19 | /gui/addButton run "beamOn 100" "/run/beamOn 100" 20 | 21 | /gui/addMenu e Energy 22 | /gui/addButton e "1 keV" "/gps/energy 1 keV" 23 | /gui/addButton e "1 MeV" "/gps/energy 1 MeV" 24 | /gui/addButton e "1 GeV" "/gps/energy 1 GeV" 25 | /gui/addButton e "1 TeV" "/gps/energy 1 TeV" 26 | 27 | /gui/addMenu particle Particle 28 | /gui/addButton particle Alpha "/gps/particle alpha" 29 | /gui/addButton particle Electron "/gps/particle e-" 30 | /gui/addButton particle Positron "/gps/particle e+" 31 | /gui/addButton particle Gamma "/gps/particle gamma" 32 | /gui/addButton particle Proton "/gps/particle proton" 33 | /gui/addButton particle Neutron "/gps/particle neutron" 34 | /gui/addButton particle "Positive Muon" "/gps/particle mu+" 35 | /gui/addButton particle "Negative Muon" "/gps/particle mu-" 36 | 37 | /gui/addMenu vis Visualization 38 | /gui/addButton vis "Open OpenGL Viewer" "/vis/open OGL" 39 | /gui/addButton vis "Zoom in" "/vis/viewer/zoom 1.2" 40 | /gui/addButton vis "Zoom out" "/vis/viewer/zoom 0.8" 41 | /gui/addButton vis "Take Screenshot" "/vis/ogl/export g4OpenGL.pdf" 42 | /gui/addButton vis "Draw B-field" "/vis/scene/add/magneticField ! lightArrow" 43 | /gui/addButton vis /vis/viewer/set/upVector /vis/viewer/set/upVector 44 | /gui/addButton vis /vis/viewer/set/viewpointVector /vis/viewer/set/viewpointVector 45 | 46 | /gui/addMenu field B-field 47 | /gui/addButton field /globalField/setValue /globalField/setValue 48 | -------------------------------------------------------------------------------- /vis.mac: -------------------------------------------------------------------------------- 1 | # display applied commands on screen 2 | /control/verbose 3 | 4 | # add more menu items in GUI 5 | /control/ifInteractive gui.mac 6 | 7 | # no need of many threads for visualization 8 | /run/numberOfThreads 1 9 | # construct detector geometry and physics processes 10 | /run/initialize 11 | 12 | # check overlapping in between detector volumes 13 | /geometry/test/run 14 | # list visualization setups for detector components 15 | /vis/geometry/list 16 | 17 | # shoot 2 MeV electrons to positive x direction 18 | /gps/particle e- 19 | /gps/energy 2 MeV 20 | /gps/pos/centre -20 0 0 cm 21 | /gps/direction 1 0 0 22 | 23 | # open a default visualization driver 24 | /vis/open 25 | # pick a component (volume) to draw (world, by default) 26 | /vis/drawVolume 27 | 28 | /vis/scene/add/axes 29 | /vis/scene/add/trajectories 30 | /vis/scene/endOfEventAction accumulate 31 | 32 | /vis/viewer/set/auxiliaryEdge 1 33 | 34 | /vis/modeling/trajectories/create/drawByParticleID 35 | /vis/modeling/trajectories/drawByParticleID-0/default/setDrawStepPts true 36 | /vis/modeling/trajectories/drawByParticleID-0/default/setStepPtsColour magenta 37 | /vis/modeling/trajectories/list 38 | 39 | /run/beamOn 10 40 | 41 | # X-ray imaging of detector components 42 | /vis/open RayTracer 43 | # white transparent background 44 | /vis/viewer/set/background 1 1 1 0 45 | # view image from a good angle 46 | /vis/viewer/set/viewpointThetaPhi 60 0 47 | /vis/drawVolume 48 | # save image to g4RayTracer.*.jpeg 49 | # it is commented out as it is time-consuming 50 | #/vis/viewer/refresh 51 | 52 | # save detector geometry to g4_000?.prim 53 | /vis/open DAWNFILE 54 | /vis/drawVolume 55 | /vis/viewer/refresh 56 | 57 | # save detector geometry and particle tracks to g4_0?.wrl 58 | /vis/open VRML2FILE 59 | /vis/drawVolume 60 | /vis/scene/add/axes 61 | /vis/scene/add/trajectories 62 | /vis/scene/endOfEventAction accumulate 63 | /run/beamOn 10 64 | 65 | # save detector geometry and particle tracks to G4Data0.heprep 66 | /vis/open HepRepFile 67 | /vis/drawVolume 68 | /vis/scene/add/axes 69 | /vis/scene/add/trajectories 70 | /vis/scene/endOfEventAction accumulate 71 | /run/beamOn 10 72 | 73 | # save detector geometry and particle tracks to 74 | # g4tsg_offscreen_zb_png_?.png 75 | /vis/open TSG_FILE 76 | /vis/drawVolume 77 | /vis/scene/add/axes 78 | /vis/scene/add/trajectories 79 | /vis/scene/endOfEventAction accumulate 80 | /run/beamOn 10 81 | /vis/viewer/rebuild 82 | 83 | # print hierarchical structure of detector components 84 | /vis/ASCIITree/verbose 13 85 | /vis/drawTree 86 | 87 | -------------------------------------------------------------------------------- /mingle.cc: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | #include 5 | 6 | class Detector : public G4VUserDetectorConstruction 7 | { 8 | public: 9 | G4VPhysicalVolume* Construct() { 10 | G4tgbVolumeMgr::GetInstance()->AddTextFile("detector.tg"); 11 | return G4tgbVolumeMgr::GetInstance()->ReadAndConstructDetector(); 12 | } ///< load detector definition from a text file "detector.tg" 13 | void ConstructSDandField() { 14 | G4AutoDelete::Register(new G4GlobalMagFieldMessenger()); 15 | } ///< enable /globalField/ to set uniform B-field 16 | }; 17 | //....oooOO0OOooo........oooOO0OOooo........oooOO0OOooo........oooOO0OOooo...... 18 | 19 | #include 20 | #include 21 | 22 | class Generator : public G4VUserPrimaryGeneratorAction 23 | { 24 | private: 25 | G4GeneralParticleSource* fGPS; 26 | public: 27 | Generator() : G4VUserPrimaryGeneratorAction() { 28 | fGPS = new G4GeneralParticleSource; } 29 | ~Generator() { delete fGPS; } 30 | void GeneratePrimaries(G4Event *evt) { fGPS->GeneratePrimaryVertex(evt); } 31 | }; 32 | //....oooOO0OOooo........oooOO0OOooo........oooOO0OOooo........oooOO0OOooo...... 33 | 34 | #include 35 | 36 | class Action : public G4VUserActionInitialization 37 | { 38 | public: 39 | void Build() const { SetUserAction(new Generator); } 40 | }; 41 | //....oooOO0OOooo........oooOO0OOooo........oooOO0OOooo........oooOO0OOooo...... 42 | 43 | #include 44 | #include 45 | #include 46 | #include 47 | #include 48 | #include 49 | #include 50 | #include 51 | #include 52 | 53 | int main(int argc,char** argv) 54 | { 55 | auto run = G4RunManagerFactory::CreateRunManager(); 56 | 57 | G4ScoringManager::GetScoringManager(); // enable macro commands in /score/ 58 | 59 | // https://geant4-forum.web.cern.ch/t/11480/3 60 | G4TScoreNtupleWriter writer; // enable data recording 61 | if (run->GetRunManagerType()!=G4RunManager::sequentialRM) 62 | writer.SetNtupleMerging(true);// merge ntuples created in multi threads 63 | 64 | // load default physics list, or the one specified by $PHYSLIST 65 | G4PhysListFactory f; run->SetUserInitialization(f.ReferencePhysList()); 66 | 67 | run->SetUserInitialization(new Detector); // specify detector setup 68 | 69 | run->SetUserInitialization(new Action); // specify user action 70 | 71 | G4UIExecutive* ui = nullptr; // assume batch mode 72 | if (argc==1) ui = new G4UIExecutive(argc, argv); // interactive mode 73 | 74 | auto vis = new G4VisExecutive("quiet"); vis->Initialize(); // enable visialization 75 | 76 | if (ui) { // interactive mode 77 | ui->SessionStart(); // do this after vis 78 | delete ui; 79 | } else { // batch mode 80 | G4String cmd = "/control/execute "; 81 | G4UImanager::GetUIpointer()->ApplyCommand(cmd+argv[1]); // run a macro file 82 | } 83 | 84 | delete vis; delete run; // clear up memory 85 | return 0; 86 | } 87 | // -*- C++; indent-tabs-mode:nil; tab-width:2 -*- 88 | // vim: ft=cpp:ts=2:sts=2:sw=2:et 89 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![YouTube](https://img.shields.io/badge/You-Tube-red?style=flat)](https://www.youtube.com/playlist?list=PLw3G-vTgPrdCkTdisAL5UdUPazZdjqlpm) 2 | [![bilibili](https://img.shields.io/badge/B-站-blue?style=flat)](https://space.bilibili.com/610308328) 3 | [![shimo](https://img.shields.io/badge/石-墨-lightgrey?style=flat)](https://shimo.im/docs/HJv6Qrvpx9R9wHqP) 4 | [![tags](https://img.shields.io/badge/Development-History-orange?style=flat)](#tags) 5 | [![Docker image](https://img.shields.io/badge/Docker-image-green?style=flat)](https://hub.docker.com/r/physino/geant4) 6 | 7 | MinGLE - Mine Geant4 Learning Example 8 | 9 | `MinGLE`, a Mini [Geant4][] Learning Example, uses minimal C++ coding (60 lines of code) to demonstrate the usage of essential [Geant4][] components step by step. It is not tied to any specific experiment or third party library, which makes it a clean starting point of writing your own [Geant4][] applications. 10 | 11 | ## Prerequisites 12 | - [Geant4][] 10.7 or above is needed to use 13 | - [G4RunManagerFactory][] 14 | - [CMake](https://cmake.org/download/) 3.5 or above is needed to compile [mingle.cc](mingle.cc) across multiple operating systems 15 | - A not-so-old C++ compiler, e.g. 16 | - [Visual studio 2019](https://visualstudio.microsoft.com/downloads/) for Windows 17 | - [GCC](https://gcc.gnu.org/) (4.9 or above) for Linux 18 | - [clang](https://clang.llvm.org/) for MacOS installed by running `xcode-select --install` in a terminal 19 | 20 | ## Getting started 21 | [![YouTube](https://img.shields.io/badge/You-Tube-red?style=flat)](https://youtu.be/6xqCtS38SXQ) 22 | 23 | If you know how to use [Git][] in a Linux or MacOS terminal, please follow the instruction below. If you don't, or use Windows, please follow [this YouTube tutorial](https://youtu.be/6xqCtS38SXQ). 24 | 25 | ```sh 26 | # download mingle git repository from github to a local hard disk 27 | git clone https://github.com/jintonic/mingle 28 | # get into the mingle directory 29 | cd mingle 30 | # create a folder build/ and run cmake with default settings inside 31 | cmake -B build 32 | # compile mingle.cc 33 | make -C build 34 | # run the generated executable (mingle) interactively in the current directory (./) 35 | ./mingle 36 | # or run mingle in TUI even if GUI is enabled in compilation 37 | G4UI_USE_TCSH=1 ./mingle 38 | 39 | Available UI session types: [ Qt, GAG, tcsh, csh ] 40 | PreInit> ls 41 | Command directory path : / 42 | Sub-directories : 43 | /control/ UI control commands. 44 | /units/ Available units. 45 | /gui/ UI interactors commands. 46 | Commands : 47 | PreInit> cd /units/ 48 | PreInit> ls 49 | Command directory path : /units/ 50 | 51 | Guidance : 52 | Available units. 53 | 54 | Sub-directories : 55 | Commands : 56 | list * full list of available units. 57 | PreInit> help list 58 | 59 | Command /units/list 60 | Guidance : 61 | full list of available units. 62 | 63 | PreInit> exit 64 | ``` 65 | 66 | Note that lines start with '#' are comments, they cannot be run. 67 | 68 | ## Tags 69 | 70 | Whenever a new [Geant4][] component is added to `MinGLE`, a new [tag](https://github.com/jintonic/mingle/tags) is created. You can check them one by one to see how a [Geant4][] application is developed step by step from scratch using the `git show` command: 71 | 72 | ```sh 73 | git show 74 | ``` 75 | 76 | The following tags are available: 77 | 78 | [![minimum](https://img.shields.io/badge/-minimum-red?style=flat)](#minimum) 79 | [![batch](https://img.shields.io/badge/+-batch-orange?style=flat)](#batch) 80 | [![run](https://img.shields.io/badge/+-run-yellow?style=flat)](#run) 81 | [![physics](https://img.shields.io/badge/+-physics-green?style=flat)](#physics) 82 | [![detector](https://img.shields.io/badge/+-detector-brightgreen?style=flat)](#detector) 83 | [![generator](https://img.shields.io/badge/+-generator-blue?style=flat)](#generator) 84 | [![visualization](https://img.shields.io/badge/+-visualization-blueviolet?style=flat)](#visualization) 85 | [![scorer](https://img.shields.io/badge/+-scorer-8033ff?style=flat)](#scorer) 86 | [![ntuple](https://img.shields.io/badge/+-ntuple-red?style=flat)](#ntuple) 87 | [![field](https://img.shields.io/badge/+-field-black?style=flat)](#field) 88 | 89 | ### Minimum 90 | [![batch](https://img.shields.io/badge/+-batch-orange?style=flat)](#batch) 91 | 92 | Believe it or not, six lines of C++ are enough to create a [Geant4][] application that can be launched. A tag [minimum](https://github.com/jintonic/mingle/releases/tag/minimum) is created for you to quickly switch to it: 93 | 94 | ```sh 95 | git clone https://github.com/jintonic/mingle 96 | cd mingle 97 | # git show : 98 | git show minimum:mingle.cc 99 | ``` 100 | ```cpp 101 | #include "G4UIExecutive.hh" 102 | 103 | int main(int argc,char** argv) 104 | { 105 | G4UIExecutive ui(argc, argv); 106 | ui.SessionStart(); 107 | } 108 | ``` 109 | 110 | This version of `MinGLE` includes only one [Geant4][] component, [G4UIExecutive][], which [provides a variety of user interfaces (UI) for us to pick](https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/graphicalUserInterface.html#how-to-select-interface-in-your-applications). 111 | 112 | We can save this version of `MinGLE` to current working folder, compile and run it: 113 | 114 | ```sh 115 | # save (>) mingle.cc in its minimum stage to mingle.cc in current working folder 116 | git show minimum:mingle.cc > mingle.cc 117 | cmake -B build 118 | cmake --build build 119 | ./mingle 120 | Available UI session types: [ tcsh, csh ] 121 | PreInit> exit 122 | ``` 123 | 124 | Use `git checkout -- mingle.cc` to get back to the latest [mingle.cc](mingle.cc). 125 | 126 | ### Batch 127 | [![minimum](https://img.shields.io/badge/previous-tag-red?style=flat)](#minimum) 128 | [![run](https://img.shields.io/badge/+-run-yellow?style=flat)](#run) 129 | 130 | The [batch](https://github.com/jintonic/mingle/releases/tag/batch) tag marks a version of `MinGLE` that can be run both interactively and in the so-called batch mode, where `MinGLE` can execute [Geant4][] commands saved in a macro file (for example, [run.mac](run.mac)) without getting into any interactive user interface (UI). 131 | 132 | ```sh 133 | # run mingle in batch mode 134 | $ ./build/mingle run.mac 135 | ``` 136 | 137 | ### Run 138 | [![batch](https://img.shields.io/badge/previous-tag-orange?style=flat)](#batch) 139 | [![physics](https://img.shields.io/badge/+-physics-green?style=flat)](#physics) 140 | 141 | The [run](https://github.com/jintonic/mingle/releases/tag/run) tag marks a version of `MinGLE` that creates a [Geant4][] [Run][] [Manager][runman] using [G4RunManagerFactory][] that is only introduced until [Geant4][] 10.7, which allows the switching between various run managers using an environment variable `G4RUN_MANAGER_TYPE`: 142 | 143 | ```sh 144 | # run mingle in serial mode 145 | $ G4RUN_MANAGER_TYPE=Serial ./build/mingle 146 | Environment variable "G4RUN_MANAGER_TYPE" enabled with value == Serial. Overriding G4RunManager type... 147 | 148 | ************************************************************** 149 | Geant4 version Name: geant4-10-07-patch-01 [MT] (5-February-2021) 150 | Copyright : Geant4 Collaboration 151 | References : NIM A 506 (2003), 250-303 152 | : IEEE-TNS 53 (2006), 270-278 153 | : NIM A 835 (2016), 186-225 154 | WWW : http://geant4.org/ 155 | ************************************************************** 156 | ``` 157 | ```sh 158 | # run mingle in multithreaded mode 159 | $ G4RUN_MANAGER_TYPE=MT ./build/mingle 160 | ************************************************************** 161 | Geant4 version Name: geant4-10-07-patch-01 [MT] (5-February-2021) 162 | << in Multi-threaded mode >> 163 | Copyright : Geant4 Collaboration 164 | References : NIM A 506 (2003), 250-303 165 | : IEEE-TNS 53 (2006), 270-278 166 | : NIM A 835 (2016), 186-225 167 | WWW : http://geant4.org/ 168 | ************************************************************** 169 | ``` 170 | 171 | ### Physics 172 | [![run](https://img.shields.io/badge/previous-tag-yellow?style=flat)](#run) 173 | [![detector](https://img.shields.io/badge/+-detector-brightgreen?style=flat)](#detector) 174 | 175 | The [physics](https://github.com/jintonic/mingle/releases/tag/physics) tag marks a version of `MinGLE` that creates a [physics list][physlist] using [G4PhysListFactory][], which allows the switching between various physics lists using an environment variable `PHYSLIST`: 176 | 177 | ```sh 178 | $ PHYSLIST=FTFP_BERT_EMV ./mingle 179 | 180 | ************************************************************** 181 | Geant4 version Name: geant4-10-07-patch-01 [MT] (5-February-2021) 182 | Copyright : Geant4 Collaboration 183 | References : NIM A 506 (2003), 250-303 184 | : IEEE-TNS 53 (2006), 270-278 185 | : NIM A 835 (2016), 186-225 186 | WWW : http://geant4.org/ 187 | ************************************************************** 188 | 189 | G4PhysListFactory::GetReferencePhysList EMoption= 1 190 | <<< Geant4 Physics List simulation engine: FTFP_BERT 191 | 192 | <<< Reference Physics List FTFP_BERT_EMV is built 193 | 194 | Available UI session types: [ GAG, tcsh, csh ] 195 | PreInit> 196 | ``` 197 | 198 | ### Detector 199 | [![physics](https://img.shields.io/badge/previous-tag-green?style=flat)](#physics) 200 | [![generator](https://img.shields.io/badge/+-generator-blue?style=flat)](#generator) 201 | 202 | The [detector](https://github.com/jintonic/mingle/releases/tag/detector) tag marks a version of `MinGLE` that can [load detector definition from a text file][tg], [detector.tg](detector.tg), where a 10 x 10 x 10 cubic meter experimental hall filled with air is defined using a [simple syntax introduced since Geant4.9.2][tg] as a simple example: 203 | 204 | ``` 205 | :volu hall BOX 5*m 5*m 5*m G4_AIR 206 | ``` 207 | 208 | Same definition written in C++ required more than 5 lines of code. In addition to its simplicity, the text geometry definition can be modified and loaded without recompiling the C++ code. More importantly, the separation of detector definition from the C++ program makes the latter more universal as it is not associated with any specific detector. `MinGLE` hence can be used for the simulation of any detector without modifying and compiling the C++ code. The last advantage of using the [text geometry definition][tg] instead of C++ is to keep the length of the C++ program unchanged no matter how complicated the detector definition becomes. 209 | 210 | To use the geometry defined in [detector.tg](detector.tg), the file must be placed in the directory where `mingle` is executed. Otherwise, Geant4 will complain that `detector.tg` file does not exist. For example, 211 | 212 | ```sh 213 | $ cd /path/to/mingle 214 | $ ls -F 215 | CMakeLists.txt README.md detector.tg mingle.cc 216 | LICENSE build/ gui.mac run.mac 217 | # in a Linux or Mac terminal 218 | $ ./build/mingle 219 | # in Git Bash in Windows 220 | $ ./build/Release/mingle.exe 221 | PreInit> /run/initialize 222 | ... a lot of output, until 223 | -------- EEEE ------- G4Exception-START -------- EEEE ------- 224 | *** G4Exception : Run0032 225 | issued by : G4RunManager::GenerateEvent() 226 | G4VUserPrimaryGeneratorAction is not defined! 227 | *** Fatal Exception *** core dump *** 228 | # The error appears because we have not defined a particle generator, 229 | # not because our detector definition is wrong. 230 | 231 | # if we run mingle in build/ where there is no detector.tg 232 | $ cd build 233 | $ ./mingle 234 | PreInit> /run/initialize 235 | # you will immediately see the following fatal error, 236 | # complaining that detector.tg cannot be found: 237 | -------- EEEE ------- G4Exception-START -------- EEEE ------- 238 | *** G4Exception : InvalidInput 239 | issued by : G4tgrFileIn::OpenNewFile() 240 | Input file does not exist: detector.tg 241 | *** Fatal Exception *** core dump *** 242 | **** Track information is not available at this moment 243 | **** Step information is not available at this moment 244 | -------- EEEE -------- G4Exception-END --------- EEEE ------- 245 | *** G4Exception: Aborting execution *** 246 | Abort trap: 6 247 | ``` 248 | 249 | ### Generator 250 | [![detector](https://img.shields.io/badge/previous-tag-brightgreen?style=flat)](#detector) 251 | [![visualization](https://img.shields.io/badge/+-visualization-blueviolet?style=flat)](#visualization) 252 | 253 | The [generator](https://github.com/jintonic/mingle/releases/tag/generator) tag marks a version of `MinGLE` that uses the [Geant4][] general particle source ([GPS][]) to generate [primary particles][], from which a [Geant4][] simulation starts, as demonstrated in the following sketch: 254 | 255 | tracks.png 256 | 257 | The up-to-date examples of [GPS][] are shipped together with the [Geant4][] source code in the folder: 258 | 259 | - [geant4/examples/extended/eventgenerator/exgps/macros](https://gitlab.cern.ch/geant4/geant4/tree/master/examples/extended/eventgenerator/exgps/macros) 260 | 261 | An [outdated webpage](http://hurel.hanyang.ac.kr/Geant4/Geant4_GPS/reat.space.qinetiq.com/gps/examples/examples.html) shows most of the examples contained in the folder above. In addition, it also shows resulted distribution plots, which are very helpful to understand the real effects of the [GPS][] macro commands. 262 | 263 | An ASCII version of the manual of [GPS][] macros is available [here](https://raw.githubusercontent.com/jintonic/gears/master/examples/sources/gps.txt). 264 | 265 | [run.mac](run.mac) is updated in this version to demonstrate how to shoot 2 MeV electrons to our geometry and print simulation steps one by one on screen: 266 | 267 | ```sh 268 | $ cd /path/to/mingle 269 | $ ./build/mingle run.mac 270 | ... 271 | G4WT0 > ********************************************************************************************************* 272 | G4WT0 > * G4Track Information: Particle = e-, Track ID = 1, Parent ID = 0 273 | G4WT0 > ********************************************************************************************************* 274 | G4WT0 > 275 | G4WT0 > Step# X(mm) Y(mm) Z(mm) KinE(MeV) dE(MeV) StepLeng TrackLeng NextVolume ProcName 276 | G4WT0 > 0 -4e+03 0 0 2 0 0 0 hall initStep 277 | G4WT0 > 1 -3.96e+03 -0.676 -1.63 1.99 0.0047 44.7 44.7 hall eIoni 278 | G4WT0 > :----- List of 2ndaries - #SpawnInStep= 1(Rest= 0,Along= 0,Post= 1), #SpawnTotal= 1 --------------- 279 | G4WT0 > : -3.96e+03 -0.676 -1.63 0.00105 e- 280 | G4WT0 > :----------------------------------------------------------------- EndOf2ndaries Info --------------- 281 | G4WT0 > 2 -3.79e+03 -13.2 -1.32 1.97 0.0204 165 209 hall eIoni 282 | ... 283 | ``` 284 | 285 | ### Visualization 286 | [![generator](https://img.shields.io/badge/previous-tag-blue?style=flat)](#generator) 287 | [![scorer](https://img.shields.io/badge/+-scorer-8033ff?style=flat)](#scorer) 288 | 289 | The [visualization](https://github.com/jintonic/mingle/releases/tag/visualization) tag marks a version of `MinGLE` that uses [Geant4][] [visualization drivers][vis] to visualize detector geometry and particle trajectories. Run the following commands 290 | 291 | ```sh 292 | $ cd /path/to/mingle 293 | $ ./build/mingle vis.mac 294 | ``` 295 | 296 | to generate various visualization output files. A detailed description on each visualization method is available [here](http://physino.xyz/gears/examples/detector/visualization). 297 | 298 | Note that many visualization methods do not work if there is no volume placed in the world (the volume that is not placed). It seems that the Qt based OpenGL needs to be used after other visualization methods, otherwise the program will crash. The good news is that the Qt based OpenGL will copy setups from other methods and no additional setup for it is needed. This is demonstrated in [gui.mac](gui.mac). 299 | 300 | ### Scorer 301 | [![visualization](https://img.shields.io/badge/previous-tag-blueviolet?style=flat)](#visualization) 302 | [![ntuple](https://img.shields.io/badge/+-ntuple-red?style=flat)](#ntuple) 303 | 304 | The [scorer](https://github.com/jintonic/mingle/releases/tag/scorer) tag marks a version of `MinGLE` that uses [G4ScoringManager][] to record some important statistical parameters from a [Geant4][] simulation. Run the following commands 305 | 306 | ```sh 307 | $ cd /path/to/mingle 308 | $ ./build/mingle mesh.mac 309 | ``` 310 | 311 | to generate two CSV files, which record numbers of steps of 6.5 MeV alpha-rays and secondary electrons in different distances from the emission point. 312 | 313 | ### Ntuple 314 | [![scorer](https://img.shields.io/badge/previous-tag-8033ff?style=flat)](#scorer) 315 | [![field](https://img.shields.io/badge/+-field-black?style=flat)](#field) 316 | 317 | The [ntuple](https://github.com/jintonic/mingle/releases/tag/ntuple) tag marks a version of `MinGLE` that uses [G4TScoreNtupleWriter][] to save important statistical parameters from a [Geant4][] simulation into [ntuples][]. Run the following commands 318 | 319 | ```sh 320 | $ cd /path/to/mingle 321 | $ ./build/mingle run.mac 322 | ``` 323 | 324 | to generate `scoring.root`, which contains a [TTree][] object `CsI_e` that has a leaf `CsI_e_score`, which records the energy deposition `e` in the volume called `CsI` in each event. Run the following commands to draw the energy spectrum recorded in the sensitive volume `CsI`: 325 | 326 | ```sh 327 | $ root scoring.root 328 | root[0] .ls 329 | root[1] CsI_e->Draw("CsI_e_score") 330 | ``` 331 | 332 | A volume called `CsI` made of a CsI scintillating crystal is placed in the vacuum chamber in the [detector.tg](detector.tg) file. 333 | 334 | ### Field 335 | [![ntuple](https://img.shields.io/badge/previous-tag-red?style=flat)](#ntuple) 336 | 337 | The [field](https://github.com/jintonic/mingle/releases/tag/field) tag marks a version of `MinGLE` that uses [G4GlobalMagFieldMessenger][] to provide macro commands in `/globalField/` to set up a uniform magnetic field throughout the detector: 338 | 339 | ~~~sh 340 | # create a B field pointing to the positive z direction 341 | /globalField/setValue 0 0 0.1 tesla 342 | # print out the setup 343 | /globalField/verbose 2 344 | ~~~ 345 | 346 | For more example usages, please see [gui.mac](gui.mac), which is called by [vis.mac](vis.mac). 347 | 348 | [Git]: http://git-scm.com 349 | [Geant4]: https://geant4.web.cern.ch 350 | [Run]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Fundamentals/run.html 351 | [physlist]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/UserActions/mandatoryActions.html#physics-lists 352 | [G4PhysListFactory]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/UserActions/mandatoryActions.html#building-physics-list-using-factory 353 | [runman]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Fundamentals/run.html#manage-the-run-procedures 354 | [G4RunManagerFactory]: https://gitlab.cern.ch/geant4/geant4/-/tree/master/source/tasking#g4runmanagerfactory 355 | [G4UIExecutive]: https://apc.u-paris.fr/~franco/g4doxy/html/classG4UIExecutive.html 356 | [tg]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Detector/Geometry/geomASCII.html 357 | [GPS]: http://geant4-userdoc.web.cern.ch/geant4-userdoc/UsersGuides/ForApplicationDeveloper/html/GettingStarted/generalParticleSource.html 358 | [primary particles]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/eventDef.html 359 | [vis]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/visualization.html 360 | [G4ScoringManager]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Detector/commandScore.html 361 | [G4TScoreNtupleWriter]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Detector/hit.html#score-ntuple-writer 362 | [histograms]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Detector/commandScore.html?highlight=score#writing-scores-to-a-file 363 | [ntuples]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Examples/BasicCodes.html?highlight=b4a#example-b4 364 | [TTree]: https://root.cern.ch/doc/master/classTTree.html 365 | [ps]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Detector/commandScore.html?highlight=score#list-of-available-primitive-scorers 366 | [G4PSEnergyDeposit]: https://gitlab.cern.ch/geant4/geant4/-/blob/master/source/digits_hits/scorer/include/G4PSEnergyDeposit.hh 367 | [G4GlobalMagFieldMessenger]: https://gitlab.cern.ch/geant4/geant4/-/blob/master/source/geometry/navigation/include/G4GlobalMagFieldMessenger.hh 368 | --------------------------------------------------------------------------------