BinUtility.h

Go to the documentation of this file.

/*
  Copyright (C) 2002-2026 CERN for the benefit of the ATLAS collaboration
*/

// BinUtility.h, (c) ATLAS Detector software
 
#ifndef TRKDETDESCRUTILS_GENERICBINUTILITY1D_H
#define TRKDETDESCRUTILS_GENERICBINUTILITY1D_H
 
// Gaudi
#include "GaudiKernel/GaudiException.h"
// Eigen
#include "GeoPrimitives/GeoPrimitives.h"
// Trk
#include "TrkDetDescrUtils/BinningData.h"
#include "TrkDetDescrUtils/BinningType.h"
 
#include <vector>
 
class MsgStream;
 
namespace Trk {

 
class BinUtility final
{
 
public:
  BinUtility() : m_binningData()
  {
    m_binningData.reserve(3);
  }
 
  BinUtility(const BinUtility& sbu) = default;
  BinUtility(BinUtility&& sbu) = default;
  BinUtility& operator=(const BinUtility& sbu) = default;
  BinUtility& operator=(BinUtility&& sbu) = default;
  ~BinUtility() = default;

  BinUtility(size_t bins, float min, float max, BinningOption opt = open, BinningValue value = binR, float sStep = 0.)
    : m_binningData()
  {
    m_binningData.reserve(3);
    std::vector<float> bValues;
    float step = (max - min) / bins;
    for (size_t ib = 0; ib <= bins; ++ib)
      bValues.push_back(min + ib * step);
    m_binningData.emplace_back(Trk::equidistant, opt, value, bins, min, max, step, sStep, bValues);
  }

  BinUtility(size_t subbins, float substep, float min, float max, BinningOption opt = open, BinningValue value = binR)
    : m_binningData()
  {
    m_binningData.reserve(3);
    std::vector<float> bValues;
    float step = (max - min) / (subbins + 1);
    bValues.push_back(min);
    for (size_t isb = 1; isb <= subbins; ++isb) {
      bValues.push_back(min + isb * step - substep);
      bValues.push_back(min + isb * step);
    }
    bValues.push_back(max);
    m_binningData.emplace_back(Trk::biequidistant, opt, value, 2 * subbins + 1, min, max, step, substep, bValues);
  }

  BinUtility(std::vector<float>& bValues, BinningOption opt = closed, BinningValue value = binPhi)
    : m_binningData()
  {
    m_binningData.reserve(3);
    size_t nBins = opt == 0 ? bValues.size() - 1 : bValues.size();
 
    m_binningData.emplace_back(Trk::arbitrary,
                                             opt,
                                             value,
                                             nBins,
                                             bValues[0],
                                             bValues.back(),
                                             (bValues.back() - bValues[0]) / (nBins),
                                             0.,
                                             bValues);
  }

  BinUtility(float phiRef, std::vector<std::pair<int, float>>& bValues)
    : m_binningData()
  {
    m_binningData.reserve(3);
    m_binningData.emplace_back(Trk::open, phiRef, bValues);
  }

  BinUtility& operator+=(const BinUtility& gbu)
  {
    const std::vector<BinningData>& bData = gbu.binningData();
    if (m_binningData.size() + bData.size() > 3){
      throw GaudiException("BinUtility does not support dim > 3", "FATAL", StatusCode::FAILURE);
    }
    m_binningData.insert(m_binningData.end(), bData.begin(), bData.end());
    return (*this);
  }

  BinUtility* clone() const { return new BinUtility(*this); }

  const std::vector<BinningData>& binningData() const { return m_binningData; }

  size_t bin(const Amg::Vector3D& position, size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      throw GaudiException("BinUtility", "dimension out of bounds", StatusCode::FAILURE);
    }
    size_t bEval = m_binningData[ba].searchGlobal(position);
    const std::size_t b = bins(ba); //can be zero, and is unsigned
    if (b == 0){ //avoid integer overflow with b - 1
      throw GaudiException("BinUtility", "integer overflow", StatusCode::FAILURE);
    }
    return (bEval > b - 1 ? b - 1 : bEval); // ST additional protection : DEBUG source
  }

