Engineering and Scientific Subroutine Library for AIX Version 3 Release 3: Guide and Reference

SWLEV, DWLEV, CWLEV, and ZWLEV--Wiener-Levinson Filter Coefficients

These subroutines compute the coefficients of an n-point Wiener-Levinson filter, using vector x, the trace for which the filter is to be designed, and vector u, the right-hand side of the system, chosen to remove reverberations or sharpen the wavelet. The result is returned in vector y.

Table 147. Data Types

Syntax

On Entry

x

is the vector x of length n, containing the trace data for which the filter is to be designed.

For SWLEV and DWLEV, x represents the first row (or the first column) of a positive definite or negative definite symmetric Toeplitz matrix, which is the autocorrelation matrix for which the filter is designed.

For CWLEV and ZWLEV, x represents the first row of a positive definite or negative definite complex Hermitian Toeplitz matrix, which is the autocorrelation matrix for which the filter is designed.

Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 147.

incx

is the stride for vector x. Specified as: a fullword integer; incx > 0.

u

is the vector u of length n, containing the right-hand side of the system to be solved. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incu|, containing numbers of the data type indicated in Table 147.

incu

is the stride for vector u. Specified as: a fullword integer. It can have any value.

y

See On Return.

incy

is the stride for vector y. Specified as: a fullword integer; incy > 0 or incy < 0.

n

is the number of elements in vectors x, u, and y. Specified as: a fullword integer; n >= 0.

aux

has the following meaning:

If naux = 0 and error 2015 is unrecoverable, aux is ignored.

Otherwise, it is the storage work area used by these subroutines.

Specified as: an area of storage of length naux, containing numbers of the data type indicated in Table 147.

naux

is the size of the work area specified by aux--that is, the number of elements in aux. Specified as: a fullword integer, where:

If naux = 0 and error 2015 is unrecoverable, SWLEV, DWLEV, CWLEV, and ZWLEV dynamically allocate the work area used by the subroutine. The work area is deallocated before control is returned to the calling program.

Otherwise, naux >= 3n.

You cannot use dynamic allocation if you need the information returned in AUX(1).

On Return

y

is the vector y of length n, containing the solution vector--that is, the coefficients of the n-point Wiener-Levinson filter. Returned as: a one-dimensional array of (at least) length 1+(n-1)|incy|, containing numbers of the data type indicated in Table 147.

aux

is the storage work area used by these subroutines, where if naux <> 0:

If AUX(1) = 0.0, the input Toeplitz matrix is positive definite or negative definite.

If AUX(1) > 0.0, the input Toeplitz matrix is indefinite (that is, it is not positive definite and it is not negative definite). The value returned in AUX(1) is the order of the first submatrix of A that is indefinite. The subroutine continues processing. See reference [62] for information about under what circumstances your solution vector y would be valid.

All other values in aux are overwritten and are not significant.

Returned as: an area of storage of length naux, containing numbers of the data type indicated in Table 147, where AUX(1)>=0.0.

Notes

1. For a description of a positive definite or negative definite symmetric Toeplitz matrix, see Positive Definite or Negative Definite Symmetric Toeplitz Matrix.
2. For a description of a positive definite or negative definite complex Hermitian Toeplitz matrix, see Positive Definite or Negative Definite Complex Hermitian Toeplitz Matrix.
3. You have the option of having the minimum required value for naux dynamically returned to your program. For details, see Using Auxiliary Storage in ESSL.

Function

The computation of the coefficients of an n-point Wiener-Levinson filter in vector y is expressed as solving the following system:

Ay = u

where:

• For SWLEV and DWLEV, matrix A is a real symmetric Toeplitz matrix whose first row (or first column) is represented by vector x.

  For CWLEV and ZWLEV, matrix A is a complex Hermitian Toeplitz matrix whose first row is represented by vector x.

• u is the vector specifying the right side of the system, chosen to remove reverberations or to sharpen the wavelet.
• y is the solution vector.

See reference [62], [27], and the IBM 3838 Array Processor Functional Characteristics.

If n is 0, no computation is performed. For SWLEV and CWLEV, intermediate results are accumulated in long precision.

SWLEV provides the same function as the IBM 3838 function WLEV, with restrictions removed. See the IBM 3838 Array Processor Functional Characteristics manual.

Error Conditions

Resource Errors

Error 2015 is unrecoverable, naux = 0, and unable to allocate work area.

Computational Errors

None

Input-Argument Errors

