diamondback.filters package — diamondback documentation

# diamondback.filters package

## Submodules

## diamondback.filters.ComplexBandPassFilter module

Description

  A complex band pass filter produces a complex exponential incident signal at a specified normalized frequency and adapts a forward complex coefficient to produce a reference signal, which estimates a component of interest in a primary signal. A normalized frequency and rate of adaptation are specified.

  \[x_{n} = e^{\ j\ \pi\ \phi_{n}}\]
  \[\phi_{n+1} = \phi_{n} + f_{n}\]
  \[y_{n} = b_{n} x_{n}\]
  \[e_{n} = d_{n} - y_{n}\]
  \[b_{n+1} = b_{n} + \mu e_{n} x_{n}^{*}\]

Example

>     from diamondback import ComplexBandPassFilter, ComplexExponentialFilter
>     import numpy

>     frequency = 0.1
>     x = numpy.linspace( -1.0e-4, 1.0e-4, 128 ) + frequency

>     # Create a primary signal.

>     d = ComplexExponentialFilter( phase = numpy.random.rand( 1 )[ 0 ] * 2.0 - 1.0 ).filter( x )

>     # Create an instance.

>     obj = ComplexBandPassFilter( frequency = frequency, rate = 5.0e-2 )

>     # Filter a primary signal.

>     obj.reset( d[ 0 ] )
>     y, e, b = obj.filter( d )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-01-31.

class diamondback.filters.ComplexBandPassFilter.ComplexBandPassFilter(frequency: float, rate: float)

  Bases: `diamondback.filters.FirFilter.FirFilter`

  Complex band pass filter.

  Initialize.

  Arguments :

    frequency : float - relative to Nyquist in [ -1.0, 1.0 ). rate : float - in [ 0.0, 1.0 ].

  property frequency

    float - relative to Nyquist in [ -1.0, 1.0 ].

    Type

      frequency

  property rate

    float - in [ 0.0, 1.0 ].

    Type

      rate

  filter(d: Union[List, numpy.ndarray]) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

    Filters a primary signal and produces a reference signal.

    Signals are Hilbert transformed to complex as necessary.

    Arguments :

      d : Union[ List, numpy.ndarray ] - primary signal.

    Returns :

      y : numpy.ndarray - reference signal. e : numpy.ndarray - error signal. b : numpy.ndarray - forward coefficient.

## diamondback.filters.ComplexExponentialFilter module

Description

  A complex exponential filter produces a complex exponential reference signal from an incident signal equal to a specified normalized frequency. A normalized phase is specified.

  \[x_{n} = f_{n}\]
  \[\phi_{n} = \phi_{n-1} + x_{n}\]
  \[y_{n} = e^{\ j\ \pi\ \phi_{n}}\]

Example

>     from diamondback import ComplexExponentialFilter
>     import numpy

>     # Create an instance.

>     obj = ComplexExponentialFilter( phase = 0.0 )

>     # Filter an incident signal.

>     x = numpy.linspace( -1.0e-4, 1.0e-4, 128 ) + 0.1
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-01-31.

class diamondback.filters.ComplexExponentialFilter.ComplexExponentialFilter(phase: float = 0.0)

  Bases: `object`

  Complex exponential filter.

  Initialize.

  Arguments :

    phase : float - relative to pi in [ -1.0, 1.0 ].

  property phase

    float - relative to pi in [ -1.0, 1.0 ].

    Type

      phase

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal frequency relative to Nyquist in [ -1.0, 1.0 ).

    Returns :

      y : numpy.ndarray - reference signal.

## diamondback.filters.ComplexFrequencyFilter module

Description

  A complex frequency filter adapts and discriminates the phase of a forward complex coefficient to produce a reference signal, which estimates a normalized frequency of a primary signal which is normalized to unity magnitude. A normalized frequency and rate of adaptation are specified.

  \[f_{n} = \frac{\tan^{-1}(\ b_{n}\ ) }{\pi}\]
  \[x_{n} = \frac{d_{n}}{|\ d_{n}\ |}\]
  \[y_{n} = b_{n} x_{n-1}\]
  \[e_{n} = d_{n} - y_{n}\]
  \[b_{0} = e^{\ j\ \pi\ f_{0}}\]
  \[b_{n} = b_{n} + \mu e_{n} x_{n}^{*}\]

Example

>     from diamondback import ComplexExponentialFilter
>     import numpy

>     x = numpy.linspace( 0.0, 0.1, 128 )

>     # Create a primary signal.

>     d = ComplexExponentialFilter( 0.0 ).filter( x )

