AggregatedRunInfo struct proposal

We are often in the need to collect global properties of a run like
run-duration, run-start, firstOrbit, lastOrbit, ...

No single CCDB source delivers all of these information. Moreover we sometimes
have multiple sources for the same information (GRPECS, RCT/Info/RunInformation)
which may not be at sync.

The proposal of this commit is to:

(a) introduce an aggregator struct "AggregatedRunInfo" in which we can
    deliver all important information describing a Run.

(b) implement an authoritative and agreed-on method to fill this struct.

The goal is to set everyone (reco, MC, analysis) on the same foot/contract.

For now the struct is minimal for demonstration purposes.

Author: sawenzel

DataFormats/Parameters/CMakeLists.txt

@@ -14,7 +14,8 @@ o2_add_library(DataFormatsParameters
                        src/GRPLHCIFData.cxx
                        src/GRPECSObject.cxx
                        src/GRPMagField.cxx
-               PUBLIC_LINK_LIBRARIES FairRoot::Base O2::CommonConstants
+                       src/AggregatedRunInfo.cxx
+                PUBLIC_LINK_LIBRARIES FairRoot::Base O2::CommonConstants
                                      O2::CommonTypes O2::CCDB
                                      O2::DetectorsCommonDataFormats)
 
@@ -24,6 +25,7 @@ o2_target_root_dictionary(DataFormatsParameters
                                   include/DataFormatsParameters/GRPLHCIFData.h
                                   include/DataFormatsParameters/GRPECSObject.h
                                   include/DataFormatsParameters/GRPMagField.h
+                                  include/DataFormatsParameters/AggregatedRunInfo.h
                           LINKDEF src/ParametersDataLinkDef.h)
 
 o2_add_executable(simgrp-tool

DataFormats/Parameters/include/DataFormatsParameters/AggregatedRunInfo.h

@@ -0,0 +1,46 @@
+// Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+// See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+// All rights not expressly granted are reserved.
+//
+// This software is distributed under the terms of the GNU General Public
+// License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+//
+// In applying this license CERN does not waive the privileges and immunities
+// granted to it by virtue of its status as an Intergovernmental Organization
+// or submit itself to any jurisdiction.
+
+/// \file GRPECSObject.h
+/// \brief Header of the AggregatedRunInfo struct
+/// \author [email protected] [email protected]
+
+#ifndef ALICEO2_DATA_AGGREGATEDRUNINFO_H_
+#define ALICEO2_DATA_AGGREGATEDRUNINFO_H_
+
+#include <cstdint>
+#include "CCDB/BasicCCDBManager.h"
+
+namespace o2::parameters
+{
+
+/// Composite struct where one may collect important global properties of data "runs"
+/// aggregated from various sources (GRPECS, RunInformation CCDB entries, etc.).
+/// Also offers the authoritative algorithms to collect these information for easy reuse
+/// across various algorithms (anchoredMC, analysis, ...)
+struct AggregatedRunInfo {
+  int runNumber;        // run number
+  uint64_t sor;         // best known timestamp for the start of run
+  uint64_t eor;         // best known timestamp for end of run
+  uint64_t orbitsPerTF; // number of orbits per TF
+  uint64_t orbitReset;  // timestamp of orbit reset before run
+  uint64_t orbitSOR;    // orbit when run starts after orbit reset
+  uint64_t orbitEOR;    // orbit when run ends after orbit reset
+
+  // we may have pointers to actual data source objects GRPECS, ...
+
+  // fills and returns AggregatedRunInfo for a given run number.
+  static AggregatedRunInfo buildAggregatedRunInfo(o2::ccdb::CCDBManagerInstance& ccdb, int runnumber);
+};
+
+} // namespace o2::parameters
+
+#endif

DataFormats/Parameters/src/AggregatedRunInfo.cxx

@@ -0,0 +1,54 @@
+// Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+// See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+// All rights not expressly granted are reserved.
+//
+// This software is distributed under the terms of the GNU General Public
+// License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+//
+// In applying this license CERN does not waive the privileges and immunities
+// granted to it by virtue of its status as an Intergovernmental Organization
+// or submit itself to any jurisdiction.
+
+/// \file AggregatedRunInfo.cxx
+/// \author [email protected]
+
+#include "DataFormatsParameters/AggregatedRunInfo.h"
+#include "CCDB/BasicCCDBManager.h"
+#include "DataFormatsParameters/GRPECSObject.h"
+#include "CommonConstants/LHCConstants.h"
+#include "Framework/Logger.h"
+
+using namespace o2::parameters;
+
+o2::parameters::AggregatedRunInfo AggregatedRunInfo::buildAggregatedRunInfo(o2::ccdb::CCDBManagerInstance& ccdb, int runnumber)
+{
+  // TODO: could think about caching results per runnumber to
+  // avoid going to CCDB multiple times ---> but should be done inside the CCDBManagerInstance
+
+  // we calculate the first orbit of a run based on sor (start-of-run) and eor
+  // we obtain these by calling getRunDuration
+  auto [sor, eor] = ccdb.getRunDuration(runnumber);
+
+  // determine a good timestamp to query OrbitReset for this run
+  // --> the middle of the run is very appropriate and safer than just sor
+  auto run_mid_timestamp = sor + (eor - sor) / 2;
+
+  // query the time of the orbit reset (when orbit is defined to be 0)
+  auto ctpx = ccdb.getForTimeStamp<std::vector<Long64_t>>("CTP/Calib/OrbitReset", run_mid_timestamp);
+  int64_t tsOrbitReset = (*ctpx)[0]; // us
+
+  // get timeframe length from GRPECS
+  std::map<std::string, std::string> metadata;
+  metadata["runNumber"] = Form("%d", runnumber);
+  auto grpecs = ccdb.getSpecific<o2::parameters::GRPECSObject>("GLO/Config/GRPECS", run_mid_timestamp, metadata);
+  auto nOrbitsPerTF = grpecs->getNHBFPerTF();
+
+  // calculate SOR orbit
+  int64_t orbitSOR = (sor * 1000 - tsOrbitReset) / o2::constants::lhc::LHCOrbitMUS;
+  int64_t orbitEOR = (eor * 1000 - tsOrbitReset) / o2::constants::lhc::LHCOrbitMUS;
+
+  // adjust to the nearest TF edge to satisfy condition (orbitSOR % nOrbitsPerTF == 0)
+  orbitSOR = orbitSOR / nOrbitsPerTF * nOrbitsPerTF;
+
+  return AggregatedRunInfo{runnumber, sor, eor, nOrbitsPerTF, tsOrbitReset, orbitSOR, orbitEOR};
+}

DataFormats/Parameters/src/ParametersDataLinkDef.h

@@ -30,5 +30,6 @@
 #pragma link C++ class o2::parameters::GRPMagField + ;
 #pragma link C++ class std::unordered_map < unsigned int, unsigned int> + ;
 #pragma link C++ class std::pair < unsigned long, std::string> + ;
+#pragma link C++ struct o2::parameters::AggregatedRunInfo + ;
 
 #endif