{"id":42961889,"url":"https://github.com/jintonic/mingle","last_synced_at":"2026-01-30T23:18:05.710Z","repository":{"id":45667145,"uuid":"371751083","full_name":"jintonic/mingle","owner":"jintonic","description":"Mini Geant4 Learning Example","archived":false,"fork":false,"pushed_at":"2026-01-02T23:32:46.000Z","size":277,"stargazers_count":32,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-03T07:21:15.295Z","etag":null,"topics":["geant4","minimalist-design","monte-carlo-simulation","tutorial"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jintonic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-05-28T15:54:31.000Z","updated_at":"2026-01-02T15:52:24.000Z","dependencies_parsed_at":"2024-05-07T01:25:14.817Z","dependency_job_id":"ce3c1e73-422a-44b6-9f52-efb0fc5c84cc","html_url":"https://github.com/jintonic/mingle","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/jintonic/mingle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jintonic%2Fmingle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jintonic%2Fmingle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jintonic%2Fmingle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jintonic%2Fmingle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jintonic","download_url":"https://codeload.github.com/jintonic/mingle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jintonic%2Fmingle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28922659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T22:32:35.345Z","status":"ssl_error","status_checked_at":"2026-01-30T22:32:31.927Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["geant4","minimalist-design","monte-carlo-simulation","tutorial"],"created_at":"2026-01-30T23:18:05.174Z","updated_at":"2026-01-30T23:18:05.704Z","avatar_url":"https://github.com/jintonic.png","language":"C++","readme":"[![arXiv](https://img.shields.io/badge/arXiv-2601.08469-maroon?style=flat)](https://arxiv.org/abs/2601.08469)\n[![YouTube](https://img.shields.io/badge/You-Tube-red?style=flat)](https://www.youtube.com/playlist?list=PLw3G-vTgPrdCkTdisAL5UdUPazZdjqlpm)\n[![Bilibili](https://img.shields.io/badge/B-站-blue?style=flat)](https://space.bilibili.com/610308328)\n[![Shimo](https://img.shields.io/badge/石-墨-lightgrey?style=flat)](https://shimo.im/docs/HJv6Qrvpx9R9wHqP)\n[![Guided Development](https://img.shields.io/badge/Guided-Development-orange?style=flat)](#guided-development)\n[![Docker Image](https://img.shields.io/badge/Docker-Image-green?style=flat)](https://hub.docker.com/r/physino/geant4)\n\n\u003cimg src=\"logo.png\" alt=\"MinGLE - Mine Geant4 Learning Example\" width=\"35%\" align=\"right\"\u003e\n\n`MinGLE`, a Mini [Geant4][] Learning Example, uses minimal C++ coding (less than 70 lines of code) to demonstrate the usage of 10 essential [Geant4][] components step by step. It is not tied to any specific experiment or third party library, making it a clean template to start your own [Geant4][] applications.\n\n## Prerequisites\n\n- [Geant4][] 10.7 or above is needed to use [G4RunManagerFactory][]\n- [CMake](https://cmake.org/download/) 3.16 or above is needed to compile [mingle.cc](mingle.cc) across multiple operating systems\n- A not-so-old C++ compiler, e.g.\n  - [Visual studio](https://visualstudio.microsoft.com/downloads/) for Windows\n  - [GCC](https://gcc.gnu.org/) for Linux\n  - [clang](https://clang.llvm.org/) for MacOS installed by running `xcode-select --install` in a terminal\n- [Git][] (optional, but highly recommended) for code downloading and development history browsing\n\n## Getting started\n\n[![YouTube](https://img.shields.io/badge/You-Tube-red?style=flat)](https://youtu.be/6xqCtS38SXQ)\n\nIf you know how to use [Git][] and [CMake][] in a Linux or Mac terminal, please follow the instruction below. It also works for Windows users in a [Git Bash](https://gitforwindows.org) terminal. If you don't, please follow [this YouTube tutorial](https://youtu.be/6xqCtS38SXQ).\n\n```sh\n# download mingle git repository from GitHub to a local hard disk\ngit clone https://github.com/jintonic/mingle\n# get into the mingle directory\ncd mingle\n# create a folder build/ and run cmake with default settings inside\ncmake -B build\n# compile mingle.cc into executable mingle\ncmake --build build --config Release\n# install mingle to /path/to/Geant4/bin\ncmake --install build --config Release\n# run mingle in batch mode with run.mac in the current folder\nmingle run.mac\n```\n\n\u003e **Note:**\n- lines start with `#` are comments, they cannot be run.\n- `--config Release` is primarily for Visual Studio on Windows, it can be ignored on Linux and MacOS.\n- Commands are case sensitive, e.g. `-B` cannot be replaced by `-b`.\n- The `cmake --install` command will install the `mingle` executable to the `bin/` directory of your Geant4 installation path (detected during the `cmake -B build` step) based on the settings in [CMakeLists.txt](CMakeLists.txt). This saves you a manual configuration step. Since a successful Geant4 installation already requires its `bin/` folder to be in your [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) (usually via the [geant4.sh][post_installation] or [geant4.bat][post_installation] setup scripts), `mingle` becomes globally available immediately. You can simply type `mingle` from any directory in your terminal to start the application.\n\nThree PNG files will be created, the first visualizes the geometry, the second shows the trajectories of the particles, and the third shows the proton flux after all detector volumes. Also created will be a [ROOT][] file `scoring.root` containing the energy deposit in the volume `Shape1` defined in [detector.tg](detector.tg).\n\nMost operations in [run.mac](run.mac) can also be executed one by one in the Geant4 GUI. This is achieved by running `mingle` and then loading [menu.mac](menu.mac) in the launched Geant4 GUI. [menu.mac](menu.mac) creates a menu in the Geant4 GUI, items in the menu can be executed one by one upon selection.\n\n## Guided Development\n\nThere are two primary ways to teach a complex software framework like Geant4. The first is to disassemble a finished, feature-complete application to see how it works. However, for a beginner, this \"reverse engineering\" often feels like trying to learn how an engine works by looking at a fully assembled car. The second way, and the one MinGLE adopts, is to evolve the code step-by-step. By building the application one component at a time, you see the specific necessity of every line of code as it is added. This \"bottom-up\" approach ensures that you are never overwhelmed by boilerplate, as each stage introduces exactly one new concept.\n\nTo facilitate this step-by-step journey, MinGLE utilizes two core features of the [Git][] version control system: branches and tags. Think of a branch as a living workspace dedicated to a specific topic, like [ui][] or [physics][]. It is a place where code is active and can be modified. A tag is like a \"snapshot\" or a \"version\", like [v0][]. It marks a specific moment in time when that stage was perfectly finished and tested.\n\nIn a typical Geant4 example, the source code contains hundreds of lines of boilerplate. In `MinGLE`'s guided development roadmap built with Git branches and tags,\n- each branch (e.g., [ui][]) represents a learning milestone associated with a specific Geant4 component, and\n- each tag (e.g., [v0][]) marks a stable, working version of that milestone:\n\n| Milestone | Branch | Tag | New Concepts |\n| :--- | :--- | :--- | :--- |\n| 0 | [ui][] | [v0][] | [G4UIExecutive][], and navigate the macro command tree |\n| 1 | [batch][] | [v1][] | transition from interactive exploration to automated [batch mode][] execution |\n| 2 | [run][] | [v2][] | [G4RunManagerFactory][], and the lifecycle of a simulation (run, event, etc.) |\n| 3 | [physics][] | [v3][] | [G4PhysListFactory][], and validated, high-level physics models |\n| 4 | [detector][] | [v4][] | define detector geometry and materials using [simple syntax in text][] files |\n| 5 | [vis][] | [v5][] | [G4VisExecutive][], and [render][] 3D geometry |\n| 6 | [gps][] | [v6][] | control particle generation with the [General Particle Source][] |\n| 7 | [scorer][] | [v7][] | use built-in [/score/][] commands to record dose, flux, etc. |\n| 8 | [ntuple][] | [v8][] | [G4TScoreNtupleWriter][], and [create histograms from ntuples](drawE.py) |\n| 9 | [field][] | [v9][] | [G4GlobalMagFieldMessenger][] to create uniform B-field |\n\n[mingle.cc](mingle.cc) grows from [v0][] to [v9][] step by step, so does [menu.mac](menu.mac). [run.mac](run.mac), however, is tailored to individual milestones to better showcase features added to each milestone. [mingle.cc](mingle.cc) and [menu.mac](menu.mac) are identical in the [main][] and [field][] branches, but [run.mac](run.mac) in [main][] is more complex than [run.mac in field](https://github.com/jintonic/mingle/blob/field/run.mac).\n\nThis structure serves the following pedagogic purposes:\n\n- **Isolation of Concepts**: By switching to a specific branch, you see only the code required for that milestone, free from the \"noise\" of yet-to-be-introduced components.\n- **Active Experimentation**: Unlike a static code snippet, a branch is a live workspace. You can modify the code and commit your own changes to see how they affect the simulation.\n- **Stable Checkpoints**: Tags provide a \"correct answer\". If your experiments in a branch lead to errors, you can always compare your work against the corresponding tag to find the solution.\n\n### Navigating Development Milestones\n\nNew to [Git][]? You can explore every stage of this project directly on the GitHub website using the branch and tag selectors at the top of the file list. However, to run the code locally, please use the terminal commands below.\n\nList existing branches and tags:\n```bash\ngit branch -a\ngit tag\n```\nA freshly cloned repository only has one branch: `main`. The `-a` option lists both local and remote branches.\n\nBoth branches and tags allow you to inspect the code at specific points in its evolution without changing your files:\n```bash\n# View the main source file for the detector geometry milestone\ngit show v4:mingle.cc\n# or\ngit show detector:mingle.cc\n```\n\nTo see exactly what code was added to the main application between two milestones:\n```bash\n# See code changes between detector (v4) and vis (v5)\ngit diff v4 v5 mingle.cc\n# or\ngit diff detector vis mingle.cc\n```\n\nTo move your physical working directory to a specific stage to run the simulation or experiment with the code:\n```bash\n# Switch to the detector branch\ngit switch detector\n```\nA local branch `detector` is created based on the remote branch `detector`, and your working directory is switched to the `detector` branch.\n\nWhen you are finished exploring and want to return to the complete version of the code:\n```bash\n# Return to the main branch\ngit switch main\n```\n\nIf you have modified the code while exploring and try to switch branches, Git may prevent the switch to protect your work. If you want to discard changes before returning:\n```bash\ngit restore .\ngit switch main\n```\nIf you want to keep your experiments for later:\n```bash\ngit stash\ngit switch main\n```\nLater, use `git stash pop` to bring your changes back.\n\n[Geant4]: https://geant4.web.cern.ch\n[ROOT]: https://root.cern\n[Git]: https://git-scm.com\n[CMake]: https://cmake.org\n[post_installation]: https://geant4-userdoc.web.cern.ch/UsersGuides/InstallationGuide/html/postinstall.html\n[G4RunManagerFactory]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/mainProgram.html#g4runmanager\n[G4PhysListFactory]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/UserActions/mandatoryActions.html?highlight=physlistfac#building-physics-list-using-factory\n[G4UIExecutive]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/graphicalUserInterface.html?highlight=g4uiexecutive#how-to-select-interface-in-your-applications\n[General Particle Source]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/generalParticleSource.html\n[batch mode]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/executeProgram.html\n[simple syntax in text]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Detector/Geometry/geomASCII.html\n[G4VisExecutive]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Visualization/visexecutable.html#how-to-realize-visualization-drivers-in-an-executable\n[render]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Visualization/visualization.html\n[/score/]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Detector/commandScore.html\n[G4TScoreNtupleWriter]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Detector/hit.html#score-ntuple-writer\n[G4GlobalMagFieldMessenger]: https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Detector/electroMagneticField.html#creating-a-uniform-magnetic-field-with-user-commands\n\n[ui]: https://github.com/jintonic/mingle/tree/ui\n[batch]: https://github.com/jintonic/mingle/tree/batch\n[run]: https://github.com/jintonic/mingle/tree/run\n[physics]: https://github.com/jintonic/mingle/tree/physics\n[detector]: https://github.com/jintonic/mingle/tree/detector\n[gps]: https://github.com/jintonic/mingle/tree/gps\n[vis]: https://github.com/jintonic/mingle/tree/vis\n[scorer]: https://github.com/jintonic/mingle/tree/scorer\n[ntuple]: https://github.com/jintonic/mingle/tree/ntuple\n[field]: https://github.com/jintonic/mingle/tree/field\n[main]: https://github.com/jintonic/mingle\n\n[v0]: https://github.com/jintonic/mingle/releases/tag/v0\n[v1]: https://github.com/jintonic/mingle/releases/tag/v1\n[v2]: https://github.com/jintonic/mingle/releases/tag/v2\n[v3]: https://github.com/jintonic/mingle/releases/tag/v3\n[v4]: https://github.com/jintonic/mingle/releases/tag/v4\n[v5]: https://github.com/jintonic/mingle/releases/tag/v5\n[v6]: https://github.com/jintonic/mingle/releases/tag/v6\n[v7]: https://github.com/jintonic/mingle/releases/tag/v7\n[v8]: https://github.com/jintonic/mingle/releases/tag/v8\n[v9]: https://github.com/jintonic/mingle/releases/tag/v9\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjintonic%2Fmingle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjintonic%2Fmingle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjintonic%2Fmingle/lists"}