Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
dsp::Convolution Class Reference

Convolves a TimeSeries using a frequency response function. More...

#include <Convolution.h>

Inheritance diagram for dsp::Convolution:
dsp::Transformation< TimeSeries, TimeSeries > dsp::Operation dsp::HasInput< TimeSeries > dsp::HasOutput< TimeSeries > OwnStream Reference::Able Reference::HeapTracked dsp::Filterbank dsp::InverseFilterbank dsp::SKFilterbank dsp::TFPFilterbank

Public Member Functions

 Convolution (const char *name="Convolution", Behaviour type=outofplace)
 Null constructor.
 
virtual ~Convolution ()
 Destructor.
 
void prepare ()
 Prepare all relevant attributes. More...
 
void reserve ()
 Reserve the maximum amount of output space required.
 
uint64_t get_minimum_samples ()
 Get the minimum number of samples required for operation.
 
uint64_t get_minimum_samples_lost ()
 Get the minimum number of samples lost.
 
double get_delay_time () const override
 Get the time delay of this operation, if any, in seconds.
 
virtual void set_response (Response *response)
 Return a descriptive string. More...
 
virtual void set_temporal_apodization (Apodization *)
 Set the temporal apodization function.
 
virtual void set_spectral_apodization (Apodization *)
 Set the spectral apodization function.
 
virtual void set_passband (Response *passband)
 Set the passband integrator.
 
bool has_response () const
 Return true if the response attribute has been set.
 
virtual const Response * get_response () const
 Return a pointer to the frequency response function.
 
virtual Response * get_response ()
 
bool has_passband () const
 Return true if the passband attribute has been set.
 
virtual const Response * get_passband () const
 Return a pointer to the integrated passband.
 
virtual Response * get_passband ()
 
bool has_temporal_apodization () const
 Return true if the temporal apodization attribute has been set.
 
virtual const Apodization * get_temporal_apodization () const
 Return a pointer to to the temporal apodization object.
 
virtual Apodization * get_temporal_apodization ()
 
bool has_spectral_apodization () const
 Return true if the spectral apodization attribute has been set.
 
virtual const Apodization * get_spectral_apodization () const
 Return a pointer to to the spectral apodization object.
 
virtual Apodization * get_spectral_apodization ()
 
bool get_matrix_convolution () const
 get the matrix_convolution flag
 
void set_critically_sampled_output (bool flag=true)
 discard the oversampled part of the band (assumed symmetric)
 
bool get_critically_sampled_output ()
 
void set_device (Memory *)
 Set the memory allocator to be used. More...
 
void set_engine (Engine *)
 
Engine * get_engine ()
 
bool get_zero_DM () const
 get the zero_DM flag
 
void set_zero_DM (bool _zero_DM)
 set the zero_DM flag
 
bool has_zero_DM_output () const
 Return true if the zero_DM_output attribute has been set.
 
virtual void set_zero_DM_output (TimeSeries *zero_DM_output)
 Set the zero_DM_output TimeSeries object.
 
virtual const TimeSeries * get_zero_DM_output () const
 Return a pointer to the zero_DM_output TimeSeries object.
 
virtual TimeSeries * get_zero_DM_output ()
 
bool has_zero_DM_response () const
 Return true if the zero DM response attribute has been set.
 
virtual const Response * get_zero_DM_response () const
 Return a pointer to the zero DM frequency response function.
 
virtual Response * get_zero_DM_response ()
 
virtual void set_zero_DM_response (Response *response)
 Set the zero DM frequency response function.
 
- Public Member Functions inherited from dsp::Transformation< TimeSeries, TimeSeries >
 Transformation (const char *_name, Behaviour _type)
 All sub-classes must specify name and capacity for inplace operation.
 
virtual ~Transformation ()
 Destructor.
 
void reserve ()
 Set the size of the output to that of the input by default.
 
void set_input (const TimeSeries *input)
 Set the container from which input data will be read.
 