>     # Create an instance.

>     obj = ComplexFrequencyFilter( frequency = 0.0, rate = 0.1 )

>     # Filter a primary signal.

>     obj.reset( d[ 0 ] )
>     y, e, b = obj.filter( d )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-02-01.

class diamondback.filters.ComplexFrequencyFilter.ComplexFrequencyFilter(frequency: float, rate: float)

  Bases: `diamondback.filters.FirFilter.FirFilter`

  Complex frequency filter.

  Initialize.

  Arguments :

    frequency : float - relative to Nyquist in [ -1.0, 1.0 ). rate : float - in [ 0.0, 1.0 ].

  property frequency

    float - relative to Nyquist in [ -1.0, 1.0 ].

    Type

      frequency

  property rate

    float - in [ 0.0, 1.0 ].

    Type

      rate

  filter(d: Union[List, numpy.ndarray]) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

    Filters a primary signal and produces a reference signal.

    Signals are Hilbert transformed to complex as necessary.

    Arguments :

      d : Union[ List, numpy.ndarray ] - primary signal.

    Returns :

      y : numpy.ndarray - reference signal. e : numpy.ndarray - error signal. b : numpy.ndarray - forward coefficient.

  reset(x: complex) → None

    Modifies a state to minimize edge effects by assuming persistent operation at a specified primary incident condition.

    Arguments :

      x : complex - incident signal.

## diamondback.filters.DerivativeFilter module

Description

  A derivative filter realizes a discrete difference equation which approximates a discrete derivative as a function of a forward coefficient array and a state array of a specified order, consuming an incident signal and producing a reference signal. A derivative is approximated relative to a sample. A derivative is electively approximated relative to a second by multiplying a reference signal by an absolute sampling frequency raised to a derivative power.

  \[y_{n} = \sum_{i = 0}^{N} b_{i} x_{n-i} = \sum_{i = 1}^{N} b_{i} s_{i,n} + b_{0} x_{n} s_{1,n+1} = x_{n}\qquad\quad s_{i,n+1} = s_{i-1,n}\]

  A frequency response is expressed as a function of a forward coefficient array.

  \[H_{z} = \sum_{i = 0}^{N} b_{i} z^{-i}\]

  A forward coefficient array and a state array of a specified order are defined, to satisfy specified constraints. A derivative, and order are specified.

  \[y_{n} = f^{D}\ \frac{x_{n}}{D}\quad\quad\quad\quad\scriptsize{ f = 1.0 }\]
  \[b_{1,1} = \scriptsize{ [ \matrix{ 1 & -1 } ] }\]
  \[b_{1,2} = \scriptsize{ [ \matrix{ 1 & 0 & -1 } ]\ \frac{1}{2} }\]
  \[b_{1,4} = \scriptsize{ [ \matrix{ -1 & 8 & 0 & -8 & 1 } ]\ \frac{1}{12} }\]
  \[b_{2,2} = \scriptsize{ [ \matrix{ 1 & -2 & 1 } ] }\]
  \[b_{2,4} = \scriptsize{ [ \matrix{ 1 & 0 & -2 & 0 & 1 } ]\ \frac{1}{4} }\]
  \[b_{2,6} = \scriptsize{ [ \matrix{ -1 & 8 & 1 & -16 & 1 & 8 & -1 } ]\ \frac{1}{24} }\]
  \[b_{2,8} = \scriptsize{ [ \matrix{ 1 & -16 & 64 & 16 & -130 & 16 & 64 & -16 & 1 } ]\ \frac{1}{144} }\]
  \[b_{3,4} = \scriptsize{ [ \matrix{ 1 & -2 & 0 & 2 & -1 } ]\ \frac{1}{2} }\]
  \[b_{3,6} = \scriptsize{ [ \matrix{ 1 & 0 & -3 & 0 & 3 & 0 & 1 } ]\ \frac{1}{8} }\]
  \[b_{3,8} = \scriptsize{ [ \matrix{ -1 & 8 & 2 & -24 & 0 & 24 & -2 & -8 & 1 } ]\ \frac{1}{48} }\]

Example

>     from diamondback import ComplexExponentialFilter, DerivativeFilter
>     import numpy

>     # Create an instance.

>     obj = DerivativeFilter( derivative = 1, order = 2 )

>     # Filter an incident signal.

>     x = ComplexExponentialFilter( 0.0 ).filter( numpy.ones( 128 ) * 0.1 ).real
>     obj.reset( x[ 0 ] )
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-02-06.

