GNU Radio Manual and C++ API Reference 3.7.14.0
The Free & Open Software Radio Ecosystem
iir_filter.h
Go to the documentation of this file.
1/* -*- c++ -*- */
2/*
3 * Copyright 2002,2012 Free Software Foundation, Inc.
4 *
5 * This file is part of GNU Radio
6 *
7 * GNU Radio is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 3, or (at your option)
10 * any later version.
11 *
12 * GNU Radio is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with GNU Radio; see the file COPYING. If not, write to
19 * the Free Software Foundation, Inc., 51 Franklin Street,
20 * Boston, MA 02110-1301, USA.
21 */
22
23#ifndef INCLUDED_IIR_FILTER_H
24#define INCLUDED_IIR_FILTER_H
25
26#include <gnuradio/filter/api.h>
27#include <gnuradio/gr_complex.h>
28#include <stdexcept>
29#include <vector>
30
31namespace gr {
32namespace filter {
33namespace kernel {
34
35/*!
36 * \brief Base class template for Infinite Impulse Response filter (IIR)
37 *
38 * \details
39 *
40 * This class provides a templated kernel for IIR filters. These
41 * iir_filters can be instantiated with a set of feed-forward
42 * and feed-back taps in the constructor. We then call the
43 * iir_filter::filter function to add a new sample to the
44 * filter, or iir_filter::filter_n to add a vector of samples to
45 * be filtered.
46 *
47 * Instantiating a filter means defining the templates for the
48 * data types being processed by the filter. There are four templates:
49 *
50 * \li i_type the data type of the input data (i.e., float).
51 * \li o_type the data type of the output data (i.e., float).
52 * \li tap_type the data type of the filter taps (i.e., double).
53 * \li acc_type the data type of the internal accumulator (i.e., double).
54 *
55 * The acc_type is specified to control how data is handled
56 * internally in the filter. This should always be the highest
57 * precision data type of any of the first three. Often, IIR
58 * filters require double-precision values in the taps for
59 * stability, and so the internal accumulator should also be
60 * double precision.
61 *
62 * Example:
63 *
64 * \code
65 * gr::filter::kernel::iir_filter<float,float,double,double> iir_filt(fftaps, fbtaps);
66 * ...
67 * float y = iir_filt.filter(x);
68 *
69 * <or>
70 *
71 * iir_filt.filter(y, x, N); // y and x are float arrays
72 * \endcode
73 *
74 * Another example for handling complex samples with
75 * double-precision taps (see filter::iir_filter_ccz):
76 *
77 * \code
78 * gr:;filter::kernel::iir_filter<gr_complex, gr_complex, gr_complexd, gr_complexd>
79 * iir_filt(fftaps, fbtaps); \endcode
80 */
81template <class i_type, class o_type, class tap_type, class acc_type>
83{
84public:
85 /*!
86 * \brief Construct an IIR with the given taps.
87 *
88 * This filter uses the Direct Form I implementation, where
89 * \p fftaps contains the feed-forward taps, and \p fbtaps the feedback ones.
90 *
91 * \p oldstyle: The old style of the IIR filter uses feedback
92 * taps that are negative of what most definitions use (scipy
93 * and Matlab among them). This parameter keeps using the old
94 * GNU Radio style and is set to TRUE by default. When taps
95 * generated from scipy, Matlab, or gr_filter_design, use the
96 * new style by setting this to FALSE.
97 *
98 * When \p oldstyle is set FALSE, the input and output satisfy a
99 * difference equation of the form
100
101 \f[
102 y[n] + \sum_{k=1}^{M} a_k y[n-k] = \sum_{k=0}^{N} b_k x[n-k]
103 \f]
104
105 * with the corresponding rational system function
106
107 \f[
108 H(z) = \frac{\sum_{k=0}^{N} b_k z^{-k}}{1 + \sum_{k=1}^{M} a_k z^{-k}}
109 \f]
110 * where:
111 * \f$x\f$ - input signal,
112 * \f$y\f$ - output signal,
113 * \f$a_k\f$ - k-th feedback tap,
114 * \f$b_k\f$ - k-th feed-forward tap,
115 * \f$M\f$ - \p len(fbtaps)-1,
116 * \f$N\f$ - \p len(fftaps)-1.
117
118 * \f$a_0\f$, that is \p fbtaps[0], is ignored.
119 */
120 iir_filter(const std::vector<tap_type>& fftaps,
121 const std::vector<tap_type>& fbtaps,
122 bool oldstyle = true) throw(std::invalid_argument)
123 {
124 d_oldstyle = oldstyle;
125 set_taps(fftaps, fbtaps);
126 }
127
128 iir_filter() : d_latest_n(0), d_latest_m(0) {}
129
131
132 /*!
133 * \brief compute a single output value.
134 * \returns the filtered input value.
135 */
136 o_type filter(const i_type input);
137
138 /*!
139 * \brief compute an array of N output values.
140 * \p input must have N valid entries.
141 */
142 void filter_n(o_type output[], const i_type input[], long n);
143
144 /*!
145 * \return number of taps in filter.
146 */
147 unsigned ntaps_ff() const { return d_fftaps.size(); }
148 unsigned ntaps_fb() const { return d_fbtaps.size(); }
149
150 /*!
151 * \brief install new taps.
152 */
153 void set_taps(const std::vector<tap_type>& fftaps,
154 const std::vector<tap_type>& fbtaps) throw(std::invalid_argument)
155 {
156 d_latest_n = 0;
157 d_latest_m = 0;
158 d_fftaps = fftaps;
159
160 if (d_oldstyle) {
161 d_fbtaps = fbtaps;
162 } else {
163 // New style negates taps a[1:N-1] to fit with most IIR
164 // tap generating programs.
165 d_fbtaps.resize(fbtaps.size());
166 d_fbtaps[0] = fbtaps[0];
167 for (size_t i = 1; i < fbtaps.size(); i++) {
168 d_fbtaps[i] = -fbtaps[i];
169 }
170 }
171
172 int n = fftaps.size();
173 int m = fbtaps.size();
174 d_prev_input.clear();
175 d_prev_output.clear();
176 d_prev_input.resize(2 * n, 0);
177 d_prev_output.resize(2 * m, 0);
178 }
179
180protected:
182 std::vector<tap_type> d_fftaps;
183 std::vector<tap_type> d_fbtaps;
186 std::vector<acc_type> d_prev_output;
187 std::vector<i_type> d_prev_input;
188};
189
190//
191// general case. We may want to specialize this
192//
193template <class i_type, class o_type, class tap_type, class acc_type>
195{
196 acc_type acc;
197 unsigned i = 0;
198 unsigned n = ntaps_ff();
199 unsigned m = ntaps_fb();
200
201 if (n == 0)
202 return (o_type)0;
203
204 int latest_n = d_latest_n;
205 int latest_m = d_latest_m;
206
207 acc = d_fftaps[0] * input;
208 for (i = 1; i < n; i++)
209 acc += (d_fftaps[i] * d_prev_input[latest_n + i]);
210 for (i = 1; i < m; i++)
211 acc += (d_fbtaps[i] * d_prev_output[latest_m + i]);
212
213 // store the values twice to avoid having to handle wrap-around in the loop
214 d_prev_output[latest_m] = acc;
215 d_prev_output[latest_m + m] = acc;
216 d_prev_input[latest_n] = input;
217 d_prev_input[latest_n + n] = input;
218
219 latest_n--;
220 latest_m--;
221 if (latest_n < 0)
222 latest_n += n;
223 if (latest_m < 0)
224 latest_m += m;
225
226 d_latest_m = latest_m;
227 d_latest_n = latest_n;
228 return (o_type)acc;
229}
230
231template <class i_type, class o_type, class tap_type, class acc_type>
233 const i_type input[],
234 long n)
235{
236 for (int i = 0; i < n; i++)
237 output[i] = filter(input[i]);
238}
239
240template <>
243
244template <>
247
248template <>
250 const gr_complex input);
251
252} /* namespace kernel */
253} /* namespace filter */
254} /* namespace gr */
255
256#endif /* INCLUDED_IIR_FILTER_H */
Base class template for Infinite Impulse Response filter (IIR)
Definition: iir_filter.h:83
unsigned ntaps_ff() const
Definition: iir_filter.h:147
~iir_filter()
Definition: iir_filter.h:130
o_type filter(const i_type input)
compute a single output value.
Definition: iir_filter.h:194
std::vector< i_type > d_prev_input
Definition: iir_filter.h:187
iir_filter(const std::vector< tap_type > &fftaps, const std::vector< tap_type > &fbtaps, bool oldstyle=true)
Construct an IIR with the given taps.
Definition: iir_filter.h:120
std::vector< tap_type > d_fbtaps
Definition: iir_filter.h:183
unsigned ntaps_fb() const
Definition: iir_filter.h:148
std::vector< acc_type > d_prev_output
Definition: iir_filter.h:186
int d_latest_n
Definition: iir_filter.h:184
iir_filter()
Definition: iir_filter.h:128
void set_taps(const std::vector< tap_type > &fftaps, const std::vector< tap_type > &fbtaps)
install new taps.
Definition: iir_filter.h:153
std::vector< tap_type > d_fftaps
Definition: iir_filter.h:182
void filter_n(o_type output[], const i_type input[], long n)
compute an array of N output values. input must have N valid entries.
Definition: iir_filter.h:232
int d_latest_m
Definition: iir_filter.h:185
bool d_oldstyle
Definition: iir_filter.h:181
#define FILTER_API
Definition: gr-filter/include/gnuradio/filter/api.h:30
std::complex< float > gr_complex
Definition: gr_complex.h:27
Include this header to use the message passing features.
Definition: basic_block.h:45
STL namespace.