BoxController.h

Go to the documentation of this file.

// Mantid Repository : https://github.com/mantidproject/mantid
//
// Copyright © 2018 ISIS Rutherford Appleton Laboratory UKRI,
//   NScD Oak Ridge National Laboratory, European Spallation Source,
//   Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS
// SPDX - License - Identifier: GPL - 3.0 +
#pragma once
 
#include "MantidAPI/DllConfig.h"
#include "MantidAPI/IBoxControllerIO.h"
#include "MantidKernel/DiskBuffer.h"
#include "MantidKernel/Exception.h"
#include "MantidKernel/ThreadPool.h"
#include "MantidNexus/NexusFile.h"
 
#include <numeric>
#include <optional>
#include <vector>
 
namespace Mantid {
namespace API {
 
class MANTID_API_DLL BoxController {
public:
  //-----------------------------------------------------------------------------------
  BoxController(size_t nd)
      : nd(nd), m_maxId(0), m_SplitThreshold(1024), m_splitTopInto(std::nullopt), m_numSplit(1), m_numTopSplit(1),
        m_fileIO(std::shared_ptr<API::IBoxControllerIO>()) {
    // TODO: Smarter ways to determine all of these values
    m_maxDepth = 5;
    m_numEventsAtMax = 0;
    m_addingEvents_eventsPerTask = 1000;
    m_significantEventsNumber = 10000000;
    m_addingEvents_numTasksPerBlock = Kernel::ThreadPool::getNumPhysicalCores() * 5;
    m_splitInto.resize(this->nd, 1);
    resetNumBoxes();
  }
 
  virtual ~BoxController();
  // create new box controller from the existing one
  virtual BoxController *clone() const;
  std::string toXMLString() const;
 
  void fromXMLString(const std::string &xml);
 
  bool operator==(const BoxController &other) const;
 
  //-----------------------------------------------------------------------------------
  size_t getNDims() const { return nd; }
 
  //-----------------------------------------------------------------------------------
  size_t getNextId() { return m_maxId++; }
 
  //-----------------------------------------------------------------------------------
  size_t getMaxId() const { return m_maxId; }
 
  //-----------------------------------------------------------------------------------
  void setMaxId(size_t newMaxId) { m_maxId = newMaxId; }
 
  //-----------------------------------------------------------------------------------
  inline std::mutex &getIdMutex() { return m_idMutex; }
 
  //-----------------------------------------------------------------------------------
  bool willSplit(size_t numPoints, size_t depth) const {
    return (numPoints > m_SplitThreshold) && (depth < m_maxDepth);
  }
 
  //-----------------------------------------------------------------------------------
  size_t getSplitThreshold() const { return m_SplitThreshold; }
 
  void setSplitThreshold(size_t threshold) { m_SplitThreshold = threshold; }
 
  //-----------------------------------------------------------------------------------
  size_t getSplitInto(size_t dim) const {
    //      if (dim >= nd)
    //        throw std::invalid_argument("BoxController::setSplitInto() called
    //        with too high of a dimension index.");
    return m_splitInto[dim];
  }
 
  //-----------------------------------------------------------------------------------
  const std::vector<size_t> &getSplitIntoAll() const { return m_splitInto; }
  //-----------------------------------------------------------------------------------
  std::optional<std::vector<size_t>> getSplitTopInto() const {
    //      if (dim >= nd)
    //        throw std::invalid_argument("BoxController::setSplitInto() called
    //        with too high of a dimension index.");
    return m_splitTopInto;
  }
 
  size_t getNumSplit() const { return m_numSplit; }
 
  //-----------------------------------------------------------------------------------
  void setSplitInto(size_t num) {
    m_splitInto.clear();
    m_splitInto.resize(nd, num);
    calcNumSplit();
  }
 
  //-----------------------------------------------------------------------------------
  void setSplitInto(size_t dim, size_t num) {
    if (dim >= nd)
      throw std::invalid_argument("BoxController::setSplitInto() called with "
                                  "too high of a dimension index.");
    m_splitInto[dim] = num;
    calcNumSplit();
  }
 
  //-----------------------------------------------------------------------------------
  void setSplitTopInto(size_t dim, size_t num) {
    if (dim >= nd)
      throw std::invalid_argument("BoxController::setSplitTopInto() called with "
                                  "too high of a dimension index.");
    // If the vector is not created, then create it
    if (!m_splitTopInto) {
      m_splitTopInto = std::vector<size_t>(nd, 1);
    }
    m_splitTopInto.value()[dim] = num;
    calcNumTopSplit();
  }
 