  size_t entry(const Amg::Vector3D& position, size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      throw GaudiException("BinUtility", "dimension out of bounds", StatusCode::FAILURE);
    }
    return m_binningData[ba].entry(position);
  }

  size_t next(const Amg::Vector3D& position, const Amg::Vector3D& direction, size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      throw GaudiException("BinUtility", "dimension out of bounds", StatusCode::FAILURE);
    }
    return m_binningData[ba].next(position, direction);
  }

  std::pair<size_t, float> distanceToNext(const Amg::Vector3D& position,
                                          const Amg::Vector3D& direction,
                                          size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      throw GaudiException("BinUtility", "dimension out of bounds", StatusCode::FAILURE);
    }
    return m_binningData[ba].distanceToNext(position, direction);
  }

  LayerOrder orderDirection(const Amg::Vector3D& position, const Amg::Vector3D& direction, size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      throw GaudiException("BinUtility", "dimension out of bounds", StatusCode::FAILURE);
    }
    return m_binningData[ba].orderDirection(position, direction);
  }

  size_t bin(const Amg::Vector2D& lposition, size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      throw GaudiException("BinUtility", "dimension out of bounds", StatusCode::FAILURE);
    }
    return m_binningData[ba].searchLocal(lposition);
  }

  bool inside(const Amg::Vector3D& position) const
  {
    std::vector<BinningData>::const_iterator bdIter = m_binningData.begin();
    for (; bdIter != m_binningData.end(); ++bdIter) {
      if (!(*bdIter).inside(position))
        return false;
    }
    return true;
  }

  bool inside(const Amg::Vector2D& /*lposition*/) const
  {
    return true;
  }

  size_t dimensions() const { return m_binningData.size(); }

  size_t max(size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      return 0;
    }
    return (m_binningData[ba].bins - 1);
  }

  size_t bins(size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      return 0;
    }
    return (m_binningData[ba].bins);
  }

  BinningValue binningValue(size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      throw GaudiException("BinUtility", "dimension out of bounds", StatusCode::FAILURE);
    }
    return (m_binningData[ba].binvalue);
  }

  float binPosition(size_t bin, float pos, size_t ba = 0) const
  {
    if (ba >= m_binningData.size()){
      throw GaudiException("BinUtility", "dimension out of bounds", StatusCode::FAILURE);
    }
    return (m_binningData[ba].binPosition(bin, pos));
  }

  void clear() { m_binningData.clear(); }

  MsgStream& dump(MsgStream& sl) const
  {
    sl << "BinUtility for " << m_binningData.size() << "-dimensional array:" << endmsg;
    std::vector<BinningData>::const_iterator bdIter = m_binningData.begin();
    for (size_t ibd = 0; bdIter != m_binningData.end(); ++bdIter, ++ibd) {
      sl << "dimension     : " << ibd << endmsg << endmsg;
      sl << " - type       : " << size_t((*bdIter).type) << endmsg;
      sl << " - option     : " << size_t((*bdIter).option) << endmsg;
      sl << " - value      : " << size_t((*bdIter).binvalue) << endmsg;
      sl << " - bins       : " << (*bdIter).bins << endmsg;
      sl << " - min/max    : " << (*bdIter).min << " / " << (*bdIter).max << endmsg;
      sl << " - step/sub   : " << (*bdIter).step << " / " << (*bdIter).subStep << endmsg;
      sl << " - boundaries : | ";
      std::vector<float>::const_iterator bIter = (*bdIter).boundaries.begin();
      for (; bIter != (*bdIter).boundaries.end(); ++bIter)
        sl << (*bIter) << " | ";
      sl << endmsg;
    }
    return sl;
  }

  std::ostream& dump(std::ostream& sl) const
  {
    sl << "BinUtility for " << m_binningData.size() << "-dimensional array:" << std::endl;
    std::vector<BinningData>::const_iterator bdIter = m_binningData.begin();
    for (size_t ibd = 0; bdIter != m_binningData.end(); ++bdIter, ++ibd) {
      sl << "dimension     : " << ibd << std::endl;
      sl << " - type       : " << size_t((*bdIter).type) << std::endl;
      sl << " - option     : " << size_t((*bdIter).option) << std::endl;
      sl << " - value      : " << size_t((*bdIter).binvalue) << std::endl;
      sl << " - bins       : " << (*bdIter).bins << std::endl;
      sl << " - min/max    : " << (*bdIter).min << " / " << (*bdIter).max << std::endl;
      sl << " - step/sub   : " << (*bdIter).step << " / " << (*bdIter).subStep << std::endl;
      sl << " - boundaries : | ";
      std::vector<float>::const_iterator bIter = (*bdIter).boundaries.begin();
      for (; bIter != (*bdIter).boundaries.end(); ++bIter)
        sl << (*bIter) << " | ";
      sl << std::endl;
    }
    return sl;
  }
 
private:
  std::vector<BinningData> m_binningData;
};

MsgStream&
operator<<(MsgStream& sl, const BinUtility& bgen);
std::ostream&
operator<<(std::ostream& sl, const BinUtility& bgen);
 
} // end of namespace Trk
 
#endif // TRKDETDESCRUTILS_GENERICBINUTILITY1D_H