casacore
Loading...
Searching...
No Matches
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
37namespace 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
134template<class T>
136{
137public:
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
250private:
251 //# Non-parameter Data
252 // Minimum order
254 // Maximum order
256
257 //# Make members of parent classes known.
258protected:
259 using Function<T>::param_p;
260public:
261 using Function<T>::nparameters;
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
FunctionParam< T > param_p
The parameters and masks.
Definition Function.h:332
uInt nparameters() const
Returns the number of parameters.
Definition Function.h:230
virtual Bool hasMode() const
return True if the implementing function supports a mode.
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.
const T & getMaxCutoff() const
return the characteristic maximum (low-pass) cutoff value.
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.
uInt getMinOrder() const
return the order of the Butterworth function for the minimum (high-pass) portion of the bandpass
const T & getCenter() const
return the center of the bandpass.
void setPeak(T val)
set the scale of the function by setting its peak value.
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
const T & getPeak() const
return the scale of the function
SimButterworthBandpass< T > & operator=(const SimButterworthBandpass< T > &other)
copy(deep) another Butterworth 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