Merge branch 'KATRIN-Experiment:main' into mott_scattering

.github/workflows/test.yml

@@ -43,12 +43,12 @@ jobs:
             export CC=/usr/bin/clang
             export CXX=/usr/bin/clang++
         fi
-        ./setup.sh
+        KASSIOPEIA_CUSTOM_CMAKE_ARGS="-DENABLE_SANITIZE_ADDRESSES=ON" ./setup.sh
       shell: bash
 
     - name: Launch environment and run tests
       run: |
-        source root/bin/thisroot.sh && source install/bin/kasperenv.sh && UnitTestKasper
+        source root/bin/thisroot.sh && source install/bin/kasperenv.sh && ASAN_OPTIONS=detect_leaks=0 UnitTestKasper
       shell: bash
 
   fedora_40:
@@ -66,7 +66,8 @@ jobs:
             root-core root-io-xmlparser root-minuit2 root-spectrum root-genvector \
             vtk vtk-qt \
             boost-devel fftw-devel gsl-devel hdf5-devel libomp-devel liburing-devel libxml2-devel log4cxx-devel \
-            ocl-icd-devel openmpi-devel openssl-devel sqlite-devel vtk-devel zlib-devel
+            ocl-icd-devel openmpi-devel openssl-devel sqlite-devel vtk-devel zlib-devel \
+            libasan
     - name: Build code
       run: |
         if ${{ matrix.use_clang }}; then
@@ -75,10 +76,10 @@ jobs:
             export CC=/usr/bin/clang
             export CXX=/usr/bin/clang++
         fi
-        ./setup.sh
+        KASSIOPEIA_CUSTOM_CMAKE_ARGS="-DENABLE_SANITIZE_ADDRESSES=ON" ./setup.sh
       shell: bash
 
     - name: Launch environment and run tests
       run: |
-        source install/bin/kasperenv.sh && UnitTestKasper
+        source install/bin/kasperenv.sh && ASAN_OPTIONS=detect_leaks=0 UnitTestKasper
       shell: bash

Documentation/gh-pages/source/configuring_simulation_statements.rst

@@ -149,7 +149,7 @@ Both examples together will yield the output::
     [INITIALIZATION NORMAL MESSAGE] This is a test message.
 
 Instead of showing normal messages, it is also possible to show a warning or an error message. An error message will
-terminate the prgogram, so it is most useful in combination with the conditional expressions described below:
+terminate the program, so it is most useful in combination with the conditional expressions described below:
 
 .. code-block:: xml
 
@@ -256,6 +256,9 @@ included by the syntax:
 As shown above, a comment can span multiple lines. Any text between ``<!-- ... -->`` is ignored by the XML initializer,
 including any XML elements. This makes it possible to quickly comment out parts of the file, e.g. for debugging.
 
+.. note::
+
+    An important difference to regular XML syntax is the fact that comments can be nested: ``<!-- ... <!-- ... --> ... -->`` is entirely ignored.
 
 
 .. rubric:: Footnotes

Documentation/gh-pages/source/element_kassiopeia.rst

@@ -33,6 +33,4 @@ outlined in this chapter.
      kassiopeia_navigation
      kassiopeia_simulation
      kassiopeia_visualization
-
-
-
+     kassiopeia_tools

Documentation/gh-pages/source/element_kemfield.rst

@@ -31,7 +31,5 @@ described here.
 
      kemfield_fields
      kemfield_visualization
+     kemfield_tools
      kemfield_manual
-
-
-

Documentation/gh-pages/source/element_kgeobag.rst

@@ -43,5 +43,4 @@ Every relevant to the geometry description is processed by *KGeoBag* and must ap
      kgeobag_simple_shapes
      kgeobag_complex_shapes
      kgeobag_visualization
-
-
+     kgeobag_tools

Documentation/gh-pages/source/index.rst

@@ -78,7 +78,6 @@ Welcome to Kassiopeia's documentation!
     :caption: Further Information
 
     Understanding Simulation Output <output.rst>
-    Additional Simulation Tools <tools.rst>
     Visualization Techniques <visualization.rst>
     XML Bindings <bindings.rst>
 

Documentation/gh-pages/source/kassiopeia_output.rst

@@ -143,8 +143,8 @@ output is written after the completion of each step. Similary, at the track leve
 to the initial and final parameters of a track, i.e. the state at particle generation and termination.
 
 The standard output fields for the particle are defined at the end of the file
-:gh-code:`Kassiopeia/Operators/Source/KSParticle.cxx` while the step and track output fields can be found in
-:gh-code:`Kassiopeia/Operators/Source/KSStep.cxx` and :gh-code:`Kassiopeia/Operators/Source/KSTrack.cxx`, respectively.
+:gh-code:`Kassiopeia/Simulation/Source/KSParticle.cxx` while the step and track output fields can be found in
+:gh-code:`Kassiopeia/Simulation/Source/KSStep.cxx` and :gh-code:`Kassiopeia/Simulation/Source/KSTrack.cxx`, respectively.
 Other specialized output fields are also available for some propagation or interaction terms.
 
 Output fields
