casacore
SimButterworthBandpass.h
Go to the documentation of this file.
1 //# SimButterworthBandpass.h: Declares a Butterworth function
2 //# Copyright (C) 2000,2001,2002,2003
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef SCIMATH_SIMBUTTERWORTHBANDPASS_H
29 #define SCIMATH_SIMBUTTERWORTHBANDPASS_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/ArrayFwd.h>
34 #include <casacore/casa/Containers/Block.h>
35 #include <casacore/scimath/Functionals/Function1D.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 // <summary>
40 // a class for evaluating a Butterworth filter transfer function.
41 // </summary>
42 
43 // <use visibility=export>
44 
45 // <reviewed reviewer="wbrouw" date="2001/11/14"
46 // tests="tSimButterworthBandpass" demos="">
47 // </reviewed>
48 
49 // <prerequisite>
50 // <li> <linkto class="FunctionParam">FunctionParam</linkto> class
51 // <li> <linkto class=Function1D>Function1D</linkto>
52 // </prerequisite>
53 //
54 // <etymology>
55 // "Butterworth" refers to the Butterworth function for describing
56 // filter transfer functions (Butterworth, S, "On the theory of filter
57 // amplifiers," Wireless Engineer, vol. 7 pp. 536-541, October 1930).
58 // "Bandpass" reflects that the transfer function is has both low and high
59 // frequency cutoffs.
60 // "Sim" indicates that this implementation is not necessarily appropriate
61 // characterizing real bandpass filters; in the future, there may be a
62 // more general class called simply "Butterworth".
63 // </etymology>
64 //
65 // <synopsis>
66 // This function class simulates the (amplitude) transfer function for a
67 // wideband bandpass filter constructed from the combination of a low-pass
68 // and a high-pass Butterworth filter.
69 //
70 // In analog electronic filter design, a Butterworth low-pass filter is
71 // one in which the amplitude transfer function, |H(jw)| (where j = sqrt(-1)
72 // and w is the angular frequency), is given by:
73 // <srcblock>
74 // |H(jw)| = 1 / sqrt(1 + (w/w_c)^(2*n))
75 // </srcblock>
76 // where n refers to the filter "order" and w_c is the "cutoff frequency".
77 // When w = w_c, the filter output is 1/sqrt(2) that of the input, and the
78 // higher the order, the steeper the drop off towards zero and the closer
79 // the approximation to a idealized step function.
80 //
81 // Filter theory provides transformations for deriving transfer functions
82 // of high-pass and band-pass filters which reflect how the electrical
83 // circuits actually work. However, to simplify this class's implementation
84 // and to make the transfer function behavior more predictable by the naive
85 // user, THIS CLASS DOES NOT ACTUALLY USE THE PROPER TRANSFORMATIONS (see
86 // Etymology section above).
87 // Instead, the Butterworth bandpass transfer function is approximated by
88 // low pass component, given above, combined with a pseudo high-pass function
89 // that is of the same form but with w substituted with -w. Both components
90 // are shifted such that its peak transfer point is at a given "center"
91 // position. The cutoff value and order can be set independently for both
92 // ends of the passband.
93 // </synopsis>
94 //
95 // <example>
96 // <srcblock>
97 // // Create a bandpass function centered on x=0.8 and cutoffs at 0 and 2.5.
98 // // The orders of the drop-offs will 4 at the low end and 5 at the high
99 // // end. The peak will by 1.0 by default.
100 // SimButterworthBandpass<Double> butt(4, 5, 0, 2.5, 0.8);
101 //
102 // Double z = butt(1); // z = 1.0
103 // z = butt(0); // z = 1/sqrt(2)
104 // z = butt(2.5); // z = 1/sqrt(2)
105 // z = butt(-25); // z ~ 9.24e-9 ~ 0
106 //
107 // // change the low-end cutoff to -25.0
108 // butt.setMinCutoff(-25);
109 // z = butt(-25); // z = 1/sqrt(2)
110 // </srcblock>
111 // </example>
112 //
113 // <motivation>
114 // This class was created to simulate systemtic Butterworth bandpasses
115 // within the simulator tool. It can used by the SimBJones class to vary the
116 // bandpass in a predictable way. However, it has limited value for real
117 // filter analysis, and it is not expected to be a realistic representation
118 // of real bandpass filters in use with radio telescopes backends.
119 // </motivation>
120 //
121 // <templating arg=T>
122 // <li> T should have standard numerical operators. Current
123 // implementation only tested for real types (and their AutoDiffs).
124 // </templating>
125 //
126 // <thrown>
127 // <li> Assertion if indices out-of-range
128 // </thrown>
129 //
130 // <todo asof="2001/11/14">
131 // <li> Nothing I know of
132 // </todo>
133 
134 template<class T>
136 {
137 public:
138  //# Enumerations
139  // Enumeration of the function parameters
141 
142  //# Constructors
143  // create a zero-th order (all-pass) Butterworth bandpass function.
145 
146  // create a Butterworth bandpass function.
147  SimButterworthBandpass(const uInt minord, const uInt maxord,
148  const T &mincut=T(-1), const T &maxcut=T(1),
149  const T &center=T(0), const T &peak=T(1));
150 
151  // create a fully specified Butterworth bandpass in which the
152  // low and high pass orders are stored in a Record
154  T mincut=T(-1), T maxcut=T(1),
155  T center=T(0), T peak=T(1));
156 
157  // create a copy of another Butterworth bandpass function
159 
160  // copy(deep) another Butterworth function
163 
164  // Destructor
166 
167 
168  //# Operators
169  // Evaluate the bandpass at "x".
170  virtual T eval(const typename FunctionTraits<T>::ArgType *x) const;
171 
172  //# Member functions
173  // set the center of the bandpass. This is the x-ordinate value that
174  // evaluates to the peak of the function.
175  void setCenter(const T &x) { param_p[CENTER] = x; }
176 
177  // return the center of the bandpass. This is the x-ordinate value that
178  // evaluates to the peak of the function.
179  const T &getCenter() const { return param_p[CENTER]; }
180 
181  // set the characteristic minimum (high-pass) cutoff value. At this
182  // x-ordinate value, the function has a value reduced 30 dB from its
183  // peak.
184  void setMinCutoff(const T &x) { param_p[MINCUTOFF] = x; }
185 
186  // set the characteristic maximum (low-pass) cutoff value. At this
187  // x-ordinate value, the function has a value reduced 30 dB from its
188  // peak.
189  void setMaxCutoff(const T &x) { param_p[MAXCUTOFF] = x; }
190 
191  // set the order of the Butterworth function for the minimum (high-pass)
192  // portion of the bandpass
193  void setMinOrder(uInt order) { nl_p = order; }
194 
195  // set the order of the Butterworth function for the maximum (low-pass)
196  // portion of the bandpass
197  void setMaxOrder(uInt order) { nh_p = order; }
198 
199  // return the characteristic minimum (high-pass) cutoff value. At this
200  // x-ordinate value, the function has a value reduced 30 dB from its
201  // peak.
202  const T &getMinCutoff() const { return param_p[MINCUTOFF]; }
203 
204  // return the characteristic maximum (low-pass) cutoff value. At this
205  // x-ordinate value, the function has a value reduced 30 dB from its
206  // peak.
207  const T &getMaxCutoff() const { return param_p[MAXCUTOFF]; }
208 
209  // return the order of the Butterworth function for the minimum (high-pass)
210  // portion of the bandpass
211  uInt getMinOrder() const { return nl_p; }
212 
213  // return the order of the Butterworth function for the maximum (low-pass)
214  // portion of the bandpass
215  uInt getMaxOrder() const { return nh_p; }
216 
217  // set the scale of the function by setting its peak value. By default,
218  // the peak value is T(1);
219  void setPeak(T val) { param_p[PEAK] = val; }
220 
221  // return the scale of the function
222  const T &getPeak() const { return param_p[PEAK]; }
223 
224  // get/set the function mode. This is an alternate way to get/set the
225  // non-coefficient data for this function. The supported record fields
226  // are as follows:
227  // <pre>
228  // Field Name Type Role
229  // -------------------------------------------------------------------
230  // minOrder TpInt the order of the Butterworth function for the
231  // minimum (high-pass) portion of the bandpass
232  // maxOrder TpInt the order of the Butterworth function for the
233  // maximum (low-pass) portion of the bandpass
234  // An exception is thrown if either value is less than zero
235  // </pre>
236  // <group>
237  virtual void setMode(const RecordInterface& mode);
238  virtual void getMode(RecordInterface& mode) const;
239  // </group>
240 
241  // return True if the implementing function supports a mode. This
242  // implementation always returns True.
243  virtual Bool hasMode() const;
244 
245  // clone this function
246  virtual Function<T> *clone() const {
247  return new SimButterworthBandpass<T>(*this);
248  }
249 
250 private:
251  //# Non-parameter Data
252  // Minimum order
254  // Maximum order
256 
257  //# Make members of parent classes known.
258 protected:
259  using Function<T>::param_p;
260 public:
262 };
263 
264 
265 } //# NAMESPACE CASACORE - END
266 
267 #ifndef CASACORE_NO_AUTO_TEMPLATES
268 #include <casacore/scimath/Functionals/SimButterworthBandpass.tcc>
269 #endif //# CASACORE_NO_AUTO_TEMPLATES
270 #endif
T ArgType
Type for arguments.
FunctionParam< T > param_p
The parameters and masks.
Definition: Function.h:332
virtual Bool hasMode() const
return True if the implementing function supports a mode.
const T & getPeak() const
return the scale of the 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.
void setMinCutoff(const T &x)
set the characteristic minimum (high-pass) cutoff value.
void setCenter(const T &x)
set the center of the bandpass.
void setMaxOrder(uInt order)
set the order of the Butterworth function for the maximum (low-pass) portion of the bandpass
void setMaxCutoff(const T &x)
set the characteristic maximum (low-pass) cutoff value.
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 R...
virtual void getMode(RecordInterface &mode) const
void setMinOrder(uInt order)
set the order of the Butterworth function for the minimum (high-pass) portion of the bandpass
SimButterworthBandpass()
create a zero-th order (all-pass) Butterworth bandpass function.
virtual T eval(const typename FunctionTraits< T >::ArgType *x) const
Evaluate the bandpass at "x".
const T & getMinCutoff() const
return the characteristic minimum (high-pass) cutoff value.
virtual ~SimButterworthBandpass()
Destructor.
const T & getCenter() const
return the center of the bandpass.
uInt getMinOrder() const
return the order of the Butterworth function for the minimum (high-pass) portion of the bandpass
void setPeak(T val)
set the scale of the function by setting its peak value.
const T & getMaxCutoff() const
return the characteristic maximum (low-pass) cutoff value.
SimButterworthBandpass< T > & operator=(const SimButterworthBandpass< T > &other)
copy(deep) another Butterworth function
virtual Function< T > * clone() const
clone this function
virtual void setMode(const RecordInterface &mode)
get/set the function mode.
SimButterworthBandpass(const SimButterworthBandpass &other)
create a copy of another Butterworth bandpass function
uInt getMaxOrder() const
return the order of the Butterworth function for the maximum (low-pass) portion of the bandpass
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42