OverriddenClusterParamsAlg.h

Go to the documentation of this file.

/** ****************************************************************************
 * @file   OverriddenClusterParamsAlg.h
 * @brief  Overrides another ClusterParamsAlgBase class with selected constants
 * @author petrillo@fnal.gov
 * @date   February 3, 2015
 * @see    StandardClusterParamsAlg.cxx
 *
 * ****************************************************************************/

#ifndef OVERRIDDENCLUSTERPARAMSALG_H
#define OVERRIDDENCLUSTERPARAMSALG_H

// C/C++ standard library
#include <bitset>
#include <type_traits> // std::is_base_of<>
#include <utility>     // std::forward<>
#include <vector>

// LArSoft libraries
#include "larreco/RecoAlg/ClusterRecoUtil/ClusterParamsAlg.h"
#include "larreco/RecoAlg/ClusterRecoUtil/ClusterParamsAlgBase.h"

namespace cluster {
  namespace details {
    /**
     * @brief Class holding a value of one among some selected types...
     *
     * FIXME: If this functionality is necessary, it should be
     * replaced with std::variant.
     */
    class MultiValue {
    public:
      using Measure_t = cluster::details::Measure_t<float>;

      union {
        Measure_t measure_value;
        float float_value;
        size_t size_t_value;
      };

      /// Default constructor; it's here only to allow for vectors to be resized
      /// and its effect is undefined. This class is not to be considered valid
      /// until it's assigned a value with the operator= .
      MultiValue() {}

      /// Sets the value from a value of type T; undefined by default
      template <typename T>
      MultiValue& operator=(T);

      /// Converts the value to type T; undefined by default
      template <typename T>
      operator T() const;

    }; // MultiValue

  } // namespace details

  /** **************************************************************************
   * @brief Algorithm collection class computing cluster parameters
   * @tparam AlgoBase class of algorithms to be overridden
   * @see ClusterParamsAlg
   *
   * This class wraps a ClusterParamsAlgBase class, and overrides selected
   * methods with constant values.
   * The same effect can be obtained explicitly creating a new class with
   * the proper methods overridden. This one is a more convenient way to get
   * the same result, but it's slower and less flexible.
   */
  template <typename AlgoBase>
  class OverriddenClusterParamsAlg : public ClusterParamsAlgBase {
    static_assert(std::is_base_of<ClusterParamsAlgBase, AlgoBase>::value,
                  "OverriddenClusterParamsAlg template parameter must derive"
                  " from ClusterParamsAlgBase");

  public:
    using Algo_t = AlgoBase;
    using This_t = OverriddenClusterParamsAlg<AlgoBase>;
    using Measure_t = typename AlgoBase::Measure_t;

    enum ParameterType_t {
      cpStartAngle,         ///< StartAngle()
      cpEndAngle,           ///< EndAngle()
      cpStartCharge,        ///< StartCharge()
      cpEndCharge,          ///< EndCharge()
      cpStartOpeningAngle,  ///< StartOpeningAngle()
      cpEndOpeningAngle,    ///< EndOpeningAngle()
      cpIntegral,           ///< Integral()
      cpIntegralStdDev,     ///< IntegralStdDev()
      cpSummedADC,          ///< SummedADC()
      cpSummedADCStdDev,    ///< SummedADCStdDev()
      cpNHits,              ///< NHits()
      cpMultipleHitDensity, ///< MultipleHitDensity()
      cpWidth,              ///< Width()
      NParameters           ///< total number of supported parameters
    };                      ///< type of cluster parameters

    /// Constructor; just forwards the arguments to the base class
    template <typename... Args>
    explicit OverriddenClusterParamsAlg(Args&&... args)
      : algo(std::forward<Args>(args)...), values(NParameters)
    {}

    /**
     * @brief Overrides the specified cluster parameter
     * @param param which cluster parameter to override
     * @param value the value of the cluster parameter to be returned
     * @return this object
     * @see ReleaseParameter()
     *
     * For parameters without uncertainty, the uncertainty will be ignored.
     */
    This_t&
    OverrideParameter(ParameterType_t param, Measure_t value)
    {
      overridden_set.set((size_t)param);
      values[(size_t)param] = value;
      return *this;
    } // OverrideParameter()