  //-----------------------------------------------------------------------------------
  void setAddingEvents_eventsPerTask(size_t m_addingEvents_eventsPerTask) {
    this->m_addingEvents_eventsPerTask = m_addingEvents_eventsPerTask;
  }
  size_t getAddingEvents_eventsPerTask() const { return m_addingEvents_eventsPerTask; }
 
  void setAddingEvents_numTasksPerBlock(size_t m_addingEvents_numTasksPerBlock) {
    this->m_addingEvents_numTasksPerBlock = m_addingEvents_numTasksPerBlock;
  }
 
  size_t getAddingEvents_numTasksPerBlock() const { return m_addingEvents_numTasksPerBlock; }
 
  //-----------------------------------------------------------------------------------
  void getAddingEventsParameters(size_t &eventsPerTask, size_t &numTasksPerBlock) const {
    // TODO: Smarter values here depending on nd, etc.
    eventsPerTask = m_addingEvents_eventsPerTask;
    numTasksPerBlock = m_addingEvents_numTasksPerBlock;
  }
 
  //-----------------------------------------------------------------------------------
  size_t getMaxDepth() const { return m_maxDepth; }
 
  void setMaxDepth(size_t value) {
    m_maxDepth = value;
    resetNumBoxes();
  }
 
  size_t getSignificantEventsNumber() const { return m_significantEventsNumber; }
 
  //-----------------------------------------------------------------------------------
  bool shouldSplitBoxes(size_t nEventsInOutput, size_t eventsAdded, size_t numMDBoxes) const {
    // Avoid divide by zero
    if (numMDBoxes == 0)
      return false;
    // Performance depends pretty strongly on WHEN you split the boxes.
    // This is an empirically-determined way to optimize the splitting calls.
    // Split when adding 1/16^th as many events as are already in the output,
    //  (because when the workspace gets very large you should split less often)
    // But no more often than every 10 million events.
    const size_t comparisonPoint = std::max(nEventsInOutput / 16, m_significantEventsNumber);
    if (eventsAdded > comparisonPoint)
      return true;
 
    // Return true if the average # of events per box is big enough to split.
    return ((eventsAdded / numMDBoxes) > m_SplitThreshold);
  }
  //-----------------------------------------------------------------------------------
 
  void clearBoxesCounter(size_t depth) {
    std::lock_guard<std::mutex> lock(m_mutexNumMDBoxes);
    m_numMDBoxes[depth] = 0;
  }
 
  void clearGridBoxesCounter(size_t depth) {
    std::lock_guard<std::mutex> lock(m_mutexNumMDBoxes);
    m_numMDGridBoxes[depth] = 0;
  }
  void incGridBoxesCounter(size_t depth, size_t inc = 1) {
    std::lock_guard<std::mutex> lock(m_mutexNumMDBoxes);
    m_numMDGridBoxes[depth] += inc;
  }
 
  void incBoxesCounter(size_t depth, size_t inc = 1) {
    std::lock_guard<std::mutex> lock(m_mutexNumMDBoxes);
    m_numMDBoxes[depth] += inc;
  }
 
  void trackNumBoxes(size_t depth) {
    std::lock_guard<std::mutex> lock(m_mutexNumMDBoxes);
    if (m_numMDBoxes[depth] > 0) {
      m_numMDBoxes[depth]--;
    }
    m_numMDGridBoxes[depth]++;
 
    // We need to account for optional top level splitting
    if (depth == 0 && m_splitTopInto) {
 
      const auto &splitTopInto = m_splitTopInto.value();
      size_t numSplitTop =
          std::accumulate(splitTopInto.cbegin(), splitTopInto.cend(), size_t{1}, std::multiplies<size_t>());
      m_numMDBoxes[depth + 1] += numSplitTop;
    } else {
      m_numMDBoxes[depth + 1] += m_numSplit;
    }
  }
 
  const std::vector<size_t> &getNumMDBoxes() const { return m_numMDBoxes; }
 
  const std::vector<size_t> &getNumMDGridBoxes() const { return m_numMDGridBoxes; }
 
  const std::vector<double> &getMaxNumMDBoxes() const { return m_maxNumMDBoxes; }
 
  size_t getTotalNumMDBoxes() const {
    return std::accumulate(m_numMDBoxes.cbegin(), m_numMDBoxes.cend(), size_t{0}, std::plus<size_t>());
  }
 
  size_t getTotalNumMDGridBoxes() const {
    return std::accumulate(m_numMDGridBoxes.cbegin(), m_numMDGridBoxes.cend(), size_t{0}, std::plus<size_t>());
  }
 