class diamondback.filters.DerivativeFilter.DerivativeFilter(derivative: int, order: int)

  Bases: `diamondback.filters.FirFilter.FirFilter`

  Derivative filter.

  Initialize.

  Arguments :

    derivative : int - in [ 1, 3 ]. order : int.

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

## diamondback.filters.FirFilter module

Description

  A Finite Impulse Response ( FIR ) filter realizes a discrete difference equation as a function of a forward coefficient array and a state array of a specified order, consuming an incident signal and producing a reference signal.

  \[y_{n} = \sum_{i = 0}^{N} b_{i,n} x_{n-i} = \sum_{i = 1}^{N} b_{i,n} s_{i,n} + b_{0,n} x_{n}\]
  \[s_{1,n+1} = x_{n}\qquad\quad s_{i,n+1} = s_{i-1,n}\]

  A reset may minimize edge effects at a discontinuity by assuming persistent operation at a specified incident signal condition.

  \[s_{i,n} = x_{n}\]

  A frequency response is expressed as a function of a forward coefficient array.

  \[H_{z,n} = \sum_{i = 0}^{N} b_{i,n} z^{-i}\]

  A forward coefficient array and state array of a specified order are defined to realize specified constraints. A style, frequency, order, count, complement, and gain are electively specified. Alternatively, a forward coefficient array and state array may be explicitly defined to ignore constraints.

  Frequency corresponds to a -3 dB frequency response normalized relative to Nyquist.

  Style is in ( ‘Blackman’, ‘Hamming’, ‘Hann’, ‘Kaiser’ ).

  - ‘Blackman’ filters demonstrate low resolution and spectral leakage
    with improved rate of attenuation.
  - ‘Hamming’ filters demonstrate minimal nearest side lobe magnitude
    response.
  - ‘Hann’ filters demonstrate high resolution and spectral leakage.
  - ‘Kaiser’ filters demonstrate flexible resolution and spectral
    leakage dependent upon a beta value of a Bessel function of the
    first kind, with beta equal to 7.0.

  Order must even to ensure a Type I form linear phase solution.

  Count is a quantity of filters of a specified order concatenated to form an aggregate frequency response in cascade form.

  Complement effectively constructs a mirror image of a specified frequency response.

Example

>     from diamondback import FirFilter
>     import numpy

>     # Create an instance with constraints.

>     obj = FirFilter( style = 'Kaiser', frequency = 0.1, order = 32, count = 1 )

>     # Create an instance with coefficients.

>     obj = FirFilter( b = obj.b )

>     # Estimate frequency response, group delay, and roots.

>     y, f = obj.response( length = 8192, count = 1 )
>     y, f = obj.delay( length = 8192, count = 1 )
>     p, z = obj.roots( count = 1 )

>     # Filter an incident signal.

>     x = numpy.random.rand( 128 ) * 2.0 - 1.0
>     obj.reset( x[ 0 ] )
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-01-23.

class diamondback.filters.FirFilter.FirFilter(style: str = '', frequency: float = 0.0, order: int = 0, count: int = 1, complement: bool = False, gain: float = 1.0, b: Union[List, numpy.ndarray] = [], s: Union[List, numpy.ndarray] = [])

  Bases: `object`

  Finite Impulse Response ( FIR ) filter.

  Initialize.

  Specify constraints including style, frequency, and order. Alternatively, a forward coefficient array may be explicitly defined to ignore constraints.

  Labels should be used to avoid ambiguity between constraints and coefficients.

  Arguments :

    style : str - in ( ‘Blackman’, ‘Hamming’, ‘Hann’, ‘Kaiser’ ). frequency : float - relative to Nyquist in ( 0.0, 1.0 ). order : int. count : int. complement : bool. gain : float. b : Union[ List, numpy.ndarray ]. s : Union[ List, numpy.ndarray ].

  property b

    Union[ List, numpy.ndarray ] - forward coefficient.

    Type

      b

  property s

    Union[ List, numpy.ndarray ] - state.

    Type

      s

  delay(length: int = 8192, count: int = 1) → Tuple[numpy.ndarray, numpy.ndarray]

    Estimates group delay and produces a reference signal.

    Arguments :

      length : int. count : int.

    Returns :

      y : numpy.ndarray - reference signal. f : numpy.ndarray - relative to Nyquist in [ -1.0, 1.0 ).

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

  reset(x: Union[complex, float]) → None

    Modifies a state to minimize edge effects by assuming persistent operation at a specified incident signal condition.

    Arguments :

      x : Union[ complex, float ] - incident signal.

  response(length=8192, count=1) → Tuple[numpy.ndarray, numpy.ndarray]

    Estimates frequency response and produces a reference signal.

    Arguments :

      length : int. count : int.

    Returns :

      y : numpy.ndarray - reference signal. f : numpy.ndarray - relative to Nyquist in [ -1.0, 1.0 ).

  roots(count=1) → Tuple[numpy.ndarray, numpy.ndarray]

    Estimates roots of a frequency response in poles and zeros.

    Arguments :

      count : int.

    Returns :

      p : numpy.ndarray - poles. z : numpy.ndarray - zeros.

