Acts/Utilities/ProtoAxis.hpp

0001 // This file is part of the ACTS project.
0002 //
0003 // Copyright (C) 2016 CERN for the benefit of the ACTS project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/Utilities/Axis.hpp"
0012 #include "Acts/Utilities/AxisDefinitions.hpp"
0013 #include "Acts/Utilities/Grid.hpp"
0014 #include "Acts/Utilities/IAxis.hpp"
0015
0016 namespace Acts {
0017 /// @brief Description of a ProtoAxis which holds an IAxis
0018 /// and lets the user to define a certain axis type, boundary type
0019 /// and associated binning.
0020 ///
0021 /// The IAxis allows via the visitor pattern to access the actual axis type
0022 /// which helps to create grid creation code by the compiler as done
0023 /// in the makeGrid helper functions.
0024 ///
0025 /// In addition to a simple axis definitions, it holds also a description
0026 /// of the axis direction.
0027 class ProtoAxis {
0028  public:
0029   /// Convenience constructors - for variable binning
0030   ///
0031   /// @param aDir the value/cast in which this is binned
0032   /// @param abType the axis boundary type
0033   /// @param edges the bin edges (variable binning)
0034   ProtoAxis(AxisDirection aDir, Acts::AxisBoundaryType abType,
0035             const std::vector<double>& edges);
0036
0037   /// Convenience constructors - for equidistant binning
0038   ///
0039   /// @param aDir the value/cast in which this is binned
0040   /// @param abType the axis boundary type
0041   /// @param minE the lowest edge of the binning
0042   /// @param maxE the highest edge of the binning
0043   /// @param nbins the number of bins
0044   ProtoAxis(AxisDirection aDir, AxisBoundaryType abType, double minE,
0045             double maxE, std::size_t nbins);
0046
0047   /// Placeholder constructor for auto-range binning
0048   ///
0049   /// @param aDir the value/cast in which this is binned
0050   /// @param abType the axis boundary type
0051   /// @param nbins the number of bins
0052   ///
0053   /// @note that auto-range is only supported for equidistant binning
0054   ProtoAxis(AxisDirection aDir, AxisBoundaryType abType, std::size_t nbins);
0055
0056   ProtoAxis(const ProtoAxis&) = delete;
0057   ProtoAxis& operator=(const ProtoAxis&) = delete;
0058   ProtoAxis(ProtoAxis&&) = default;
0059   ProtoAxis& operator=(ProtoAxis&&) = default;
0060
0061   /// @brief returns the axis direction
0062   ///
0063   /// @return @c AxisDirection of this axis
0064   AxisDirection getAxisDirection() const;
0065
0066   /// @brief Return the IAxis representation
0067   ///
0068   /// @return @c AxisType of this axis
0069   const IAxis& getAxis() const;
0070
0071   /// Set the range, this will change auto-range to false
0072   ///
0073   /// @throws std::invalid_argument if the axis is not auto-range
0074   /// @throws std::invalid_argument if the axis is not equidistant
0075   ///
0076   /// @param minE the lowest edge of the binning
0077   /// @param maxE the highest edge of the binning
0078   void setRange(double minE, double maxE);
0079
0080   /// @brief check if this is an auto-range binning
0081   bool isAutorange() const;
0082
0083   /// Dump into a string
0084   /// @return the string representation
0085   std::string toString() const;
0086
0087  private:
0088   /// Dispatch to the correct stream operator
0089   /// @param os output stream
0090   void toStream(std::ostream& os) const;
0091
0092   /// The axis direction
0093   AxisDirection m_axisDir = AxisDirection::AxisX;
0094
0095   /// The axis representation
0096   std::unique_ptr<IAxis> m_axis = nullptr;
0097
0098   /// Indicate if this is a place holder auto-range binning
0099   bool m_autorange = false;
0100 };
0101
0102 /// @brief Helper method to create a 1D grid from a single proto axis
0103 ///
0104 /// @tparam payload_t the grid payloat type
0105 ///
0106 /// @param a the proto axis
0107 ///
0108 /// @return an IGrid unique ptr and hence transfers ownership
0109 template <typename payload_t>
0110 std::unique_ptr<IGrid> makeGrid(const ProtoAxis& a) {
0111   if (a.isAutorange()) {
0112     throw std::invalid_argument(
0113         "ProtoAxis::makeGrid: Auto-range of the proto axis is not (yet) "
0114         "resolved, call setRange() first.");
0115   }
0116
0117   return a.getAxis().visit(
0118       [&]<typename AxisTypeA>(const AxisTypeA& axis) -> std::unique_ptr<IGrid> {
0119         using GridType = Grid<payload_t, AxisTypeA>;
0120         return std::make_unique<GridType>(axis);
0121       });
0122 }
0123
0124 /// @brief Helper method to create a 2D grid from a two proto axes
0125 ///
0126 /// @tparam payload_t the grid payloat type
0127 ///
0128 /// @param a the first proto axis
0129 /// @param b the second proto axis
0130 ///
0131 /// @return an IGrid unique ptr and hence transfers ownership
0132 template <typename payload_t>
0133 std::unique_ptr<IGrid> makeGrid(const ProtoAxis& a, const ProtoAxis& b) {
0134   // Validate axis compatibility
0135   if (a.getAxisDirection() == b.getAxisDirection()) {
0136     throw std::invalid_argument(
0137         "ProtoAxis::makeGrid: Axes must have different directions");
0138   }
0139
0140   if (a.isAutorange() || b.isAutorange()) {
0141     throw std::invalid_argument(
0142         "ProtoAxis::makeGrid: Auto-range of the proto axis is not (yet) "
0143         "resolved, call setRange() first.");
0144   }
0145
0146   return a.getAxis().visit([&]<typename AxisTypeA>(const AxisTypeA& axisA)
0147                                -> std::unique_ptr<IGrid> {
0148     return b.getAxis().visit([&]<typename AxisTypeB>(const AxisTypeB& axisB)
0149                                  -> std::unique_ptr<IGrid> {
0150       using GridType = Grid<payload_t, AxisTypeA, AxisTypeB>;
0151       return std::make_unique<GridType>(axisA, axisB);
0152     });
0153   });
0154 }
0155
0156 }  // namespace Acts