Merge branch 'master' of github.com:OpenGATE/opengate

docs/source/user_guide/index.rst

@@ -21,7 +21,7 @@ User Guide
 
 .. toctree::
    :caption: Detailed description of components
-   :maxdepth: 2
+   :maxdepth: 3
 
    user_guide_reference_simulation
    user_guide_reference_volumes

docs/source/user_guide/user_guide_advanced.rst

@@ -194,11 +194,9 @@ automatically added:
 -  Wave-length shifting
 -  Boundary Scattering
 
-.. note:: It’s important to note that merely including the
-G4OpticalPhysics physics list does not automatically activate the
-Cherenkov process. To generate Cherenkov photons, it’s necessary to set
-an appropriate electron physics cut in the relevant volume. Currently,
-setting the electron physics cut to 0.1 mm has been found effective:
+.. note:: It’s important to note that merely including the G4OpticalPhysics physics list does not automatically activate the Cherenkov process.
+
+To generate Cherenkov photons, it’s necessary to set an appropriate electron physics cut in the relevant volume. Currently, setting the electron physics cut to 0.1 mm has been found effective:
 
 .. code:: python
 
@@ -473,7 +471,7 @@ reflection.
 Defining Surfaces
 -----------------
 
-.. image:: figures/surface-definition.png
+.. image:: ../figures/surface-definition.png
 
 The photon travels through the surface between the two volumes Volume1
 and Volume2. To create an optical surface from Volume1 to Volume2, the
@@ -537,11 +535,15 @@ reflector (e.g. ESR) or a Lambertian reflector (e.g. Teflon). The
 specular reflector can be coupled to the crystal with air or optical
 grease. Teflon tape is wrapped around the crystal with 4 layers.
 
-Surface names of available LUTs - \| \| BARE \| TEFLON \| ESR AIR \| ESR
-GREASE \| \|———–|——————-|——————-|——————-|————————-\| \| POLISHED \|
-Polished_LUT \| PolishedTeflon_LUT\| PolishedESR_LUT \|
-PolishedESRGrease_LUT \| \| ROUGH \| Rough_LUT \| RoughTeflon_LUT \|
-RoughESR_LUT \| RoughESRGrease_LUT \|
+Surface names of available LUTs
+
++-----------+--------------+--------------------+-----------------+-----------------------+
+|           |   BARE       |      TEFLON        |   ESR AIR       |   ESR GREASE          |
++===========+==============+====================+=================+=======================+
+| POLISHED  | Polished_LUT | PolishedTeflon_LUT | PolishedESR_LUT | PolishedESRGrease_LUT |
++-----------+--------------+--------------------+-----------------+-----------------------+
+| ROUGH     | Rough_LUT    | RoughTeflon_LUT    |  RoughESR_LUT   |  RoughESRGrease_LUT   |
++-----------+--------------+--------------------+-----------------+-----------------------+
 
 The user can extend the list of finishes with custom measured surface
 data. In GATE, this can be achieved by utilising
@@ -621,7 +623,7 @@ includes a 3 mm x 3 mm x 20 mm scintillation crystal coupled to a 3 mm x
 irradiating it at 10 mm depth. The set surface is RoughTeflon_LUT in
 combination with the Detector_LUT as the photo detector surface.
 
-.. image:: figures/example_lut_davis_model.png
+.. image:: ../figures/example_lut_davis_model.png
 
 Background
 ----------
@@ -640,7 +642,7 @@ extracted from the first LUT. A Bernoulli test determines whether the
 photon is reflected or transmitted. In case of reflection two angles are
 drawn from the reflection direction LUT.
 
-.. image:: figures/flowchart_lut_model.png
+.. image:: ../figures/flowchart_lut_model.png
 
 Old Momentum to New Momentum. The old momentum is the unit vector that
 describes the incident photon. The reflected/transmitted photon is the
@@ -661,7 +663,7 @@ distribution of micro-facets around the average surface normal. In the
 case of a perfectly polished surface, the normal used by the
 G4BoundaryProcess is the normal to the surface.
 
-.. image:: figures/reflection_types_and_microfacets.png
+.. image:: ../figures/reflection_types_and_microfacets.png
 
 An example of a surface definition looks like:
 

docs/source/user_guide/user_guide_reference_actors.rst

@@ -62,26 +62,38 @@ DoseActor
 Description
 ~~~~~~~~~~~
 
