a class for evaluating a Butterworth filter transfer function. More...

#include <SimButterworthBandpass.h>

Inheritance diagram for casa::SimButterworthBandpass< T >:

Public Types
enum	{ CENTER, MINCUTOFF, MAXCUTOFF, PEAK }
	Enumeration of the function parameters. More...
Public Member Functions
	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.
	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.
const T &	getCenter () const
	return the center of the bandpass.
void	setMinCutoff (const T &x)
	set the characteristic minimum (high-pass) cutoff value.
void	setMaxCutoff (const T &x)
	set the characteristic maximum (low-pass) cutoff value.
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.
const T &	getMaxCutoff () const
	return the characteristic maximum (low-pass) cutoff value.
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.
const T &	getPeak () const
	return the scale of the function
virtual void	setMode (const RecordInterface &mode)
	get/set the function mode.
virtual void	getMode (RecordInterface &mode) const
virtual Bool	hasMode () const
	return True if the implementing function supports a mode.
virtual Function< T > *	clone () const
	clone this function
Private Attributes
uInt	nl_p
	Minimum order.
uInt	nh_p
	Maximum order.

Detailed Description

template<class T>
class casa::SimButterworthBandpass< T >

a class for evaluating a Butterworth filter transfer function.

Intended use:

Public interface

Review Status

Reviewed By:: wbrouw
Date Reviewed:: 2001/11/14
Test programs:: tSimButterworthBandpass

Prerequisite

FunctionParam class
Function1D

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)

T should have standard numerical operators. Current implementation only tested for real types (and their AutoDiffs).

Thrown Exceptions

Assertion if indices out-of-range

To Do

Nothing I know of

Definition at line 137 of file SimButterworthBandpass.h.

Member Enumeration Documentation

template<class T>

anonymous enum

Enumeration of the function parameters.

Enumerator:

CENTER
MINCUTOFF
MAXCUTOFF
PEAK

Definition at line 142 of file SimButterworthBandpass.h.

Constructor & Destructor Documentation

template<class T>

casa::SimButterworthBandpass< T >::SimButterworthBandpass ( )

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

template<class T>

casa::SimButterworthBandpass< T >::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.

template<class T>

casa::SimButterworthBandpass< T >::SimButterworthBandpass	(	const RecordInterface &	gr,
		T	mincut = `T(-1)`,
		T	maxcut = `T(1)`,
		T	center = `T(0)`,
		T	peak = `T(1)`
	)		`[explicit]`

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

template<class T>

casa::SimButterworthBandpass< T >::SimButterworthBandpass ( const SimButterworthBandpass< T > & other )

create a copy of another Butterworth bandpass function

template<class T>

virtual casa::SimButterworthBandpass< T >::~SimButterworthBandpass ( ) [virtual]

Destructor.

Member Function Documentation

template<class T>

virtual Function<T>* casa::SimButterworthBandpass< T >::clone ( ) const [inline, virtual]

clone this function

Implements casa::Function< T, T >.

Reimplemented in casa::MarshButterworthBandpass< T >.

Definition at line 248 of file SimButterworthBandpass.h.

template<class T>

virtual T casa::SimButterworthBandpass< T >::eval ( const typename FunctionTraits< T >::ArgType * x ) const [virtual]

Evaluate the bandpass at "x".

template<class T>

const T& casa::SimButterworthBandpass< T >::getCenter ( ) const [inline]

return the center of the bandpass.

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

Definition at line 181 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::CENTER, and casa::Function< T, T >::param_p.

template<class T>

const T& casa::SimButterworthBandpass< T >::getMaxCutoff ( ) const [inline]

return the characteristic maximum (low-pass) cutoff value.

At this x-ordinate value, the function has a value reduced 30 dB from its peak.

Definition at line 209 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::MAXCUTOFF, and casa::Function< T, T >::param_p.

template<class T>

uInt casa::SimButterworthBandpass< T >::getMaxOrder ( ) const [inline]

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

Definition at line 217 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::nh_p.

template<class T>

const T& casa::SimButterworthBandpass< T >::getMinCutoff ( ) const [inline]

return the characteristic minimum (high-pass) cutoff value.

At this x-ordinate value, the function has a value reduced 30 dB from its peak.

Definition at line 204 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::MINCUTOFF, and casa::Function< T, T >::param_p.

template<class T>

uInt casa::SimButterworthBandpass< T >::getMinOrder ( ) const [inline]

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

Definition at line 213 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::nl_p.

template<class T>

virtual void casa::SimButterworthBandpass< T >::getMode ( RecordInterface & mode ) const [virtual]

Reimplemented from casa::Function< T, T >.

template<class T>

const T& casa::SimButterworthBandpass< T >::getPeak ( ) const [inline]

return the scale of the function

Definition at line 224 of file SimButterworthBandpass.h.

References casa::Function< T, T >::param_p, and casa::SimButterworthBandpass< T >::PEAK.

template<class T>

virtual Bool casa::SimButterworthBandpass< T >::hasMode ( ) const [virtual]

return True if the implementing function supports a mode.

This implementation always returns True.

Reimplemented from casa::Function< T, T >.

template<class T>

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

copy(deep) another Butterworth function

Reimplemented in casa::MarshButterworthBandpass< T >.

template<class T>

void casa::SimButterworthBandpass< T >::setCenter ( const T & x ) [inline]

set the center of the bandpass.

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

Definition at line 177 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::CENTER, and casa::Function< T, T >::param_p.

template<class T>

void casa::SimButterworthBandpass< T >::setMaxCutoff ( const T & x ) [inline]

set the characteristic maximum (low-pass) cutoff value.

At this x-ordinate value, the function has a value reduced 30 dB from its peak.

Definition at line 191 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::MAXCUTOFF, and casa::Function< T, T >::param_p.

template<class T>

void casa::SimButterworthBandpass< T >::setMaxOrder ( uInt order ) [inline]

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

Definition at line 199 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::nh_p.

template<class T>

void casa::SimButterworthBandpass< T >::setMinCutoff ( const T & x ) [inline]

set the characteristic minimum (high-pass) cutoff value.

At this x-ordinate value, the function has a value reduced 30 dB from its peak.

Definition at line 186 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::MINCUTOFF, and casa::Function< T, T >::param_p.

template<class T>

void casa::SimButterworthBandpass< T >::setMinOrder ( uInt order ) [inline]

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

Definition at line 195 of file SimButterworthBandpass.h.

References casa::SimButterworthBandpass< T >::nl_p.

template<class T>

virtual void casa::SimButterworthBandpass< T >::setMode ( const RecordInterface & mode ) [virtual]

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

Reimplemented from casa::Function< T, T >.

template<class T>

void casa::SimButterworthBandpass< T >::setPeak ( T val ) [inline]

set the scale of the function by setting its peak value.

By default, the peak value is T(1);

Definition at line 221 of file SimButterworthBandpass.h.

References casa::Function< T, T >::param_p, and casa::SimButterworthBandpass< T >::PEAK.