  double getAverageDepth() const {
    double total = 0;
    double maxNumberOfFinestBoxes = m_maxNumMDBoxes.back();
    for (size_t depth = 0; depth < m_numMDBoxes.size(); depth++) {
      // Add up the number of MDBoxes at that depth, weighed by their volume in
      // units of the volume of the finest possible box.
      // I.e. a box at level 1 is 100 x bigger than a box at level 2, so it
      // counts 100x more.
      total += double(depth * m_numMDBoxes[depth]) * (maxNumberOfFinestBoxes / m_maxNumMDBoxes[depth]);
    }
    return total / maxNumberOfFinestBoxes;
  }
 
  void resetNumBoxes() {
    std::lock_guard<std::mutex> lock(m_mutexNumMDBoxes);
    m_numMDBoxes.clear();
    m_numMDBoxes.resize(m_maxDepth + 1, 0);     // Reset to 0
    m_numMDGridBoxes.resize(m_maxDepth + 1, 0); // Reset to 0
    m_numMDBoxes[0] = 1;                        // Start at 1 at depth 0.
    resetMaxNumBoxes();                         // Also the maximums
  }
 
  // { return m_useWriteBuffer; }
  bool isFileBacked() const { return bool(m_fileIO); }
  IBoxControllerIO *getFileIO() { return m_fileIO.get(); }
  void setFileBacked(const std::shared_ptr<IBoxControllerIO> &newFileIO, const std::string &fileName = "");
  void clearFileBacked();
  //-----------------------------------------------------------------------------------
  // BoxCtrlChangesInterface *getChangesList(){return m_ChangesList;}
  // void setChangesList(BoxCtrlChangesInterface *pl){m_ChangesList=pl;}
  //-----------------------------------------------------------------------------------
  // increase the counter, calculatinb events at max;
  void rizeEventAtMax() { ++m_numEventsAtMax; }
  size_t getNumEventAtMax() const { return m_numEventsAtMax; }
  size_t claimIDRange(size_t range);
 
  std::string getFilename() const;
  bool useWriteBuffer() const;
 
private:
  void calcNumSplit() {
    m_numSplit = 1;
    for (size_t d = 0; d < nd; d++) {
      m_numSplit *= m_splitInto[d];
    }
    resetMaxNumBoxes();
  }
 
  void calcNumTopSplit() {
    m_numTopSplit = 1;
    for (size_t d = 0; d < nd; d++) {
      m_numTopSplit *= m_splitTopInto.value()[d];
    }
    resetMaxNumBoxes();
  }
 
  void resetMaxNumBoxes() {
    // Now calculate the max # of boxes
    m_maxNumMDBoxes.resize(m_maxDepth + 1, 0); // Reset to 0
    m_maxNumMDBoxes[0] = 1;
    for (size_t depth = 1; depth < m_maxNumMDBoxes.size(); depth++) {
      if (depth == 1 && m_splitTopInto) {
        m_maxNumMDBoxes[depth] = m_maxNumMDBoxes[depth - 1] * double(m_numTopSplit);
      } else {
        m_maxNumMDBoxes[depth] = m_maxNumMDBoxes[depth - 1] * double(m_numSplit);
      }
    }
  }
 
protected:
  BoxController(const BoxController &other);
  BoxController &operator=(const BoxController &) = delete;
 
private:
  size_t nd;
 
  size_t m_maxId;
 
  size_t m_SplitThreshold;
 
  size_t m_significantEventsNumber;
 
  size_t m_maxDepth;
  volatile size_t m_numEventsAtMax;
 
  std::vector<size_t> m_splitInto;
 
  std::optional<std::vector<size_t>> m_splitTopInto;
 
  size_t m_numSplit;
 
  size_t m_numTopSplit;
 
  size_t m_addingEvents_eventsPerTask;
 
  size_t m_addingEvents_numTasksPerBlock;
 
  std::vector<size_t> m_numMDBoxes;
 
  std::vector<size_t> m_numMDGridBoxes;
 
  std::mutex m_mutexNumMDBoxes;
 
  std::vector<double> m_maxNumMDBoxes;
 
  std::mutex m_idMutex;
 
  // the class which does actual IO operations, including MRU support list
  std::shared_ptr<IBoxControllerIO> m_fileIO;
 
  // size_t m_bytesPerEvent;
public:
};
 
using BoxController_sptr = std::shared_ptr<BoxController>;
 
using BoxController_const_sptr = std::shared_ptr<const BoxController>;
 
} // namespace API
 
} // namespace Mantid