## diamondback.filters.GoertzelFilter module

Description

  A Goertzel filter realizes a discrete difference equation which approximates a discrete Fourier transform evaluated at a specified normalized frequency and order, consuming an incident signal and producing a reference signal.

  \[y_{n} = \sum_{i = 1}^{N} a_{i} y_{n-i} + \sum_{i = 0}^{N} b_{i} x_{n-i} = \sum_{i = 1}^{N} (\ a_{i} b_{0} + b_{i}\ ) s_{i,n} + b_{0} x_{n}\qquad a_{0} = 0\]
  \[s_{1,n+1} = \sum_{i = 1}^{N} a_{i} s_{i,n} + x_{n}\qquad\quad s_{i,n+1} = s_{i-1,n}\]
  \[\matrix{ a = \scriptsize{ [\ \matrix{ 0 & 2\ \cos(\ \pi\ f\ ) & -1 }\ ] } & b = \scriptsize{ [\ \matrix{ 1 & -e^{\ j\ \pi\ f\ } & 0 } }\ ] }\]

  At the terminus of each window length a reference signal is evaluated to estimate a discrete Fourier transform at a specified normalized frequency.

  \[H_{z} = \frac{\sum_{i = 0}^{N} b_{i} z^{-i}}{{1 - \sum_{i = 1}^{N} a_{i} z^{-i}}}\]

  A Goertzel filter is normalized by incident signal length. An incident signal length is is inversely proportional to a normalized frequency resolution.

  \[N = \frac{2}{R}\]

Example

>     from diamondback import ComplexExponentialFilter, GoertzelFilter
>     import numpy

>     b = WindowFilter( 'Hann', 128 ).b
>     frequency = 0.1

>     # Create an instance.

>     obj = GoertzelFilter( b = b, frequency = frequency )

>     # Filter an incident signal.

>     x = ComplexExponentialFilter( 0.0 ).filter( numpy.ones( 1024 ) * frequency ) * numpy.random.rand( 1 )[ 0 ]
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-04-16.

class diamondback.filters.GoertzelFilter.GoertzelFilter(b: Union[List, numpy.ndarray], frequency: float)

  Bases: `diamondback.filters.IirFilter.IirFilter`

  Goertzel filter.

  Initialize.

  Arguments :

    b : Union[ List, numpy.ndarray ] - forward coefficient. frequency : float - relative to Nyquist in [ -1.0, 1.0 ].

  property frequency

    float - relative to Nyquist in [ -1.0, 1.0 ].

    Type

      frequency

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

## diamondback.filters.IirFilter module

Description

  An Infinite Impulse Response ( IIR ) filter realizes a discrete difference equation as a function of a recursive coefficient array, a forward coefficient array, and a state array of a specified order, consuming an incident signal and producing a reference signal.

  \[y_{n} = \sum_{i = 1}^{N} a_{i,n} y_{n-i} + \sum_{i = 0}^{N} b_{i,n} x_{n-i} = \sum_{i = 1}^{N} (\ a_{i,n} b_{0,n} + b_{i,n}\ ) s_{i,n} + b_{0,n} x_{n}\qquad a_{0,n} = 0\]
  \[s_{1,n+1} = \sum_{i = 1}^{N} a_{i,n} s_{i,n} + x_{n}\qquad\qquad s_{i,n+1} = s_{i-1,n}\]

  A reset may minimize edge effects at a discontinuity by assuming persistent operation at a specified incident signal condition.

  \[s_{i,n} = \frac{1.0 - b_{0,n}}{\sum_{i=1}^{N} a_{i,n} b_{0,n} + b_{i,n}}\ x_{n}\]

  A frequency response is expressed as a function of a recursive coefficient array and a forward coefficient array.

  \[H_{z,n} = \frac{\sum_{i = 0}^{N} b_{i,n} z^{-i}}{{1 - \sum_{i = 1}^{N} a_{i,n} z^{-i}}}\]

  A recursive coefficient array, forward coefficient array, and state array of a specified order are defined to realize specified constraints. A style, frequency, order, count, complement, and gain are electively specified. Alternatively, a recursive coefficient array, forward coefficient array, and state array may be explicitly defined to ignore constraints.

  Frequency corresponds to a -3 dB frequency response normalized relative to Nyquist.

  Style is in ( ‘Bessel’, ‘Butterworth’, ‘Chebyshev’ ).

  - ‘Bessel’ filters demonstrate maximally linear phase response or
    constant group delay.
  - ‘Butterworth’ filters demonstrate maximally flat magnitude response.
  - ‘Chebyshev’ filters demonstrate minimally low magnitude response error
    and improved rate of attenuation in a Type I form, with a maximum in
    band ripple of 0.125 dB.

  Count is a quantity of filters of a specified order concatenated to form an aggregate frequency response in cascade form.

  Complement effectively constructs a mirror image of a specified frequency response.

