LAL  7.2.0.1-a5e7375
ZPGFilter.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2007 Jolien Creighton, Teviet Creighton
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with with program; see the file COPYING. If not, write to the
16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
17 * MA 02110-1301 USA
18 */
19 
20 #ifndef _ZPGFILTER_H
21 #define _ZPGFILTER_H
22 
23 #include <lal/LALStdlib.h>
24 
25 #if defined(__cplusplus)
26 extern "C" {
27 #elif 0
28 } /* so that editors will match preceding brace */
29 #endif
30 
31 /**
32  * \defgroup ZPGFilter_h Header ZPGFilter.h
33  * \ingroup lal_tdfilter
34  * \author Creighton, T. D.
35  *
36  * \brief Provides routines to manipulate ZPG filters.
37  *
38  * ### Synopsis ###
39  *
40  * \code
41  * #include <lal/ZPGFilter.h>
42  * \endcode
43  *
44  * The \ref ZPGFilter_h provides routines for manipulating filters in
45  * the ``zeros, poles, gain'' representation, which is typically the
46  * simplest way of representing a filter response. These routines
47  * create and destroy ZPG filters, and can transform the complex
48  * variable used to represent them.
49  *
50  * This header covers routines that create, destroy, and
51  * transform objects of type <tt><datatype>ZPGFilter</tt>, where
52  * <tt><datatype></tt> is either \c COMPLEX8 or \c COMPLEX16.
53  * Generically, these data types can be used to store any rational
54  * complex function in a factored form. Normally this function is a
55  * filter response, or "transfer function" \f$T(z)\f$, expressed in terms
56  * of a complex frequency parameter \f$z=\exp(2\pi if\Delta t)\f$, where
57  * \f$\Delta t\f$ is the sampling interval. The rational function is
58  * factored as follows:
59  * \f[
60  * T(f) = g\times\frac{\prod_k (z-a_k)}{\prod_l (z-b_l)}
61  * \f]
62  * where \f$g\f$ is the gain, \f$a_k\f$ are the (finite) zeros, and \f$b_l\f$ are the
63  * (finite) poles. It should be noted that rational functions always
64  * have the same number of zeros as poles if one includes the point
65  * \f$z=\infty\f$; any excess in the number of finite zeros or poles in the
66  * rational expression simply indicates that there is a corresponding
67  * pole or zero of that order at infinity. It is also worth pointing out
68  * that the "gain" is just the overall prefactor of this rational
69  * function, and is not necessarily equal to the actual gain of the
70  * transfer function at any particular frequency.
71  *
72  * Another common complex frequency space is the \f$w\f$-space, obtained
73  * from the \f$z\f$-space by the bilinear transformation:
74  * \f[
75  * w = i\left(\frac{1-z}{1+z}\right) = \tan(\pi f\Delta t) , \quad
76  * z = \frac{1+iw}{1-iw} \; .
77  * \f]
78  * Other variables can also be used to represent the complex frequency
79  * plane. The <tt><datatype>ZPGFilter</tt> structure can be used to
80  * represent the transfer function in any of these spaces by transforming
81  * the coordinates of the zeros and poles, and incorporating any residual
82  * factors into the gain. Care must be taken to include any zeros or
83  * poles that are brought in from infinity by the transformation, and to
84  * remove any zeros or poles which were sent to infinity. Thus the
85  * number of zeros and poles of the <tt><datatype>ZPGFilter</tt> is not
86  * necessarily constant under transformations! Routines invoking the
87  * <tt><datatype>ZPGFilter</tt> data types should document which complex
88  * variable is assumed.
89  *
90  */
91 /** @{ */
92 
93 /**
94  * @{
95  * \defgroup CreateZPGFilter_c Module CreateZPGFilter.c
96  * \defgroup DestroyZPGFilter_c Module DestroyZPGFilter.c
97  * \defgroup BilinearTransform_c Module BilinearTransform.c
98  * @}
99  */
100 
101 /** \name Error Codes */
102 /** @{ */
103 #define ZPGFILTERH_ENUL 1 /**< Unexpected null pointer in arguments */
104 #define ZPGFILTERH_EOUT 2 /**< Output handle points to a non-null pointer */
105 #define ZPGFILTERH_EMEM 3 /**< Memory allocation error */
106 #define ZPGFILTERH_EBAD 4 /**< Bad filter parameters */
107 /** @} */
108 /** @} */
109 
110 #define ZPGFILTERH_MSGENUL "Unexpected null pointer in arguments"
111 #define ZPGFILTERH_MSGEOUT "Output handle points to a non-null pointer"
112 #define ZPGFILTERH_MSGEMEM "Memory allocation error"
113 #define ZPGFILTERH_MSGEBAD "Bad filter parameters"
114 
115 
116 /* ---------- Function prototypes. ---------- */
123 
124 void
127  INT4 numZeros,
128  INT4 numPoles );
129 
130 void
133  INT4 numZeros,
134  INT4 numPoles );
135 
136 void
138  COMPLEX8ZPGFilter **input );
139 
140 void
142  COMPLEX16ZPGFilter **input );
143 
144 void
146  COMPLEX8ZPGFilter *filter );
147 
148 void
150  COMPLEX16ZPGFilter *filter );
151 
152 #if 0
153 { /* so that editors will match succeeding brace */
154 #elif defined(__cplusplus)
155 }
156 #endif
157 
158 #endif /* _ZPGFILTER_H */
void XLALDestroyCOMPLEX8ZPGFilter(COMPLEX8ZPGFilter *filter)
int XLALWToZCOMPLEX16ZPGFilter(COMPLEX16ZPGFilter *filter)
void LALDestroyCOMPLEX8ZPGFilter(LALStatus *status, COMPLEX8ZPGFilter **input)
void LALCreateCOMPLEX16ZPGFilter(LALStatus *status, COMPLEX16ZPGFilter **output, INT4 numZeros, INT4 numPoles)
int XLALWToZCOMPLEX8ZPGFilter(COMPLEX8ZPGFilter *filter)
See DATATYPE-ZPGFilter types for details.
Definition: LALDatatypes.h:930
See DATATYPE-ZPGFilter types for details.
Definition: LALDatatypes.h:921
void output(int gps_sec, int output_type)
Definition: tconvert.c:432
void LALWToZCOMPLEX8ZPGFilter(LALStatus *status, COMPLEX8ZPGFilter *filter)
Deprecated.
void LALWToZCOMPLEX16ZPGFilter(LALStatus *status, COMPLEX16ZPGFilter *filter)
Deprecated.
void LALCreateCOMPLEX8ZPGFilter(LALStatus *status, COMPLEX8ZPGFilter **output, INT4 numZeros, INT4 numPoles)
LAL status structure, see The LALStatus structure for more details.
Definition: LALDatatypes.h:947
COMPLEX16ZPGFilter * XLALCreateCOMPLEX16ZPGFilter(INT4 numZeros, INT4 numPoles)
void LALDestroyCOMPLEX16ZPGFilter(LALStatus *status, COMPLEX16ZPGFilter **input)
int32_t INT4
Four-byte signed integer.
void XLALDestroyCOMPLEX16ZPGFilter(COMPLEX16ZPGFilter *filter)
COMPLEX8ZPGFilter * XLALCreateCOMPLEX8ZPGFilter(INT4 numZeros, INT4 numPoles)