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.
contains information about the position of the active elements (depending on the
version: anchors, optical and base modules and PMTs) of the detector and the
timing information.
\section{DETX}
...
...
@@ -76,28 +84,28 @@ and PMTs) of the detector and the timing information.
\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 opt\n
pmt_id_global x y z dx dy dz t0 opt\n
...
pmt_id_global x y z dx dy dz t0 additional_parameters\n
pmt_id_global x y z dx dy dz t0 opt\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.}
\begin{fieldspecs}
\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.}
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]+
\begin{fieldspecs}
\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[string]{format_version}{The version of the data format with the following format: (v|V)[1-9][0-9]+}
\datafield[float with 0.1 precision, min: 0.0]{UTC_validity_from}{The begin of the valid time range for the detector description in seconds.}
\datafield[float with 0.1 precision, max: 999999999999.9]{UTC_validity_to}{The end of the valid time range for the detector description in seconds.}
\datafield[string]{UTM_ref_grid}{The reference ellipsoid of the UTM grid of the detector, e.g. "UTM WGS84 33N"}
\datafield[int]{UTM_ref_easting}{Easting of the reference point in the UTM grid.}
\datafield[int]{UTM_ref_northing}{Northing of the reference point in the UTM grid.}
\datafield[int]{UTM_ref_ref_z}{z-position of the reference point in the UTM grid.}
\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 with reference to the UTM coordinate with x (y) defining the relative distance in Easting (Northing) in metres.}
\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.}
The main additions in the third version of the DETX format are PMT status flags
for every PMT and comment lines at the beginning of the file to store meta data.
\begin{fieldspecs}
\datafield[hashtag-prefixed string]{comment line}{Only allowed at beginning of the file. New lines may appear inside double quotes (") and are treated as multi-line comments.}
\datafield[string]{format_version}{The version of the data format with the following format: (v|V)[1-9][0-9]+}
\datafield[float with 0.1 precision, min: 0.0]{UTC_validity_from}{The begin of the valid time range for the detector description in seconds.}
\datafield[float with 0.1 precision, max: 999999999999.9]{UTC_validity_to}{The end of the valid time range for the detector description in seconds.}
\datafield[string]{UTM_ref_grid}{The reference ellipsoid of the UTM grid of the detector, e.g. "UTM WGS84 33N"}
\datafield[int]{UTM_ref_easting}{Easting of the reference point in the UTM grid.}
\datafield[int]{UTM_ref_northing}{Northing of the reference point in the UTM grid.}
\datafield[int]{UTM_ref_ref_z}{z-position of the reference point in the UTM grid.}
\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 with reference to the UTM coordinate with x (y) defining the relative distance in Easting (Northing) in metres.}
\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]{PMT_STATUS}{MSB: default = 0 means PMT OK for analysis; 1 = PMT NOT OK for analysis; other status flags to be updated}
\end{fieldspecs}
\alertinfo{Within each DOM section, the PMTs are listed according to an ascending order of their DAQ channel ID, starting at 0.}
pmt_id_global p_x p_y p_z dx dy dz p_t0 PMT_STATUS\n
pmt_id_global p_x p_y p_z dx dy dz p_t0 PMT_STATUS\n
...
pmt_id_global p_x p_y p_z dx dy dz p_t0 PMT_STATUS\n
#repeat for each dom
\end{lstlisting}
The main additions in the fourth version of the DETX format are extended module
parameters: position, orientation (represented by a quaternion) and t0 to allow
for defining non-optical modules (like base modules).
\begin{fieldspecs}
\datafield[hashtag-prefixed string]{comment line}{Only allowed at beginning of the file. New lines may appear inside double quotes (") and are treated as multi-line comments.}
\datafield[string]{format_version}{The version of the data format with the following format: (v|V)[1-9][0-9]+}
\datafield[float with 0.1 precision, min: 0.0]{UTC_validity_from}{The begin of the valid time range for the detector description in seconds.}
\datafield[float with 0.1 precision, max: 999999999999.9]{UTC_validity_to}{The end of the valid time range for the detector description in seconds.}
\datafield[string]{UTM_ref_grid}{The reference ellipsoid of the UTM grid of the detector, e.g. "UTM WGS84 33N"}
\datafield[int]{UTM_ref_easting}{Easting of the reference point in the UTM grid.}
\datafield[int]{UTM_ref_northing}{Northing of the reference point in the UTM grid.}
\datafield[int]{UTM_ref_ref_z}{z-position of the reference point in the UTM grid.}
\datafield[unsigned int]{nmodules}{Number of optical modules, can be 0, which automatically means the ``end of the file''.}
\datafield[int]{module_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[int or float]{m_x, m_y, m_z}{The position of the module with reference to the UTM coordinate with x (y) defining the relative distance in Easting (Northing) in metres.}
\datafield[int or float]{q0, qx, qy, qz}{The orientation of the module represented by a quaternion.}
\datafield[int or float]{m_t0}{The calibration time offset which has to be added to the detected hit times.}
\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]{p_x, p_y, p_z}{The position of the PMT with reference to the UTM coordinate with x (y) defining the relative distance in Easting (Northing) in metres.}
\datafield[int or float]{dx, dy, dz}{The direction where the PMT is pointing at.}
\datafield[int or float]{p_t0}{The calibration time offset which has to be added to the detected hit times.}
\datafield[int]{PMT_STATUS}{MSB: default = 0 means PMT OK for analysis; 1 = PMT NOT OK for analysis; other status flags to be updated}
\end{fieldspecs}
\alertinfo{Within each module section, the PMTs are listed according to an ascending order of their DAQ channel ID, starting at 0.}
pmt_id_global p_x p_y p_z dx dy dz p_t0 PMT_STATUS\n
pmt_id_global p_x p_y p_z dx dy dz p_t0 PMT_STATUS\n
...
pmt_id_global p_x p_y p_z dx dy dz p_t0 PMT_STATUS\n
#repeat for each module
\end{lstlisting}
The main additions in the fifth version of the DETX format is the COMPONENTESTATUS
\begin{fieldspecs}
\datafield[hashtag-prefixed string]{comment line}{Only allowed at beginning of the file. New lines may appear inside double quotes (") and are treated as multi-line comments.}
\datafield[string]{format_version}{The version of the data format with the following format: (v|V)[1-9][0-9]+}
\datafield[float with 0.1 precision, min: 0.0]{UTC_validity_from}{The begin of the valid time range for the detector description in seconds.}
\datafield[float with 0.1 precision, max: 999999999999.9]{UTC_validity_to}{The end of the valid time range for the detector description in seconds.}
\datafield[string]{UTM_ref_grid}{The reference ellipsoid of the UTM grid of the detector, e.g. "UTM WGS84 33N".}
\datafield[int]{UTM_ref_easting}{Easting of the reference point in the UTM grid.}
\datafield[int]{UTM_ref_northing}{Northing of the reference point in the UTM grid.}
\datafield[int]{UTM_ref_ref_z}{z-position of the reference point in the UTM grid.}
\datafield[unsigned int]{nmodules}{Number of optical modules, can be 0, which automatically means the ``end of the file''.}
\datafield[int]{module_id}{The unique 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[int or float]{m_x, m_y, m_z}{The position of the module with reference to the UTM coordinate with x (y) defining the relative distance in Easting (Northing) in metres.}
\datafield[int or float]{q0, qx, qy, qz}{The orientation of the module represented by a quaternion.}
\datafield[int or float]{m_t0}{The calibration time offset which has to be added to the detected hit times.}
\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]{p_x, p_y, p_z}{The position of the PMT with reference to the UTM coordinate with x (y) defining the relative distance in Easting (Northing) in metres.}
\datafield[int or float]{dx, dy, dz}{The direction where the PMT is pointing at.}
\datafield[int or float]{p_t0}{The calibration time offset which has to be added to the detected hit times.}
\datafield[int]{PMT_STATUS}{MSB: default = 0 means PMT OK for analysis; 1 = PMT NOT OK for analysis; other status flags to be updated}
\end{fieldspecs}
\alertinfo{Within each module section, the PMTs are listed according to an ascending order of their DAQ channel ID, starting at 0.}