void set_output (TimeSeries *output)
 Set the container into which output data will be written.
 
Behaviour get_type () const
 Return the Transformation type.
 
virtual void set_buffering_policy (BufferingPolicy *policy)
 Set the policy for buffering input and/or output data.
 
bool has_buffering_policy () const
 Returns true if buffering_policy is set.
 
BufferingPolicy * get_buffering_policy () const
 
void reset_min_samps ()
 Reset minimum_samps_can_process.
 
std::string name (const std::string &function) const
 String preceding output in verbose mode.
 
virtual void set_cerr (std::ostream &os) const
 Set verbosity ostream.
 
- Public Member Functions inherited from dsp::Operation
 Operation (const char *name)
 All sub-classes must specify a unique name. More...
 
 Operation (const Operation &)
 Copy constructor.
 
virtual ~Operation ()
 Virtual destructor.
 
virtual bool operate ()
 Call this method to operate on data Returns false on failure. More...
 
virtual void add_extensions (Extensions *)
 Add any extensions.
 
virtual void combine (const Operation *)
 Combine accumulated results with another operation. More...
 
virtual void report () const
 Report operation statistics.
 
virtual void reset ()
 Reset accumulated results to intial values. More...
 
std::string get_name () const
 Return the unique name of this operation.
 
double get_total_time () const
 Return the total time spent on this Operation in seconds.
 
double get_elapsed_time () const
 Get the time spent in the last invocation of operate()
 
virtual uint64_t get_total_weights () const
 Return the total number of timesample weights encountered. More...
 
virtual uint64_t get_discarded_weights () const
 Return the number of invalid timesample weights encountered.
 
int get_id ()
 Inquire the unique instantiation id.
 
virtual Function get_function () const
 Get the function classification of this operation.
 
virtual void set_scratch (Scratch *)
 Set the scratch space.
 
bool scratch_was_set () const
 
virtual uint64_t bytes_storage () const
 The number of bytes of additional storage used by the operation.
 
virtual uint64_t bytes_scratch () const
 The number of bytes of scratch space used by the operation. More...
 
- Public Member Functions inherited from OwnStream
 OwnStream (const OwnStream &)
 
const OwnStream & operator= (const OwnStream &)
 
virtual void set_cout (std::ostream &) const
 
- Public Member Functions inherited from Reference::Able
 Able (const Able &)
 
Able & operator= (const Able &)
 
unsigned get_reference_count () const
 
- Public Member Functions inherited from Reference::HeapTracked
 HeapTracked (const HeapTracked &)
 
HeapTracked & operator= (const HeapTracked &)
 
bool __is_on_heap () const
 
- Public Member Functions inherited from dsp::HasInput< TimeSeries >
virtual ~HasInput ()
 Destructor.
 
const TimeSeries * get_input () const
 Return pointer to the container from which input data will be read.
 
bool has_input () const
 Returns true if input is set.
 
- Public Member Functions inherited from dsp::HasOutput< TimeSeries >
virtual ~HasOutput ()
 Destructor.
 
virtual TimeSeries * get_output () const
 Return pointer to the container into which output data will be written.
 
bool has_output () const
 Returns true if output is set.
 

Protected Member Functions

virtual void transformation ()
 Perform the convolution transformation on the input TimeSeries. More...
 
void prepare_output ()
 Prepare the output TimeSeries.
 
void prepare_temporal_apodization ()
 Prepare the temporal apodization function. More...
 
void prepare_spectral_apodization (unsigned bcc_nfft)
 Prepare the spectral apodization function using input->get_dual_sideband. More...
 
void prepare_spectral_apodization (unsigned bcc_nfft, bool dual_sideband)
 Prepare the spectral apodization function. More...
 
void prepare_passband ()
 Prepare the output passband.
 
- Protected Member Functions inherited from dsp::Transformation< TimeSeries, TimeSeries >
virtual bool can_operate ()
 Return false if the input doesn't have enough data to proceed.
 
virtual void operation ()
 Define the Operation pure virtual method.
 
