molcounters/basic/README.md

0001 \page Examplebasic Example basic
0002
0003 This molecule counter basic example is provided by the Geant4-DNA collaboration
0004   (http://geant4-dna.org).
0005
0006 The custom (spatially-aware) molecule counter used here
0007 is further described in:
0008 - Radiat. Phys. Chem. 212 (2023) 111194 \
0009 doi:10.1016/j.radphyschem.2023.111194
0010
0011   Any report or published results obtained using the Geant4-DNA software
0012   shall cite the following Geant4-DNA collaboration publications:\n
0013   Med. Phys. 51 (2024) 5873–5889\n
0014   Med. Phys. 45 (2018) e722-e739\n
0015   Phys. Med. 31 (2015) 861-874\n
0016   Med. Phys. 37 (2010) 4692-4708\n
0017   Int. J. Model. Simul. Sci. Comput. 1 (2010) 157–178\n
0018
0019 \Description:
0020
0021
0022 ## Geometry
0023
0024 A box of liquid water with a 8 µm (radius) spherical cell placed at its center.
0025 The cell contains a 4 µm (radius) nucleus and 100 mitochondria.
0026
0027 ## Particles
0028
0029 Electrons with 1 keV energy, which can be changed in
0030 the simple_sbs.ini macro file.
0031 They are shot from the center of the box (inside the nucleus).
0032
0033 ## Physics
0034
0035 The default Geant4-DNA physics constructor 2 is used in
0036 the PhysicsList class with chemistry constructor 3.
0037
0038 ## Counters
0039
0040 Counters are defined and registered in the ActionInitialization
0041 class for master & workers using the BuildMoleculeCounters(), and
0042 BuildMultipleAndCustomMoleculeCounters() methods.
0043 To switch between either of these methods, change the
0044 boolean value of fBuildMultipleAndCustomMoleculeCounters in
0045 ActionInitialization.hh.
0046
0047 By default, the molecule counter manager will accumulate counts from
0048 worker instances into the master instance. To facilitate this the user
0049 __must__ create a `UserEventAction` and `UserRunAction` and override
0050 the `(Begin|End)Of(Event|Run)Action` methods and call the corresponding
0051 method on the `G4DNAChemistryManager::Instance()`. See the example's
0052 `EventAction.hh` and `RunAction.(hh|cc)` on how to do this.
0053
0054     __Default Method: `BuildMoleculeCounters()`:__
0055     * Reset counters before each run but not keep counter values between events
0056     * Register a default `G4MoleculeCounter` instance called "Molecules"
0057     * Register a default `G4MoleculeReactionCounter` instance called "Reactions"
0058
0059
0060     __Alternative Method: `BuildMultipleAndCustomMoleculeCounters()`:__
0061     * Reset counters before each run but not keep counter values between events
0062     * Register a `G4MoleculeCounter` instance called "BasicCounter":
0063         * set its time precision to 25 ps
0064     * Register a `G4MoleculeCounter` instance called "BasicCounter_Restricted":
0065         * set its time precision to 25 ps
0066         * activate the counter for global times in [500 ps, 10 ns]
0067     * Register a `G4MoleculeCounter` instance called "BasicCounter_VariablePrecision":
0068         * set its time precision to vary with global time:
0069         ```
0070             <= 10 ps: 5 ps
0071             <= 100 ps: 50 ps
0072             <= 1 ns: 0.5 ns
0073             <= 1 µs: 50 ns
0074         ```
0075         * activate the counter for global times in [500 ps, 10 ns]
0076     * Register a custom `MoleculeCounter` instance called "MoleculeCounter"
0077         * set its time precision to vary with global time:
0078         ```
0079             <= 10 ps: 5 ps
0080             <= 100 ps: 50 ps
0081             <= 1 ns: 0.5 ns
0082             <= 1 µs: 50 ns
0083         ```
0084         * __(important)__ `SetSensitiveToStepping(true)` to change molecule count when traversing geometry boundaries
0085         * `SetIgnoreMoleculePosition(false)` if set to `true` the counter behaves like `G4MoleculeCounter`
0086         * `SetNegativeCountsAreFatal(true)` to throw a FatalException if any molecule count drops below 0 through misregistration
0087     * Register a `G4MoleculeReactionCounter` instance called "Reactions":
0088         * set its time precision to 50 ps
0089         * activate the counter for global times in [0 ps, 1 µs]
0090
0091 ## Execute the code by running:
0092
0093 ```
0094 ./molcounters_basic [simple_sbs.in,simple_irt_syn_react.in]
0095 ```
0096
0097 The `simple_sbs.in` macro __only__ includes molecule transport (diffusion)!
0098
0099 Contents of the molecule counters are dumped to `stdout`
0100 at the end of each run by the RunAction::EndOfRunAction()