SimButterworthBandpass.h

Classes

SimButterworthBandpass -- a class for evaluating a Butterworth filter transfer function. (full description)

class SimButterworthBandpass : public Function1D<T>

Types

enum

CENTER
MINCUTOFF
MAXCUTOFF
PEAK

Interface

Public Members
SimButterworthBandpass()
SimButterworthBandpass(const uInt minord, const uInt maxord, const T &mincut=T(-1), const T &maxcut=T(1), const T &center=T(0), const T &peak=T(1))
explicit SimButterworthBandpass(const RecordInterface& gr, T mincut=T(-1), T maxcut=T(1), T center=T(0), T peak=T(1))
SimButterworthBandpass(const SimButterworthBandpass &other)
SimButterworthBandpass<T> & operator=(const SimButterworthBandpass<T> &other)
virtual ~SimButterworthBandpass()
virtual T eval(const typename FunctionTraits<T>::ArgType *x) const
void setCenter(const T &x)
const T &getCenter() const
void setMinCutoff(const T &x)
void setMaxCutoff(const T &x)
void setMinOrder(uInt order)
void setMaxOrder(uInt order)
const T &getMinCutoff() const
const T &getMaxCutoff() const
uInt getMinOrder() const
uInt getMaxOrder() const
void setPeak(T val)
const T &getPeak() const
virtual void setMode(const RecordInterface& mode)
virtual void getMode(RecordInterface& mode) const
virtual Bool hasMode() const
virtual Function<T> *clone() const

Description

Prerequisite

Etymology

"Butterworth" refers to the Butterworth function for describing filter transfer functions (Butterworth, S, "On the theory of filter amplifiers," Wireless Engineer, vol. 7 pp. 536-541, October 1930). "Bandpass" reflects that the transfer function is has both low and high frequency cutoffs. "Sim" indicates that this implementation is not necessarily appropriate characterizing real bandpass filters; in the future, there may be a more general class called simply "Butterworth".

Synopsis

This function class simulates the (amplitude) transfer function for a wideband bandpass filter constructed from the combination of a low-pass and a high-pass Butterworth filter.

In analog electronic filter design, a Butterworth low-pass filter is one in which the amplitude transfer function, |H(jw)| (where j = sqrt(-1) and w is the angular frequency), is given by:

   |H(jw)| = 1 / sqrt(1 + (w/w_c)^(2*n)) 
where n refers to the filter "order" and w_c is the "cutoff frequency". When w = w_c, the filter output is 1/sqrt(2) that of the input, and the higher the order, the steeper the drop off towards zero and the closer the approximation to a idealized step function.

Filter theory provides transformations for deriving transfer functions of high-pass and band-pass filters which reflect how the electrical circuits actually work. However, to simplify this class's implementation and to make the transfer function behavior more predictable by the naive user, THIS CLASS DOES NOT ACTUALLY USE THE PROPER TRANSFORMATIONS (see Etymology section above). Instead, the Butterworth bandpass transfer function is approximated by low pass component, given above, combined with a pseudo high-pass function that is of the same form but with w substituted with -w. Both components are shifted such that its peak transfer point is at a given "center" position. The cutoff value and order can be set independently for both ends of the passband.

Example

   // Create a bandpass function centered on x=0.8 and cutoffs at 0 and 2.5.
   // The orders of the drop-offs will 4 at the low end and 5 at the high
   // end.  The peak will by 1.0 by default.
   SimButterworthBandpass<Double> butt(4, 5, 0, 2.5, 0.8);
   
   Double z = butt(1);    // z = 1.0
   z = butt(0);           // z = 1/sqrt(2)
   z = butt(2.5);         // z = 1/sqrt(2)
   z = butt(-25);         // z ~ 9.24e-9 ~ 0

   // change the low-end cutoff to -25.0
   butt.setMinCutoff(-25);
   z = butt(-25);         // z = 1/sqrt(2)

Motivation

This class was created to simulate systemtic Butterworth bandpasses within the simulator tool. It can used by the SimBJones class to vary the bandpass in a predictable way. However, it has limited value for real filter analysis, and it is not expected to be a realistic representation of real bandpass filters in use with radio telescopes backends.

Template Type Argument Requirements (T)

Thrown Exceptions

To Do

Member Description

enum

Enumeration of the function parameters

SimButterworthBandpass()

create a zero-th order (all-pass) Butterworth bandpass function.

SimButterworthBandpass(const uInt minord, const uInt maxord, const T &mincut=T(-1), const T &maxcut=T(1), const T &center=T(0), const T &peak=T(1))

create a Butterworth bandpass function.

explicit SimButterworthBandpass(const RecordInterface& gr, T mincut=T(-1), T maxcut=T(1), T center=T(0), T peak=T(1))

create a fully specified Butterworth bandpass in which the low and high pass orders are stored in a Record

SimButterworthBandpass(const SimButterworthBandpass &other)

create a copy of another Butterworth bandpass function

SimButterworthBandpass<T> & operator=(const SimButterworthBandpass<T> &other)

copy(deep) another Butterworth function

virtual ~SimButterworthBandpass()

Destructor

virtual T eval(const typename FunctionTraits<T>::ArgType *x) const

Evaluate the bandpass at "x".

void setCenter(const T &x)

set the center of the bandpass. This is the x-ordinate value that evaluates to the peak of the function.

const T &getCenter() const

return the center of the bandpass. This is the x-ordinate value that evaluates to the peak of the function.

void setMinCutoff(const T &x)

set the characteristic minimum (high-pass) cutoff value. At this x-ordinate value, the function has a value reduced 30 dB from its peak.

void setMaxCutoff(const T &x)

set the characteristic maximum (low-pass) cutoff value. At this x-ordinate value, the function has a value reduced 30 dB from its peak.

void setMinOrder(uInt order)

set the order of the Butterworth function for the minimum (high-pass) portion of the bandpass

void setMaxOrder(uInt order)

set the order of the Butterworth function for the maximum (low-pass) portion of the bandpass

const T &getMinCutoff() const

return the characteristic minimum (high-pass) cutoff value. At this x-ordinate value, the function has a value reduced 30 dB from its peak.

const T &getMaxCutoff() const

return the characteristic maximum (low-pass) cutoff value. At this x-ordinate value, the function has a value reduced 30 dB from its peak.

uInt getMinOrder() const

return the order of the Butterworth function for the minimum (high-pass) portion of the bandpass

uInt getMaxOrder() const

return the order of the Butterworth function for the maximum (low-pass) portion of the bandpass

void setPeak(T val)

set the scale of the function by setting its peak value. By default, the peak value is T(1);

const T &getPeak() const

return the scale of the function

virtual void setMode(const RecordInterface& mode)
virtual void getMode(RecordInterface& mode) const

get/set the function mode. This is an alternate way to get/set the non-coefficient data for this function. The supported record fields are as follows:

 Field Name     Type            Role
 -------------------------------------------------------------------
 minOrder   TpInt   the order of the Butterworth function for the 
                    minimum (high-pass) portion of the bandpass
 maxOrder   TpInt   the order of the Butterworth function for the 
                    maximum (low-pass) portion of the bandpass
 An exception is thrown if either value is less than zero
 

virtual Bool hasMode() const

return True if the implementing function supports a mode. This implementation always returns True.

virtual Function<T> *clone() const

clone this function