diff --git a/src/external/MusrRoot/doc/MusrRootDefinition.pdf b/src/external/MusrRoot/doc/MusrRootDefinition.pdf index 14b005271..d466864d2 100644 Binary files a/src/external/MusrRoot/doc/MusrRootDefinition.pdf and b/src/external/MusrRoot/doc/MusrRootDefinition.pdf differ diff --git a/src/external/MusrRoot/doc/MusrRootDefinition.tex b/src/external/MusrRoot/doc/MusrRootDefinition.tex index 11ec0224e..04b6bfbf1 100644 --- a/src/external/MusrRoot/doc/MusrRootDefinition.tex +++ b/src/external/MusrRoot/doc/MusrRootDefinition.tex @@ -58,6 +58,7 @@ \newcommand{\tbrowser}{\texttt{TBrowser}\xspace} \newcommand{\tfile}{\texttt{TFile}\xspace} \newcommand{\tfolder}{\texttt{TFolder}\xspace} +\newcommand{\tdir}{\texttt{TDirectory}\xspace} \newcommand{\tobject}{\texttt{TObject}\xspace} \newcommand{\tobjarray}{\texttt{TObjArray}\xspace} \newcommand{\tobjstring}{\texttt{TObjString}\xspace} @@ -115,14 +116,16 @@ The \musr data acquisition systems at PSI are utilizing \midas \cite{Midas}. The The \musrroot file format to be described below is only using a small subset of possible \rootcern objects, namely: \begin{itemize} - \item \tfolder: This are the top level objects in the \musrroot file. + \item \tfolder/\tdir: This are the top level objects in the \musrroot file. \item \thonef: Hold the $\mu^\pm$-decay-histograms. - \item \tobjarray: Holding collection of header information. + \item \tobjarray/\tdir: Holding collection of header information. \item \tobjstring: Holding the content of any header information. \end{itemize} \noindent Since all these objects are deriving form \tobject, they will be directly accessible via the \tbrowser. For instance, the $\mu^\pm$-decay-histograms can be directly plotted, are even fitted, out of the box. +\noindent \color{red}\textbf{Note Oct.\ 2025:}\color{black}\xspace Since \tfolder has bee marked as \emph{deprecated} from the ROOT team, we will switch gradually over to use \tdir instead. This will have a minimal impact on the following, as you will see. In the description to follow, the term ``folder'' will be used synonymous with ``directory''. Only if necessary it will be distinguished. + \cleardoublepage \section{\musrroot: an open $\boldsymbol{\mu}$SR file format} @@ -172,9 +175,27 @@ RunHeader (TFolder) ---| \end{verbatim} \end{small} +\newpage +\noindent In case it is already switched to \tdir, it will look like this (default starting 2026): + +\begin{small} + \begin{verbatim} + RunHeader (TDirectory) ---| + |- RunInfo (TDirectory) + |- DetectorInfo (TDirectory) + |- SampleEnvironmentInfo (TDirectory) + |- MagneticFieldEnvironmentInfo (TDirectory) + |- BeamlineInfo (TDirectory) + \end{verbatim} +\end{small} + \noindent In brackets the object type is given. \texttt{RunInfo} contains most information relevant for the user and will be itemized Sec.\,\ref{sec:RunInfo} and \ref{sec:RunInfoRequired}. \texttt{DetectorInfo} contains detector specific information, like detector name, time zero bin, \etc (details in Sec.\,\ref{sec:DetectorInfoRequired}). \texttt{SampleEnvironmentInfo} (details in Sec.\,\ref{sec:SampleEnvironmentInfoRequired}), and \texttt{MagneticFieldEnvironmentInfo} (details in Sec.\,\ref{sec:MagneticFieldEnvironmentInfoRequired}) store additional, more detailed information concerning the sample environment. \texttt{BeamlineInfo} stores beamline relevant information (details in Sec.\,\ref{sec:BeamlineInfoRequired}). -Before elaborating more on the required items within this structure, a few words on the \rootcern types used here: \texttt{RunHeader} is a \tfolder object. All the ``sub-directory'' entries are of type \tobjarray and collect items of type \tobjstring or other \tobjarray (\ie sub-directories and sub-sub-directories, etc.). +Before elaborating more on the required items within this structure, a few words on the \rootcern types used here: \texttt{RunHeader} is a \tfolder (\emph{deprecated}) or a \tdir object. +\begin{itemize} + \item[(i)] In case of the \emph{deprected} \tfolder \texttt{RunHeader}, all the ``sub-directory'' entries are of type \tobjarray and collect items of type \tobjstring or other \tobjarray (\ie sub-directories and sub-sub-directories, etc.). + \item[(ii)] In case the top entry \texttt{RunHeader} is a \tdir object, all potential ``sub-directories'' are indeed \tdir objects as well. In this case, the data are represented by \tobjstring objects. +\end{itemize} \subsubsection{\texttt{RunInfo}}\label{sec:RunInfo} @@ -314,7 +335,7 @@ header->Set("DetectorInfo/Detector001/Time Zero Bin", 3419.0); \end{verbatim} \end{shaded} -\noindent To write the whole run header into a file would look something like this: +\noindent To write the whole run header into a file would look something like this (\emph{deprecated} \tfolder version): \begin{shaded} \begin{verbatim} @@ -337,6 +358,30 @@ f->Close(); \end{verbatim} \end{shaded} +\newpage +\noindent In the \tdir version it will look like this: + +\begin{shaded} + \begin{verbatim} + std::unique_ptr f = std::make_unique(fileName, "RECREATE", + "write_musrRoot_runHeader"); + if (f->IsZombie()) { + return -1; + } + + // create the needed TDirectory object + TDirectory* runHeader = f->mkdir("RunHeader"); + + // create the "directory" structure + if (header->FillDirectory(runHeader)) { + runHeader->Write(); // write run header to file + } + + f->Close(); + \end{verbatim} +\end{shaded} + + \subsubsection{Reading a \musrroot Run Header}\label{sec:UserInterfaceReading} @@ -350,10 +395,11 @@ if (f->IsZombie()) { return -1; } -TFolder *runHeader = nullptr; +// TFolder *runHeader = nullptr; // deprecated +TDirectoryFile *runHeader = nullptr; f->GetObject("RunHeader", runHeader); if (runHeader == nullptr) { - cerr << endl << ">> **ERROR** Couldn't get top folder RunHeader"; + cerr << endl << ">> **ERROR** Couldn't get top folder/directory RunHeader"; closeFile(f); return -1; } @@ -439,7 +485,7 @@ All validation files need to be open to the community via web-page. The URL from \begin{small} \begin{tabular}{l|l|l} Name & internal type & Comment \\ \hline\hline -Version & \tstring & SVN version of \tmrh \\ +Version & \tstring & GIT hash of \tmrh \\ Generic Validator URL & \tstring & URL of the generic \musrroot validation xsd-file, \\ & & example given below $^1$. \\ Specific Validator URL & \tstring & URL of the instrument specific validation xsd-file$^2$ \\ @@ -479,6 +525,7 @@ RedGreen Offsets & \tintvec & \eg \verb!0; 20! \\ \noindent $^2$ \eg \verb!http://lmu.web.psi.ch/facilities/software/MusrRoot/Validation/MusrRootLEM.xsd! \end{small} +\newpage \section{DetectorInfo --- Required Items} \label{sec:DetectorInfoRequired} The \texttt{DetectorInfo} is organized in a sub-tree like