edu.mines.jtk.dsp
Class CausalFilter

java.lang.Object
  edu.mines.jtk.dsp.CausalFilter

public class CausalFilter
extends java.lang.Object

A multi-dimensional causal filter that is linear and shift-invariant. The output samples of a causal filter depend only on present and past input samples. In two dimensions, causal filters are also called non-symmetric half-plane (NSHP) filters, and this notion of causal can be extended to higher dimensions.

A causal filter is a linear operator with a corresponding anti-causal transpose (adjoint) operator. A causal filter may have a causal inverse, and its transpose may have an anti-causal inverse.

A causal filter is a stable all-zero filter that may or may not be minimum-phase; that is, it may or may not have a causal stable inverse. That inverse is a recursive all-pole filter, as described by Claerbout, J., 1998, Multidimensional recursive filters via a helix: Geophysics, v. 63, n. 5, p. 1532-1541.

The filter and its transpose, inverse, and inverse-transpose may all be applied in-place; that is, the input and output arrays may be the same array.

Version:

2007.01.15

Author:

Dave Hale, Colorado School of Mines

Constructor Summary

CausalFilter(int[] lag1)
Constructs a unit-impulse filter for specified lag1.

CausalFilter(int[] lag1, float[] a)
Constructs a causal filter for specified lag1.

CausalFilter(int[] lag1, int[] lag2)
Constructs a unit-impulse filter for specified lag1 and lag2.

CausalFilter(int[] lag1, int[] lag2, float[] a)
Constructs a causal filter for specified lag1 and lag2.

CausalFilter(int[] lag1, int[] lag2, int[] lag3)
Constructs a unit-impulse filter for specified lag1, lag2, and lag3.

CausalFilter(int[] lag1, int[] lag2, int[] lag3, float[] a)
Constructs a causal filter for specified lag1, lag2, and lag3.

Method Summary

void	apply(float[][][] x, float[][][] y) Applies this filter.
void	apply(float[][] x, float[][] y) Applies this filter.
void	apply(float[] x, float[] y) Applies this filter.
void	applyInverse(float[][][] y, float[][][] x) Applies the inverse of this filter.
void	applyInverse(float[][] y, float[][] x) Applies the inverse of this filter.
void	applyInverse(float[] y, float[] x) Applies the inverse of this filter.
void	applyInverseTranspose(float[][][] y, float[][][] x) Applies the inverse transpose of this filter.
void	applyInverseTranspose(float[][] y, float[][] x) Applies the inverse transpose of this filter.
void	applyInverseTranspose(float[] y, float[] x) Applies the inverse transpose of this filter.
void	applyTranspose(float[][][] x, float[][][] y) Applies the transpose of this filter.
void	applyTranspose(float[][] x, float[][] y) Applies the transpose of this filter.
void	applyTranspose(float[] x, float[] y) Applies the transpose of this filter.
void	factorWilsonBurg(int maxiter, float epsilon, float[] r) Wilson-Burg factorization for the specified 1-D auto-correlation.
void	factorWilsonBurg(int maxiter, float epsilon, float[][] r) Wilson-Burg factorization for the specified 2-D auto-correlation.
void	factorWilsonBurg(int maxiter, float epsilon, float[][][] r) Wilson-Burg factorization for the specified 3-D auto-correlation.
float[]	getA() Gets a copy of the filter coefficients.
int[]	getLag1() Gets a copy of the lags in the 1st dimension.
int[]	getLag2() Gets a copy of the lags in the 2nd dimension.
int[]	getLag3() Gets a copy of the lags in the 3rd dimension.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CausalFilter

public CausalFilter(int[] lag1)

Constructs a unit-impulse filter for specified lag1. By default, all lag2 and lag3 are assumed to be zero.

For j=0 only, lag1[j] is zero. All lag1[j] must be non-negative.

Parameters:

lag1 - array of lags.

CausalFilter

public CausalFilter(int[] lag1,
                    int[] lag2)

Constructs a unit-impulse filter for specified lag1 and lag2. By default, all lag3 are assumed to be zero.

For j=0 only, lag1[j] and lag2[j] are zero. All lag2[j] must be non-negative. If lag2[j] is zero, then lag1[j] must be non-negative.

