casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Types | Public Member Functions | Private Attributes | List of all members
casacore::SimButterworthBandpass< T > Class Template Reference

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

#include <SimButterworthBandpass.h>

Inheritance diagram for casacore::SimButterworthBandpass< T >:
casacore::Function1D< T > casacore::Function< T, U > casacore::Functional< FunctionTraits< T >::ArgType, U > casacore::Functional< Vector< FunctionTraits< T >::ArgType >, U > casacore::MarshButterworthBandpass< T >

Public Types

enum  {
  CENTER,
  MINCUTOFF,
  MAXCUTOFF,
  PEAK
}
 Enumeration of the function parameters. More...
 
- Public Types inherited from casacore::Function1D< T >
typedef const T * FunctionArg
 
- Public Types inherited from casacore::Function< T, U >
typedef FunctionTraits< T >
::ArgType 
ArgType
 
typedef const ArgTypeFunctionArg
 

Public Member Functions

 SimButterworthBandpass ()
 create a zero-th order (all-pass) Butterworth bandpass function. More...
 
 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. More...
 
 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 More...
 
 SimButterworthBandpass (const SimButterworthBandpass &other)
 create a copy of another Butterworth bandpass function More...
 
SimButterworthBandpass< T > & operator= (const SimButterworthBandpass< T > &other)
 copy(deep) another Butterworth function More...
 
virtual ~SimButterworthBandpass ()
 Destructor. More...
 
virtual T eval (const typename FunctionTraits< T >::ArgType *x) const
 Evaluate the bandpass at "x". More...
 
void setCenter (const T &x)
 set the center of the bandpass. More...
 
const T & getCenter () const
 return the center of the bandpass. More...
 
void setMinCutoff (const T &x)
 set the characteristic minimum (high-pass) cutoff value. More...
 
void setMaxCutoff (const T &x)
 set the characteristic maximum (low-pass) cutoff value. More...
 
void setMinOrder (uInt order)
 set the order of the Butterworth function for the minimum (high-pass) portion of the bandpass More...
 
void setMaxOrder (uInt order)
 set the order of the Butterworth function for the maximum (low-pass) portion of the bandpass More...
 
const T & getMinCutoff () const
 return the characteristic minimum (high-pass) cutoff value. More...
 
const T & getMaxCutoff () const
 return the characteristic maximum (low-pass) cutoff value. More...
 
uInt getMinOrder () const
 return the order of the Butterworth function for the minimum (high-pass) portion of the bandpass More...
 
uInt getMaxOrder () const
 return the order of the Butterworth function for the maximum (low-pass) portion of the bandpass More...
 
void setPeak (T val)
 set the scale of the function by setting its peak value. More...
 
const T & getPeak () const
 return the scale of the function More...
 
virtual void setMode (const RecordInterface &mode)
 get/set the function mode. More...
 
virtual void getMode (RecordInterface &mode) const
 
virtual Bool hasMode () const
 return True if the implementing function supports a mode. More...
 
virtual Function< T > * clone () const
 clone this function More...
 
- Public Member Functions inherited from casacore::Function1D< T >
 Function1D ()
 Constructors. More...
 
 Function1D (const uInt n)
 
 Function1D (const Vector< T > &in)
 
 Function1D (const FunctionParam< T > &other)
 
 Function1D (const Function1D< T, T > &other)
 
 Function1D (const Function1D< W, X > &other)
 
virtual ~Function1D ()
 Destructor. More...
 
virtual uInt ndim () const
 Returns the number of dimensions of function. More...
 
- Public Member Functions inherited from casacore::Function< T, U >
 Function ()
 Constructors. More...
 
 Function (const uInt n)
 
 Function (const Vector< T > &in)
 
 Function (const FunctionParam< T > &other)
 
template<class W , class X >
 Function (const Function< W, X > &other)
 
 Function (const Function< T, U > &other)
 
virtual ~Function ()
 Destructor. More...
 
uInt nparameters () const
 Returns the number of parameters. More...
 
virtual U eval (FunctionArg x) const =0
 Evaluate the function object. More...
 
T & operator[] (const uInt n)
 Manipulate the nth parameter (0-based) with no index check. More...
 
const T & operator[] (const uInt n) const
 
virtual U operator() () const
 Evaluate this function object at xor at x, y. More...
 
virtual U operator() (const ArgType &x) const
 
virtual U operator() (const Vector< ArgType > &x) const
 
virtual U operator() (FunctionArg x) const
 
virtual U operator() (const ArgType &x, const ArgType &y) const
 
virtual U operator() (const ArgType &x, const ArgType &y, const ArgType &z) const
 
virtual const Stringname () const
 Specify the name associated with the function (default will be unknown) More...
 
