molcounters/sdcounters/README.md

0001 \page Examplesdcounters Example sdcounters
0002
0003 Author: C. Velten \n
0004 Date: 7 April 2025 \n
0005 Email: cv2415@columbia.edu
0006
0007 The custom (spatially-aware) molecule counter used here
0008 is further described in:
0009 - Radiat. Phys. Chem. 212 (2023) 111194 \n
0010 doi:10.1016/j.radphyschem.2023.111194
0011
0012  This example is provided by the Geant4-DNA collaboration
0013   (http://geant4-dna.org).
0014
0015   Any report or published results obtained using the Geant4-DNA software
0016   shall cite the following Geant4-DNA collaboration publications:\n
0017   Med. Phys. 45 (2018) e722-e739\n
0018   Phys. Med. 31 (2015) 861-874\n
0019   Med. Phys. 37 (2010) 4692-4708\n
0020   Int. J. Model. Simul. Sci. Comput. 1 (2010) 157–178\n
0021
0022 \Description:
0023
0024 ## Geometry
0025
0026 A box of liquid water with a 8 µm (radius) spherical cell placed at its center.
0027 The cell contains a 4 µm (radius) nucleus and 100 mitochondria.
0028
0029 ## Incident particles
0030
0031 Electrons with 1 keV energy, which can be changed in
0032 the simple_sbs.ini macro file.
0033 They are shot from the center of the box (inside the nucleus).
0034
0035 ## Physics
0036
0037 The default Geant4-DNA physics constructor 2 is used in
0038 the PhysicsList class with chemistry constructor 3.
0039
0040 ## Molecule Counters
0041
0042 Counters are defined and registered in the ActionInitialization
0043 class for master & workers using the BuildMoleculeCounters(), and
0044 BuildMultipleAndCustomMoleculeCounters() methods.
0045 To switch between either of these methods, change the
0046 boolean value of fBuildMultipleAndCustomMoleculeCounters in
0047 ActionInitialization.hh.
0048
0049 By default, the molecule counter manager will accumulate counts from
0050 worker instances into the master instance. To facilitate this the user
0051 __must__ create a `UserEventAction` and `UserRunAction` and override
0052 the `(Begin|End)Of(Event|Run)Action` methods and call the corresponding
0053 method on the `G4DNAChemistryManager::Instance()`. See the example's
0054 `EventAction.hh` and `RunAction.(hh|cc)` on how to do this.
0055
0056     __`BuildMoleculeCounters()`:__
0057     * __[important]__ Reset counters before each event but not keep counter values between events. \
0058     This is required since our scorers will read out the molecule counters using
0059     their `EndOfEvent()` method and save the recorded molecules.
0060     * Register a `G4MoleculeCounter` instance called "BasicCounter":
0061         * set its time precision to 10 ps
0062     * Register a `G4MoleculeCounter` instance called "BasicCounter_VariablePrecision":
0063         * set its time precision to vary with global time:
0064         ```
0065             <= 10 ps: 5 ps
0066             <= 100 ps: 50 ps
0067             <= 1 ns: 0.5 ns
0068             <= 1 µs: 50 ns
0069         ```
0070     * Register a `G4MoleculeReactionCounter` instance called "Reactions":
0071         * set its time precision to 10 ps
0072
0073 ## Multifunctional Detector & Primitive Scorers:
0074
0075 Two scorers are defined for molecule (`ScoreBasicMoleculeCounts`) and
0076 reaction (`ScoreBasicReactionCounts`) counts. The basic molecule scorers
0077 are instantiated once for each molecule counter.
0078 The results are saved as ROOT trees to a single file.
0079
0080 ## Execute the code by running:
0081
0082 ```
0083 ./sdcounters [simple_sbs.in,simple_irt_syn_react.in]
0084 ```
0085
0086 The `simple_sbs.in` macro __only__ includes molecule transport (diffusion)!
0087
0088 ## Output
0089
0090 Visualize the molecule and reaction counts using the Python notebook `plotRoot.ipynb`. It does not require a ROOT installation but the following packages:
0091     `matplotlib pandas seaborn uproot`