Parameters:

lag1 - array of lags in 1st dimension.

lag2 - array of lags in 2nd dimension.

CausalFilter

public CausalFilter(int[] lag1,
                    int[] lag2,
                    int[] lag3)

Constructs a unit-impulse filter for specified lag1, lag2, and lag3.

For j=0 only, lag1[j] and lag2[j] and lag3[j] are zero. All lag3[j] must be non-negative. If lag3[j] is zero, then lag2[j] must be non-negative. If lag3[j] and lag2[j] are zero, then lag1[j] must be non-negative.

Parameters:

lag1 - array of lags in 1st dimension.

lag2 - array of lags in 2nd dimension.

lag3 - array of lags in 3rd dimension.

CausalFilter

public CausalFilter(int[] lag1,
                    float[] a)

Constructs a causal filter for specified lag1. By default, all lag2 and lag3 are assumed to be zero.

For j=0 only, lag1[j] is zero. All lag1[j] must be non-negative.

Parameters:

lag1 - array of lags.

a - array of filter coefficients for each lag.

CausalFilter

public CausalFilter(int[] lag1,
                    int[] lag2,
                    float[] a)

Constructs a causal filter for specified lag1 and lag2. By default, all lag3 are assumed to be zero.

For j=0 only, lag1[j] and lag2[j] are zero. All lag2[j] must be non-negative. If lag2[j] is zero, then lag1[j] must be non-negative.

Parameters:

lag1 - array of lags in 1st dimension.

lag2 - array of lags in 2nd dimension.

a - array of filter coefficients for each lag.

CausalFilter

public CausalFilter(int[] lag1,
                    int[] lag2,
                    int[] lag3,
                    float[] a)

Constructs a causal filter for specified lag1, lag2, and lag3.

For j=0 only, lag1[j] and lag2[j] and lag3[j] are zero. All lag3[j] must be non-negative. If lag3[j] is zero, then lag2[j] must be non-negative. If lag3[j] and lag2[j] are zero, then lag1[j] must be non-negative.

Parameters:

lag1 - array of lags in 1st dimension.

lag2 - array of lags in 2nd dimension.

lag3 - array of lags in 3rd dimension.

a - array of filter coefficients for each lag.

Method Detail

getLag1

public int[] getLag1()

Gets a copy of the lags in the 1st dimension.

Returns:

array of lags; by copy, not by reference.

getLag2

public int[] getLag2()

Gets a copy of the lags in the 2nd dimension.

Returns:

array of lags; by copy, not by reference.

getLag3

public int[] getLag3()

Gets a copy of the lags in the 3rd dimension.

Returns:

array of lags; by copy, not by reference.

getA

public float[] getA()

Gets a copy of the filter coefficients.

Returns:

array of filter coefficients; by copy, not by reference.

factorWilsonBurg

public void factorWilsonBurg(int maxiter,
                             float epsilon,
                             float[] r)

Wilson-Burg factorization for the specified 1-D auto-correlation. Modifies this filter using the iterative Wilson-Burg algorithm. If this algorithm converges, the impulse response of this filter cascaded with its transpose approximates the specified auto-correlation.

Parameters:

maxiter - maximum number of Wilson-Burg iterations.

epsilon - tolerance for convergence. Iterations have converged when the change in all filter coefficients is less than this factor times the square root of the zero-lag of the auto correlation.

r - the auto-correlation. This 1-D array must have odd length. The middle array element is the zero-lag of the auto-correlation, and other elements are symmetric about the middle element.

Throws:

java.lang.IllegalStateException - if Wilson-Burg iterations do not converge within the specified maximum number of iterations.

factorWilsonBurg

public void factorWilsonBurg(int maxiter,
                             float epsilon,
                             float[][] r)

Wilson-Burg factorization for the specified 2-D auto-correlation. Modifies this filter using the iterative Wilson-Burg algorithm. If this algorithm converges, the impulse response of this filter cascaded with its transpose approximates the specified auto-correlation.

Parameters:

maxiter - maximum number of Wilson-Burg iterations.

epsilon - tolerance for convergence. Iterations have converged when the change in all filter coefficients is less than this factor times the square root of the zero-lag of the auto correlation.