    /**
     * @brief Cancels the override of the specified cluster parameter
     * @param param which cluster parameter not to override any more
     * @return this object
     * @see OverrideParameter()
     */
    This_t&
    ReleaseParameter(ParameterType_t param)
    {
      overridden_set.set((size_t)param);
      return *this;
    }

    /// Returns whether the specified parameter is currently overridden
    bool
    isOverridden(ParameterType_t param) const
    {
      return overridden_set.test((size_t)param);
    }

    /// @{
    /// @name Standard ClusterParamsAlgBase interface
    ///
    /// The following methods replicate the ones of the templated Algo_t class.
    /// Except, of course, when they are overridden.

    /**
     * @brief Restores the class to post-configuration, pre-initialization state
     * @see Algo_t::Clear()
     */
    void
    Clear() override
    {
      algo.Clear();
    }

    /**
     * @brief Sets the list of input hits
     * @param hits list of pointers to hits
     * @throw undefined in case of error, this method can throw (anything)
     * @see Algo_t::SetHits().
     */
    void
    SetHits(util::GeometryUtilities const& gser,
            std::vector<recob::Hit const*> const& hits) override
    {
      algo.SetHits(gser, hits);
    }

    /**
     * @brief Sets the list of input hits
     * @param hits list of hits (hits will not be modified)
     * @throw undefined in case of error, this method can throw (anything)
     * @see Algo_t::SetHits().
     */
    void
    SetHits(util::GeometryUtilities const& gser, std::vector<recob::Hit> const& hits) override
    {
      algo.SetHits(gser, hits);
    }

    /// Set the verbosity level; @see Algo_t::SetVerbose().
    void
    SetVerbose(int level = 1) override
    {
      ClusterParamsAlgBase::SetVerbose(level);
      algo.SetVerbose(level);
    }

    /// @{
    /// @name Algorithm results

    //@{
    /**
     * @brief Computes the charge on the first and last wire of the track
     * @return the charge in ADC counts, with uncertainty
     * @see Algo_t::StartCharge(), Algo_t::EndCharge()
     */
    Measure_t
    StartCharge(util::GeometryUtilities const& gser) override
    {
      return ReturnValue(cpStartCharge, &Algo_t::StartCharge, gser);
    }
    Measure_t
    EndCharge(util::GeometryUtilities const& gser) override
    {
      return ReturnValue(cpEndCharge, &Algo_t::EndCharge, gser);
    }
    //@}

    //@{
    /**
     * @brief Computes the angle of the cluster
     * @return angle of the cluster in the wire x time space, in radians
     * @see Algo_t::StartAngle(), Algo_t::EndAngle()
     *
     * The angle is in the @f$ [ -\pi, \pi ] @f$ range, with 0 corresponding to
     * a cluster parallel to the wire plane and @f$ \pi @f$ to a cluster
     * orthogonal to the wire plane, going farther from it.
     */
    Measure_t
    StartAngle() override
    {
      return ReturnValue(cpStartAngle, &Algo_t::StartAngle);
    }

    Measure_t
    EndAngle() override
    {
      return ReturnValue(cpEndAngle, &Algo_t::EndAngle);
    }
    //@}

    //@{
    /**
     * @brief Computes the opening angle at the start or end of the cluster
     * @return angle at the start of the cluster, in radians
     * @see Algo_t::StartOpeningAngle(), Algo_t::EndOpeningAngle()
     */
    Measure_t
    StartOpeningAngle() override
    {
      return ReturnValue(cpStartOpeningAngle, &Algo_t::StartOpeningAngle);
    }
    Measure_t
    EndOpeningAngle() override
    {
      return ReturnValue(cpEndOpeningAngle, &Algo_t::EndOpeningAngle);
    }
    //@}