@@ -296,6 +296,8 @@ overview of the different fields and their types.
 +--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
 | Number of Turns    | ``number_of_turns``                 | ``unsigned int`` | ``KSRun``                  | Number of particle turns/reflections during run          |
 +--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
+| Processing Duration| ``processing_duration``             | ``double``       | ``KSRun``                  | Computing time used for run                              |
++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
 | Event ID           | ``event_id``                        | ``int``          | ``KSEvent``                | Event ID of current event                                |
 +--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
 | Event Count        | ``event_count``                     | ``int``          | ``KSEvent``                | Total number of events                                   |
@@ -338,6 +340,8 @@ overview of the different fields and their types.
 +--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
 | Generator Radius   | ``generator_radius``                | ``double``       | ``KSEvent``                | Maximum radius of the generated particles (in m)         |
 +--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
+| Processing Duration| ``processing_duration``             | ``double``       | ``KSEvent``                | Computing time used for event                            |
++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
 | Track ID           | ``event_id``                        | ``int``          | ``KSTrack``                | Track ID of current track                                |
 +--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
 | Track Count        | ``event_count``                     | ``int``          | ``KSTrack``                | Total number of tracks                                   |
@@ -440,6 +444,8 @@ overview of the different fields and their types.
 +--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
 | Intermed. Particle | ``trajectory_particle``             | ``KSParticle``   | ``KSStep``                 | Pointer to initial particle before propagation           |
 +--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
+| Processing Duration| ``processing_duration``             | ``double``       | ``KSStep``                 | Computing time used for step                             |
++--------------------+-------------------------------------+------------------+----------------------------+----------------------------------------------------------+
 
 Vector and matrix type can be accessed by their components in the written output data. For example, when the ``position``
 element is used, the corresponding fields in the output data can be found under the names ``position_x``, ``position_y``,

Documentation/gh-pages/source/kassiopeia_tools.rst

@@ -0,0 +1,16 @@
+Tools
+=====
+
+Some helper tools are provided with *Kassiopeia* that can be used together with simulations:
+
+* ``ROOTFileMerge`` combines several simulation output files into a single file with all runs/events combined. This is
+  useful in the case of Monte-Carlo simulations, where *Kassiopeia* is executed several times with the same or slightly
+  different settings. Although the individual output files could be analyzed separately, sometimes it is beneficial to
+  combine all results into a single file that can then be analyzed in a single go. The program simply takes a list
+  of input files, followed by the name of an output file that will be created.
+* ``ParticleGenerator`` provides a quick method to generate particles as specified in a configuration file, without
+  running a simulations. This is useful for the design of simulations, and to compare and validate the generators used
+  by the simulations. The program generates an output text file that contains one line for each generated particle,
+  with information about its position, energy, and so on.
+
+All listed programs will show a brief usage summary if called without arguments.

Documentation/gh-pages/source/kemfield_tools.rst

@@ -0,0 +1,53 @@
+Tools
+*****
+
+Field calculation
+=================
+
+Although *Kassiopeia* is quite powerful in terms of configuration options, sometimes it is necessary to calculate the
+electric or magnetic field at one or more defined points in the geometry. This is especially useful to compare
+different geometry setups, or during the design stage when full-scale simulations are not yet feasible. The field
+calculation tools are intended to help with these tasks.
+
+Several programs are available for working with electric fields:
+
+* ``SimpleElectricFieldCalculator`` calculates the electric field and potential at a single point in the global
+  coordinate system, and prints the results to the terminal.
+* ``SimpleElectricFieldCalculatorAlongZaxis`` calculates the electric field and potential at several points spread
+  along the z-axis, defined by a start and stop position on the z-axis and a distance between points. The results are
+  printed to the terminal and saved to a output text file.
+* ``SimpleElectricFieldCalculatorOverXYplane`` calculates the electric field and potential at several points spread
+  over the xy-plane, defined by a position on the z-axis, a maimum radius, and a distance between points. The results
+  are printed to the terminal and saved to a output text file.
+* ``SimpleElectricFieldCalculatorAlongFieldline`` calculates the electric field and potential along a field line,
+  which is calculated with the help of *Kassiopeia* using a magnetic trajectory. In principle this can be done through
+  the *Kassiopeia* XML interfaces, but this program provides a convenient method for a simple field line calculation.
+  The results are printed to the terminal and saved to a output text file.
+* ``SimpleElectricFieldCalculatorFromFile`` takes coordinates from a given input text file and calculates the electric
+  field and potential at each point. The results are printed to the terminal and saved to a output text file.
+
+For working with magnetic fields, the same programs are available under the adapted name ``SimpleMagneticFieldCalculator``
+and so on. In addition, there is:
+
+* ``SimpleMagneticGradientCalculator`` calculates the magnetic field and its gradient at a single point in the global
+  coordinate system, and prints the results to the terminal.
+
+Development
+===========
+
+Some KEMField tools are especially useful for development. `InspectEMFile` e.g. prints an overview over all keys in 
+`.kbd` files (like KEMField cache files, from which the hash values can be used for the `explicit_superposition_cached_charge_density_solver`). These tools can be found here: :gh-code:`KEMField/Source/Applications/Tools`.
+
+Usage
+=====
+
+All listed programs will show a brief usage summary if called without arguments. For example, the
+``SimpleElectricFieldCalculatorAlongZaxis`` will show a message:
+
+.. code-block::
+
+    usage: ./SimpleElectricFieldCalculatorAlongZaxis <config_file.xml> <z1> <z2> <dz> <output_file.txt> <electric_field_name1> [<electric_field_name2> <...>]
+
+which indicates that at least 6 arguments are required: the name of a configuration file with at least one defined
+electric field; the start and stop position and step distance on the z-axis; the name of an output file; and the name
+of an electric field. If multiple fields are specified, their contributions will be summed up.