r - the auto-correlation. This 2-D array must have odd lengths. The middle array element is the zero-lag of the auto-correlation, and other elements are symmetric about the middle element.

Throws:

java.lang.IllegalStateException - if Wilson-Burg iterations do not converge within the specified maximum number of iterations.

factorWilsonBurg

public void factorWilsonBurg(int maxiter,
                             float epsilon,
                             float[][][] r)

Wilson-Burg factorization for the specified 3-D auto-correlation. Modifies this filter using the iterative Wilson-Burg algorithm. If this algorithm converges, the impulse response of this filter cascaded with its transpose approximates the specified auto-correlation.

Parameters:

maxiter - maximum number of Wilson-Burg iterations.

epsilon - tolerance for convergence. Iterations have converged when the change in all filter coefficients is less than this factor times the square root of the zero-lag of the auto correlation.

r - the auto-correlation. This 3-D array must have odd lengths. The middle array element is the zero-lag of the auto-correlation, and other elements are symmetric about the middle element.

Throws:

java.lang.IllegalStateException - if Wilson-Burg iterations do not converge within the specified maximum number of iterations.

apply

public void apply(float[] x,
                  float[] y)

Applies this filter. Uses lag1; ignores lag2 or lag3, if specified.

May be applied in-place; input and output arrays may be the same.

Parameters:

x - input array.

y - output array.

applyTranspose

public void applyTranspose(float[] x,
                           float[] y)

Applies the transpose of this filter. Uses lag1; ignores lag2 or lag3, if specified.

May be applied in-place; input and output arrays may be the same.

Parameters:

x - input array.

y - output array.

applyInverse

public void applyInverse(float[] y,
                         float[] x)

Applies the inverse of this filter. Uses lag1; ignores lag2 or lag3, if specified.

May be applied in-place; input and output arrays may be the same.

Parameters:

y - input array.

x - output array.

applyInverseTranspose

public void applyInverseTranspose(float[] y,
                                  float[] x)

Applies the inverse transpose of this filter. Uses lag1; ignores lag2 or lag3, if specified.

May be applied in-place; input and output arrays may be the same.

Parameters:

y - input array.

x - output array.

apply

public void apply(float[][] x,
                  float[][] y)

Applies this filter. Uses lag1 and lag2; ignores lag3, if specified.

May be applied in-place; input and output arrays may be the same.

Parameters:

x - input array.

y - output array.

applyTranspose

public void applyTranspose(float[][] x,
                           float[][] y)

Applies the transpose of this filter. Uses lag1 and lag2; ignores lag3, if specified.

May be applied in-place; input and output arrays may be the same.

Parameters:

x - input array.

y - output array.

applyInverse

public void applyInverse(float[][] y,
                         float[][] x)

Applies the inverse of this filter. Uses lag1 and lag2; ignores lag3, if specified.

May be applied in-place; input and output arrays may be the same.

Parameters:

y - input array.

x - output array.

applyInverseTranspose

public void applyInverseTranspose(float[][] y,
                                  float[][] x)

Applies the inverse transpose of this filter. Uses lag1 and lag2; ignores lag3, if specified.

May be applied in-place; input and output arrays may be the same.

Parameters:

y - input array.

x - output array.

apply

public void apply(float[][][] x,
                  float[][][] y)

Applies this filter. Uses lag1, lag2, and lag3.

May be applied in-place; input and output arrays may be the same.

Parameters:

x - input array.

y - output array.

applyTranspose

public void applyTranspose(float[][][] x,
                           float[][][] y)

Applies the transpose of this filter. Uses lag1, lag2, and lag3.

May be applied in-place; input and output arrays may be the same.

Parameters:

x - input array.

y - output array.

applyInverse

public void applyInverse(float[][][] y,
                         float[][][] x)

Applies the inverse of this filter. Uses lag1, lag2, and lag3.

Parameters:

y - output array.

x - input array.

May be applied in-place; input and output arrays may be the same.

applyInverseTranspose

public void applyInverseTranspose(float[][][] y,
                                  float[][][] x)

Applies the inverse transpose of this filter. Uses lag1, lag2, and lag3.

May be applied in-place; input and output arrays may be the same.

Parameters:

y - output array.

x - input array.