dsp::InverseFilterbank Class Reference

Performs the PFB inversion synthesis operation. More...

#include <InverseFilterbank.h>

Inheritance diagram for dsp::InverseFilterbank:

Classes
class	Engine
	Abstract base class for derived engines that operate on data in order to perform inverse (synthesis) filterbank operation. More...

Public Member Functions
	InverseFilterbank (const char *name="InverseFilterbank", Behaviour type=outofplace)
	Null constructor.
void	set_input (const TimeSeries *input)
	Set the container from which input data will be read.
void	prepare ()
	Prepare all relevant attributes.
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.
void	set_input_nchan (unsigned _input_nchan)
	Set the number of input channels.
unsigned	get_input_nchan () const
	Get the number of input channels.
void	set_output_nchan (unsigned _output_nchan)
	Set the number of output channels.
unsigned	get_output_nchan () const
	Get the number of output channels.
unsigned	get_nchan_subband () const
	Get the number of input channels per output channels.
void	set_freq_res (unsigned _freq_res)
	Set the frequency resolution factor.
void	set_frequency_resolution (unsigned _freq_res)
	Set the frequency resolution factor.
unsigned	get_freq_res () const
	Get the frequency resolution factor.
unsigned	get_frequency_resolution () const
	Get the frequency resolution factor.
void	set_frequency_overlap (unsigned over)
	Set the frequency overlap.
unsigned	get_frequency_overlap () const
	Get the frequency overlap.
void	set_oversampling_factor (const Rational &_osf)
	Set oversampling_factor.
const Rational &	get_oversampling_factor ()
	Get oversampling_factor.
bool	get_pfb_all_chan () const
	Get the pfb_all_chan flag.
void	set_pfb_all_chan (bool)
	Set the pfb_all_chan flag.
int	get_input_discard_neg () const
	Get the number of samples discarded at the end of an input step.
void	set_input_discard_neg (int _input_discard_neg)
	Set the number of samples discarded at the end of an input step.
int	get_input_discard_pos () const
	Get the number of samples discarded at the start of an input step.
void	set_input_discard_pos (int _input_discard_pos)
	Set the number of samples discarded at the start of an input step.
int	get_output_discard_neg () const
	Get the number of samples discarded at the end of an output step.
void	set_output_discard_neg (int _output_discard_neg)
	Set the number of samples discarded at the end of an output step.
int	get_output_discard_pos () const
	Get the number of samples discarded at the start of an output step.
void	set_output_discard_pos (int _output_discard_pos)
	Get the number of samples discarded at the start of an output step.
int	get_input_fft_length () const
	Get the size of the forward fft, in number of samples.
void	set_input_fft_length (int _input_fft_length)
	Set the size of the forward fft, in number of samples.
int	get_output_fft_length () const
	Get the size of the backward fft, in number of samples.
void	set_output_fft_length (int _output_fft_length)
	Set the size of the backward fft, in number of samples.
void	set_engine (Engine *)
Public Member Functions inherited from dsp::Convolution
	Convolution (const char *name="Convolution", Behaviour type=outofplace)
	Null constructor.
virtual	~Convolution ()
	Destructor.
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.
virtual void	filterbank ()
	Perform the filterbank step.
virtual void	custom_prepare ()
	Override this in a child class to do any custom pre-transformation data preparation.
Protected Member Functions inherited from dsp::Convolution
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
unsigned	input_nchan
	number of input channels
unsigned	output_nchan
	Number of channels into which the input will be synthesized This is the final number of channels in the output.
unsigned	freq_res
	Frequency resolution factor.
unsigned	nchan_subband
	This is the number of input channels per output channel, or input_nchan / output_nchan.
double	overlap_ratio
	Frequency channel overlap ratio.
Rational	oversampling_factor
	Polyphase filterbank oversampling ratio. More...
bool	pfb_all_chan
	This flag indicates whether we have all the channels from the last stage of upstream channelization.
Reference::To< Engine >	engine
	Interface to alternate processing engine (e.g. GPU)
Protected Attributes inherited from dsp::Convolution
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.

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

Performs the PFB inversion synthesis operation.

Combines multiple input frequency channels into a smaller number of output channels.

The PFB inversion algorithm is fed a chunk of input data. The size of this chunk is determined by the upstream IOManager. For each input chunk, it does the following.

• Advance through the input data by input_fft_length minus input_discard_total, or the number of samples skipped from the start and end of each input step. If the input_discard_total is greater than zero, this means that each successive step will be reading from data that we've already operated on.
• For each channel in the input data step, apply an input_fft_length size FFT. If there is an oversampling factor that is greater than one, discard samples from either end of the resulting frequency domain data, before stitching into a large array whose size will be output_fft_length long. How these samples get stitched into this array is determined by the presence of the zeroth PFB channel.
• Apply an inverse FFT to the stitched spectrum, before copying the newly created upsampled time domain data into the output TimeSeries buffer. In the same way that we read overlapped chunks of input data, we also write out the output data in overlapped segments.

The input TimeSeries can be critically sampled or over sampled. In the over sampled case, input spectra will be appropriately stitched together, discarding band edge overlap regions.

The manner in which input channels are synthesized depends on the number of input channels that are present, and if the zeroth PFB channel is present. Here, the "reassembled" spectrum refers to the spectrum that gets assembled from forward FFTs operating on each input channel in the transformation step. There are three distinct scenarios:

• All PFB channels are present, and the zeroth, or DC PFB channel is present. Here, the first half channel of the reassembled spectrum gets put at the end of the spectrum; we "roll" the assembled spectrum by half a channel.
• The DC PFB channel is present, but we only have a subset of the channels from upstream channelization. In this case, we discard the zeroth channel, and append a half channel's worth of zeros to the end of the assembled spectrum
• We have neither the DC PFB channel nor all the PFB channels. In this case we leave the assembled spectrum as is.

WvS AT3-119 Are these scenarios specific to a certain analysis PFB implementation, or are they generic?

Member Data Documentation

oversampling_factor

Rational dsp::InverseFilterbank::oversampling_factor

protected

Polyphase filterbank oversampling ratio.

This will be 1/1 for critically sampled, and some number greater than 1 for over sampled case

Referenced by get_freq_res(), and get_frequency_resolution().

---

The documentation for this class was generated from the following files:

• InverseFilterbank.h
• InverseFilterbank.C