Example

>     from diamondback import IirFilter
>     import numpy

>     # Create an instance with constraints.

>     obj = IirFilter( style = 'Chebyshev', frequency = 0.1, order = 8, count = 1 )

>     # Create an instance with coefficients.

>     obj = IirFilter( a = obj.a, b = obj.b )

>     # Estimate frequency response, group delay, and roots.

>     y, f = obj.response( length = 8192, count = 1 )
>     y, f = obj.delay( length = 8192, count = 1 )
>     p, z = obj.roots( count = 1 )

>     # Filter an incident signal.

>     x = numpy.random.rand( 128 ) * 2.0 - 1.0
>     obj.reset( x[ 0 ] )
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-01-23.

class diamondback.filters.IirFilter.IirFilter(style: str = '', frequency: float = 0.0, order: int = 0, count: int = 1, complement: bool = False, gain: float = 1.0, a: Union[List, numpy.ndarray] = [], b: Union[List, numpy.ndarray] = [], s: Union[List, numpy.ndarray] = [])

  Bases: `diamondback.filters.FirFilter.FirFilter`

  Infinite Impulse Response ( IIR ) filter.

  Initialize.

  Specify constraints including style, frequency, and order. Alternatively, a recursive coefficient array and forward coefficient array may be explicitly defined to ignore constraints.

  Labels should be used to avoid ambiguity between constraints and coefficients.

  Arguments :

    style : str - in ( ‘Bessel’, ‘Butterworth’, ‘Chebyshev’ ). frequency : float - relative to Nyquist in ( 0.0, 1.0 ). order : int. count : int. complement : bool. gain : float. a : Union[ List, numpy.ndarray ] - recursive coefficient, s-domain. b : Union[ List, numpy.ndarray ] - forward coefficient. s : Union[ List, numpy.ndarray ] - state.

  property a

    Union[ List, numpy.ndarray ] - recursive coefficient.

    Type

      a

  static _evaluate(style: str, frequency: float, order: int) → Tuple[numpy.ndarray, numpy.ndarray]

    Evaluates coefficients.

    Arguments :

      style : str - in ( ‘Bessel’, ‘Butterworth’, ‘Chebyshev’ ). frequency : float - relative to Nyquist in ( 0.0, 1.0 ). order : int.

    Returns :

      a : numpy.ndarray - recursive coefficient. b : numpy.ndarray - forward coefficient.

  delay(length: int = 8192, count: int = 1) → Tuple[numpy.ndarray, numpy.ndarray]

    Estimates group delay and produces a reference signal.

    Arguments :

      length : int. count : int.

    Returns :

      y : numpy.ndarray - reference signal. f : numpy.ndarray - relative to Nyquist in [ -1.0, 1.0 ).

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

  reset(x: Union[complex, float]) → None

    Modifies a state to minimize edge effects by assuming persistent operation at a specified incident signal condition.

    Arguments :

      x : Union[ complex, float ] - incident signal.

  response(length=8192, count=1) → Tuple[numpy.ndarray, numpy.ndarray]

    Estimates frequency response and produces a reference signal.

    Arguments :

      length : int. count : int.

    Returns :

      y : numpy.ndarray - reference signal. f : numpy.ndarray - relative to Nyquist in [ -1.0, 1.0 ).

  roots(count=1) → Tuple[numpy.ndarray, numpy.ndarray]

    Estimates roots of a frequency response in poles and zeros.

    Arguments :

      count : int.

    Returns :

      p : numpy.ndarray - poles. z : numpy.ndarray - zeros.

## diamondback.filters.IntegralFilter module

