Archive.h

//-*-C++-*-
/***************************************************************************
 *
 *   Copyright (C) 2002 - 2022 by Willem van Straten
 *   Licensed under the Academic Free License version 2.1
 *
 ***************************************************************************/
 
// psrchive/Base/Classes/Pulsar/Archive.h
 
#ifndef __Pulsar_Archive_h
#define __Pulsar_Archive_h
 
#include "Pulsar/IntegrationManager.h"
#include "Pulsar/Config.h"
 
#include "sky_coord.h"
#include "MJD.h"
 
#include "Functor.h"
#include "Estimate.h"
#include "Types.h"
 
#include <iostream>
 
template<typename T> class Jones;
 
namespace Pulsar
{
  class Receiver;
  class Integration;
  class Profile;
  class PhaseWeight;
 
  class Predictor;
  class Parameters;
 
  class StrategySet;
  

  class Archive : public IntegrationManager
  {
 
  public:
 
    // //////////////////////////////////////////////////////////////////
    //
    //
    // //////////////////////////////////////////////////////////////////

    Archive ();

    Archive (const Archive& archive);

    virtual ~Archive ();

    Archive& operator = (const Archive& a);
 
 
    // //////////////////////////////////////////////////////////////////
    //
    // Factories, loading, unloading, and refreshing
    //
    // //////////////////////////////////////////////////////////////////


    static Archive* new_Archive (const std::string& class_name);

    static Archive* load (const std::string& name);

    static unsigned get_instance_count ();



    virtual bool can_unload () const = 0;

    void unload (const char* filename = 0) const;

    void unload (const std::string& filename) const
      { unload (filename.c_str()); }

    std::string get_filename () const { return unload_filename; }


    void set_filename (const std::string& filename)
    { unload_filename = filename; }

    void update ();

    void refresh ();

 
    // //////////////////////////////////////////////////////////////////
    //
    // Copying and cloning
    //
    // //////////////////////////////////////////////////////////////////


    void copy (const Archive&);
    void copy (const Archive*);


    virtual Archive* clone () const = 0;

    Archive* total (bool tscrunch = true) const;


    Archive* tscrunched () const;

    Archive* extract (std::vector<unsigned>& subints) const;

 
    // //////////////////////////////////////////////////////////////////
    //
    // Dimension Attributes
    //
    // //////////////////////////////////////////////////////////////////


    virtual unsigned get_nbin () const = 0;

    virtual unsigned get_nchan () const = 0;

    virtual unsigned get_npol () const = 0;

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

    virtual void erase (unsigned isubint);

    void reverse_chan ();

 
    // //////////////////////////////////////////////////////////////////
    //
    // Common Attributes
    //
    // //////////////////////////////////////////////////////////////////


    virtual std::string get_telescope () const = 0;
    virtual void set_telescope (const std::string& code) = 0;

    virtual Signal::State get_state () const = 0;
    virtual void set_state (Signal::State state) = 0;

    virtual Signal::Scale get_scale () const = 0;
    virtual void set_scale (Signal::Scale scale) = 0;

    virtual Signal::Source get_type () const = 0;
    virtual void set_type (Signal::Source type) = 0;

    virtual std::string get_source () const = 0;
    virtual void set_source (const std::string& source) = 0;

    virtual sky_coord get_coordinates () const = 0;
    virtual void set_coordinates (const sky_coord& coordinates) = 0;

    virtual double get_centre_frequency () const = 0;
    virtual void set_centre_frequency (double cf) = 0;

    virtual double get_bandwidth () const = 0;
    virtual void set_bandwidth (double bw) = 0;

    virtual double get_dispersion_measure () const = 0;
    virtual void set_dispersion_measure (double dm) = 0;

    virtual bool get_dedispersed () const = 0;
    virtual void set_dedispersed (bool done = true) = 0;

    virtual double get_rotation_measure () const = 0;
    virtual void set_rotation_measure (double rm) = 0;

    virtual bool get_faraday_corrected () const = 0;
    virtual void set_faraday_corrected (bool done = true) = 0;

    virtual bool get_poln_calibrated () const = 0;
    virtual void set_poln_calibrated (bool done = true) = 0;

 
 
    // //////////////////////////////////////////////////////////////////
    //
    // Access to data
    //
    // //////////////////////////////////////////////////////////////////


    Profile* get_Profile (unsigned subint, unsigned pol, unsigned chan);

    const Profile*
    get_Profile (unsigned subint, unsigned pol, unsigned chan) const;

 
 
    // //////////////////////////////////////////////////////////////////
    //
    // Pulsar Ephemeris and Predictor
    //
    // //////////////////////////////////////////////////////////////////


    void set_ephemeris (const Parameters* ephemeris, bool update = true);

    const Parameters* get_ephemeris() const;

    bool has_ephemeris () const { return ephemeris; }

    void set_model (const Predictor* model, bool apply = true);

    const Predictor* get_model() const;

    bool has_model() const { return model; }

    void update_model ();

 
    // //////////////////////////////////////////////////////////////////
    //
    // Basic algorithms
    //
    // //////////////////////////////////////////////////////////////////

    void bscrunch (unsigned nscrunch);

    void fold (unsigned nfold);

    void pscrunch();

    void fscrunch (unsigned nscrunch=0);

    void tscrunch (unsigned nscrunch=0);

    void rotate (double time);

    void rotate_phase (double phase);

    void append (const Archive* archive);