-The DoseActor computes a 3D energy deposition (edep) or absorbed dose map in a given volume. The dose map is a 3D matrix parameterized with: dimension (number of voxels), spacing (voxel size), and translation (according to the coordinate system of the attached volume). By default, the matrix is centered according to the volume center.
+The DoseActor scores the energy deposition (edep) or absorbed dose map in a given volume. The dose map is a 3D matrix parameterized with: size (number of voxels), spacing (voxel size), and translation (according to the coordinate system of the attached volume) and rotation. By default, the matrix is centered according to the volume center. Note that this virtual scoring grid is independent of a potential geometric grid (e.g. simulation using a voxelized CT image as geometry).  The dose map may also have singleton dimensions (dose.size values with 1) reducing its effecctive dimension.
 
-Like any image, the output dose map will have an origin. By default, it will consider the coordinate system of the volume it is attached to, so at the center of the image volume. The user can manually change the output origin using the option `output_origin` of the DoseActor. Alternatively, if the option `img_coord_system` is set to `True`, the final output origin will be automatically computed from the image the DoseActor is attached to. This option calls the function `get_origin_wrt_images_g4_position` to compute the origin.
+A sample code to score the energy deposition (default) is shown below. Let's assume a geometry of type box with name "waterbox" is already defined and is [200, 200, 200] *mm big. The dose actor output would now cover the entire size of the "waterbox" and has the same center.
+.. code-block:: python
+
+   dose_act_obj = sim.add_actor("DoseActor", "dose_act_obj")
+   dose_act_obj.output_filename = "test008-edep.mhd"
+   dose_act_obj.attached_to = "waterbox"
+   dose_act_obj.size = [100, 100, 100]
+   mm = gate.g4_units.mm
+   dose_act_obj.spacing = [2 * mm, 2 * mm, 2 * mm]
+
+Adding following lines
+.. code-block:: python
+   dose_act_obj.user_output.dose.active True
+   dose_act_obj.user_output.uncertainty.active True
+to the dose actor object will trigger an additional image scoring the dose. The unctertainty tag will additionally provide an uncertainty image for each of the scoring quantities. Set user_output.edep.active False to disable the edep computation and only return the dose.
+
+Like any image, the output dose map will have an origin, spacing and orientation. By default, it will consider the coordinate system of the volume it is attached to, so at the center of the image volume. The user can manually change the output origin using the option `output_origin` of the DoseActor. Alternatively, if the option `img_coord_system` is set to `True`, the final output origin will be automatically computed from the image the DoseActor is attached to. This option calls the function `get_origin_wrt_images_g4_position` to compute the origin.
 
 .. image:: ../figures/image_coord_system.png
 
 Several tests depict the usage of DoseActor: test008, test009, test021, test035, etc.
 
 .. code-block:: python
 
-   dose = sim.add_actor("DoseActor", "dose")
-   dose.output_filename = output_path / "test008-edep.mhd"
-   dose.attached_to = "waterbox"
-   dose.size = [99, 99, 99]
-   mm = gate.g4_units.mm
-   dose.spacing = [2 * mm, 2 * mm, 2 * mm]
-   dose.translation = [2 * mm, 3 * mm, -2 * mm]
-   dose.uncertainty = True
-   dose.hit_type = "random"
+Following would translate and rotate the scoring image:
+   from scipy.spatial.transform import Rotation
+   dose_act_obj.translation = [2 * mm, 3 * mm, -2 * mm]
+   dose_act_obj.rotation = Rotation.from_euler("y", 90, degrees=True).as_matrix()
 
+In this example a uniform scoring object was created for simplicity. To test trans- and rotations, non-uniform sized and spaced voxelized image are highly encouraged.
 
 Reference
 ~~~~~~~~~
@@ -92,7 +104,14 @@ Reference
 LETActor
 --------
 
-.. note:: Refer to test050 for current examples.
+Description
+~~~~~~~~~~~
+
+The LET Actor scores the fluence- (also referred to as track-) or dose averaged LET within a volume using a voxelizing parametrization identical to the Dose Actor. Hence, see the Dose Actor documentation for spatial commands like image resolution, origin etc. - the same commands apply for the LET Actor.
+
+.. note:: In most use cases of LET in literature, only a subset of particles is considered for the calculation of averaged LET, e.g. in proton radiotherapy, where often only protons are considered. Therefore, the LET actor often goes along with a particle filter. See test050 as an example.
+
+.. note:: Refer to test050 for a current example.
 
 
 Reference
@@ -589,4 +608,4 @@ Similar to :class:`~.opengate.actors.miscactors.ComptSplittingActor`
 Reference
 ~~~~~~~~~
 
