Merge pull request #470 from benedikt-nagler/main

Geant4 tutorial page: reformatting, error fixing

Author: fhagemann

docs/Project.toml

@@ -4,6 +4,7 @@ Geant4 = "559df036-b7a0-42fd-85df-7d5dd9d70f44"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+SolidStateDetectors = "71e43887-2bd9-5f77-aebd-47f656f0a3f0"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 

docs/src/tutorials/geant4_ssd_lit.jl

@@ -1,15 +1,15 @@
 # # Geant4 Support
 
 # SolidStateDetectors.jl provides an extension for Geant4.jl.
-# This extension allows to simulate realistic event distributions resulting from particles emitted by a given source, which can be used as input to the waveform simulation.
+# The extension allows users to generate realistic event distributions resulting from particles emitted by a specified source, which could then in turn also be used as input for a waveform simulation.
 #
 # To use the extension, both `SolidStateDetectors` and `Geant4` have to be loaded.
 
 using SolidStateDetectors
 using Geant4
 
-# In order to run `Geant4` simulations, a `Geant4.G4JLApplication` needs to be defined based on the detector geometry and the particle source.
-# The extension features a function that creates a `Geant4.G4JLApplcation` from an SSD `Simulation` object and a particle source.
+# In order to run Geant4 simulations, a `Geant4.G4JLApplication` needs to be defined, which needs to include both the detector geometry and the particle source.
+# The extension features a function that creates a `Geant4.G4JLApplcation` object from a SSD `Simulation` object and a particle source.
 
 using Plots
 using Unitful
@@ -18,7 +18,7 @@ using Unitful
 # 
 # #### 1. `MonoenergeticSource`
 # 
-# This source emits particles of the same type and same energy.
+# This source emits particles with a fixed type and energy.
 
 source_1 = MonoenergeticSource(
     "gamma",                              # Type of particle beam
@@ -29,11 +29,10 @@ source_1 = MonoenergeticSource(
 )
 
 # - The particle type is given as a string (e.g. `"e-"` or `"gamma"`) and directly passed to `Geant4`. See the `Geant4` documentation on how to name the desired particle type.
-# - The energy of the emitted particles is passed as a number with unit.
+# - The energy of the emitted particles is passed as a number with the required unit.
 # - The `position` of the particle source relative to the origin is defined by a `CartesianPoint` (in units of `m`).
-# - The source can emit particles in a given `direction` if a `CartesianVector` is provided. 
-#   If not, the emission is isotropic.
-# - If an `opening_angle` is provided, the source emits via a directed cone with the defined opening angle.
+# - The source emits particles in a given `direction`, specified by a `CartesianVector` object. If the user provides no direction, the emission will be isotropic.
+# - If an `opening_angle` is provided, the particles are emitted in a directed cone with the specified opening angle.
 
 # #### 2. `IsotopeSource`
 # 
@@ -50,7 +49,7 @@ source_2 = IsotopeSource(
 )
 
 # The source is defined using
-# - The number of protons `Z` and the number of nucleons `A` in the isotope. <br/>
+# - The number of protons `Z` and the number of nucleons `A` in the isotope.
 # - The excitation energy
 # - The charge of the isotope
 # - The position, direction and opening angle from the source can be defined in the same way as for a `MonoenergeticSource`
@@ -69,13 +68,12 @@ plot!(source_1)
 
 # A `Geant4.G4JLApplication` is built from a SSD `Simulation` `sim` and one of the previously defined particle sources, e.g. `source_1`.
 # 
-# Internally, a GDML file is created that is subsequently read in by `Geant4.jl`. <br/> 
-# If needed, the resulting GDML file can also be saved by using the `Geant4.G4JLDetector(sim, "output_filename.gdml")` command.
+# Internally, the translated geometry description is written to a temporary GDML file. This file will in turn be read in by `Geant4.jl` and deleted afterwards. However, if needed, the resulting GDML file can also be saved by using the `Geant4.G4JLDetector(sim, "output_filename.gdml", save_gdml = true)` function.
 
 app = G4JLApplication(sim, source_1, verbose = false);
 
 
-# The method `run_geant4_simulation` is used to generate a given number of events.
+# Having defined a `G4JLApplication`, it is now possible to generate events using the `run_geant4_simulation` function. The function will continue running until the desired number of energy depositions have been recorded.
 
 N_events = 50000
 events = run_geant4_simulation(app, N_events)
@@ -87,7 +85,7 @@ events = run_geant4_simulation(app, N_events)
 # - `edep`: Amount of energy that was deposited in the detector
 # - `pos`: Position where the interaction happened
 
-# By extracting the position of each energy deposition from `events`, the spatial distribution of the events inside the detector can be plotted:
+# By extracting the position of each energy deposition from `events`, the spatial distribution of the events inside the detector can be visualized:
 
 plot(sim.detector, show_passives = false, size = (500,500), fmt = :png)
 plot!(source_1)
@@ -99,19 +97,19 @@ plot!(CartesianPoint.(broadcast(p -> ustrip.(u"m", p), events[1:1000].pos.data))
 
 # The output of `run_geant4_simulation` can be stored using the `LegendHDF5IO` package:
 
-# ```
+# ```Julia
 # using LegendHDF5IO
-#
+# 
 # lh5open("simulation_output.lh5", "w") do h
-#      LegendHDF5IO.writedata(h.data_store, "SimulationData", events)
+#     LegendHDF5IO.writedata(h.data_store, "SimulationData", events)
 # end
-#
+
 # events_in = lh5open("simulation_output.lh5", "r") do h
 #     LegendHDF5IO.readdata(h.data_store, "SimulationData")
 # end
 # ```
 
-# In order to visualize the energy spectrum of the events in a histogram, you can use the following code:
+# In order to visualize the energy spectrum of the events in a histogram, the following code can be used:
 
 using StatsBase
 
@@ -125,16 +123,16 @@ xlims!(0,3000, xlabel = "E in keV", ylabel = "counts")
 #md # [![spectrum](spectrum.svg)](spectrum.pdf) 
 
 
-# Now that the energy depositions in the detector are simulated, they can be passed to SSD to calculate the corresponding waveforms.
-# This requires to calculate the electric potential, the electric field and the weighting potential of the detector first.
+# Now that a realistic event distribution has been generated, it can be used as input for the waveform simulation.
+# To perform the waveform simulation, the detectors electric field and weighting potential have to be calculated first.
 
 sim.detector = SolidStateDetector(sim.detector, ADLChargeDriftModel(T=T))
 calculate_electric_potential!(sim, refinement_limits = [0.4,0.2,0.1,0.06], verbose = false)
 calculate_electric_field!(sim, n_points_in_φ = 10)
 calculate_weighting_potential!(sim, 1, refinement_limits = [0.4,0.2,0.1,0.06], verbose = false)
 
 
-# The waveforms can be simulated using `simulate_waveforms`:
+# The previously generated events from the Geant4 simulation can now be used as input for the `simulate_waveforms` function:
 
 wf = simulate_waveforms(events[1:100], sim, Δt = 1u"ns", max_nsteps = 2000)
 plot(wf[1:20].waveform, label = "")
@@ -145,7 +143,6 @@ plot(wf[1:20].waveform, label = "")
 
 
 
-
 # We can add some baseline and tail to the pulses to match their lengths (in this case to 2000ns):
 
 w = add_baseline_and_extend_tail.(wf.waveform, 100, 2000)