    /// @name Cluster charge
    /// @{
    /**
     * @brief Computes the total charge of the cluster from Hit::Integral()
     * @return total charge of the cluster, in ADC count units
     * @see IntegralStdDev(), SummedADC()
     * @see Algo_t::Integral()
     */
    Measure_t
    Integral() override
    {
      return ReturnValue(cpIntegral, &Algo_t::Integral);
    }

    /**
     * @brief Computes the standard deviation on the charge of the cluster hits
     * @return the standard deviation of charge of hits, in ADC count units
     * @see Integral()
     * @see Algo_t::IntegralStdDev()
     */
    Measure_t
    IntegralStdDev() override
    {
      return ReturnValue(cpIntegralStdDev, &Algo_t::IntegralStdDev);
    }

    /**
     * @brief Computes the total charge of the cluster from Hit::SummedADC()
     * @return total charge of the cluster, in ADC count units
     * @see SummedADCStdDev(), Integral()
     * @see Algo_t::SummedADC()
     */
    Measure_t
    SummedADC() override
    {
      return ReturnValue(cpSummedADC, &Algo_t::SummedADC);
    }

    /**
     * @brief Computes the standard deviation on the charge of the cluster hits
     * @return the standard deviation of charge of hits, in ADC count units
     * @see SummedADC()
     * @see Algo_t::SummedADCStdDev()
     */
    Measure_t
    SummedADCStdDev() override
    {
      return ReturnValue(cpSummedADCStdDev, &Algo_t::SummedADCStdDev);
    }

    /// @}

    /// Returns the number of hits in the cluster
    size_t
    NHits() override
    {
      return ReturnValue(cpNHits, &Algo_t::NHits);
    }

    /**
     * @brief Fraction of wires in the cluster with more than one hit
     * @return fraction of wires with more than one hit, or 0 if no wires
     * @see Algo_t::MultipleHitDensity()
     */
    float
    MultipleHitDensity() override
    {
      return ReturnValue(cpMultipleHitDensity, &Algo_t::MultipleHitDensity);
    }

    /**
     * @brief Computes the width of the cluster
     * @return width of the cluster
     * @see Algo_t::Width()
     */
    float
    Width(util::GeometryUtilities const& gser) override
    {
      return ReturnValue(cpWidth, &Algo_t::Width, gser);
    }

    /// @}

    /// @}

  protected:
    using ValueFunction_t = float (Algo_t::*)();
    using MeasureFunction_t = Measure_t (Algo_t::*)();

    Algo_t algo; ///< an instance of the wrapped algorithm class

    std::vector<details::MultiValue> values; ///< the overridden values
    std::bitset<NParameters> overridden_set; ///< bits for overriding

    template <typename Func, typename... Args>
    auto
    ReturnValue(ParameterType_t param, Func func, Args&&... args) -> decltype((algo.*func)(args...))
    {
      if (isOverridden(param)) {
        // convert here to the return type of the function
        // (even if we are not using that function, it still defines the type)
        return values[(size_t)param];
      }
      else
        return (algo.*func)(args...);
    } // ReturnValue()

  }; // class OverriddenClusterParamsAlg

} // namespace cluster

//==============================================================================
//===  Template implementation
//==============================================================================

namespace cluster {

  namespace details {

    // specialization: size_t
    template <>
    MultiValue&
    MultiValue::operator=(size_t value)
    {
      size_t_value = value;
      return *this;
    }

    template <>
    MultiValue::operator size_t() const
    {
      return size_t_value;
    }

    // specialization: float
    template <>
    MultiValue&
    MultiValue::operator=(float value)
    {
      float_value = value;
      return *this;
    }

    template <>
    MultiValue::operator float() const
    {
      return float_value;
    }

    // specialization: Measure_t
    template <>
    MultiValue&
    MultiValue::operator=(Measure_t value)
    {
      measure_value = value;
      return *this;
    }

    template <>
    MultiValue::operator MultiValue::Measure_t() const
    {
      return measure_value;
    }

  } // namespace details
} // namespace cluster

#endif // OVERRIDDENCLUSTERPARAMSALG_H