GBaseSampleFFT.hh

Go to the documentation of this file.

//======================================================================
/*! \file GBaseSampleFFT.hh
 *
 *  Include file for class GBaseSampleFFT.
 */
//======================================================================

#ifndef G_BASE_SAMPLE_FFT_HH
#define G_BASE_SAMPLE_FFT_HH

//======================================================================

#include "GFFTDianelsonLanczos.hh"
#include "GLogMessage.hh"

//! Samples data type identifier
#define GFFT_DATA_UNDEFINED   0
//! Samples data type identifier
#define GFFT_DATA_REAL        1
//! Samples data type identifier
#define GFFT_DATA_COMPLEX     2

//! File header identifier
#define GFFT_HEADER_ID        "GFFT_SAMPLE "

//! I/O error code
#define GFFT_IOERR_FOPEN        1
//! I/O error code
#define GFFT_IOERR_HEADER       2
//! I/O error code
#define GFFT_IOERR_HEADER_DATA  3
//! I/O error code
#define GFFT_IOERR_DATA_TYPE    4
//! I/O error code
#define GFFT_IOERR_DATA         5

//----------------------------------------------------------------------
/*! \class GBaseSampleFFT
 *
 *  This class defines a base class to manage data samples and the
 *  corresponding Fourier transform.
 *
 *  The data are processed as real numbers with the FFT functions
 *  using the Danielson-Lanczos algorithm (see \ref FFT_Dianelson_Lanczos).
 *  Thus, the arrays (sample and Fourier transform) sizes depend whether
 *  the function is a real or a complex function.
 *
 *  The FFT algorithm works with dimensions N=2^k (power of two), so if the
 *  data dimension is not a power of 2, it is padded with zeros.
 *  It is anyway suggested to use samples with a dimension that is a
 *  power of 2.
 *
 *  In order to reduce computation time, the Fourier transform and/or the
 *  function samples are only computed when required.
 *  The status for the 2 data arrays (function samples and Fourier transform
 *  data) is defined by 2 boolean variables: \b data_set and \b fft_set.
 *
 *  \ref GFFT_time_scale_mode
 */
class GBaseSampleFFT
{
  //------------------------------------------------------------
  /*! \object_doc */
  GObjectV(GBaseSampleFFT);
  //------------------------------------------------------------

  protected:
    static double   epsilon;            ///< Limit for 0 checking
    static string   data_type_name[3];  ///< Names of the data types

    int       data_type;        ///< 0=undefined; 1=real; 2=complex
    u_int     samples_number;   ///< Number of data samples
    u_int     samples_dim;      ///< Effective arrays dimension (power of 2)
    u_int     alloc_dim;        ///< Effective allocated dim

    double  * data_array;       ///< Array of function samples
    double  * fft_array;        ///< Array of Fourier transform data

    bool      data_set;         ///< Indicate if the data samples are set
    bool      fft_set;          ///< Indicate if the FFT data are set

    // sampling rate data
    double    time_min;         ///< Time of the first sample
    double    time_max;         ///< Time of the last sample (after padding with zeros)
    double    time_end;         ///< Time of the last (defined) sample (before padding)
    double    time_step;        ///< Time step
    double    freq_step;        ///< Frequency step
    double    freq_crit;        ///< Frequency maximum value (Nyquist critical frequency)

  public:
    // Constructors
    GBaseSampleFFT ( u_int n = 0, double dt = 1.L );
    GBaseSampleFFT ( const GBaseSampleFFT & original );
    
    // Affectation
    GBaseSampleFFT & operator = ( const GBaseSampleFFT & original );

    // Destructors
    virtual ~GBaseSampleFFT ( );

  //----------------------------------------------------------
  // Initialisation and setting functions
    virtual void  ResetData   ( );
    virtual void  ClearData   ( );
    virtual u_int InitData    ( u_int n, double dt = 1.L, bool clear = true );
    virtual int   ResizeData  ( u_int n );

    /*! Pure virtual function that must be defined in derived classes
     *  to fill the function samples data from an array.
     *  \param  n       number of data (expressed in real)
     *  \param  data    data array
     */
    virtual void  InitFunctionData  ( u_int n, const double data [] ) = 0;

    /*! Pure virtual function that must be defined in derived classes
     *  to fill the Fourier transform data from an array of real numbers.
     *  The array must be sorted in the following  order:
     *  Re[0], Im[0], Re[1], Im[1], ... Re[n/2-1], Im[n/2-1]
     *  (see \ref GFFTComplex, \ref GFFTReal, ...).
     *  \param  n       number of data (expressed in real)
     *  \param  data    data array
     */
    virtual void  InitTransformData ( u_int n, const double data [] ) = 0;