Boolmask (const uInt n)
 Manipulate the mask associated with the nth parameter (e.g. More...
 
const Boolmask (const uInt n) const
 
const FunctionParam< T > & parameters () const
 Return the parameter interface. More...
 
FunctionParam< T > & parameters ()
 
const Vector< ArgType > & argp () const
 Get arg_p and parset_p. More...
 
Bool parsetp () const
 
void lockParam ()
 Compiler cannot always find the correct 'const' version of parameter access. More...
 
void unlockParam ()
 
ostream & print (ostream &os) const
 Print the function (i.e. More...
 
virtual Function< typename
FunctionTraits< T >::DiffType > * 
cloneAD () const
 
virtual Function< typename
FunctionTraits< T >::BaseType > * 
cloneNonAD () const
 
- Public Member Functions inherited from casacore::Functional< FunctionTraits< T >::ArgType, U >
virtual ~Functional ()
 Destructor. More...
 
virtual U operator() (const FunctionTraits< T >::ArgType &x) const =0
 Map a Domain x into a Range y value. More...
 
- Public Member Functions inherited from casacore::Functional< Vector< FunctionTraits< T >::ArgType >, U >
virtual ~Functional ()
 Destructor. More...
 
virtual U operator() (const Vector< FunctionTraits< T >::ArgType > &x) const =0
 Map a Domain x into a Range y value. More...
 

Private Attributes

uInt nl_p
 Minimum order. More...
 
uInt nh_p
 Maximum order. More...
 

Additional Inherited Members

- Protected Attributes inherited from casacore::Function< T, U >
FunctionParam< T > param_p
 The parameters and masks. More...
 
Vector< ArgTypearg_p
 Aid for non-contiguous argument storage. More...
 
Bool parset_p
 Indicate parameter written. More...
 
Bool locked_p
 Indicate that parameters are expected to be locked from changing. More...
 

Detailed Description

template<class T>
class casacore::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

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

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

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

template<class T>
casacore::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>
casacore::SimButterworthBandpass< T >::SimButterworthBandpass ( const RecordInterface gr,
mincut = T(-1),
maxcut = T(1),
center = T(0),
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>
casacore::SimButterworthBandpass< T >::SimButterworthBandpass ( const SimButterworthBandpass< T > &  other)

create a copy of another Butterworth bandpass function

template<class T>
virtual casacore::SimButterworthBandpass< T >::~SimButterworthBandpass ( )
virtual

Destructor.

Member Function Documentation

template<class T>
virtual Function<T>* casacore::SimButterworthBandpass< T >::clone ( ) const
inlinevirtual

clone this function

Implements casacore::Function< T, U >.

Reimplemented in casacore::MarshButterworthBandpass< T >.

Definition at line 248 of file SimButterworthBandpass.h.

template<class T>
virtual T casacore::SimButterworthBandpass< T >::eval ( const typename FunctionTraits< T >::ArgType x) const
virtual

Evaluate the bandpass at "x".

template<class T>
const T& casacore::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 casacore::SimButterworthBandpass< T >::CENTER, and casacore::Function< T, U >::param_p.

template<class T>
const T& casacore::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 casacore::SimButterworthBandpass< T >::MAXCUTOFF, and casacore::Function< T, U >::param_p.

template<class T>
uInt casacore::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 casacore::SimButterworthBandpass< T >::nh_p.

template<class T>
const T& casacore::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 casacore::SimButterworthBandpass< T >::MINCUTOFF, and casacore::Function< T, U >::param_p.

template<class T>
uInt casacore::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 casacore::SimButterworthBandpass< T >::nl_p.

template<class T>
virtual void casacore::SimButterworthBandpass< T >::getMode ( RecordInterface mode) const
virtual

Reimplemented from casacore::Function< T, U >.

template<class T>
const T& casacore::SimButterworthBandpass< T >::getPeak ( ) const
inline

return the scale of the function

Definition at line 224 of file SimButterworthBandpass.h.

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

template<class T>
virtual Bool casacore::SimButterworthBandpass< T >::hasMode ( ) const
virtual

return True if the implementing function supports a mode.

This implementation always returns True.

Reimplemented from casacore::Function< T, U >.

template<class T>
SimButterworthBandpass<T>& casacore::SimButterworthBandpass< T >::operator= ( const SimButterworthBandpass< T > &  other)

copy(deep) another Butterworth function

Referenced by casacore::MarshButterworthBandpass< T >::operator=().

template<class T>
void casacore::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 casacore::SimButterworthBandpass< T >::CENTER, and casacore::Function< T, U >::param_p.

template<class T>
void casacore::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 casacore::SimButterworthBandpass< T >::MAXCUTOFF, and casacore::Function< T, U >::param_p.

template<class T>
void casacore::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 casacore::SimButterworthBandpass< T >::nh_p.

template<class T>
void casacore::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 casacore::SimButterworthBandpass< T >::MINCUTOFF, and casacore::Function< T, U >::param_p.

template<class T>
void casacore::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 casacore::SimButterworthBandpass< T >::nl_p.

template<class T>
virtual void casacore::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 casacore::Function< T, U >.

template<class T>
void casacore::SimButterworthBandpass< T >::setPeak ( 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 casacore::Function< T, U >::param_p, and casacore::SimButterworthBandpass< T >::PEAK.

Member Data Documentation

template<class T>
uInt casacore::SimButterworthBandpass< T >::nh_p
private
template<class T>
uInt casacore::SimButterworthBandpass< T >::nl_p
private

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