Description

  An integral filter realizes a discrete difference equation which approximates a discrete integral as a function of a recursive coefficient array, a forward coefficient array, and a state array of a specified order, consuming an incident signal and producing a reference signal. An integral is approximated relative to a sample. An integral is electively approximated relative to a second by dividing a reference signal by an absolute sampling frequency.

  \[y_{n} = \sum_{i = 1}^{N} a_{i} y_{n-i} + \sum_{i = 0}^{N} b_{i} x_{n-i} = \sum_{i = 1}^{N} (\ a_{i} b_{0} + b_{i}\ ) s_{i,n} + b_{0} x_{n}\qquad a_{0} = 0\]
  \[s_{1,n+1} = \sum_{i = 1}^{N} a_{i} s_{i,n} + x_{n}\qquad\quad s_{i,n+1} = s_{i-1,n}\]

  A frequency response is expressed as a function of a recursive coefficient array and a forward coefficient array.

  \[H_{z} = \frac{\sum_{i = 0}^{N} b_{i} z^{-i}}{{1 - \sum_{i = 1}^{N} a_{i} z^{-i}}}\]

  A recursive coefficient array, forward coefficient array, and state array of a specified order are defined to satisfy specified constraints. An instance and order are specified.

  \[y_{n} = \frac{1}{f}\ \sum_{i=0}^{N} x_{n}\quad\quad\quad\quad\scriptsize{ f = 1.0 }\]
  \[\matrix{ a_{1,0} = \scriptsize{ [ \matrix{ 0 & 1 } ] } & b_{1,0} = \scriptsize{ [ \matrix{ 1 } ] } }\quad\quad\scriptsize{ Rectangular }\]
  \[\matrix{ a_{1,1} = \scriptsize{ [ \matrix{ 0 & 1 } ] } & b_{1,1} = \scriptsize{ [ \matrix{ 1 & 1 } ]\ \frac{1}{2} } }\quad\quad\scriptsize{ Trapezoidal }\]
  \[\matrix{ a_{1,2} = \scriptsize{ [ \matrix{ 0 & 1 } ] } & b_{1,2} = \scriptsize{ [ \matrix{ 1 & 4 & 1 } ]\ \frac{1}{6} } }\quad\quad\scriptsize{ Simpson\ 2 }\]
  \[\matrix{ a_{1,3} = \scriptsize{ [ \matrix{ 0 & 1 } ] } & b_{1,3} = \scriptsize{ [ \matrix{ 1 & 3 & 3 & 1 } ]\ \frac{1}{8} } }\quad\quad\scriptsize{ Simpson\ 3 }\]
  \[\matrix{ a_{1,4} = \scriptsize{ [ \matrix{ 0 & 1 } ] } & b_{1,4} = \scriptsize{ [ \matrix{ 7 & 32 & 12 & 32 & 7 } ]\ \frac{1}{90} } }\quad\quad\scriptsize{ Newton\ Coats }\]

Example

>     from diamondback import ComplexExponentialFilter, IntegralFilter
>     import numpy

>     # Create an instance.

>     obj = IntegralFilter( order = 2 )

>     # Filter an incident signal.

>     x = ComplexExponentialFilter( 0.0 ).filter( numpy.ones( 128 ) * 0.1 ).real
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-02-06.

class diamondback.filters.IntegralFilter.IntegralFilter(order: int)

  Bases: `diamondback.filters.IirFilter.IirFilter`

  Integral filter.

  Initialize.

  Arguments :

    order : int.

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

## diamondback.filters.PidFilter module

Description

  A Proportional Integral Derivative ( PID ) filter realizes a discrete difference equation as a function of a forward coefficient array and a state array of a static order. A forward coefficient array applies a gain to proportional, integral, and derivative representations of an incident signal, producing a reference signal. An integral limit is specified, preventing integral saturation which may adversely affect control stability and latency.

  \[y_{n} = b_{0}\ x_{n} + b_{1}\max(\ min( \sum_{0}^{n}\ x_{n},\ limit\ ),\ -limit\ ) + b_{2}\ \frac{d}{dn}(\ x_{n}\ )\]

Example

>     from diamondback import ComplexExponentialFilter, PidFilter
>     import numpy

>     # Create an instance.

>     obj = PidFilter( b = numpy.array( [ 0.1, 5.0e-2, 0.0 ] ) )

>     # Filter an incident signal.

>     x = ComplexExponentialFilter( 0.0 ).filter( numpy.linspace( -1.0e-4, 1.0e-4, 128 ) * 0.1 ).real
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-01-31.