Documentation/gh-pages/source/kgeobag_tools.rst

@@ -0,0 +1,89 @@
+Tools
+*****
+
+The main application for simulations is ``Kassiopeia``. The XML interface allows flexible configuration that is suited
+to many tasks. However, sometimes a more direct approach to certain investigations is needed. In the following, 
+additional tools that are included with *KGeoBag* are presented that are typically of use during simulation design and
+debugging.
+
+Geometry viewers
+================
+
+The geometry viewwers are intended to help with constructing and optimizing a simulation geometry that is typically
+used with *Kassiopeia* and *KEMField*. In most cases, the simulation requires a sophistocated geometry setup where
+additional tools are beneficial.
+
+* ``GeometryDump`` prints information about the selected geometry elements to the terminal. This provides a quick method
+  to access positions and rotations of any elements placed in the global coordinate system. The output is constructed
+  in XML_ format, which can be further processed by external software.
+* ``GeometryViewer`` opens a VTK_ visualization window showing the geometry in a 3D view. In the case that appearance
+  definitions are embedded in the configuration file (via the ``<appearance .../>`` element), the shown geometry
+  elements will be displayed accordingly.
+* ``GeometryViewerROOT`` opens a ROOT_ visualization window showing the geometry in a 2D view. Spaces are shown as green
+  boxes, surfaces as black lines. In order to project the geometry onto a 2D plane, the center point and direction
+  of the plane must be defined. By default, the ROOT viewer draws the geometry in the Y-Z plane.
+
+Usage
+-----
+
+All listed programs will show a brief usage summary if called without arguments. The applications are called with a
+configuration file name and a valid geometry path, e.g.:
+
+.. code-block:: bash
+
+    GeometryViewer QuadrupoleTrapSimulation.xml 'world/@electrode_tag'
+
+Below is an example of the VTK_ geometry viewer:
+
+.. image:: _images/tools_geometry_viewer.png
+   :width: 500pt
+
+In case of the ROOT_ viewer, additional options can be passed to define the 2D view plane:
+
+.. code-block:: bash
+
+    GeometryViewerROOT QuadrupoleTrapSimulation.xml 'world/@electrode_tag' 'world/@magnet_tag' --plane=XZ
+
+Below is an example of the ROOT_ geometry viewer:
+
+.. image:: _images/tools_geometry_viewer_root.png
+   :width: 500pt
+
+As shown above, it is possible to specify multiple geometry paths as well.
+
+Advanced visualization
+----------------------
+
+Note that in addition to these geometry viewers, *Kassiopeia* also supports to define visualizations in the
+configuration file directly so that no additional commands are necessary. For details see :ref:`visualization-label`.
+
+
+Mesh viewers
+============
+
+The mesh viewers are intended to help with constructing and optimizing an electrostatic geometry that is provided
+to *KEMField*. In this case a mesh needs to be defined according to the selected symmetry level. The viewers show
+the defined mesh in a VTK_ window, coloring each mesh element individually.
+
+* ``AxialMeshViewer`` opens a visualization window showing the axial mesh. A corresponding mesh must be defined in the
+  configuration file with the ``<axial_mesh .../>`` element.
+* ``MeshViewer`` opens a visualization window showing the asymmetric (3D) mesh. A corresponding mesh must be defined in
+  the configuration file with the ``<mesh .../>`` element.
+
+Usage
+-----
+
+All listed programs will show a brief usage summary if called without arguments. The viewers are called with a
+configuration file name and a valid geometry path, e.g.:
+
+.. code-block:: bash
+
+    AxialMeshViewer QuadrupoleTrapSimulation.xml 'world/@electrode_tag'
+
+In this case, the geometry path selects all elements with the tag `electrode_tag`, which in this geometry corresponds
+to all electrode elements. Note that because the configuration file is processed before the mesh viewer visualization,
+there may be additional messages or windows shown (e.g. the internal VTK_ geometry viewer). Below is an example of the
+axial mesh viewer:
+
+.. image:: _images/tools_axial_mesh_viewer.png
+   :width: 500pt