    void remove_chan(unsigned first, unsigned last);

    void update_centre_frequency();

    void centre (double phase_offset = 0.5);

    void centre_max_bin (double phase_offset = 0.5);

    void convert_state (Signal::State state);

    Signal::Basis get_basis () const;

    void dedisperse ();

    void defaraday ();

    void transform (const Jones<float>&);

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

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

    void invint ();

    PhaseWeight* baseline () const;

    void remove_baseline ();

    void uniform_weight (float new_weight = 1.0);

    bool standard_match (const Archive* arch, std::string& reason) const;

    bool calibrator_match (const Archive* arch, std::string& reason) const;

    bool processing_match (const Archive* arch, std::string& reason) const;

    bool mixable (const Archive* arch, std::string& reason) const;

    double weighted_frequency (unsigned ichan,
                               unsigned start, unsigned end) const;

    void bscrunch_to_nbin (unsigned new_nbin);

    void fscrunch_to_nchan (unsigned new_nchan);

    void tscrunch_to_nsub (unsigned new_nsub);

    MJD  start_time () const;
    
    MJD  end_time () const;

    double integration_length() const;

    bool type_is_cal () const;

    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.15) const;

    float rms_baseline (float dc = 0.4);

    class Interface;

    virtual Interface* get_interface ();
 
    // //////////////////////////////////////////////////////////////////
    //
    // Archive Extension interface
    //
    // //////////////////////////////////////////////////////////////////


    class Extension;

    virtual unsigned get_nextension () const;

    virtual const Extension* get_extension (unsigned iextension) const;

    virtual Extension* get_extension (unsigned iextension);

    template<class ExtensionType>
    bool has () const;

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

    template<class ExtensionType>
    ExtensionType* get ();

    template<class ExtensionType>
    ExtensionType* getadd ();


    virtual void add_extension (Extension* extension);

 
    // //////////////////////////////////////////////////////////////////
    //
    // Class members
    //
    // //////////////////////////////////////////////////////////////////

    static void agent_report ();

    static void agent_list ();


    static void set_verbosity (unsigned level);

    class Check;
 
    // //////////////////////////////////////////////////////////////////
    //
    // Expert interface
    //
    // //////////////////////////////////////////////////////////////////

    class Expert;

    Expert* expert ();
    const Expert* expert () const;
 
    // //////////////////////////////////////////////////////////////////
    //
    // Matching policies
    //
    // //////////////////////////////////////////////////////////////////

    class Match;

    const Match* get_standard_match () const;
    void set_standard_match (Match*);

    const Match* get_calibrator_match () const;
    void set_calibrator_match (Match*);

    const Match* get_processing_match () const;
    void set_processing_match (Match*);

    const Match* get_mixable () const;
    void set_mixable (Match*);

    static Functor< void (Archive*) > remove_baseline_strategy;

    StrategySet* get_strategy() const;
 
  protected:
 
    friend class Expert;

    static std::string get_revision (const char* revision);
 
    // //////////////////////////////////////////////////////////////////
    //
    // File I/O
    //
    // //////////////////////////////////////////////////////////////////


    static Option<std::string> unload_class;

    static Option<bool> unload_cull_predictor;

    static Option<bool> no_clobber;

    virtual void load_header (const char* filename) = 0;

    virtual Integration*
    load_Integration (const char* filename, unsigned subint) = 0;

    virtual void unload_file (const char* filename) const = 0;


    std::string unload_filename;
 
    // //////////////////////////////////////////////////////////////////
    //
    // Dimension Attributes
    //
    // //////////////////////////////////////////////////////////////////


    virtual void set_nbin (unsigned numbins) = 0;

    virtual void set_nchan (unsigned numchan) = 0;

    virtual void set_npol (unsigned numpol) = 0;



    void set_predictor (Predictor* model);

    Reference::To<Parameters> ephemeris;

    Integration* use_Integration (Integration*);


    void init_Integration (Integration* subint, bool check_phase = false);

    void resize_Integration (Integration* integration);

    void apply_model (Integration* subint, const Predictor* old = 0);

    void update_model (unsigned old_nsubint, bool clear_model = false);

    void update_model (const MJD& time, bool clear_model = false);

    void create_updated_model (bool clear_model);

    bool good_model (const Predictor* test_model) const;

    bool zero_phase_aligned () const;

    Reference::To<Expert> expert_interface;

    Reference::To<Interface> text_interface;
 
    mutable Reference::To<Match> standard_match_policy;
    mutable Reference::To<Match> calibrator_match_policy;
    mutable Reference::To<Match> processing_match_policy;
    mutable Reference::To<Match> mixable_policy;
 
  private:

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

    mutable Reference::To<StrategySet> strategy;

    Reference::To<Predictor> model;

    mutable Reference::To<Predictor> unload_model;

    void create_unload_model() const;


    std::string __load_filename;

    mutable std::vector<unsigned>* copy_subints;
    unsigned copy_nsubint () const;
    unsigned copy_isubint (unsigned) const;

    Integration* load_Integration (unsigned isubint);


    void update_absolute_dispersion();


    void update_absolute_rotation();
    
    void init ();
   
    void correct ();

    void verify () const;
 
    // Advocates the use of an Archive derived class
    class Agent;
 
  protected:
 
    // Advocates the use of Plugin
    template<class Plugin> class Advocate;
 
  };

  bool in_frequency_order (const Archive* A, const Archive* B);
  
}
 
#endif