class diamondback.filters.PidFilter.PidFilter(b: Union[List, numpy.ndarray])

  Bases: `diamondback.filters.FirFilter.FirFilter`

  Proportional Integral Derivative ( PID ) filter.

  Initialize.

  Arguments :

    b : Union[ List, numpy.ndarray ] - forward coefficient.

  property limit

    float.

    Type

      limit

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

## diamondback.filters.PolynomialRateFilter module

Description

  A polynomial rate filter produces a reference signal which approximates an incident signal evaluated at an effective frequency equal to the product of an incident sample frequency and a specified rate.

  A polynomial rate filter synthesizes a sequence of polynomials which form local approximations to an incident signal, and are evaluated at indices corresponding to a specified rate to produce a reference signal, effectively modifying the sampling rate by a specified rate ratio.

  A specified rate must be greater than zero, supporting decimation and interpolation.

  Latency compensation is not necessary, as no group delay is introduced.

  Edge effects are internally mitigated by linear extension of an incident signal.

  A polynomial rate filter may be the most appropriate option in applications which require fractional decimation and interpolation and benefit from minimization of edge effects due to discontinuous operation or dynamic rate.

Example

>     from diamondback import ComplexExponentialFilter, PolynomialRateFilter
>     import math
>     import numpy

>     # Create an instance.

>     obj = PolynomialRateFilter( rate = math.pi, order = 3 )

>     # Filter an incident signal.

>     x = ComplexExponentialFilter( 0.0 ).filter( numpy.ones( 128 ) * 0.1 ).real
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-03-19.

class diamondback.filters.PolynomialRateFilter.PolynomialRateFilter(rate: float, order: int = 3)

  Bases: `object`

  Polynomial rate filter.

  Initialize.

  Arguments :

    rate : float - ratio of effective frequency in [ 0.0, inf ). order : int - in [ 2 , inf ).

  property order

    int - in [ 2, inf ).

    Type

      order

  property rate

    float - in [ 0.0, inf ).

    Type

      rate

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

## diamondback.filters.PolyphaseRateFilter module

Description

  A polyphase rate filter produces a reference signal which approximates an incident signal evaluated at an effective frequency equal to the product of an incident sample frequency and a specified rate.

  A polyphase rate filter synthesizes a polyphase filter bank with comprised of a sequence of low pass filters. Each low pass filter in a filter bank realizes a common frequency response, with a fractional sample difference in group delay. A stride is defined to be dependent upon a specified rate ratio and count. An incident signal is filtered to reduce aliasing and decimated or interpolated to produce a reference signal, effectively modifying the sampling rate by a specified rate ratio.

  \[b_{k,i} = b^{M}[\ k (\ N\ +\ 1\ )\ +\ i\ ] \qquad\qquad k\ :\ [\ 0,\ K\sim 256\ )\qquad\ i\ :\ [\ 0,\ N\sim 15 \ ]\]
  \[y_{n} = \sum_{i = 0}^{N} b_{k_{n},i}\ x_{n-i} = \sum_{i = 1}^{N} b_{k_{n},i}\ s_{i,n} + b_{k_{n},0}\ x_{n}\]
  \[s_{1,n+1} = x_{n}\quad\quad s_{i,n+1} = s_{i-1,n}\]

  A specified rate must be greater than zero, and less than or equal to the quantity of filters comprising a polyphase filter bank, supporting decimation and interpolation.

  Phase dither is present for a real rate, though error is accumulated to ensure that the specified rate is realized without bias. Group delay may be addressed by latency compensation.

  \[\phi_{n+1,Rate} = \phi_{n,Rate}\ +\ \frac{K}{\scriptsize{Rate}}\]
  \[\phi_{n+1,Rate}\ \geq\ K\qquad\longrightarrow\qquad \phi_{n+1,Rate} = \phi_{n+1,Rate}\ -\ K\]
  \[k_{n+1} = \mod(\ \lfloor{\ k_{n}\ +\ \phi_{n+1,Rate}}\rfloor,\ M\ )\]

  A reset may minimize edge effects at a discontinuity by assuming persistent operation at a specified incident signal condition. Edge extension may also be applied to an incident signal.

  A polyphase rate filter may be the most appropriate option in applications which require fractional decimation and interpolation and are not highly sensitive to minimization of edge effects or have continuous operation.

Example

>     from diamondback import ComplexExponentialFilter, PolyphaseRateFilter
>     import math
>     import numpy

>     # Create an instance.

>     obj = PolyphaseRateFilter( rate = 1.0 / math.pi )

>     # Filter an incident signal.

