Integration.h

//-*-C++-*-
/***************************************************************************
 *
 *   Copyright (C) 2002 by Willem van Straten
 *   Licensed under the Academic Free License version 2.1
 *
 ***************************************************************************/
 
// /psrchive/Base/Classes/Pulsar/Integration.h
 
#ifndef __Pulsar_Integration_h
#define __Pulsar_Integration_h
 
#include "Pulsar/Pulsar.h"
#include "Pulsar/Container.h"
#include "Pulsar/Profile.h"
 
#include "MJD.h"
#include "Types.h"
#include "Estimate.h"
#include "Jones.h"
#include "sky_coord.h"
 
#include <vector>
 
template<typename T> class Stokes;
 
namespace Pulsar {
 
  class PolnProfile;
  class PhaseWeight;
  class Archive;


  class Integration : public Container {
    
  public:
    
    static unsigned verbose;

    static double match_max_frequency_difference;

    Integration ();

    Integration (const Integration& subint);

    Integration& operator = (const Integration& subint);
    
    virtual ~Integration ();

    static unsigned get_instance_count ();

    class Interface;

    virtual Interface* get_interface ();

    void zero ();

    MJD get_start_time () const;

    MJD get_end_time () const;

    double get_centre_frequency (unsigned ichan) const;
    void set_centre_frequency (unsigned ichan, double frequency);

    float get_weight (unsigned ichan) const;
    void set_weight (unsigned ichan, float weight);

    void find_transitions (int& hi2lo, int& lo2hi, int& buffer) const;

    void find_peak_edges (int& rise, int& fall) const;

    float find_max_phase () const;

    float find_min_phase (float dc = 0.10) const;

    PhaseWeight* baseline () const;

    void baseline_stats (std::vector< std::vector< Estimate<double> > >* mean,
                         std::vector< std::vector<double> >* variance = 0,
                         const PhaseWeight* baseline = 0) const;

    void remove_baseline (const PhaseWeight* baseline = 0);

    void cal_levels (std::vector< std::vector< Estimate<double> > >& hi,
                     std::vector< std::vector< Estimate<double> > >& lo) const;

    double weighted_frequency (unsigned ch_start=0, unsigned ch_end=0) const;

    double effective_bandwidth (unsigned ch_start=0, unsigned ch_end=0) const;

    void uniform_weight (float new_weight = 1.0);
    
    void dedisperse ();

    void defaraday ();
 
    // //////////////////////////////////////////////////////////////////
    //
    // Copying and cloning
    //
    // //////////////////////////////////////////////////////////////////


    virtual Integration* clone () const = 0;

    void orphan ();

    void adopt (const Archive*);

    Integration* total () const;
    
 
 
    // //////////////////////////////////////////////////////////////////
    //
    // Dimension Attributes
    //
    // //////////////////////////////////////////////////////////////////



    virtual unsigned get_nchan () const = 0;


    virtual unsigned get_npol () const = 0;


    virtual unsigned get_nbin () const = 0;
 
 
 
    // //////////////////////////////////////////////////////////////////
    //
    // Integration Unique Attributes
    //
    // //////////////////////////////////////////////////////////////////


    virtual MJD get_epoch () const = 0;
    /*  When not dealing with single-pulse data, the epoch should
       refer to that of the rising edge of phase bin zero near the
       middle of the integration. */
    virtual void set_epoch (const MJD& mjd) = 0;

    virtual double get_duration() const =0;
    virtual void set_duration (double seconds) = 0;

    virtual double get_folding_period() const = 0;
    /*  The topocentric folding period of the pulsar should be equal
        to that at the epoch defined by get_epoch. */
    virtual void set_folding_period (double seconds) = 0;

    virtual double get_gate_duty_cycle() const { return 1.0; }
    /*  When gated data are recorded, this is the duty cycle of the
        recording window */
    virtual void set_gate_duty_cycle (double turns) { }

 
 
    // //////////////////////////////////////////////////////////////////
    //
    // Archive Shared Attributes
    //
    // //////////////////////////////////////////////////////////////////


    std::string get_telescope() const;

    sky_coord get_coordinates() const;

    double get_centre_frequency() const;
    
    double get_bandwidth() const;

    double get_dispersion_measure () const;
    
    bool get_dedispersed () const;

    double get_rotation_measure () const;

    bool get_faraday_corrected () const;

    Signal::Basis get_basis () const;

    Signal::State get_state () const;

    bool get_absolute_dispersion_corrected () const;

    bool get_absolute_birefringence_corrected () const;


    double get_effective_dispersion_measure () const;


    double get_effective_rotation_measure () const;

    double get_relative_dispersion_measure () const;

    double get_relative_rotation_measure () const;    

    double get_absolute_dispersion_measure () const;