virtual void vchecks ()
 Makes sure input & output are okay before calling transformation()
 
- Protected Member Functions inherited from dsp::Operation
virtual void set_name (const std::string &_name)
 Set the name!
 
int timers_index (const std::string &op_name)
 Returns the index in the 'timers' array of a particular timer.
 
- Protected Member Functions inherited from Reference::Able
Handle * __reference (bool active) const
 
void __dereference (bool auto_delete=true) const
 

Protected Attributes

Reference::To< ScalarFilter > normalizer
 Scalar filter (normalizer)
 
Reference::To< Response > response
 Frequency response (convolution kernel)
 
Reference::To< Response > zero_DM_response
 Frequency response to use in zero DM case.
 
Reference::To< ResponseProduct > response_product
 Product of response and normaliser.
 
Reference::To< ResponseProduct > zero_dm_response_product
 Product of response and normaliser.
 
Reference::To< Apodization > temporal_apodization
 Apodization function (time domain window)
 
Reference::To< Apodization > spectral_apodization
 Apodization function (frequency domain window)
 
Reference::To< Response > passband
 Integrated passband.
 
bool zero_DM
 zero DM flag – this indicates whether to do a parallel transformation without any dedispersion
 
Reference::To< dsp::TimeSeries > zero_DM_output
 zero DM output timeseries from convolution
 
- Protected Attributes inherited from dsp::Transformation< TimeSeries, TimeSeries >
Reference::To< BufferingPolicy > buffering_policy
 The buffering policy in place (if any)
 
int64_t minimum_samps_can_process
 If input doesn't have this many samples, operate() returns false.
 
- Protected Attributes inherited from dsp::Operation
Scratch * scratch
 Shared scratch space, if needed.
 
bool set_scratch_called
 
std::string name
 Operation name.
 
uint64_t discarded_weights
 Number of time sample weights encountered that are flagged invalid.
 
uint64_t total_weights
 Total number of time sample weights encountered.
 
RealTimer optime
 Stop watch records the amount of time spent performing this operation.
 
int id
 Unique instantiation id.
 
bool prepared
 Set true when preparation optimizations are completed.
 
- Protected Attributes inherited from dsp::HasInput< TimeSeries >
Reference::To< const TimeSeries > input
 Container from which input data will be read.
 
- Protected Attributes inherited from dsp::HasOutput< TimeSeries >
Reference::To< TimeSeries > output
 Container into which output data will be written.
 

Friends

class Filterbank
 
class InverseFilterbank
 
class TFPFilterbank
 
class SKFilterbank
 

Additional Inherited Members

- Public Types inherited from dsp::Operation
enum  Function { Producer, Procedural, Structural }
 The function of the operator. More...
 
- Static Public Member Functions inherited from Reference::Able
static size_t get_instance_count ()
 
- Static Public Member Functions inherited from Reference::HeapTracked
static void * operator new (size_t size, void *ptr=0)
 
static void operator delete (void *location, void *ptr)
 
static void operator delete (void *location)
 
static size_t get_heap_queue_size ()
 
- Public Attributes inherited from dsp::Transformation< TimeSeries, TimeSeries >
Callback< Transformation * > pre_transformation
 Functions called before the transformation takes place.
 
Callback< Transformation * > post_transformation
 Functions called after the transformation takes place.
 
- Static Public Attributes inherited from dsp::Operation
static bool record_time = false
 Global flag enables stopwatch to record the time spent operating. More...
 
static bool report_time = true
 Global flag enables report of time spent in operation on descruction. More...
 
static bool verbose = false
 Global verbosity flag.
 
static int operation_status = 0
 Operations can set this to non-zero in operation() if they fail.
 
static bool check_state = true
 Operations should perform internal consistency checks.
 
static int instantiation_count = 0
 Counts how many Operation instantiations there have been Used for setting the unique instantiation ID. More...
 

Detailed Description

Convolves a TimeSeries using a frequency response function.

