Loading [MathJax]/extensions/TeX/AMSsymbols.js
LAL 7.7.0.1-8a6b96f
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
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)
26extern "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
124void
127 INT4 numZeros,
128 INT4 numPoles );
129
130void
133 INT4 numZeros,
134 INT4 numPoles );
135
136void
138 COMPLEX8ZPGFilter **input );
139
140void
142 COMPLEX16ZPGFilter **input );
143
144void
146 COMPLEX8ZPGFilter *filter );
147
148void
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 LALWToZCOMPLEX8ZPGFilter(LALStatus *status, COMPLEX8ZPGFilter *filter)
Deprecated.
int XLALWToZCOMPLEX8ZPGFilter(COMPLEX8ZPGFilter *filter)
void LALWToZCOMPLEX16ZPGFilter(LALStatus *status, COMPLEX16ZPGFilter *filter)
Deprecated.
int XLALWToZCOMPLEX16ZPGFilter(COMPLEX16ZPGFilter *filter)
void LALCreateCOMPLEX8ZPGFilter(LALStatus *status, COMPLEX8ZPGFilter **output, INT4 numZeros, INT4 numPoles)
void LALCreateCOMPLEX16ZPGFilter(LALStatus *status, COMPLEX16ZPGFilter **output, INT4 numZeros, INT4 numPoles)
COMPLEX16ZPGFilter * XLALCreateCOMPLEX16ZPGFilter(INT4 numZeros, INT4 numPoles)
COMPLEX8ZPGFilter * XLALCreateCOMPLEX8ZPGFilter(INT4 numZeros, INT4 numPoles)
void LALDestroyCOMPLEX16ZPGFilter(LALStatus *status, COMPLEX16ZPGFilter **input)
void LALDestroyCOMPLEX8ZPGFilter(LALStatus *status, COMPLEX8ZPGFilter **input)
void XLALDestroyCOMPLEX8ZPGFilter(COMPLEX8ZPGFilter *filter)
void XLALDestroyCOMPLEX16ZPGFilter(COMPLEX16ZPGFilter *filter)
int32_t INT4
Four-byte signed integer.
See DATATYPE-ZPGFilter types for details.
Definition: LALDatatypes.h:930
See DATATYPE-ZPGFilter types for details.
Definition: LALDatatypes.h:921
LAL status structure, see The LALStatus structure for more details.
Definition: LALDatatypes.h:947
void output(int gps_sec, int output_type)
Definition: tconvert.c:440