Transforms the complex frequency coordinate of a ZPG filter.
These functions perform an inplace bilinear transformation on an object *filter
of type <datatype>ZPGFilter
, transforming from \(w\) to \(z=(1+iw)/(1iw)\). Care is taken to ensure that zeros and poles at \(w=\infty\) are correctly transformed to \(z=1\), and zeros and poles at \(w=i\) are correctly transformed to \(z=\infty\). In addition to simply relocating the zeros and poles, residual factors are also incorporated into the gain of the filter (i.e. the leading coefficient of the rational function).
The vectors filter>zeros
and filter>poles
only record those zeros and poles that have finite value. If one includes the point \(\infty\) on the complex plane, then a rational function always has the same number of zeros and poles: a number num
that is the larger of z>zeros>length
or z>poles>length
. If one or the other vector has a smaller length, then after the transformation that vector will receive additional elements, with a complex value of \(z=1\), to bring its length up to num
. However, each vector will then lose those elements that previously had values \(w=i\), (which are sent to \(z=\infty\),) thus possibly decreasing the length of the vector. These routines handle this by simply allocating a new vector for the transformed data, and freeing the old vector after the transformation.
When transforming a zero \(w_k\) on the complex plane, one makes use of the identity:
\[ (w  w_k) = (w_k + i)\times\frac{zz_k}{z+1} \; , \]
and similarly, when transforming a pole at \(w_k\),
\[ (w  w_k)^{1} = (w_k + i)^{1}\times\frac{z+1}{zz_k} \; , \]
where \(z=(1+iw)/(1iw)\) and \(z_k=(1+iw_k)/(1iw_k)\). If there are an equal number of poles and zeros being transformed, then the factors of \(z+1\) will cancel; otherwise, the remaining factors correspond to the zeros or poles at \(z=1\) brought in from \(w=\infty\). The factor \((zz_k)\) represents the new position of the transformed zero or pole. The important factor to note, though, is the factor \((w_k+i)^{\pm1}\). This factor represents the change in the gain filter>gain
. When \(w_k=i\), the transformation is slightly different:
\[ (w + i) = \frac{2i}{z+1} \; ; \]
thus the gain correction factor is \(2i\) (rather than 0) in this case.
The algorithm in this module computes and stores all the gain correction factors before applying them to the gain. The correction factors are sorted in order of absolute magnitude, and are multiplied together in small and largemagnitude pairs. In this way one reduces the risk of overrunning the floatingpoint dynamical range during intermediate calculations.
As a similar precaution, the routines in this module use the algorithm discussed in the VectorOps
package whenever they perform complex division, to avoid intermediate results that may be the product of two large numbers. When transforming \(z=(1+iw)/(1iw)\), these routines also test for special cases (such as \(w\) purely imaginary) that have qualitatively significant results ( \(z\) purely real), so that one doesn't end up with, for instance, an imaginary part of \(10^{12}\) instead of 0.
Prototypes  
static int  CompareCOMPLEX8Abs (void UNUSED *p, const void *a, const void *b) 
static int  CompareCOMPLEX16Abs (void UNUSED *p, const void *a, const void *b) 
int  XLALWToZCOMPLEX8ZPGFilter (COMPLEX8ZPGFilter *filter) 
int  XLALWToZCOMPLEX16ZPGFilter (COMPLEX16ZPGFilter *filter) 
void  LALWToZCOMPLEX8ZPGFilter (LALStatus *stat, COMPLEX8ZPGFilter *filter) 
Deprecated. More...  
void  LALWToZCOMPLEX16ZPGFilter (LALStatus *stat, COMPLEX16ZPGFilter *filter) 
Deprecated. More...  

static 
Definition at line 112 of file BilinearTransform.c.

static 
Definition at line 128 of file BilinearTransform.c.
int XLALWToZCOMPLEX8ZPGFilter  (  COMPLEX8ZPGFilter *  filter  ) 
Definition at line 140 of file BilinearTransform.c.
int XLALWToZCOMPLEX16ZPGFilter  (  COMPLEX16ZPGFilter *  filter  ) 
Definition at line 359 of file BilinearTransform.c.
void LALWToZCOMPLEX8ZPGFilter  (  LALStatus *  stat, 
COMPLEX8ZPGFilter *  filter  
) 
Deprecated.
Definition at line 583 of file BilinearTransform.c.
void LALWToZCOMPLEX16ZPGFilter  (  LALStatus *  stat, 
COMPLEX16ZPGFilter *  filter  
) 
Deprecated.
Definition at line 611 of file BilinearTransform.c.