MDetector/Channel.h

Go to the documentation of this file.

#ifndef _mdet_Channel_h
#define _mdet_Channel_h

#include <mdet/MDetectorComponent.h>
//
#include <utl/Validated.h>
//
#include <complex>
#include <memory>


namespace det {
  struct ParentCreator;
  struct ComponentUpdater;
}

namespace mdet {

  class FrontEnd;


  class Channel : public MDetectorComponent<Channel>::Type {
  public:
    class Discriminator {
    private:
      class Callable {
      public:
        virtual double operator()(double t) const = 0;
        virtual Callable* Clone() const = 0;
        virtual ~Callable();
      };
    public:
      template<class Functor>
      class Proxy : public Callable {
      public:
        Proxy(const Functor& f) : fFunctor(f) { }
        double operator()(double t) const
        { return fFunctor(t); /* As a good proxy, forward the call */ }

        Channel::Discriminator::Callable*
        Clone()
          const
        {
          /*
           * The function MakeDiscriminator returns by copy, tough
           * thanks to Named-Return-Value-Optimization it's likely
           * that no temporaries will be created. Nevertheless, one cannot
           * just make private the copy constructor because, tough not
           * finally used, needs to be visible.
           *
           * So, being it visible copying is allowed. If we don't do
           * something the compiler generated copy constructor will
           * inherit std::auto_ptr's behaviour and so the copies
           * won't be equivalent (since the original auto_ptr
           * gets its pointer zeroed).
           *
           * See
           * http://www.artima.com/forums/flat.jsp?forum=226&thread=175294
           */
          return new Channel::Discriminator::Proxy<Functor>(fFunctor);
        }
      private:
        const Functor& fFunctor;
      };

    private:
      /*
       * Types of nested members.
       */
      friend class Channel;
      struct Root {
        double fTime;
        double fOutput;
      };
      typedef std::vector<Root> RootContainer;
      typedef RootContainer::const_iterator RootIterator;
      /*
       * We should use list since we don't know the number in advance;
       * but on the other hand we need to sort'em and so a random access
       * container is needed.
       */
      typedef std::vector<double> RawRootsContainer;
    public:
      typedef RawRootsContainer::const_iterator AtThresholdConstIterator;
      AtThresholdConstIterator AtThresholdBegin() const;
      AtThresholdConstIterator AtThresholdEnd() const;
      double operator()(double t) const;
      double GetOverThresholdTimeSpan() const;
      double operator()(double* x, double* p) const;
      Discriminator(const Discriminator& d);
    private:
      template<class Functor>
      Discriminator(const Channel& c, const Functor& f, double beginTime, double endTime) :
        fChannel(c),
        /*
         * Exception Safety Note: We're initiliazing a std::auto_ptr here, with
         * a constructor that doesn't throw exceptions.
         * Also the constructor called by the new expression also doesn't throw
         * exceptions, it just binds a reference.
         * And, of course, being a auto_ptr it handles its resource.
         * See Guru Of the Week "Constructor Failures" at
         * http://www.gotw.ca/gotw/066.htm.
         */
        fInputPulse(new Proxy<Functor>(f)),
        fTransitionTime((c.GetDiscriminatorHiLevel() - c.GetDiscriminatorLowLevel())
                                           / c.GetSlewRate()),
        fBeginTime(beginTime),
        fEndTime(endTime)
      {
        // Define this constructor here due to being a template.
        // Delegate initialization to the helper method.
        Init();
      }
      void Init();
      bool OverThreshold(double t) const;
      double ApplySaturation(double v) const;
      double ComputeOutput(double signReferenceTime, double deltaTime, double prevOutput) const;
      template<class Iterator>
      double ComputeBorderTime(Iterator beg, Iterator end, double time) const;
      const Channel& fChannel;
      const std::unique_ptr<Callable> fInputPulse;
      double fTransitionTime;
      double fBeginTime;
      double fEndTime;
      RootContainer fRoots;
      RawRootsContainer fRawRoots;
    };

    static const char* const kComponentName;