-.. autoclass:: opengate.actors.miscactors.BremSplittingActor
+.. autoclass:: opengate.actors.miscactors.BremSplittingActor

docs/source/user_guide/user_guide_reference_sources.rst

@@ -3,89 +3,16 @@
 Details: Sources
 ****************
 
-Common parameters
-=================
 
-Sources are the objects that create particles *ex nihilo*. The particles
-created from sources are called the *Event* in the Geant4 terminology,
-they got a *EventID* which is unique in a given *Run*.
 
-Several sources can be defined and are managed at the same time. To add
-a source description to the simulation, you do:
+.. toctree::
+   :maxdepth: 2
 
-.. code:: python
+   user_guide_reference_sources_common_params.rst
+   user_guide_reference_sources_generic_source.rst
+   user_guide_reference_sources_voxel_source.rst
+   user_guide_reference_sources_ion_pencil_beam_source.rst
+   user_guide_reference_sources_treatment_plan_pencil_beam_source.rst
+   user_guide_reference_sources_gan_source.rst
+   user_guide_reference_sources_phid_source.rst
 
-   source1 = sim.add_source('GenericSource', 'source1')
-   source1.n = 100
-
-   source2 = sim.add_source('VoxelSource', 'source2')
-   source2.activity = 10 * g4_units.Bq
-
-There are several source types, each one with different parameter. In
-this example, ``source1.n`` indicates that this source will generate 100
-Events. The second source manages the time and will generate 10 Events
-per second, so according to the simulation run timing, a different
-number of Events will be generated.
-
-Information about the sources may be displayed with:
-
-.. code:: python
-
-   # Print all types of source
-   print(sim.dump_source_types())
-
-   # Print information about all sources
-   print(sim.dump_sources())
-
-Some of the parameters are common to **all** types of sources, while others
-are specific to a certain type of source.
-Given a source ``source``, use ``print(source)`` to display the
-source's parameters and their default values.
-
-Common parameters are:
-
-* | ``attached_to``: the name of the volume to which the source is attached (``world`` by default) in the hierarchy of volumes.
-  | See :ref:`geometry-and-volumes` for more details.
-* | ``position.translation``: list of 2 numerical values, e.g. ``[0, 2 * cm, 3 * mm]``.
-  | It defines the translation of the source with respect to the reference frame of the attached volume.
-  | Note: the origin of the reference frame is always at the center of the shape in Geant4.
-* | ``rotation``: a 3×3 rotation matrix.
-  | Rotation of the volume with respect to the attached volume.
-  | We advocate the use of `scipy.spatial.transform.Rotation` to manage the rotation matrix.
-* | ``n``: the number (integer) of particles to emit (the number of Geant4 Events).
-* | ``activity``: the number (real, in Bq) of particle to emit per second.
-  | The number of Geant4 Events will depend on the simulation time.
-
-
-Coordinate system
------------------
-
-The :attr:`~.opengate.sources.base.SourceBase.attached_to` option indicates the coordinate system of the source. By
-default, it is the world, but it is possible to attach a source to any
-volume. In that case, the coordinate system of all emitted particles
-will follow the given volume.
-Using ``source.direction_relative_to_attached_volume = True`` will make
-your source direction change following the rotation of that volume.
-
-
-Reference
----------
-
-.. autoproperty:: opengate.sources.base.SourceBase.attached_to
-
-The current types of sources are the following:
-
-* :ref:`source-generic-source`
-* :ref:`source-voxel-source`
-* :ref:`source-ion-pencil-beam-source`
-* :ref:`source-treatment-plan-pencil-beam-source`
-* :ref:`source-gan-source`
-* :ref:`source-phid-source`
-
-
-.. include:: user_guide_reference_sources_generic_source.rst
-.. include:: user_guide_reference_sources_voxel_source.rst
-.. include:: user_guide_reference_sources_ion_pencil_beam_source.rst
-.. include:: user_guide_reference_sources_treatment_plan_pencil_beam_source.rst
-.. include:: user_guide_reference_sources_gan_source.rst
-.. include:: user_guide_reference_sources_phid_source.rst

docs/source/user_guide/user_guide_reference_sources_common_params.rst