This class implements the overlap-save method of discrete convolution with a finite impulse response (FIR) function, as described in Chapter 13.1 of Numerical Recipes.

The algorithm can perform both scalar and matrix convolution methods, and is highly suited to phase-coherent dispersion removal and phase-coherent polarimetric calibration.

If g(t) is the finite impulse response function with which the data stream will be convolved, then the Convolution::response attribute represents G(w), the FFT of g(t). Convolution::response may contain an array of filters, one for each frequency channel.

In order to improve the spectral leakage characteristics, an apodization function may be applied to the data in the time domain by setting the Convolution::temporal_apodization attribute.

In order to improve the temporal leakage characteristics, an apodization function may be applied to the data in the frequency domain by setting the Convolution::spectral_apodization attribute.

Referring to Figure 13.1.3 in Numerical Recipes, $m_+$=response->get_impulse_pos() and $m_-$=response->get_impulse_neg(), so that the duration, M= $m_+ + m_-$, of g(t) corresponds to the number of complex time samples in the result of each backward FFT that are polluted by the cyclical convolution transformation. Consequently, $m_+$ and $m_-$ complex samples are dropped from the beginning and end, respectively, of the result of each backward FFT; neighbouring FFTs will overlap by the appropriate number of points to make up for this loss.

Member Function Documentation

◆ prepare()

void dsp::Convolution::prepare ( )
virtual

Prepare all relevant attributes.

Complex samples dropped from beginning of cyclical convolution result

Complex samples dropped from end of cyclical convolution result

Reimplemented from dsp::Operation.

Reimplemented in dsp::InverseFilterbank, and dsp::Filterbank.

References Signal::Analytic, FTransform::bcc, FTransform::fcc, FTransform::frc, FTransform::get_norm(), and Signal::Nyquist.

◆ prepare_spectral_apodization() [1/2]

void dsp::Convolution::prepare_spectral_apodization ( unsigned  bcc_nfft)
protected

Prepare the spectral apodization function using input->get_dual_sideband.

Prepare spectral apodization / tapering window.

◆ prepare_spectral_apodization() [2/2]

void dsp::Convolution::prepare_spectral_apodization ( unsigned  bcc_nfft,
bool  dual_sideband 
)
protected

Prepare the spectral apodization function.

Prepare spectral apodization / tapering window.

◆ prepare_temporal_apodization()

void dsp::Convolution::prepare_temporal_apodization ( )
protected

Prepare the temporal apodization function.

Prepare temporal apodization / tapering window.

References Signal::Analytic, and Signal::Nyquist.

◆ set_device()

void dsp::Convolution::set_device ( Memory *  mem)

Set the memory allocator to be used.

Set the device memory to use.

References dsp::Scratch::set_memory().

◆ set_response()

void dsp::Convolution::set_response ( Response *  response)
virtual

Return a descriptive string.

Set the frequency response function.

Initialize from a descriptor string as output by above Set the frequency response function

◆ transformation()

void dsp::Convolution::transformation ( )
protectedvirtual

Perform the convolution transformation on the input TimeSeries.

Precondition
input TimeSeries must contain phase coherent (undetected) data
Postcondition
output TimeSeries will contain complex (Analytic) data
IMPORTANT!! Most backward complex FFT functions expect frequency components organized with f0+bw/2 -> f0, f0-bw/2 -> f0. The forward real-to-complex FFT produces f0-bw/2 -> f0+bw/2. To save CPU cycles, convolve() does not re-sort the ouput array, and therefore introduces a frequency shift in the output data. This results in a phase gradient in the time domain. Since only relative phases matter when calculating the Stokes parameters, this effect is basically ignorable for our purposes.

Implements dsp::Transformation< TimeSeries, TimeSeries >.

Reimplemented in dsp::InverseFilterbank, and dsp::Filterbank.

References Signal::Analytic, and Signal::Nyquist.

The documentation for this class was generated from the following files:
Generated using doxygen 1.8.17