    static const char* const kComponentId;
    const FrontEnd& GetFrontEnd() const { return fFrontEnd; }
    double GetThreshold() const;
    std::complex<double> ComputeTransfer(double freq) const;
    double ComputeSignalShift() const;
    double GetSignalShiftMean() const;
    double GetSignalShiftStdDev() const;
    template <class Functor>
    Discriminator
    MakeDiscriminator(const Functor& inputPulse, double beginTime, double endTime)
      const
    {
      // Note that tough we're returning by-value it's likely that no copies will be made:
      // The (good) compilers likely optimize away the unnecessary temporaries.
      // Nevertheless, despite being not called at last, the copy constructor needs to
      // be visible from the calling point (ie we cannot privatize it).
      //
      // Also note that we're using an auto_ptr to handle the proxy:
      // if there were copies involved, remember that when copying auto_ptr s
      // we don't get equivalent objects: the pointed-to object ownership
      // passes to the target of the copy (and the source doesn't own it anymore:
      // we don't get a deadly double deletion).
      // See
      // http://www.aristeia.com/BookErrata/auto_ptr-update.html,
      // http://www.gotw.ca/gotw/025.htm and
      // http://www.gotw.ca/publications/using_auto_ptr_effectively.htm (beware
      // that this last one is outdated in some aspects).
      return Discriminator(*this, inputPulse, beginTime, endTime);
    }
  private:
    /*
     * Properties that characterize the amplification
     * stage (with its frequency response). The
     * idea is that client code doesn't access
     * to this properties.
     * Instead the client code would provide a signal
     * and in this class (through this, or any other
     * mean) would give the output-response to that
     * given signal by the channel.
     */
    double GetInvertingInputResistance() const;
    double GetFeedbackResistance() const;
    double GetDCGain() const;
    double GetLowCutoffFrequency() const;
    double GetHighCutoffFrequency() const;
    /*
     * Propeties that characterize the discrimination stage.
     * The output signal of the discriminator is ideally a
     * two valued continuous wave. This two values are set
     * according to the comparisson with the threshold,
     * the hi value level meaning that the signal was
     * greater than the threshold and viceversa.
     * In reality, the signal has a finite transition time
     * between states, and finite stabilization times.
     */
    double GetDiscriminatorLowLevel() const;
    double GetDiscriminatorHiLevel() const;
    double GetSlewRate() const;
    double GetResponseTime() const;
    double GetAbsoluteError() const;
    double GetInitialIntervalLength() const;
    unsigned int GetIterationsNumber() const;
    unsigned int GetMaxNumberOfErrors() const;
    std::complex<double> ComputeFrequencyFactor(double freq, double freqLimit) const;
    Channel(int cId, const det::VManager::IndexMap& parentMap, const FrontEnd& parent);
    ~Channel() { }
    friend struct det::ParentCreator;
    template<class T>
    friend void boost::checked_delete(T*) BOOST_NOEXCEPT;
    friend struct det::ComponentUpdater;
    /*
     * As told by Manuel Platino, there could be a parasite capacitance
     * in parallel with the op-amp amplification circuit.
     */
    mutable utl::Validated<double> fInvertingInputResistance;

    mutable utl::Validated<double> fFeedbackResistance;

    mutable utl::Validated<double> fDCGain;

    mutable utl::Validated<double> fLowCutoffFrequency;

    mutable utl::Validated<double> fHighCutoffFrequency;

    mutable utl::Validated<double> fThreshold;

    mutable utl::Validated<double> fResponseTime;

    mutable utl::Validated<double> fDiscriminatorLowLevel;

    mutable utl::Validated<double> fDiscriminatorHiLevel;

    mutable utl::Validated<double> fSlewRate;

    mutable utl::Validated<double> fAbsoluteError;

    mutable utl::Validated<double> fInitialIntervalLength;

    // Used int instead of unsigned due to lack of an specific overload for the later.
    mutable utl::Validated<int> fIterationsNumber;

    // Idem.
    mutable utl::Validated<int> fMaxNumberOfErrors;

    mutable utl::Validated<double> fSignalShiftMean;

    mutable utl::Validated<double> fSignalShiftStdDev;

    const FrontEnd& fFrontEnd;

  };

}


#endif