Jpp  18.0.0-rc.2
the software that should make you happy
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
JDetector.hh
Go to the documentation of this file.
1 #ifndef __JDETECTOR__JDETECTOR__
2 #define __JDETECTOR__JDETECTOR__
3 
4 #include <istream>
5 #include <ostream>
6 #include <sstream>
7 #include <string>
8 #include <vector>
9 
10 #include "JLang/JMultiEquals.hh"
11 #include "JLang/JException.hh"
12 #include "JLang/JManip.hh"
13 #include "Jeep/JComment.hh"
14 #include "JDetector/JDetectorID.hh"
17 #include "JDetector/JPMT.hh"
18 #include "JDetector/JModule.hh"
19 #include "JDetector/JPMTAddress.hh"
21 #include "JGeometry3D/JVector3D.hh"
22 #include "JIO/JSerialisable.hh"
23 #include "JIO/JByteArrayIO.hh"
24 #include "JIO/JSTDIO.hh"
25 
26 
27 /**
28  * \file
29  *
30  * Data structure for detector geometry and calibration.
31  * \author mdejong
32  */
33 namespace JDETECTOR {}
34 namespace JPP { using namespace JDETECTOR; }
35 
36 namespace JDETECTOR {
37 
38  using JLANG::JMultiEquals;
39  using JLANG::JTYPELIST;
41  using JLANG::JIOException;
42  using JEEP::JComment;
43  using JIO::JSerialisable;
44  using JIO::JReader;
45  using JIO::JWriter;
47 
48 
49  /**
50  * Detector data structure.
51  *
52  * A detector consists of a header and a list of modules, each of which consists of a list of PMTs.
53  * Each PMT comprises position, orientation and time calibration data.
54  * Note that the index of the PMT in the module data structure corresponds to the readout channel (TDC).
55  *
56  * The following formats and file name extension are supported:
57  *
58  * <table border="1" width="300">
59  * <tr><th> extension </th><th> format </th><th> function </th></tr>
60  * <tr><td> ".detx" </td><td> ASCII </td><td> I/O </td></tr>
61  * <tr><td> ".gz" </td><td> gzipped ASCII </td><td> I/O </td></tr>
62  * <tr><td> ".dat" </td><td> binary </td><td> I/O </td></tr>
63  * <tr><td> ".det" </td><td> ASCII </td><td> I </td></tr>
64  * </table>
65  *
66  * The different formats can transparently be read and written using the methods:
67  * <pre>
68  * inline void load(const JString& file_name, JDetector& detector);
69  * inline void store(const JString& file_name, const JDetector& detector);
70  * </pre>
71  * respectively.
72  * These methods are available in the include file JDetectorToolkit.hh.
73  *
74  * The JDETECTOR::JModuleRouter and JDETECTOR::JPMTRouter classes provide for fast look-up
75  * methods of module and PMT calibration data for real data and Monte Carlo data, respectively.\n
76  * Note that the (not) equal operator strictly applies to the detector identifier and version.
77  * For quantitative comparisons, use JCompareDetector.cc.\n
78  * The official detector description document is available on the google drive for anyone with a %KM3NeT account.\n
79  * It can directly be found at this <a href="https://drive.google.com/open?id=0B6l8SNtndcwaUTZPOWZOXzd6R3M">link</a>.
80  *
81  * For a given detector,
82  * the module identifier (JModule::getID) and
83  * the PMT identifier (JPMT::getID)
84  * are unique.\n
85  * The serial number in the %UPI of a PMT is equal to its identifier in the detector description.\n
86  * For more information on the %PBS (product breakdown structure) and %UPI (universal product identifier),
87  * see this <a href="https://drive.google.com/file/d/0B-oDhZjfBP59QUVrdFFoaktUZTA/view?resourcekey=0-m7KPlni8jv8WTc07ER4m6g">link</a>.
88  */
89  class JDetector :
90  public JDetectorID,
91  public JDetectorVersion,
92  public JDetectorHeader,
93  public std::vector<JModule>,
94  public JMultiEquals<JDetector, JTYPELIST<JDetectorID, JVersion>::typelist>,
95  public JSerialisable
96  {
97  public:
98  /**
99  * Default constructor.
100  */
102  JDetectorID(),
104  JDetectorHeader (),
105  std::vector<JModule>(),
106  JSerialisable()
107  {}
108 
109 
110  /**
111  * Constructor.
112  *
113  * \param id detector identifier
114  * \param version version
115  * \param header header
116  */
118  const JVersion& version,
119  const JDetectorHeader& header) :
120  JDetectorID(id),
121  JDetectorVersion(version),
122  JDetectorHeader (header),
123  std::vector<JModule>(),
124  JSerialisable()
125  {
126  setVersion();
127  }
128 
129 
130  /**
131  * Set version.
132  *
133  * \param version version
134  */
136  {
137  static_cast<JDetectorVersion&>(*this).setVersion(version.getVersion());
138 
139  setVersion();
140  }
141 
142 
143  /**
144  * Set version.
145  *
146  * Note that the version is only set to a higher version or when forced to set it.
147  *
148  * \param version version
149  * \param force force setting of version
150  * \return true if set; else false
151  */
152  bool setVersion(const JDetectorVersion::JVersion_t& version, const bool force = false)
153  {
154  if (this->getVersion() == JDetectorVersion() || version > getDetectorVersion(this->getVersion()) || force) {
155 
156  setVersion(putDetectorVersion(version));
157 
158  return true;
159  }
160 
161  return false;
162  }
163 
164 
165  /**
166  * Set to latest version.
167  *
168  * \return true if set; else false
169  */
171  {
172  return setVersion(getLatestDetectorVersion<JDetectorVersion::JVersion_t>());
173  }
174 
175 
176  /**
177  * Set status of all modules.
178  *
179  * \param bit bit
180  */
181  void setModuleStatus(const int bit)
182  {
183  for (iterator module = this->begin(); module != this->end(); ++module) {
184  module->getStatus().set(bit);
185  }
186  }
187 
188 
189  /**
190  * Reset status of all modules.
191  *
192  * \param bit bit
193  */
194  void resetModuleStatus(const int bit)
195  {
196  for (iterator module = this->begin(); module != this->end(); ++module) {
197  module->getStatus().reset(bit);
198  }
199  }
200 
201 
202  /**
203  * Set status of all PMTs.
204  *
205  * \param bit bit
206  */
207  void setPMTStatus(const int bit)
208  {
209  for (iterator module = this->begin(); module != this->end(); ++module) {
210  for (JModule::iterator pmt = module->begin(); pmt != module->end(); ++pmt) {
211  pmt->getStatus().set(bit);
212  }
213  }
214  }
215 
216 
217  /**
218  * Reset status of all PMTs.
219  *
220  * \param bit bit
221  */
222  void resetPMTStatus(const int bit)
223  {
224  for (iterator module = this->begin(); module != this->end(); ++module) {
225  for (JModule::iterator pmt = module->begin(); pmt != module->end(); ++pmt) {
226  pmt->getStatus().reset(bit);
227  }
228  }
229  }
230 
231 
232  /**
233  * Move detector elements.
234  *
235  * \param pos offset position
236  * \return this JDetector
237  */
239  {
240  for (iterator i = begin(); i != end(); ++i) {
241  i->add(pos);
242  }
243 
244  return *this;
245  }
246 
247 
248  /**
249  * Move detector elements.
250  *
251  * \param pos offset position
252  * \return this JDetector
253  */
255  {
256  for (iterator i = begin(); i != end(); ++i) {
257  i->sub(pos);
258  }
259 
260  return *this;
261  }
262 
263 
264  /**
265  * Get module parameters.
266  *
267  * \param address module address
268  * \return module parameters
269  */
270  const JModule& getModule(const JModuleAddress& address) const
271  {
272  return at(address.first);
273  }
274 
275 
276  /**
277  * Get module parameters.
278  *
279  * \param address module address
280  * \return module parameters
281  */
283  {
284  return at(address.first);
285  }
286 
287 
288  /**
289  * Get module parameters.
290  *
291  * \param location module location
292  * \return module parameters
293  */
294  const JModule& getModule(const JLocation& location) const
295  {
296  for (JDetector::const_iterator module = this->begin(); module != this->end(); ++module) {
297  if (*module == location) {
298  return *module;
299  }
300  }
301 
302  THROW(JIndexOutOfRange, "Invalid location " << location);
303  }
304 
305 
306  /**
307  * Get module parameters.
308  *
309  * \param location module location
310  * \return module parameters
311  */
312  JModule& getModule(const JLocation& location)
313  {
314  for (JDetector::iterator module = this->begin(); module != this->end(); ++module) {
315  if (*module == location) {
316  return *module;
317  }
318  }
319 
320  THROW(JIndexOutOfRange, "Invalid location " << location);
321  }
322 
323 
324  /**
325  * Get PMT parameters.
326  *
327  * \param address JPMTAddress
328  * \return JPMT
329  */
330  const JPMT& getPMT(const JPMTAddress& address) const
331  {
332  return at(address.first).at(address.second);
333  }
334 
335 
336  /**
337  * Get PMT parameters.
338  *
339  * \param address JPMTAddress
340  * \return JPMT
341  */
342  JPMT& getPMT(const JPMTAddress& address)
343  {
344  return at(address.first).at(address.second);
345  }
346 
347 
348  /**
349  * Read detector from input.
350  *
351  * \param in input stream
352  * \param detector detector
353  * \return input stream
354  */
355  friend inline std::istream& operator>>(std::istream& in, JDetector& detector)
356  {
357  using namespace std;
358 
359  detector.clear();
360 
361  string buffer;
362 
363  if (in
364  >> detector.comment
365  >> static_cast<JDetectorID&>(detector)
366  >> buffer) {
367 
368  int number_of_modules;
369  int version = -1;
370 
371  try {
372  version = getDetectorVersion(buffer);
373  }
374  catch(std::exception&) {}
375 
376  switch (version) {
377 
378  default:
379  in >> static_cast<JDetectorHeader&>(detector);
380 
381  case V1:
382  in >> number_of_modules;
383  detector.setVersion(buffer);
384  break;
385 
386  case -1:
387  detector.setVersion(putDetectorVersion(V1));
388  istringstream(buffer) >> number_of_modules;
389  break;
390  }
391 
392  for (JModule module; number_of_modules != 0 && in >> module; --number_of_modules) {
393  detector.push_back(module);
394  }
395  }
396 
397  return in;
398  }
399 
400 
401  /**
402  * Write detector to output.
403  *
404  * \param out output stream
405  * \param detector detector
406  * \return output stream
407  */
408  friend inline std::ostream& operator<<(std::ostream& out, const JDetector& detector)
409  {
410  using namespace std;
411  using namespace JPP;
412 
413  detector.setVersion();
414 
415  setFormat<JPosition3D> (JFormat_t( 9, 3, std::ios::fixed | std::ios::showpos));
416  setFormat<JDirection3D> (JFormat_t( 9, 6, std::ios::fixed | std::ios::showpos));
417  setFormat<JQuaternion3D>(JFormat_t( 9, 6, std::ios::fixed | std::ios::showpos));
418  setFormat<JCalibration> (JFormat_t(10, 3, std::ios::fixed | std::ios::showpos));
419 
420  if (getDetectorVersion(detector.getVersion()) >= V3) {
421  out << detector.comment;
422  }
423 
424  out << static_cast<const JDetectorID&>(detector);
425 
426  switch (getDetectorVersion(detector.getVersion())) {
427 
428  default:
429  out << " ";
430  out << static_cast<const JDetectorVersion&>(detector) << endl;
431  out << static_cast<const JDetectorHeader&> (detector) << endl;
432  break;
433 
434  case V1:
435  out << " ";
436  break;
437  }
438 
439  out << detector.size() << endl;
440 
441  for (const_iterator i = detector.begin(); i != detector.end(); ++i) {
442  out << *i << endl;
443  }
444 
445  return out;
446  }
447 
448 
449  /**
450  * Read from input.
451  *
452  * \param in reader
453  * \return reader
454  */
455  virtual JReader& read(JReader& in) override
456  {
457  using namespace std;
458  using namespace JPP;
459 
460  this->clear();
461 
463 
464  char prefix[sizeof(JDetectorID)];
465 
466  for (string buffer; in.read(prefix, N) == N && count(prefix, prefix + N, JComment::START_COMMENT) == N; ) {
467 
468  in >> buffer;
469 
470  this->comment.add(buffer);
471  }
472 
473  if (this->comment.empty()) {
474  THROW(JIOException, "Missing comments");
475  }
476 
477  in.read(&prefix[N], sizeof(JDetectorID) - N);
478 
479  JByteArrayReader is(prefix, N);
480 
481  int number_of_modules;
482 
483  is >> static_cast<JDetectorID&> (*this);
484  in >> static_cast<JDetectorVersion&>(*this);
485  in >> static_cast<JDetectorHeader&> (*this);
486  in >> number_of_modules;
487 
488  this->setVersion();
489  this->resize(number_of_modules);
490 
491  for (JDetector::iterator out = this->begin(); number_of_modules != 0; --number_of_modules, ++out) {
492  in >> *out;
493  }
494 
495  return in;
496  }
497 
498 
499  /**
500  * Write to output.
501  *
502  * \param out writer
503  * \return writer
504  */
505  virtual JWriter& write(JWriter& out) const override
506  {
507  using namespace std;
508  using namespace JPP;
509 
510  if (getDetectorVersion(this->getVersion()) < V3 || this->comment.empty()) {
511  THROW(JIOException, "Version " << getDetectorVersion(this->getVersion()) << " < " << V3 << " or missing comments.");
512  }
513 
514  this->setVersion();
515 
516  if (getDetectorVersion(this->getVersion()) >= V3) {
517 
518  for (JComment::const_iterator i = this->comment.begin(); i != this->comment.end(); ++i) {
519 
520  for (size_t i = 0; i != LENGTH_START_OF_COMMENT; ++i) {
522  }
523 
524  out << *i;
525  }
526  }
527 
528  const int number_of_modules = this->size();
529 
530  out << static_cast<const JDetectorID&> (*this);
531  out << static_cast<const JDetectorVersion&>(*this);
532  out << static_cast<const JDetectorHeader&> (*this);
533  out << number_of_modules;
534 
535  for (const_iterator module = this->begin(); module != this->end(); ++module) {
536  out << *module;
537  }
538 
539  return out;
540  }
541 
542 
544 
545 
546  /**
547  * Enumeration for different lengths of start of comment in binary I/O.
548  */
552  };
553 
554 
555  /**
556  * Get option for short start of comment in binary I/O.
557  *
558  * \return option
559  */
561  {
562  return get_start_of_comment();
563  }
564 
565 
566  /**
567  * Set option for short start of comment in binary I/O.
568  *
569  * \param option option
570  */
571  static void setStartOfComment(const start_of_comment_type option)
572  {
573  get_start_of_comment() = option;
574  }
575 
576  protected:
577  /**
578  * Set version.
579  *
580  * This method should be called to set up the handling of detector version specific module and PMT I/O.
581  */
582  void setVersion() const
583  {
585  JPMT ::setVersion(this->getVersion());
586  }
587 
588 
589  /**
590  * Get option for short start of comment in binary I/O.
591  *
592  * \return option
593  */
595  {
596  static start_of_comment_type start_of_comment = NEW_START_OF_COMMENT;
597 
598  return start_of_comment;
599  }
600 
601 
602  /**
603  * Length of start of comment in binary I/O.
604  */
605  static const size_t LENGTH_START_OF_COMMENT = sizeof(JDetectorID);
606  };
607 }
608 
609 #endif
start_of_comment_type
Enumeration for different lengths of start of comment in binary I/O.
Definition: JDetector.hh:549
static start_of_comment_type getStartOfComment()
Get option for short start of comment in binary I/O.
Definition: JDetector.hh:560
static const char START_COMMENT
start comment
Definition: JComment.hh:48
Exceptions.
Interface for binary output.
static void setVersion(const JVersion &version)
Set detector version.
Definition: JModule.hh:131
Data structure for a composite optical module.
Definition: JModule.hh:68
JUTMPosition & sub(const JUTMPosition &pos)
Subtract UTM position.
JDetectorVersion()
Default constructor.
JVersion_t
Enumeration of version types.
Detector data structure.
Definition: JDetector.hh:89
friend std::ostream & operator<<(std::ostream &out, const JDetector &detector)
Write detector to output.
Definition: JDetector.hh:408
#define THROW(JException_t, A)
Marco for throwing exception with std::ostream compatible message.
Definition: JException.hh:696
bool setToLatestVersion()
Set to latest version.
Definition: JDetector.hh:170
int second
index of PMT in module data structure.
Definition: JPMTAddress.hh:100
static void setStartOfComment(const start_of_comment_type option)
Set option for short start of comment in binary I/O.
Definition: JDetector.hh:571
virtual int read(char *buffer, const int length)=0
Read byte array.
void setModuleStatus(const int bit)
Set status of all modules.
Definition: JDetector.hh:181
friend std::istream & operator>>(std::istream &in, JDetector &detector)
Read detector from input.
Definition: JDetector.hh:355
void setPMTStatus(const int bit)
Set status of all PMTs.
Definition: JDetector.hh:207
const std::string & getVersion() const
Get version.
const JPMT & getPMT(const JPMTAddress &address) const
Get PMT parameters.
Definition: JDetector.hh:330
static const size_t LENGTH_START_OF_COMMENT
Length of start of comment in binary I/O.
Definition: JDetector.hh:605
void setVersion(const JVersion &version)
Set version.
Definition: JDetector.hh:135
is
Definition: JDAQCHSM.chsm:167
JModule & getModule(const JLocation &location)
Get module parameters.
Definition: JDetector.hh:312
Data structure for detector header.
Template definition of auxiliary base class for data structures composed of multiple base classes wit...
Definition: JMultiEquals.hh:32
JDetector()
Default constructor.
Definition: JDetector.hh:101
int first
index of module in detector data structure
void setVersion(const std::string &version)
Set version.
void resetModuleStatus(const int bit)
Reset status of all modules.
Definition: JDetector.hh:194
Forward declaration of binary output.
virtual JReader & read(JReader &in) override
Read from input.
Definition: JDetector.hh:455
void resetPMTStatus(const int bit)
Reset status of all PMTs.
Definition: JDetector.hh:222
Version with PMT status field and comments.
Data structure for vector in three dimensions.
Definition: JVector3D.hh:34
virtual JWriter & write(JWriter &out) const override
Write to output.
Definition: JDetector.hh:505
Logical location of module.
Definition: JLocation.hh:37
Auxiliary class for recursive type list generation.
Definition: JTypeList.hh:351
Data structure for PMT geometry, calibration and status.
Definition: JPMT.hh:43
Data structure for detector version.
bool setVersion(const JDetectorVersion::JVersion_t &version, const bool force=false)
Set version.
Definition: JDetector.hh:152
Address of module in detector data structure.
Interface for binary input.
static const JGetDetectorVersion getDetectorVersion
Function object to map detector version to numerical value.
I/O manipulators.
const JModule & getModule(const JModuleAddress &address) const
Get module parameters.
Definition: JDetector.hh:270
Auxiliary class for comment.
Definition: JComment.hh:41
static const JPutDetectorVersion putDetectorVersion(getDetectorVersion)
Function object to map numerical value to detector version.
static void setVersion(const JVersion &version)
Set detector version.
Definition: JPMT.hh:114
then usage $script< input file >[option[primary[working directory]]] nWhere option can be N
Definition: JMuonPostfit.sh:36
Address of PMT in detector data structure.
Definition: JPMTAddress.hh:32
JDetector(const JDetectorID &id, const JVersion &version, const JDetectorHeader &header)
Constructor.
Definition: JDetector.hh:117
static start_of_comment_type & get_start_of_comment()
Get option for short start of comment in binary I/O.
Definition: JDetector.hh:594
Data structure for PMT geometry and calibration.
Auxiliary class for object identification.
Definition: JObjectID.hh:22
JPMT & getPMT(const JPMTAddress &address)
Get PMT parameters.
Definition: JDetector.hh:342
void setVersion() const
Set version.
Definition: JDetector.hh:582
JDetector & operator+=(const JVector3D &pos)
Move detector elements.
Definition: JDetector.hh:238
JUTMPosition & add(const JUTMPosition &pos)
Add UTM position.
const JModule & getModule(const JLocation &location) const
Get module parameters.
Definition: JDetector.hh:294
JComment & add(const std::string &comment)
Add comment.
Definition: JComment.hh:100
Exception for accessing an index in a collection that is outside of its range.
Definition: JException.hh:90
do set_variable DETECTOR_TXT $WORKDIR detector
Auxiliary class for version identifier.
then fatal Wrong number of arguments fi set_variable DETECTOR $argv[1] set_variable INPUT_FILE $argv[2] eval JPrintDetector a $DETECTOR O IDENTIFIER eval JPrintDetector a $DETECTOR O SUMMARY JAcoustics sh $DETECTOR_ID source JAcousticsToolkit sh CHECK_EXIT_CODE typeset A EMITTERS get_tripods $WORKDIR tripod txt EMITTERS get_transmitters $WORKDIR transmitter txt EMITTERS for EMITTER in
Definition: JCanberra.sh:46
JDetector & operator-=(const JVector3D &pos)
Move detector elements.
Definition: JDetector.hh:254
JLANG::JObjectID JDetectorID
Type definition of detector identifier.
Definition: JDetectorID.hh:19
Data structure for format specifications.
Definition: JManip.hh:522
JModule & getModule(const JModuleAddress &address)
Get module parameters.
Definition: JDetector.hh:282
STD extensions for binary I/O.
Data structure for optical module.
Exception for I/O.
Definition: JException.hh:324