LAL  7.1.7.1-56c71ae

Detailed Description

Transforms the complex frequency coordinate of a ZPG filter.

Author
Creighton, T. D.

Description

These functions perform an in-place bilinear transformation on an object *filter of type <datatype>ZPGFilter, transforming from \(w\) to \(z=(1+iw)/(1-iw)\). 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).

Algorithm

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{z-z_k}{z+1} \; , \]

and similarly, when transforming a pole at \(w_k\),

\[ (w - w_k)^{-1} = -(w_k + i)^{-1}\times\frac{z+1}{z-z_k} \; , \]

where \(z=(1+iw)/(1-iw)\) and \(z_k=(1+iw_k)/(1-iw_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 \((z-z_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 large-magnitude pairs. In this way one reduces the risk of overrunning the floating-point 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)/(1-iw)\), 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...
 

Function Documentation

◆ CompareCOMPLEX8Abs()

static int CompareCOMPLEX8Abs ( void UNUSED *  p,
const void *  a,
const void *  b 
)
static

Definition at line 112 of file BilinearTransform.c.

◆ CompareCOMPLEX16Abs()

static int CompareCOMPLEX16Abs ( void UNUSED *  p,
const void *  a,
const void *  b 
)
static

Definition at line 128 of file BilinearTransform.c.

◆ XLALWToZCOMPLEX8ZPGFilter()

int XLALWToZCOMPLEX8ZPGFilter ( COMPLEX8ZPGFilter filter)
See also
See Module BilinearTransform.c for documentation

Definition at line 140 of file BilinearTransform.c.

◆ XLALWToZCOMPLEX16ZPGFilter()

int XLALWToZCOMPLEX16ZPGFilter ( COMPLEX16ZPGFilter filter)
See also
See Module BilinearTransform.c for documentation

Definition at line 359 of file BilinearTransform.c.

◆ LALWToZCOMPLEX8ZPGFilter()

void LALWToZCOMPLEX8ZPGFilter ( LALStatus stat,
COMPLEX8ZPGFilter filter 
)

Deprecated.

Deprecated:
Use XLALWToZCOMPLEX8ZPGFilter() instead

Definition at line 583 of file BilinearTransform.c.

◆ LALWToZCOMPLEX16ZPGFilter()

void LALWToZCOMPLEX16ZPGFilter ( LALStatus stat,
COMPLEX16ZPGFilter filter 
)

Deprecated.

Deprecated:
Use XLALWToZCOMPLEX16ZPGFilter() instead

Definition at line 611 of file BilinearTransform.c.