    /*! Pure virtual function that must be defined in derived classes
     *  to fill the Fourier transform data from 2 arrays of real numbers:
     *  1 for the real terms of the Fourier transform, 1 for the imaginary
     *  terms.
     *  \param  n         number of complex numbers data
     *  \param  data_re   array for real part of data
     *  \param  data_im   array for imaginary part of data
     */
    virtual void  InitTransformData ( u_int n, const double data_re [],
                                               const double data_im [] ) = 0;


    /*! Pure virtual function to set a single value in the sample.
     *  The index meaning is different for a real or a complex data sample.
     *
     *  The use of this function implies that the full sample is set using this
     *  function, and that the FFT data have to be recomputed.
     *
     *  \param  i     data index
     *  \param  val   data (real) value
     */
    virtual void  SetFunctionValue ( u_int i, double val ) = 0;

    /*! Set a single (complex) value for the FFT
     *  (see derived class descriptions for SetFFTValue and SetTransformValue).
     *  \param  i   index of the FFT value
     *  \param  re  real part of the data
     *  \param  im  imaginary part of the data
     */
    virtual void  SetTransformValue ( u_int i, double re, double im = 0.L ) = 0;

    /*! Set a single (complex) value for the FFT
     *  (see derived class descriptions for SetFFTValue and SetTransformValue).
     *  \param  i   index of the FFT value
     *  \param  re  real part of the data
     *  \param  im  imaginary part of the data
     */
    virtual void  SetFFTValue ( u_int i, double re, double im = 0.L ) = 0;

    /*! Compute the Fourier transform from the function samples that are
     *  currently stored in the object.
     *  The function returns 0 if no error occured (dimensions and arrays
     *  are defined, ...).
     */
    virtual int   ComputeTransformData ( ) = 0;

    /*! Compute the inverse Fourier transform (function samples) from the
     *  Fourier transform data that are currently stored in the object.
     *  The function returns 0 if no error occured (dimensions and arrays
     *  are defined, ...).
     */
    virtual int   ComputeFunctionData  ( ) = 0;

    /*! Normalisation of the samples sum.
     *  This function is virtual because the normalisation procedure
     *  is different for real or complex samples).
     *  \param  s   requested normalisation
     */
    virtual void  Normalise ( double s = 1.L ) = 0;

    virtual void  Scale     ( double s );

    // total power
    virtual double  GetSumSquared ( bool f = false );

  //----------------------------------------------------------
  // Retrieve sample information
    bool  IsDefined ( ) const;        // inline
    bool  IsFunctionSet  ( ) const;   // inline
    bool  IsTransformSet ( ) const;   // inline

    void  FunctionSet  ( bool b = true );   // inline
    void  TransformSet ( bool b = true );   // inline

    int   GetDataType      ( ) const;   // inline
    u_int GetSamplesNumber ( ) const;   // inline
    u_int GetDimension     ( ) const;   // inline

    bool  HasSameSampling ( const GBaseSampleFFT & sample, double prec = 0.0001 ) const;

    // time sampling functions
    virtual int     SetTimeRange ( double t_lo, double t_up, bool ctr = false );

    virtual double  GetTimeMin  ( ) const;
    virtual double  GetTimeMax  ( ) const;
    virtual double  GetTimeEnd  ( ) const;
    virtual double  GetTimeStep ( ) const;

    virtual double  GetCriticalFrequency ( ) const;
    virtual double  GetFrequencyMax      ( ) const;
    virtual double  GetFrequencyStep     ( ) const;

    // Get the data
    double * GetFunctionData  ( bool check = true );
    double * GetTransformData ( bool check = true );

    // Dupplicate the arrays
    double * CopyFunctionData  ( ) const;
    double * CopyTransformData ( ) const;

    double * CreatePowerSpectralDensity ( );
    double * CreatePSD ( );

  //----------------------------------------------------------
  // Write/read functions
    virtual int   Write ( const string & fname );
    virtual int   Write ( FILE * fp );

    virtual int   Read  ( const string & fname );
    virtual int   Read  ( FILE * fp );

  //----------------------------------------------------------
  protected:
    // Functions for internal use
    virtual int   WriteHeader ( FILE * fp );
    virtual int   ReadHeader  ( FILE * fp );

    void CopyData ( const GBaseSampleFFT & original );

  public:
};

//======================================================================
//  Inline functions
#include "icc/GBaseSampleFFT.icc"


//======================================================================
#endif