Subtle-ish differences with integer types between LCIO and EDM4hep

[tmadlener]

There are a few more or less subtle differences with some integer type data members or functions returning integer type values. This is an unordered list of these and the main point of this issue is to have this list available such that it can be put into documentation at some point.

• Return types of SimCalorimeterHit::getNMCContributions is int, but in EDM4hep these are OneToManyRelations so the corresponding call to SimCalorimeterHit::getContributions()::size returns a size_t.
• The handling of CellIDs is somewhat inconsistent in LCIO as in quite a few cases there is an int getCellID and additional versions for getCellID0 and getCellID1 both returning 32 bit integers from which it is possible to construct the uint64_t cellID from edm4hep.
  • SimTrackerHit, SimCalorimeterHit, CalorimeterHit, TrackerHit, TrackerHitPlane, RawCalorimeterHit
  • In general we use the following to do the conversion and bit packing in this case:

template<typename LcioT>
auto to64BitCellID(LcioT* obj)
{
  const auto cellID0 = obj->getCellID0();
  const auto cellID1 = obj->getCellID1();
  uint64_t cellID = cellID1;
  cellID = (cellID << 32) | cellID0;
  return cellID;
}

• The TPCHit in LCIO does only have an int cellID, no other overloads. It still has a uint64_t CellID in the edm4hep::RawTimeSeries.
• The LCEvent::getTimeStamp is long64 in LCIO, but a uint64_t in the edm4hep::EventHeader. (This might be something that we could consider fixing?) Event timestamps will always be positive (no relative time). Not fixing this, document only.

[hegner]

Add a new documentation for LCIO users in migration