From 9cf3dbc9da145858ba8f06859dc2082f9522643d Mon Sep 17 00:00:00 2001
From: Tamas Gal <himself@tamasgal.com>
Date: Tue, 8 Oct 2024 10:20:21 +0200
Subject: [PATCH] Update skeleton
---
GitRev.tex | 1 -
Makefile | 15 +-
create_git_info.sh | 8 -
km3net-dataformat-specifications.tex | 269 ++++++++++++++++++++++++++-
4 files changed, 275 insertions(+), 18 deletions(-)
delete mode 100644 GitRev.tex
delete mode 100755 create_git_info.sh
diff --git a/GitRev.tex b/GitRev.tex
deleted file mode 100644
index bacbcb3..0000000
--- a/GitRev.tex
+++ /dev/null
@@ -1 +0,0 @@
-\begin{center} Git release: , date . \end{center}
diff --git a/Makefile b/Makefile
index fa7d223..bc4f523 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,12 @@
-km3net-dataformat-specifications: km3net-dataformat-specifications.tex GitRev.tex
- pdflatex $<
+SPECS_PATH = specs
+SPECS := $(wildcard $(SPECS_PATH)/*.json)
+#SPEC_TEX_INCLUDES := $(shell find $(SPECS_PATH)/*.py | sed 's/\.py/\.tex/g')
-GitRev.tex:
- ./create_git_info.sh
+km3net-dataformat-specifications: km3net-dataformat-specifications.tex #$(SPEC_TEX_INCLUDES)
+ latexmk
+
+#$(SPECS_PATH)/%.tex: $(SPECS_PATH)/%.py
+# python3 $< > $@
+
+clean:
+ rm -f *.pdf *.toc *.aux *.fdb_latexmk *.fls *.log
diff --git a/create_git_info.sh b/create_git_info.sh
deleted file mode 100755
index 38895ab..0000000
--- a/create_git_info.sh
+++ /dev/null
@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-export GIT_VERSION=`git --no-pager describe --tags --always`
-export GIT_COMMIT=`git rev-parse --verify HEAD`
-export GIT_DATE=`git --no-pager show --date=format:'%Y-%m-%dT%H:%M:%S%z' --format="%ad" --name-only | head -n1`
-export BUILD_DATE=`date +%Y-%m-%dT%H:%M:%S%z`
-
-
-echo "\\begin{center} Git release: ${GIT_VERSION}, date ${GIT_DATE}. \\end{center}" > GitRev.tex
diff --git a/km3net-dataformat-specifications.tex b/km3net-dataformat-specifications.tex
index aa48de0..a137f2a 100644
--- a/km3net-dataformat-specifications.tex
+++ b/km3net-dataformat-specifications.tex
@@ -1,22 +1,281 @@
\documentclass[a4paper, 11pt]{article}
+
\usepackage{graphicx}
\usepackage{color}
\usepackage{hyperref}
+\usepackage{alertmessage}
+\usepackage{listings}
+\usepackage{bytefield}
+\usepackage{xcolor}
+
+\definecolor{codegreen}{rgb}{0,0.6,0}
+\definecolor{codegray}{rgb}{0.5,0.5,0.5}
+\definecolor{codepurple}{rgb}{0.58,0,0.82}
+\definecolor{backcolour}{rgb}{0.95,0.95,0.92}
+
+\lstdefinestyle{ascii}{
+ backgroundcolor=\color{backcolour},
+ commentstyle=\color{codegreen},
+ keywordstyle=\color{magenta},
+ numberstyle=\tiny\color{codegray},
+ stringstyle=\color{codepurple},
+ basicstyle=\ttfamily\footnotesize,
+ breakatwhitespace=false,
+ breaklines=true,
+ captionpos=b,
+ keepspaces=true,
+ numbers=left,
+ numbersep=5pt,
+ showspaces=false,
+ showstringspaces=false,
+ showtabs=false,
+ tabsize=2
+}
+
+\lstset{style=ascii}
+
+\newcommand{\datafield}[3][]{%
+ \noindent\parbox{\linewidth}{
+ \noindent\textbf{\texttt{\detokenize{#2}}}%
+ \ifx&% Check if the optional argument is empty
+ \else\ \textit{(#1)}\fi\ % Display datatype in italics if given
+ \vspace{0.2em}
+ \\
+ \vspace{0.5em}\hspace{2.0em}\parbox[t]{\linewidth - 2.0em}{%
+ #3%
+ }\par\vspace{0.5em} % Adds spacing between each field
+
+ }
+}
+
\begin{document}
+
\title{KM3NeT Dataformat Specifications}
-\author{Tamas Gal and Mieke Bouwhuis}
+\author{Tam\'as G\'al}
\date{\today}
\maketitle
\tableofcontents
-\section{Detector Description (DETX, DATX)...}
+\part{Detector Description}
+
+The KM3NeT detector description is stored in two different file formats: ASCII
+(.detx) and binary (.datx). The ASCII version uses UTF-16 encoding. The file
+contains information about the position of the active elements (anchors, DOMs
+and PMTs) of the detector and the timing information.
+
+
+\section{DETX}
+\subsection{Version 1 (August 2014)}
+\begin{lstlisting}
+global_det_id ndoms\n
+dom_id line_id floor_id npmts\n
+pmt_id_global x y z dx dy dz t0 additional_parameters\n
+pmt_id_global x y z dx dy dz t0 additional_parameters\n
+...
+pmt_id_global x y z dx dy dz t0 additional_parameters\n
+#repeat for each dom
+\end{lstlisting}
+
+\datafield[int]{global_det_id}{The global detector identifier. Negative values between -100 and 0 are indicating simulation detectors. It is 1 for the PPM-DU and follows the KM3NeT serial number for all detectors in testing and the sea.}
+\datafield[unsigned int]{ndoms}{Number of optical modules, can be 0, which automatically means the ``end of the file''.}
+\datafield[int]{dom_id}{The unique optical module ID. For real detectors, the number is part of the product number and is usually the last 9 digits of the CLBs MAC address).}
+\datafield[int]{line_id}{The string number.}
+\datafield[int]{floor_id}{The floor number starting at 1. In some older DETX files, this might be -1. In this case, the floors are assumed to be numbered strictly monotonically increasing as they appear in the file.}
+\datafield[unsigned int]{npmts}{The number of PMTs. Can be 0.}
+\datafield[int]{pmt_id_global}{The unique global PMT ID. When applicable, the ID corresponds to the ID in the MC files or the KM3NeT product number.}
+\datafield[int or float]{x, y, z}{The position of the PMT.}
+\datafield[int or float]{dx, dy, dz}{The direction where the PMT is pointing at.}
+\datafield[int or float]{t0}{The calibration time offset which has to be added to the detected hit times.}
+\datafield[int or float]{Optional (undocumented) calibration values might appear here.}
+
+
+\alertinfo{Within each DOM section, the PMTs are listed according to an ascending order of their channel ID, starting at 0.}
+
+
+
+\subsubsection*{Example}
+
+Example for DU-2 (ARCA-DU1) at its test in the dark room (detector-ID 5) this is:
+
+\begin{lstlisting}
+5 18
+808992603 1 1 31
+1838 -0.166 0 72.111 -0.830 0 0.556 0
+4944 0 -0.191 72.059 0 -0.954 0.296 0
+4945 -0.165 -0.096 72.059 -0.826 -0.478 0.297 0
+...
+808974928 1 2 31
+1746 -0.166 0 108.111 -0.830 0 0.556 0
+...
+\end{lstlisting}
+
+\subsection{Version 2 (April 2016)}
+
+\begin{lstlisting}
+global_det_id format_version\n
+UTC_validity_from UTC_validity_to \n
+UTM_ref_grid UTM_ref_easting UTM_ref_northing UTM_ref_z \n
+ndoms \n
+dom_id line_id floor_id npmts \n
+ pmt_id_global x y z dx dy dz t0 \n
+ pmt_id_global x y z dx dy dz t0 \n
+ ...
+ pmt_id_global x y z dx dy dz t0 \n
+#repeat for each dom
+\end{lstlisting}
+
+The main additions in the second version of the DETX format are the format
+version, the validity time range and the UTM coordinates of the detector.
+
+ (v|V)[1-9][0-9]+
+
+\subsection{Version 3 (November 2018)}
+\subsection{Version 4 (November 2020)}
+\subsection{Version 5 (October 2021)}
+\section{DATX}
The corresponding Google drive document: https://drive.google.com/open?id=0B6l8SNtndcwaUTZPOWZOXzd6R3M
-\section{Acoustics Data}
-\section{Online Dataformat}
-\section{Offline Dataformat}
+Test
+
+\part{DAQ}
+\section{DAQ Common Header}
+
+\begin{bytefield}{32}
+ \bitheader{0-31} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{0}
+ \wordbox{1}{Frame Length}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{32}
+ \wordbox{1}{Data Type}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{64}
+ \wordbox{1}{Detector ID}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{96}
+ \wordbox{1}{Run Number}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{128}
+ \wordbox{1}{Sequence Number}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{160}
+ \wordbox{2}{Time Stamp}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{224}
+ \wordbox{1}{DOM Identifier}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{256}
+ \wordbox{1}{DataQueue Status}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{288}
+ \wordbox{1}{DOM Status I}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{320}
+ \wordbox{1}{DOM Status II}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{352}
+ \wordbox{1}{DOM Status III}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{384}
+ \wordbox{1}{DOM Status IV}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{416}
+ \wordbox{1}{Number of Items}
+ \end{rightwordgroup} \\
+\end{bytefield}
+
+\section{Summaryslice}
+
+\begin{bytefield}{32}
+ \bitheader{0-31} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{0}
+ \wordbox{1}{Frame Length}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{32}
+ \wordbox{1}{Data Type}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{64}
+ \wordbox{1}{Detector ID}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{96}
+ \wordbox{1}{Run Number}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{128}
+ \wordbox{1}{TimeSlice Number}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{160}
+ \wordbox{2}{Time Stamp}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{224}
+ \wordbox{1}{Nsummaryframes}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{256}
+ \wordbox{1}{DOM Identifier}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{288}
+ \wordbox{1}{status}
+ \end{rightwordgroup} \\
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{320}
+ \bitbox{8}{Rates PMT 0}
+ \bitbox{8}{Rates PMT 1}
+ \bitbox{8}{Rates PMT 2}
+ \bitbox{8}{Rates PMT 3}
+ \end{rightwordgroup} \\
+
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{352}
+ \bitbox{8}{Rates PMT 4}
+ \bitbox{8}{Rates PMT 5}
+ \bitbox{8}{Rates PMT 6}
+ \bitbox{8}{Rates PMT 7}
+ \end{rightwordgroup} \\
+
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{384}
+ \bitbox{8}{Rates PMT 8}
+ \bitbox{8}{Rates PMT 9}
+ \bitbox{8}{Rates PMT 10}
+ \bitbox{8}{Rates PMT 11}
+ \end{rightwordgroup} \\
+
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{416}
+ \bitbox{8}{Rates PMT 12}
+ \bitbox{8}{Rates PMT 13}
+ \bitbox{8}{Rates PMT 14}
+ \bitbox{8}{Rates PMT 15}
+ \end{rightwordgroup} \\
+
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{448}
+ \bitbox{8}{Rates PMT 16}
+ \bitbox{8}{Rates PMT 17}
+ \bitbox{8}{Rates PMT 18}
+ \bitbox{8}{Rates PMT 19}
+ \end{rightwordgroup} \\
+
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{480}
+ \bitbox{8}{Rates PMT 20}
+ \bitbox{8}{Rates PMT 21}
+ \bitbox{8}{Rates PMT 22}
+ \bitbox{8}{Rates PMT 23}
+ \end{rightwordgroup} \\
+
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{512}
+ \bitbox{8}{Rates PMT 24}
+ \bitbox{8}{Rates PMT 25}
+ \bitbox{8}{Rates PMT 26}
+ \bitbox{8}{Rates PMT 27}
+ \end{rightwordgroup} \\
+
+ \begin{rightwordgroup}[rightcurly=., rightcurlyspace=0pt]{544}
+ \bitbox{8}{Rates PMT 28}
+ \bitbox{8}{Rates PMT 29}
+ \bitbox{8}{Rates PMT 30}
+ \bitbox{8}{unused}
+ \end{rightwordgroup} \\
+\end{bytefield}
+
+\part{Acoustics Data}
+\part{Online Dataformat}
+\part{Offline Dataformat}
\end{document}
--
GitLab