1. n < 0
2. incx <= 0
3. incy = 0
4. Error 2015 is recoverable or naux<>0, and naux is too small--that is, less than the minimum required value specified in the syntax for this argument. Return code 1 is returned if error 2015 is recoverable.

Example 1

This example shows how to compute filter coefficients in vector y by solving the system Ay = u. Matrix A is:

                     *                        *
                     | 50.0  -8.0   7.0  -5.0 |
                     | -8.0  50.0  -8.0   7.0 |
                     |  7.0  -8.0  50.0  -8.0 |
                     | -5.0   7.0  -8.0  50.0 |
                     *                        *

This input Toeplitz matrix is positive definite, as indicated by the zero value in AUX(1) on output.

Call Statement and Input

            X  INCX  U  INCU  Y  INCY  N   AUX  NAUX
            |   |    |   |    |   |    |    |    |
CALL SWLEV( X , 1  , U , 1  , Y , 1  , 4 , AUX , 12 )

Output

Y        =  (0.7667, -0.0663, 0.5745, 0.5778)
AUX      =  (0.0, . , . , . , . , . , . , . , . , . , . , . )

Example 2

This example shows how to compute filter coefficients in vector y by solving the system Ay = u. Matrix A is:

                        *                        *
                        | 10.0  -8.0   7.0  -5.0 |
                        | -8.0  10.0  -8.0   7.0 |
                        |  7.0  -8.0  10.0  -8.0 |
                        | -5.0   7.0  -8.0  10.0 |
                        *                        *

This input Toeplitz matrix is not positive definite, as indicated by the zero value in AUX(1) on output.

Call Statement and Input

            X  INCX  U  INCU  Y  INCY  N   AUX  NAUX
            |   |    |   |    |   |    |    |    |
CALL SWLEV( X , 1  , U , 1  , Y , 1  , 4 , AUX , 12 )

Output

Y        =  (5.1111, 5.5555, 12.2222, 10.4444)
AUX      =  (0.0, . , . , . , . , . , . , . , . , . , . , . )

Example 3

This example shows a vector x with a stride greater than 1, a vector u with a negative stride, and a vector y with a stride of 1. It uses the same input Toeplitz matrix as in Example 2, which is not positive definite.

Call Statement and Input

            X  INCX  U  INCU  Y  INCY  N   AUX  NAUX
            |   |    |    |   |   |    |    |    |
CALL SWLEV( X , 2  , U , -2 , Y , 1  , 4 , AUX , 12 )

Output

Y        =  (5.1111, 5.5555, 12.2222, 10.4444)
AUX      =  (0.0, . , . , . , . , . , . , . , . , . , . , . )

Example 4

This example shows how to compute filter coefficients in vector y by solving the system Ay = u. Matrix A is:

           *                                                      *
           |  (10.0, 0.0)   (2.0, -3.0)  (-3.0, 1.0)   (1.0, 1.0) |
           |   (2.0, 3.0)   (10.0, 0.0)  (2.0, -3.0)  (-3.0, 1.0) |
           | (-3.0, -1.0)    (2.0, 3.0)  (10.0, 0.0)  (2.0, -3.0) |
           |  (1.0, -1.0)  (-3.0, -1.0)   (2.0, 3.0)  (10.0, 0.0) |
           *                                                      *

This input complex Hermitian Toeplitz matrix is positive definite, as indicated by the zero value in AUX(1) on output.

Call Statement and Input

            X  INCX  U  INCU  Y  INCY  N   AUX  NAUX
            |   |    |   |    |   |    |    |    |
CALL ZWLEV( X , 1  , U , 1  , Y , 1  , 4 , AUX , 12 )

Output

Y        =  ((1.0, 0.0), (3.0, 0.0), (5.0, 0.0), (7.0, 0.0))
AUX      =  ((0.0, 0.0), . , . , . , . , . , . , . , . , . , . , . )

Example 5

This example shows a vector x with a stride greater than 1, a vector u with a negative stride, and a vector y with a stride of 1. It uses the same input complex Hermitian Toeplitz matrix as in Example 4.

This input complex Hermitian Toeplitz matrix is positive definite, as indicated by the zero value in AUX(1) on output.

Call Statement and Input

            X  INCX  U  INCU   Y  INCY  N   AUX  NAUX
            |   |    |    |    |   |    |    |    |
CALL ZWLEV( X , 2  , U , -2  , Y , 1  , 4 , AUX , 12 )

Output

Y        =  ((1.0, 0.0), (3.0, 0.0), (5.0, 0.0), (7.0, 0.0))
AUX      =  ((0.0, 0.0), . , . , . , . , . , . , . , . , . , . , . )