Commit 97f0d9b0 authored by Jens Kroeger's avatar Jens Kroeger
Browse files
parents 5fdcdcb4 99bebe7c
Pipeline #1274315 failed with stages
in 2 minutes and 52 seconds
...@@ -109,8 +109,8 @@ IF(LATEX_COMPILER) ...@@ -109,8 +109,8 @@ IF(LATEX_COMPILER)
usermanual/figures/trackChi2ndof_goodexample.pdf usermanual/figures/trackChi2ndof_goodexample.pdf
usermanual/figures/residualX_goodexample.pdf usermanual/figures/residualX_goodexample.pdf
usermanual/figures/correlationX_goodexample.pdf usermanual/figures/correlationX_goodexample.pdf
usermanual/figures/datadrivenandframebased.png usermanual/figures/corrymanual_eventbuilding_datadriven.pdf
usermanual/figures/datadrivendevice.png usermanual/figures/corrymanual_eventbuilding_framebased.pdf
usermanual/figures/reconstruction-chain-simple.png usermanual/figures/reconstruction-chain-simple.png
usermanual/figures/reconstruction-chain-complicated.png usermanual/figures/reconstruction-chain-complicated.png
usermanual/figures/onlinemon.png usermanual/figures/onlinemon.png
......
This diff is collapsed.
...@@ -10,23 +10,23 @@ The repository contains a few tools to facilitate contributions and to ensure co ...@@ -10,23 +10,23 @@ The repository contains a few tools to facilitate contributions and to ensure co
\section{Writing Additional Modules} \section{Writing Additional Modules}
Given the modular structure of the framework, its functionality can be easily extended by adding a new module. Given the modular structure of the framework, its functionality can be easily extended by adding a new module.
To facilitate the creation of new modules including their CMake files and initial documentation, the script \command{addModule.sh} is provided in the \dir{etc/} directory of the repository. To facilitate the creation of new modules including their CMake files and initial documentation, the script \file{addModule.sh} is provided in the \dir{etc/} directory of the repository.
It will ask for a name and type of the module and create all code necessary to compile a first (and empty) version of the files. It will ask for a name and type of the module as described in Section~\ref{sec:module_manager} and create all code necessary to compile a first (and empty) version of the files.
The content of each of the files is described in detail in the following paragraphs. The content of each of the files is described in detail in the following paragraphs.
\subsection{Files of a Module} \subsection{Files of a Module}
\label{sec:module_files} \label{sec:module_files}
Every module directory should at minimum contain the following documents (with \texttt{ModuleName} replaced by the name of the module): Every module directory should at minimum contain the following documents (with \texttt{<ModuleName>} replaced by the name of the module):
\begin{itemize} \begin{itemize}
\item \textbf{CMakeLists.txt}: The build script to load the dependencies and define the source files of the library. \item \textbf{\file{CMakeLists.txt}}: The build script to load the dependencies and define the source files of the library.
\item \textbf{README.md}: Full documentation of the module. \item \textbf{\file{README.md}}: Full documentation of the module.
\item \textbf{\textit{ModuleName}.h}: The header file of the module. \item \textbf{\file{<ModuleName>.h}}: The header file of the module.
\item \textbf{\textit{ModuleName}.cpp}: The implementation file of the module. \item \textbf{\file{<ModuleName>.cpp}}: The implementation file of the module.
\end{itemize} \end{itemize}
These files are discussed in more detail below. These files are discussed in more detail below.
By default, all modules added to the \textit{src/modules/} directory will be built automatically by CMake. By default, all modules added to the \dir{src/modules/} directory will be built automatically by CMake.
If a module depends on additional packages which not every user may have installed, one can consider adding the following line to the top of the module's \textit{CMakeLists.txt}: If a module depends on additional packages which not every user may have installed, one can consider adding the following line to the top of the module's \file{CMakeLists.txt}:
\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{cmake} \begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{cmake}
CORRYVRECKAN_ENABLE_DEFAULT(OFF) CORRYVRECKAN_ENABLE_DEFAULT(OFF)
\end{minted} \end{minted}
...@@ -50,7 +50,7 @@ Only ROOT is automatically included and linked to the module. ...@@ -50,7 +50,7 @@ Only ROOT is automatically included and linked to the module.
\item A line containing \parameter{CORRYVRECKAN_MODULE_INSTALL(${MODULE_NAME})} to set up the required target for the module to be installed to. \item A line containing \parameter{CORRYVRECKAN_MODULE_INSTALL(${MODULE_NAME})} to set up the required target for the module to be installed to.
\end{enumerate} \end{enumerate}
A simple CMakeLists.txt for a module named \parameter{Test} which should run only on DUT detectors of type \emph{Timepix3} is provided below as an example. A simple \file{CMakeLists.txt} for a module named \parameter{Test} which should run only on DUT detectors of type \emph{Timepix3} is provided below as an example.
\vspace{5pt} \vspace{5pt}
\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{cmake} \begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{cmake}
...@@ -69,7 +69,7 @@ CORRYVRECKAN_MODULE_INSTALL(${MODULE_NAME}) ...@@ -69,7 +69,7 @@ CORRYVRECKAN_MODULE_INSTALL(${MODULE_NAME})
\paragraph{README.md} \paragraph{README.md}
The \file{README.md} serves as the documentation for the module and should be written in Markdown format~\cite{markdown}. The \file{README.md} serves as the documentation for the module and should be written in Markdown format~\cite{markdown}.
It is automatically converted to \LaTeX using Pandoc~\cite{pandoc} and included in the user manual in Chapter~\ref{ch:modules}. It is automatically converted to \LaTeX~using Pandoc~\cite{pandoc} and included in the user manual in Chapter~\ref{ch:modules}.
By documenting the module functionality in Markdown, the information is also viewable with a web browser in the repository within the module sub-folder. By documenting the module functionality in Markdown, the information is also viewable with a web browser in the repository within the module sub-folder.
The \file{README.md} should follow the structure indicated in the \file{README.md} file of the \parameter{Dummy} module in \dir{src/modules/Dummy}, and should contain at least the following sections: The \file{README.md} should follow the structure indicated in the \file{README.md} file of the \parameter{Dummy} module in \dir{src/modules/Dummy}, and should contain at least the following sections:
...@@ -94,21 +94,21 @@ The parameters should be briefly explained in an itemised list with the name of ...@@ -94,21 +94,21 @@ The parameters should be briefly explained in an itemised list with the name of
\item An H3-size section with the title \textbf{Usage} which should contain at least one simple example of a valid configuration for the module. \item An H3-size section with the title \textbf{Usage} which should contain at least one simple example of a valid configuration for the module.
\end{itemize} \end{itemize}
\paragraph{\texttt{ModuleName}.h and \texttt{ModuleName}.cpp} \paragraph{ModuleName.h and ModuleName.cpp}
All modules should consist of both a header file and a source file. All modules should consist of both a header file and a source file.
In the header file, the module is defined together with all of its methods. In the header file, the module is defined together with all of its methods.
Brief Doxygen documentation should be added to explain what each method does. Doxygen documentation should be added to explain what each method does.
The source file should provide the implementation of every method and also its more detailed Doxygen documentation. The source file should provide the implementation of every method.
Methods should only be declared in the header and defined in the source file in order to keep the interface clean. Methods should only be declared in the header and defined in the source file in order to keep the interface clean.
\subsection{Module structure} \subsection{Module structure}
\label{sec:module_structure} \label{sec:module_structure}
All modules must inherit from the \texttt{Module} base class, which can be found in \textit{src/core/module/Module.hpp}. All modules must inherit from the \parameter{Module} base class, which can be found in \dir{src/core/module/Module.hpp}.
The module base class provides two base constructors, a few convenient methods and several methods which the user is required to override. The module base class provides two base constructors, a few convenient methods and several methods which the user is required to override.
Each module should provide a constructor using the fixed set of arguments defined by the framework; this particular constructor is always called during by the module instantiation logic. Each module should provide a constructor using the fixed set of arguments defined by the framework; this particular constructor is always called during by the module instantiation logic.
These arguments for the constructor differ for global and detector/DUT modules. These arguments for the constructor differ for global and detector/DUT modules.
For global modules, the constructor for a \texttt{TestModule} should be: For global modules, the constructor for a \module{TestModule} should be:
\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{c++} \begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{c++}
TestModule(Configuration& config, std::vector<std::shared_ptr<Detector>> detectors): Module(std::move(config), detectors) {} TestModule(Configuration& config, std::vector<std::shared_ptr<Detector>> detectors): Module(std::move(config), detectors) {}
\end{minted} \end{minted}
...@@ -124,9 +124,9 @@ In addition to the constructor, each module can override the following methods: ...@@ -124,9 +124,9 @@ In addition to the constructor, each module can override the following methods:
\begin{itemize} \begin{itemize}
\item \parameter{initialise()}: Called after loading and constructing all modules and before starting the analysis loop. \item \parameter{initialise()}: Called after loading and constructing all modules and before starting the analysis loop.
This method can for example be used to initialize histograms. This method can for example be used to initialize histograms.
\item \parameter{run(std::shared_ptr<Clipboard> clipboard)}: Called for every time frame or triggered event to be analyzed in the simulation. The argument represents a pointer to the clipboard where the event data is stored. \item \parameter{run(std::shared_ptr<Clipboard> clipboard)}: Called for every time frame or triggered event to be analyzed. The argument represents a pointer to the clipboard where the event data is stored.
A status code is returned to signal the framework whether to continue processing data or to end the run. A status code is returned to signal the framework whether to continue processing data or to end the run.
\item \parameter{finalise()}: Called after processing all events in the run and before destructing the module. \item \parameter{finalise()}: Called after processing all events in the run and before destructing the module.
Typically used to save the output data (like histograms). Typically used to summarize statistics like the number of tracks used in the analysis or analysis results like the chip efficiency.
Any exceptions should be thrown from here instead of the destructor. Any exceptions should be thrown from here instead of the destructor.
\end{itemize} \end{itemize}
This diff is collapsed.
This diff is collapsed.
\chapter{Alignment Procedure} \chapter{Alignment Procedure}
\label{ch:howtoalign} \label{ch:howtoalign}
This chapter provides a description of how to use the alignment features of \corry. As decribed in Section~\ref{sec:detector_config}, an analysis with \corry requires a configuration file defining which detectors are present in the setup.
It also includes step-by-step instructions on how to align a new set of testbeam data. This file also contains the position and rotation of each detector plane.
The Z-positions of all planes can \textbf{and must} be measured by hand in the existing test beam setup and entered in this configuration file for the analysis.
The X- and Y-positions as well as the rotations cannot be measured precisely by hand.
+However, these have a strong influence on the tracking since a misalignment of a fraction of a millimeter might already correspond to a shift by multiple pixel pitches.
Consequently, an alignment procedure is needed in which the detector planes are shifted and rotated iteratively relative to the detector with \parameter{role = reference} to increase the tracking quality.
More technically, the track residuals on all planes,~i.e. the distribution of the spatial distance between the interpolated track intercept and the associated cluster on the plane need to be centered around zero and 'as narrow as possible' -- the width of the distribution depends on the tracking resolution of the telescope and is influenced by many factors such as the beam energy, the material budget of the detector planes, the distance between the detector planes, etc.
+It is important to correctly set the \parameter{spatial_resolution} specified in the detector configuration file described in Section~\ref{sec:detector_config} because is defining the uncertainty on the cluster positions and therefore influences the track $\chi^2$.
This chapter provides a description of how to use the alignment features of \corry.
It also includes step-by-step instructions on how to align the detector planes for new set of test beam data.
Example configuration files can be found in the \dir{testing/} directory of the repository.
These are based on a Timepix3~\cite{timepix3} telescope with an ATLASpix~\cite{atlaspix} DUT at the CERN SPS with a pion beam of \SI{120}{GeV}.
For the alignment of the \textbf{reference telescope} and \textbf{device-under-test (DUT)}, the following modules are available in \corry. For the alignment of the \textbf{reference telescope} and \textbf{device-under-test (DUT)}, the following modules are available in \corry.
\begin{itemize} \begin{itemize}
\item \texttt{[Prealignment]} for both telescope and DUT prealignment (see Section~\ref{prealignment}). \item \module{Prealignment} for both telescope and DUT prealignment (see Section~\ref{prealignment}).
\item \texttt{[AlignmentTrackChi2]} used for telescope alignment (see Section~\ref{alignmenttrackchi2}). \item \module{AlignmentTrackChi2} used for telescope alignment (see Section~\ref{alignmenttrackchi2}) and is relatively robust against an initial misalignment but usually needs several iterations.
\item \texttt{[AlignmentMillepede]}, an alternative telescope alignment algorithm (see Section~\ref{alignmentmillepede}). \item \module{AlignmentMillepede}, an alternative telescope alignment algorithm (see Section~\ref{alignmentmillepede}) which requires fewer iterations to reach a precise alignment but needs a better prealignment.
\item \texttt{[AlignmentDUTResidual]} used for DUT alignment (see Section~\ref{alignmentdutresidual}). \item \module{AlignmentDUTResidual} used for DUT alignment (see Section~\ref{alignmentdutresidual}).
\end{itemize} \end{itemize}
The general procedure that needs to be followed for a successful alignment is outlined here and explained in detail below. The general procedure that needs to be followed for a successful alignment is outlined here and explained in detail below.
...@@ -25,24 +37,33 @@ When using the alignment modules, the new geometry is written out to a new geome ...@@ -25,24 +37,33 @@ When using the alignment modules, the new geometry is written out to a new geome
For details, see Section~\ref{sec:framework_parameters}. For details, see Section~\ref{sec:framework_parameters}.
\end{warning} \end{warning}
\paragraph{Correlation vs. Residual}
A spatial \textbf{correlation} plot is filled with the spatial difference of any cluster on a given detector plane minus the position of any cluster on the reference plane. No tracking is required to fill these histograms.
A spatial \textbf{residual} plot shows the difference of the interpolated track intercept onto a given plane minus the position of its associated cluster.\\
Consequently, the goal of the alignment is to force the \textbf{residuals} to be centered around zero.
The \textbf{correlations} do not necessarily have to be centered at zero as a possible offset reflects the \emph{physical displacement} of a detector plane in X and Y with respect to the reference plane.
However, it can be useful to inspect the \textbf{correlation} plots especially in the beginning when the alignment is not yet good enough for a reasonable tracking.
\section{Aligning the Telescope} \section{Aligning the Telescope}
\label{sec:align_tel} \label{sec:align_tel}
Initially, the telescope needs to be aligned. Initially, the telescope needs to be aligned.
For this, the DUT is ignored. For this, the DUT is ignored.
\subsection*{Prealignment of the Telescope} \subsection*{Prealignment of the Telescope}
The \texttt{[AlignmentTrackChi2]} module requires a careful prealignment. Otherwise it does not converge and the alignment will fail. The \module{AlignmentTrackChi2} module requires a careful prealignment. Otherwise it does not converge and the alignment will fail.
For the prealignment, two strategies can be applied. The Z-positions of all planes need to be measured by hand \textbf{in the existing test beam setup} and then adjusted in the detectors file.
For X and Y, the alignment file from an already aligned run with the same telescope plane arrangement is a solid basis to start from.
If no previous alignment is available, all values for X and Y should be set to 0.
For the prealignment, two strategies can be applied:
\begin{itemize} \begin{itemize}
\item The \texttt{[Prealignment]} module can be used (see Section~\ref{prealignment}). \item The \module{Prealignment} module can be used (see Section~\ref{prealignment}).
\item If the above does not bring the expected result, a manual prealignment can be performed by having a look at correlations plots between a defined reference plane and the other planes in both x and y and the residuals of tracks with respect to hits on the DUT. \item If the above does not bring the expected result, a manual prealignment can be performed as described below.
\end{itemize} \end{itemize}
The z-positions of all planes need to be measured by hand \textbf{in the existing testbeam setup} and then adjusted in the detectors file.
These will not be changed during the alignment process.
For x and y, the alignment file from the last testbeam is a solid basis to start from.
If no previous alignment is available, all values for x and y should be set to 0.
To have a first look at the initial alignment guess, one can run To have a first look at the initial alignment guess, one can run
\begin{verbatim} \begin{verbatim}
$ /path/to/corryvreckan/bin/corry \ $ /path/to/corryvreckan/bin/corry \
...@@ -52,22 +73,17 @@ $ /path/to/corryvreckan/bin/corry \ ...@@ -52,22 +73,17 @@ $ /path/to/corryvreckan/bin/corry \
-o EventLoaderTimepix3.input_directory=<inputDir>] -o EventLoaderTimepix3.input_directory=<inputDir>]
\end{verbatim} \end{verbatim}
The \parameter{spatial_cut} in \texttt{[Tracking4D]} should be set to multiple ($\sim4$) pixel pitch. The \parameter{spatial_cut_abs/rel} in \module{Tracking4D} should be set to multiple ($\sim4$) pixel pitch.
One can inspect the track $\chi^2$, the correlation in x and y and the residuals with the online monitoring or by opening the generated ROOT file after finishing the script. One can inspect the spatial correlations in X and Ythe track $\chi^2$, and the residuals with the online monitoring or by opening the generated ROOT file after finishing the script.
These can be found in the modules \texttt{[Tracking4D]} (see Section~\ref{tracking4d}) and \texttt{[Correlations]} (see Section~\ref{correlations}). These can be found in the modules \module{Correlations} (see Section~\ref{correlations}) and \module{Tracking4D} (see Section~\ref{tracking4d}).
\begin{warning} To save time, one can limit the number of processed tracks. For instance, set \parameter{number_of_events = 10000} or \parameter{number_of_tracks = 10000} (see Section~\ref{sec:framework_parameters}).
\textbf{Tip:} To save time, one can limit the number of processed tracks. For instance, set \parameter{number_of_tracks = 100000} (see Section~\ref{sec:framework_parameters}).
\end{warning}
If no peak at all is apparent in the correlations, the hitmaps can be checked to see if valid data is actually available for all planes. If no peak at all is apparent in the correlations or residuals, the hitmaps can be checked to see if valid data is actually available for all planes.
Now, the \texttt{[Prealignment]} module can be used. Now, the \texttt{[Prealignment]} module can be used.
To prealign only the telescope, the DUT can be excluded by using \parameter{type = <detector_type_of_telescope>} (e.g.~\parameter{CLICPIX2}). For details, see Section~\ref{sec:module_manager}. To prealign only the telescope, the DUT can be excluded by using \parameter{type = <detector_type_of_telescope>} (e.g.~\parameter{CLICPIX2}). For details, see Section~\ref{sec:module_manager}.
However, all planes including the DUT can be prealigned at once.
Since the prealignment utilizes hit correlations rather than tracks, no cuts are needed here.
To use the module, \file{align_tel.conf} needs to be edited such that \texttt{[Prealignment]} is enabled and \texttt{[Alignment]} is disabled: To use the module, \file{align_tel.conf} needs to be edited such that \texttt{[Prealignment]} is enabled and \texttt{[Alignment]} is disabled:
\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{ini} \begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{ini}
...@@ -92,20 +108,27 @@ $ /path/to/corryvreckan/bin/corry \ ...@@ -92,20 +108,27 @@ $ /path/to/corryvreckan/bin/corry \
-o EventLoaderTimepix3.input_directory=<inputDir>] -o EventLoaderTimepix3.input_directory=<inputDir>]
\end{verbatim} \end{verbatim}
The actual prealignment is only performed after the events have been analyzed and written to the detectors file in the finalizing step. The actual prealignment is only performed after the events have been analyzed and written to the detectors file in the finalizing step.
This means to check whether the alignment has improved, one needs to re-run the analysis or the next iteration of the alignment as the previously generated ROOT file corresponds to the initial alignment. This means to check whether the alignment has improved, one needs to re-run the analysis or the next iteration of the alignment as the previously generated ROOT file corresponds to the initial alignment.
This is the case for every iteration of the prealignment or alignment. This is the case for every iteration of the prealignment or alignment.
Generally, it suffices to run the \texttt{[Prealignment]} module once and then proceed with the next step. Generally, it suffices to run the \texttt{[Prealignment]} module once and then proceed with the next step.
If the prealignment using the modulde \texttt{[Prealignment]} does not bring the expected results, one can also perform the same steps manually by investigating the residuals of the DUT with respect to tracks. \subsubsection*{Manual Prealignment of the Telescope}
If the prealignment using the module \texttt{[Prealignment]} does not bring the expected results, one can also perform the same steps manually by investigating the residuals of the DUT with respect to tracks.
For the residuals, the shift of the peak from 0 can be estimated with a precision of $\mathcal{O}(\SI{100}{\micro m})$ by zooming in using the \texttt{TBrowser}. For the residuals, the shift of the peak from 0 can be estimated with a precision of $\mathcal{O}(\SI{100}{\micro m})$ by zooming in using the \texttt{TBrowser}.
For instance, if the peak is shifted by +\SI{+300}{\micro m}, the detectors file needs to be edited and \SI{+300}{\micro m} should be added to the respective position, if \SI{-300}{\micro m}, subtracted. For instance, if the peak is shifted by +\SI{+300}{\micro m}, the detectors file needs to be edited and \SI{+300}{\micro m} should be added to the respective position, if \SI{-300}{\micro m}, subtracted.
After modifying the positions of individual planes in the configuration file, \corry can be re-run to check the correlation plots for the updated geometry. After modifying the positions of individual planes in the configuration file, \corry can be re-run to check the correlation and residual plots for the updated geometry.
These steps need to be iterated a few times until the peaks of the \textbf{residuals} are centered around 0. These steps need to be iterated a few times until the peaks of the \textbf{residuals} are centered around 0.
It is important \textbf{not} to force the peak of the \textbf{correlations} to be at exactly 0 because the position of the peak in fact corresponds to the physical offset of a plane from its ideal position. Rotational misalignments can be inferred from the slope of the 2D spatial correlation plots, the actual rotation angle has to be calculated using the respective pixel pitches of the devices.
\begin{warning}
It is important \textbf{not} to force the peak of the spatial \textbf{correlations} to be at exactly 0 because the position of the peak corresponds to the \textit{physical displacement} of a detector plane in X and Y with respect to the reference plane.
The spatial \textbf{correlations} should \textbf{only be used} if the spatial \textbf{residual} plots are not filled reasonable due to bad tracking.
Hence, the spatial correlations can be shifted towards zero in a first iteration.
\end{warning}
\subsection*{Alignment of the Telescope} \subsection*{Alignment of the Telescope}
...@@ -123,11 +146,11 @@ align_position=true ...@@ -123,11 +146,11 @@ align_position=true
\end{minted} \end{minted}
The algorithm performs an optimisation of the track $\chi^2$. The algorithm performs an optimisation of the track $\chi^2$.
Typically, the alignment needs to be iterated a handful of times until the residuals (which again can be inspected in the ROOT file after re-running the analysis) are nicely centered around 0 and narrow.
In fact, the RMS of the residuals corresponds to the spatial resolution of each plane (convolved with the resolution of the telescope) and should thus be $\lesssim$ pixel pitch$/\sqrt{12}$. Typically, the alignment needs to be iterated a handful of times until the residuals (which again can be inspected in the ROOT file after re-running the analysis) are nicely centered around 0 and 'as narrow as possible' -- the RMS of the residuals corresponds to the spatial resolution of each plane (convolved with the resolution of the telescope) and should thus be $\lesssim$ pixel pitch$/\sqrt{12}$.
Starting with a \parameter{spatial_cut} in \texttt{[Tracking4D]} (see Section~\ref{tracking4d}) of multiple ($\sim4$) pixel pitches, it should be decreased incrementally down to the pixel pitch (e.g. run \SI{200}{\micro\m} twice, then run \SI{150}{\micro\m} twice, then \SI{100}{\micro\m} twice, and then \SI{50}{\micro\m}) twice. Starting with a \parameter{spatial_cut_abs/rel} in \texttt{[Tracking4D]} (see Section~\ref{tracking4d}) of multiple ($\sim4$) pixel pitches, it should be decreased incrementally down to the pixel pitch (e.g. run \SI{200}{\micro\m} twice, then run \SI{150}{\micro\m} twice, then \SI{100}{\micro\m} twice, and then \SI{50}{\micro\m} twice).
This allows to perform the alignment with a tight selection of very high quality tracks only. This allows to perform the alignment with a tight selection of very high quality tracks only.
Also the \parameter{max_track_chi2ndof} should be decrease for the same reason. Also the \parameter{max_track_chi2ndof} should be decreased for the same reason.
For the further analysis, the cuts can be released again. For the further analysis, the cuts can be released again.
It may happen that the procedure runs into a 'false minimum', i.e. it converges in a wrong alignment in which the residuals are clearly not centered around 0. It may happen that the procedure runs into a 'false minimum', i.e. it converges in a wrong alignment in which the residuals are clearly not centered around 0.
...@@ -156,25 +179,26 @@ align_position=true ...@@ -156,25 +179,26 @@ align_position=true
\end{subfigure} \end{subfigure}
\begin{subfigure}[t]{0.66\textwidth} \begin{subfigure}[t]{0.66\textwidth}
\includegraphics[width=\textwidth]{correlationX_goodexample} \includegraphics[width=\textwidth]{correlationX_goodexample}
\caption{Good example of a correlation plot.} \caption{Good example of a spatial correlation plot between two telescope planes. The offset from zero corresponds to the \emph{physical displacement} of the plane with respect to the reference plane.}
\label{fig:correlationX} \label{fig:correlationX}
\end{subfigure} \end{subfigure}
\begin{subfigure}[t]{0.66\textwidth} \begin{subfigure}[t]{0.66\textwidth}
\includegraphics[width=\textwidth]{residualX_goodexample} \includegraphics[width=\textwidth]{residualX_goodexample}
\caption{Good example of a residual distribution.} \caption{Good example of a spatial residual distribution. It is centered around zero.}
\label{fig:residualX} \label{fig:residualX}
\end{subfigure} \end{subfigure}
\caption{Examples of distributions as they should look like.} \caption{Examples of distributions how they should look after a successful alignment of the Timepix3 telescope at the CERN SPS with \SI{120}{\GeV} pions.}
\label{fig:exampleAlignment} \label{fig:exampleAlignment}
\end{figure} \end{figure}
Instead of using \texttt{[AlignmentTrackChi2]}, one can also use the module \texttt{[AlignmentMillepede]} (see Section~\ref{alignmentmillepede}). Instead of using \texttt{[AlignmentTrackChi2]}, one can also use the module \texttt{[AlignmentMillepede]} (see Section~\ref{alignmentmillepede}).
It should be noted that this module requires a rather good alignment already. It allows a simultaneous fit of both the tracks and the alignment constants.
Once the alignment has converged, this module stops and the alignment is complete. The modules stops if the convergence, i.e.~the absolute sum of all corrections over the total number of parameters, is smaller than the configured value, and the aligment is complete.
It should be noted that this module requires a rather good prealignment already.
\section{Aligning the DUT} \section{Aligning the DUT}
\label{sec:align_dut} \label{sec:align_dut}
Once the telescope is aligned, its geometry is not touched anymore. From now on, it is used to build tracks which are then matched to clusters on the DUT. Once the telescope is aligned, its geometry is not changed anymore. From now on, it is used to build tracks which are then matched to clusters on the DUT.
\subsection*{Prealignment of the DUT} \subsection*{Prealignment of the DUT}
The prealignment of the DUT follows the same strategy as for the telescope. To look at the current alignment, the script The prealignment of the DUT follows the same strategy as for the telescope. To look at the current alignment, the script
...@@ -189,8 +213,8 @@ $ /path/to/corryvreckan/bin/corry \ ...@@ -189,8 +213,8 @@ $ /path/to/corryvreckan/bin/corry \
needs to be run. needs to be run.
If no better guess is available, the initial alignment of the DUT should be set to $x=y=0$. If no better guess is available, the initial alignment of the DUT should be set to $x=y=0$.
Then, by repeatedly running \corry and modifying the position of the DUT in the detectors file one should be able to bring the peaks of the correlations in x and y close to 0. Then, by repeatedly running \corry and modifying the position of the DUT in the detectors file one should be able to bring the peaks of the spatial residuals in X and Y close to zero.
If no peak at all can be seen in the correlation plots, potentially parameters related to the corresponding event loader need to be corrected in the configuration file. If no peak at all can be seen in the residual plots, the spatial correlations plots can be inspected. In addition, potentially parameters related to the corresponding event loader need to be corrected in the configuration file.
\begin{warning} \begin{warning}
If using the \texttt{[Prealignment]} module, it is possible to prealign all planes at once as described above in Section~\ref{sec:align_tel}. If using the \texttt{[Prealignment]} module, it is possible to prealign all planes at once as described above in Section~\ref{sec:align_tel}.
...@@ -212,7 +236,7 @@ align_position=true ...@@ -212,7 +236,7 @@ align_position=true
\end{minted} \end{minted}
\subsection*{Alignment of the DUT} \subsection*{Alignment of the DUT}
Again, the alignment strategy for the DUT is similar as for the telescope and requires multiple iterations. The alignment strategy for the DUT is similar as for the telescope and requires multiple iterations.
In \file{align_dut.conf}, the prealignment needs to be disabled and the alignment enabled. In \file{align_dut.conf}, the prealignment needs to be disabled and the alignment enabled.
Now, the algorithm optimizes the residuals of the tracks through the DUT. Now, the algorithm optimizes the residuals of the tracks through the DUT.
...@@ -238,8 +262,8 @@ $ /path/to/corryvreckan/bin/corry \ ...@@ -238,8 +262,8 @@ $ /path/to/corryvreckan/bin/corry \
-o EventLoaderATLASpix.input_directory=<inputDir_APX>] -o EventLoaderATLASpix.input_directory=<inputDir_APX>]
\end{verbatim} \end{verbatim}
Like for the telescope alignment, the RMS of the residuals can be interpreted as the spatial resolution of the DUT (convolved with the resolution of the telescope) and should thus be $\lesssim$~pixel pitch$/\sqrt{12}$. Like for the telescope alignment, the RMS of the residuals can be interpreted as the spatial resolution of the DUT (convolved with the track resolution of the telescope at the position if the DUT) and should thus be $\lesssim$~pixel pitch$/\sqrt{12}$.
Again, starting with a \parameter{spatial_cut} in \texttt{[DUTAssociation]} (see Section~\ref{dutassociation}) of multiple ($\sim4$) pixel pitches, it should be decreased incrementally down to the pixel pitch. Note that an asymmetric pixel geometry requires the \parameter{spatial_cut} to be chosen accordingly. Again, starting with a \parameter{spatial_cut_abs/rel} in \texttt{[DUTAssociation]} (see Section~\ref{dutassociation}) of multiple ($\sim4$) pixel pitches, it should be decreased incrementally down to the pixel pitch. Note that an asymmetric pixel geometry requires the \parameter{spatial_cut_abs/rel} to be chosen accordingly.
If the alignment keeps to fail, it is possible to allow only for rotational or translational alignment while freezing the other for one or a few iterations. If the alignment keeps to fail, it is possible to allow only for rotational or translational alignment while freezing the other for one or a few iterations.
......
...@@ -12,22 +12,22 @@ This chapter contains details on the standard installation process and informati ...@@ -12,22 +12,22 @@ This chapter contains details on the standard installation process and informati
Furthermore, the continuous integration of the project ensures correct building and functioning of the software framework on CentOS\,7 (with GCC and LLVM), SLC\,6 (with GCC and LLVM) and Mac OS Mojave (OS X 10.14, with AppleClang). Furthermore, the continuous integration of the project ensures correct building and functioning of the software framework on CentOS\,7 (with GCC and LLVM), SLC\,6 (with GCC and LLVM) and Mac OS Mojave (OS X 10.14, with AppleClang).
\section{CMVFS} \section{CMVFS}
\label{sec:cvmfs} \label{sec:cvmfs_install}
The software is automatically deployed to CERN's VM file system (CVMFS)~\cite{cvmfs} for every new tag. The software is automatically deployed to CERN's VM file system (CVMFS)~\cite{cvmfs} for every new tag.
In addition, the \parameter{master} branch is built and deployed every night. In addition, the \parameter{master} branch is built and deployed every night.
New versions are published to the folder \dir{/cvmfs/clicdp.cern.ch/software/corryvreckan/} where a new folder is created for every new tag, while updates via the \parameter{master} branch are always stored in the \dir{latest} folder. New versions are published to the folder \dir{/cvmfs/clicdp.cern.ch/software/corryvreckan/} where a new folder is created for every new tag, while updates via the \parameter{master} branch are always stored in the \dir{latest} folder.
The deployed version currently comprises all modules which are active by default and do not require additional dependencies. The deployed version currently comprises of all modules that are active by default and do not require additional dependencies.
A \file{setup.sh} is placed in the root folder of the respective release, which allows to set up all runtime dependencies necessary for executing this version. A \file{setup.sh} is placed in the root folder of the respective release, which allows all runtime dependencies necessary for executing this version to be set up.
Versions for both SLC\,6 and CentOS\,7 are provided. Versions for both SLC\,6 and CentOS\,7 are provided.
\section{Docker} \section{Docker}
\label{sec:docker} \label{sec:docker}
Docker images are provided for the framework to allow anyone to run analyses without the need of installing \corry on their system. Docker images are provided for the framework allowing anyone to run analyses without needing to install \corry on their system.
The only required program is the Docker executable, all other dependencies are provided within the Docker images. The only required program is the Docker executable as all other dependencies are provided within the Docker images.
In order to exchange configuration files and output data between the host system and the Docker container, a folder from the host system should be mounted to the container's data path \dir{/data}, which also acts as the Docker \parameter{WORKDIR} location. In order to exchange configuration files and output data between the host system and the Docker container, a folder from the host system should be mounted to the container's data path \dir{/data}, which also acts as the Docker \parameter{WORKDIR} location.
The following command creates a container from the latest Docker image in the project registry and start an interactive shell session with the \command{corry} executable already in the \texttt{\$PATH}. The following command creates a container from the latest Docker image in the project registry and starts an interactive shell session with the \command{corry} executable already in the \texttt{\$PATH}.
Here, the current host system path is mounted to the \dir{/data} directory of the container. Here, the current host system path is mounted to the \dir{/data} directory of the container.
\begin{verbatim} \begin{verbatim}
...@@ -64,13 +64,13 @@ The following paragraphs describe how to compile the \corry framework and its in ...@@ -64,13 +64,13 @@ The following paragraphs describe how to compile the \corry framework and its in
\subsection{Prerequisites} \subsection{Prerequisites}
\label{sec:prerequisites} \label{sec:prerequisites}
The core framework is compiled separately from the individual modules and \corry has therefore only one required dependency: ROOT 6 (versions below 6 are not supported)~\cite{root}. The core framework is compiled separately from the individual modules, therefore \corry has only one required dependency: ROOT 6 (versions below 6 are not supported)~\cite{root}.
Please refer to~\cite{rootinstallation} for instructions on how to install ROOT. Please refer to~\cite{rootinstallation} for instructions on how to install ROOT.
ROOT has several components of which the GenVector package is required to run \corry, a package included in the default build. ROOT has several components and to run \corry the GenVector package is required, a package that is included in the default build.
\subsection{Downloading the source code} \subsection{Downloading the source code}
The latest version of \corry can be downloaded from the CERN Gitlab repository~\cite{corry-repo}. The latest version of \corry can be downloaded from the CERN Gitlab repository~\cite{corry-repo}.
For production environments it is recommended to only download and use tagged software versions, as many of the available git branches are considered development versions and might exhibit unexpected behavior. For production environments, it is recommended to only download and use tagged software versions as many of the available git branches are considered development versions and might exhibit unexpected behavior.
For developers, it is recommended to always use the latest available version from the git \texttt{master} branch. For developers, it is recommended to always use the latest available version from the git \texttt{master} branch.
The software repository can be cloned as follows: The software repository can be cloned as follows:
...@@ -82,10 +82,10 @@ $ cd corryvreckan ...@@ -82,10 +82,10 @@ $ cd corryvreckan
\subsection{Configuration via CMake} \subsection{Configuration via CMake}
\label{sec:cmake_config} \label{sec:cmake_config}
\corry uses the CMake build system to configure, build and install the core framework as well as all modules. \corry uses the CMake build system to configure, build, and install the core framework as well as all modules.
An out-of-source build is recommended: this means CMake should not be directly executed in the source folder. An out-of-source build is recommended: this means CMake should not be directly executed in the source folder.
Instead, a \textit{build} folder should be created, from which CMake should be run. Instead, a \dir{build} folder should be created from which CMake should be run.
For a standard build without any additional flags this implies executing: For a standard build without any additional flags this entails executing:
\begin{verbatim} \begin{verbatim}
$ mkdir build $ mkdir build
...@@ -97,32 +97,33 @@ CMake can be run with several extra arguments to change the type of installation ...@@ -97,32 +97,33 @@ CMake can be run with several extra arguments to change the type of installation
These options can be set with -D\textit{option}. These options can be set with -D\textit{option}.
The following options are noteworthy: The following options are noteworthy:
\begin{itemize} \begin{itemize}
\item \parameter{CMAKE_INSTALL_PREFIX}: The directory to use as a prefix for installing the binaries, libraries and data. \item \parameter{CMAKE_INSTALL_PREFIX}: The directory to use as a prefix for installing the binaries, libraries, and data.
Defaults to the source directory (where the folders \textit{bin/} and \textit{lib/} are added). Defaults to the source directory (where the folders \dir{bin/} and \dir{lib/} are added).
\item \parameter{CMAKE_BUILD_TYPE}: Type of build to install, defaults to \parameter{RelWithDebInfo} (compiles with optimizations and debug symbols). \item \parameter{CMAKE_BUILD_TYPE}: The type of build to install, which defaults to \parameter{RelWithDebInfo} (compiles with optimizations and debug symbols).
Other possible options are \texttt{Debug} (for compiling with no optimizations, but with debug symbols and extended tracing using the Clang Address Sanitizer library) and \texttt{Release} (for compiling with full optimizations and no debug symbols). Other possible options are \texttt{Debug} (for compiling with no optimizations, but with debug symbols and extended tracing using the Clang Address Sanitizer library) and \texttt{Release} (for compiling with full optimizations and no debug symbols).
\item \textbf{\texttt{BUILD\_\textit{ModuleName}}}: If the specific module \parameter{ModuleName} should be installed or not. \item \textbf{\texttt{BUILD\_\textit{ModuleName}}}: If the specific module \parameter{ModuleName} should be installed or not.
Defaults to \texttt{ON} for most modules, however some modules with additional dependencies such as EUDAQ or EUDAQ2~\cite{eudaq,eudaq2} are disabled by default. Defaults to \texttt{ON} for most modules, however some modules with additional dependencies such as EUDAQ or EUDAQ2~\cite{eudaq,eudaq2} are disabled by default.
This set of parameters allows to configure the build for minimal requirements as detailed in Section~\ref{sec:prerequisites}. This set of parameters allows to configure the build for minimal requirements as detailed in Section~\ref{sec:prerequisites}.
\item \parameter{BUILD_ALL_MODULES}: Build all included modules, defaulting to \parameter{OFF}. \item \parameter{BUILD_ALL_MODULES}: Build all included modules, defaulting to \texttt{OFF}.
This overwrites any selection using the parameters described above. This overwrites any selection using the parameters described above.
\end{itemize} \end{itemize}
An example of a custom debug build, without the \parameter{EventLoaderCLICpix2} module and with installation to a custom directory is shown below: An example of a custom debug build, including the \module{EventLoaderEUDAQ2} module and with installation to a custom directory, is shown below:
\begin{verbatim} \begin{verbatim}
$ mkdir build $ mkdir build
$ cd build $ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=../install/ \ $ cmake -DCMAKE_INSTALL_PREFIX=../install/ \
-DCMAKE_BUILD_TYPE=DEBUG \ -DCMAKE_BUILD_TYPE=DEBUG \
-DBUILD_EventLoaderCLICpix2=OFF .. -DBUILD_EventLoaderEUDAQ2=OFF ..
\end{verbatim} \end{verbatim}
It should be noted that the \module{EventLoaderEUDAQ2} module requires additional dependencies and is therefore not built by default.
\subsection{Compilation and installation} \subsection{Compilation and installation}
Compiling the framework is now a single command in the build folder created earlier (replacing \textit{\textless number\_of\_cores\textgreater} with the number of cores to use for compilation): Compiling the framework is now a single command in the build folder created earlier, where \parameter{<number_of_cores>} is replaced with the number of cores to use for compilation:
\begin{verbatim} \begin{verbatim}
$ make -j<number_of_cores> $ make -j<number_of_cores>
\end{verbatim} \end{verbatim}
The compiled (non-installed) version of the executable can be found at \textit{src/exec/corry} in the \dir{build} folder. The compiled (non-installed) version of the executable can be found at \file{src/exec/corry} in the \dir{build} folder.
Running \corry directly without installing can be useful for developers. Running \corry directly without installing can be useful for developers.
It is not recommended for normal users, because the correct library and model paths are only fully configured during installation. It is not recommended for normal users, because the correct library and model paths are only fully configured during installation.
...@@ -131,4 +132,4 @@ To install the library to the selected installation location (defaulting to the ...@@ -131,4 +132,4 @@ To install the library to the selected installation location (defaulting to the
$ make install $ make install