Merge branch 'manualUpdates' into 'master'

Furthermore, it may be beneficial to split up modules to support the modular design of \apsq.

Before starting the development of a new module, it is essential to carefully read the documentation of the framework module manager which can be found in Section~\ref{sec:module_manager}.

The basic steps ti implement a new module, hereafter referred to as \parameter{ModuleName}, are the following:

The basic steps to implement a new module, hereafter referred to as \parameter{ModuleName}, are the following:

\begin{enumerate}

    \item Initialization of the code for the new module, using the script \file{etc/scripts/make_module.sh} in the repository.

    The script will ask for the name of the model and the type (unique or detector-specific).

The former is constantly filled with new events to be processed by the main thread, while the latter is used to temporarily buffer events which wait to be picked up in the correct sequence by a \texttt{SequentialModule}.

By default modules are assumed to not operate in a thread-safe way and therefore cannot participate in multithreaded processing of events.

Therefore each module each module must explicitly enable multithreading in its constructor in order to signal its multithreading capabilities to \apsq.

Therefore each module must explicitly enable multithreading in its constructor in order to signal its multithreading capabilities to \apsq.

To support multithreading, the module \texttt{run()} method should be re-entrant and any shared member variables should be protected.

If multithreading is enabled in the run configuration, the module manager will check if all the loaded modules support multithreading.

In case one or more modules do not support multithreading, a warning is printed and the feature is disabled. Modules can inform themselves about the decision via the \texttt{multithreadingEnabled()} method.

See Section~\ref{sec:models_geometry} for details.

\item The \parameter{orientation} specified as X-Y-Z extrinsic Euler angles.

This means the detector is rotated first around the world's X-axis, then around the world's Y-axis and then around the world's Z-axis.

Alternatively the orientation can be set as Z-Y-X or X-Z-X extrinsic Euler angles, refer to Section~\ref{sec:models_geometry} for details.

Alternatively the orientation can be set as Z-Y-X or Z-X-Z extrinsic Euler angles, refer to Section~\ref{sec:models_geometry} for details.

\end{itemize}

In addition to these required parameters, the following parameters allow to randomly misalign the respective detector from its initial position. The values are interpreted as width of a normal distribution centered around zero.

\section{Supported Compilers}

\label{sec:compilers}

\apsq relies on functionality from the {\CPP}17 standard and therefore requires a {\CPP}17-compliant compiler.

This comprises for example GCC\,7+, LLVM/Clang\,4.0+ and AppleClang\,10.0+. A detailed list of supported compilers can be found at~\cite{cppcompilersupport}.

This comprises for example GCC\,9+, LLVM/Clang\,4.0+ and AppleClang\,10.0+. A detailed list of supported compilers can be found at~\cite{cppcompilersupport}.

\section{Prerequisites}

\label{sec:prerequisites}

The latest stable release of ROOT\,6 is recommended and older versions, such as ROOT\,5.x, are not supported.

Please refer to~\cite{rootinstallation} for instructions on how to install ROOT.

ROOT has several components of which the \parameter{GenVector} package is required to run \apsq.

This package is included in the default build.

This package is included in the default build. ROOT needs to be built using {\CPP}17, which is accomplished by supplying the CMake flag

\begin{verbatim}

-DCMAKE_CXX_STANDARD=17

\end{verbatim}

\item Boost.Random\,1.64.0 or later~\cite{boostrandom}:

Random number generator and distribution library of the Boost project, used in order to get cross-platform portable, STL-compatible random number distributions.

While STL random number generators are portable and guarantee to deliver the same random number sequence given the same seed, random distributions are not, and their implementation is platform-dependent leading to different simulation results with the same seed.

\begin{itemize}

\item Geant4~\cite{geant4}: Simulates the desired particles and their interactions with matter, depositing charges in the detectors with the help of the constructed geometry.

See the instructions in~\cite{geant4installation} for details on how to install the software.

All Geant4 data sets are required to run the modules successfully.

All Geant4 data sets are required to run the modules successfully, and Geant4 must be built using {\CPP}17. For multithreading to be possible, this must also be enabled in the Geant4 installation.

It is recommended to enable the Geant4 Qt extensions to allow visualization of the detector setup and the simulated particle tracks.

A recommended set of CMake flags to build a Geant4 package suitable for usage with \apsq are:

\begin{verbatim}

-DGEANT4_USE_XM=ON

-DGEANT4_USE_OPENGL_X11=ON

-DGEANT4_USE_SYSTEM_CLHEP=OFF

-DGEANT4_BUILD_CXXSTD=17

-DGEANT4_BUILD_MULTITHREADED=ON

\end{verbatim}

\item Eigen3~\cite{eigen3}: Vector package used to perform Runge-Kutta integration, used in some of the charge carrier propagation modules.

Eigen is available in almost all Linux distributions through the package manager.

The project documentation is deployed to the project's EOS space at \dir{/eos/project/a/allpix-squared/www/} for publication on the project website.

This comprises both the PDF and HTML versions of the user manual (subdirectory \dir{usermanual}) as well as the Doxygen code reference (subdirectory \dir{reference/}).

The documentation is only published only for new tagged versions of the framework.

The documentation is only published for new tagged versions of the framework.

The CI jobs uses the \parameter{ci-web-deployer} Docker image from the CERN GitLab CI tools to access EOS, which requires a specific file structure of the artifact.

All files in the artifact's \dir{public/} folder will be published to the \dir{www/} folder of the given project.