    double get_absolute_rotation_measure () const;        
 
 
    // //////////////////////////////////////////////////////////////////
    //
    // Access to data
    //
    // //////////////////////////////////////////////////////////////////


    Profile* get_Profile (unsigned ipol, unsigned ichan);

    const Profile* get_Profile (unsigned ipol, unsigned ichan) const;

    PolnProfile* new_PolnProfile (unsigned ichan);

    PolnProfile* new_PolnProfile (unsigned ichan) const;

    Stokes<float> get_Stokes (unsigned ichan, unsigned ibin) const;

    void get_Stokes (std::vector< Stokes<float> >& S, unsigned iother,
                     Signal::Dimension abscissa = Signal::Phase ) const;
 
    // //////////////////////////////////////////////////////////////////
    //
    // Extension access
    //
    // //////////////////////////////////////////////////////////////////

    
    class Extension;
    
    virtual unsigned get_nextension () const;

    virtual const Extension* get_extension (unsigned iextension) const;

    virtual Extension* get_extension (unsigned iextension);

    template<class ExtensionType>
    const ExtensionType* get () const;

    template<class ExtensionType>
    ExtensionType* get ();

    template<class ExtensionType>
    ExtensionType* getadd ();


    virtual void add_extension (Extension* extension);

    virtual std::string list_extensions () const;

    virtual void edit_extensions (const std::string& name);
    

    class Expert;

    Expert* expert ();
    const Expert* expert () const;

    Profile::Strategies* get_strategy() const;
 
  protected:
 
    // //////////////////////////////////////////////////////////////////
    //
    // Dimension Attributes
    //
    // //////////////////////////////////////////////////////////////////


    virtual void set_nbin (unsigned nbin) = 0;

    virtual void set_nchan (unsigned nchan) = 0;

    virtual void set_npol (unsigned npol) = 0;

    virtual void resize (unsigned npol=0, unsigned nchan=0, unsigned nbin=0);

    virtual void insert (Integration*);

    virtual void remove (unsigned ichan);

    virtual void remove (unsigned ichan_first, unsigned ichan_last);

    void reverse_chan ();

 
    friend class Archive;
    friend class Extension;
    friend class Calibrator;
    friend class Expert;

    void combine (const Integration* from);

    bool mixable (const Integration* integ, std::string& reason) const;

    virtual void copy (const Integration* subint, bool management = true);

    void swap_profiles (unsigned ipol, unsigned ichan, unsigned jpol, unsigned jchan);

    void rotate (double time);

    void rotate_phase (double phase);

    void fold (unsigned nfold);

    void bscrunch (unsigned nscrunch);
    
    void bscrunch_to_nbin (unsigned nbin);

    void fscrunch (unsigned nscrunch = 0);

    void pscrunch ();
    
    void invint ();
    
    void transform (const Jones<float>& response);

    void transform (const std::vector< Jones<float> >& response);

    void convert_state (Signal::State state);

    virtual Profile* new_Profile ();

    mutable std::vector< Reference::To<Extension> > extension;

    std::vector< std::vector< Reference::To<Profile> > > profiles;

    Reference::To<const Archive, false> parent;
 
    class Meta;

    Reference::To<Meta> orphaned;

    void range_check (unsigned ipol, unsigned ichan) const;

    Reference::To<Expert> expert_interface;
 
  private:

    void dedisperse (unsigned ichan, unsigned kchan,
                     double reference_frequency);

    void defaraday (unsigned ichan, unsigned kchan,
                    double reference_frequency);


    void update_absolute_dispersion();


    void update_absolute_rotation();

    void poln_convert (Signal::State out_state);

    bool zero_phase_aligned;

    void update_nbin ();
  };
 
  template<typename UnaryProfileMethod, typename Argument>
  void foreach (Integration* integration,
                UnaryProfileMethod method, const Argument& arg)
  {
    const unsigned npol = integration->get_npol();
    const unsigned nchan = integration->get_nchan();
 
    for (unsigned ipol=0; ipol<npol; ipol++)
      for (unsigned ichan=0; ichan<nchan; ichan++)
        (integration->get_Profile(ipol, ichan)->*(method)) (arg);
  }
 
  template<typename BinaryProfileMethod>
  void foreach (Integration* integration, const Integration* operand,
                BinaryProfileMethod method)
  {
    const unsigned npol = integration->get_npol();
    const unsigned nchan = integration->get_nchan();
 
    for (unsigned ipol=0; ipol<npol; ipol++)
      for (unsigned ichan=0; ichan<nchan; ichan++)
      {
        Profile* into = integration->get_Profile(ipol, ichan);
        const Profile* from = operand->get_Profile(ipol, ichan);
        (into->*(method)) (from);
      }
  }
}
 
#endif