@@ -0,0 +1,69 @@
+Common parameters
+=================
+
+Sources are the objects that create particles *ex nihilo*. The particles
+created from sources are called the *Event* in the Geant4 terminology,
+they got a *EventID* which is unique in a given *Run*.
+
+Several sources can be defined and are managed at the same time. To add
+a source description to the simulation, you do:
+
+.. code:: python
+
+   source1 = sim.add_source('GenericSource', 'source1')
+   source1.n = 100
+
+   source2 = sim.add_source('VoxelSource', 'source2')
+   source2.activity = 10 * g4_units.Bq
+
+There are several source types, each one with different parameter. In
+this example, ``source1.n`` indicates that this source will generate 100
+Events. The second source manages the time and will generate 10 Events
+per second, so according to the simulation run timing, a different
+number of Events will be generated.
+
+Information about the sources may be displayed with:
+
+.. code:: python
+
+   # Print all types of source
+   print(sim.dump_source_types())
+
+   # Print information about all sources
+   print(sim.dump_sources())
+
+Some of the parameters are common to **all** types of sources, while others
+are specific to a certain type of source.
+Given a source ``source``, use ``print(source)`` to display the
+source's parameters and their default values.
+
+Common parameters are:
+
+* | ``attached_to``: the name of the volume to which the source is attached (``world`` by default) in the hierarchy of volumes.
+  | See :ref:`volumes-reference-label` for more details.
+* | ``position.translation``: list of 2 numerical values, e.g. ``[0, 2 * cm, 3 * mm]``.
+  | It defines the translation of the source with respect to the reference frame of the attached volume.
+  | Note: the origin of the reference frame is always at the center of the shape in Geant4.
+* | ``rotation``: a 3×3 rotation matrix.
+  | Rotation of the volume with respect to the attached volume.
+  | We advocate the use of `scipy.spatial.transform.Rotation` to manage the rotation matrix.
+* | ``n``: the number (integer) of particles to emit (the number of Geant4 Events).
+* | ``activity``: the number (real, in Bq) of particle to emit per second.
+  | The number of Geant4 Events will depend on the simulation time.
+
+
+Coordinate system
+-----------------
+
+The :attr:`~.opengate.sources.base.SourceBase.attached_to` option indicates the coordinate system of the source. By
+default, it is the world, but it is possible to attach a source to any
+volume. In that case, the coordinate system of all emitted particles
+will follow the given volume.
+Using ``source.direction_relative_to_attached_volume = True`` will make
+your source direction change following the rotation of that volume.
+
+
+Reference
+---------
+
+.. autoproperty:: opengate.sources.base.SourceBase.attached_to

docs/source/user_guide/user_guide_reference_sources_gan_source.rst

@@ -1,6 +1,3 @@
-.. The next line draws an horizontal line
------
-
 .. _source-gan-source:
 
 GAN sources (Generative Adversarial Network)

docs/source/user_guide/user_guide_reference_sources_generic_source.rst

@@ -1,6 +1,3 @@
-.. The next line draws an horizontal line
------
-
 .. _source-generic-source:
 
 Generic source
@@ -47,6 +44,7 @@ can be defined by a single value (‘mono’) or Gaussian (‘gauss’).
 
 
 .. _source-particle-type:
+
 Particle type
 -------------
 
@@ -79,6 +77,7 @@ Source of ion can be set with the following (see ``test013``)
 
 
 .. _source-position:
+
 Particle initial position
 -------------------------
 
@@ -117,6 +116,7 @@ Here are some examples (mostly from ``test010_generic_source.py``):
 
 
 .. _source-direction:
+
 Particle initial direction
 --------------------------
 
@@ -134,20 +134,6 @@ Particle initial direction
       source.direction.phi = [0, 90 * deg]
 
 
-``direction.type = "iso"`` assigns directions to primary particles
-based on 𝜃 and 𝜙 angles in a `spherical coordinate system
-<https://en.wikipedia.org/wiki/Spherical_coordinate_system>`__.
-By default, 𝜃 varies from 0° to 180° and 𝜙 varies from 0° to 360°
-(such that any direction is possible). You can define the 𝜃 and 𝜙
-ranges with minimum and maximum values as follows:
-
-.. code:: python
-
-    source.direction.type = "iso"
-    source.direction.theta = [0, 10 * deg]
-    source.direction.phi = [0, 90 * deg]
-
-
 Geant4 defines the direction as: - x = -sin𝜃 cos𝜙; - y = -sin𝜃 sin𝜙; - z
 = -cos𝜃.
 

docs/source/user_guide/user_guide_reference_sources_ion_pencil_beam_source.rst

@@ -1,7 +1,3 @@
-.. The next line draws an horizontal line
------
-
-
 .. _source-ion-pencil-beam-source:
 
 Ion Pencil Beam Source