>     x = ComplexExponentialFilter( 0.0 ).filter( numpy.ones( 128 ) * 0.1 ).real
>     obj.reset( x[ 0 ] )
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-03-19.

class diamondback.filters.PolyphaseRateFilter.PolyphaseRateFilter(rate: float)

  Bases: `object`

  Polyphase rate filter.

  Initialize.

  Arguments :

    rate : float - ratio of effective frequency in ( 0.0, b.shape[ 0 ] ].

  property b

    numpy.ndarray - forward coefficient.

    Type

      b

  property rate

    float - in [ 0.0, b.shape[ 0 ] ].

    Type

      rate

  property s

    Union[ List, numpy.ndarray ] - state.

    Type

      s

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

  reset(x: float) → None

    Modifies a state to minimize edge effects by assuming persistent operation at a specified incident signal condition.

    Arguments :

      x : float - incident signal.

## diamondback.filters.RankFilter module

Description

  A rank filter realizes a nonlinear morphological operator consuming an incident signal, sorting, indexing, and selecting over a sliding window of a specified order, and producing a reference signal.

  Simple morphological operations include dilation, which defines a rank index equal to zero, erosion, which defines a rank index equal to order, and median, which defines a rank index equal to order divided by two for even order. Compound morphological operations include close, consisting of sequential dilation and erosion, and open, consisting of sequential erosion and dilation. An order and rank are specified.

  \[y_{n} = sort(\ x_{n-N+1\ :\ n}\ )[\ i\ ]\]

Example

>     from diamondback import RankFilter
>     import numpy

>     # Create an instance.

>     obj = RankFilter( rank = 4, order = 4 )

>     # Filter an incident signal.

>     x = numpy.concatenate( ( numpy.ones( 1 ), numpy.zeros( 10 ), numpy.ones( 4 ), numpy.zeros( 2 ), numpy.ones( 5 ), numpy.zeros( 6 ) ) )
>     obj.reset( x[ 0 ] )
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-01-31.

class diamondback.filters.RankFilter.RankFilter(index: int, order: int)

  Bases: `diamondback.filters.FirFilter.FirFilter`

  Rank filter.

  Initialize.

  Arguments :

    index : int - in [ 0, order ]. order : int.

  property index

    int - in [ 0, order ].

    Type

      index

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

## diamondback.filters.WindowFilter module

Description

  A window filter realizes a discrete difference equation as a function of a forward coefficient array of a specified order, consuming an incident signal and producing a reference signal.

  \[y_{n} = b_{n}\ x_{n}\]

  A forward coefficient array of a specified order is defined. A style, order, and normalization are specified.

  Style is in ( ‘Blackman’, ‘Hamming’, ‘Hann’, ‘Kaiser’ ).

  - ‘Blackman’ filters demonstrate low resolution and spectral leakage
    with improved rate of attenuation.
  - ‘Hamming’ filters demonstrate minimal nearest side lobe magnitude
    response.
  - ‘Hann’ filters demonstrate high resolution and spectral leakage.
  - ‘Kaiser’ filters demonstrate flexible resolution and spectral
    leakage dependent upon a beta value of a Bessel function of the
    first kind, with beta equal to 7.0.

  Normal condition scales a forward coefficient array to electively compensate for energy loss.

  \[b_{n} = b_{n}\ \frac{ N }{ \sum_{0}^{N-1}\ |\ b_{n}\ |}\]

Example

>     from diamondback import ComplexExponentialFilter, WindowFilter
>     import numpy

>     # Create an instance.

>     obj = WindowFilter( style = 'Hann', order = 15, normal = True )

>     # Filter an incident signal.

>     x = ComplexExponentialFilter( 0.0 ).filter( numpy.ones( len( obj.b ) ) * 0.1 ).real
>     y = obj.filter( x )

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-04-13.

class diamondback.filters.WindowFilter.WindowFilter(style: str, order: int, normal: bool = True)

  Bases: `object`

  Window filter.

  Initialize.

  Arguments :

    style : str - in ( ‘Blackman’, ‘Hamming’, ‘Hann’, ‘Kaiser’ ). order : int. normal : bool.

  property b

    Union[ List, numpy.ndarray ] - forward coefficient.

    Type

      b

  filter(x: Union[List, numpy.ndarray]) → numpy.ndarray

    Filters an incident signal and produces a reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal.

    Returns :

      y : numpy.ndarray - reference signal.

## Module contents

Description

  Initialize.

License

  BSD-3C. © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

  Larry Turner, Schneider Electric, Analytics & AI, 2018-03-22.