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 with frequency and rate.

>     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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

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

  Bases: `diamondback.filters.FirFilter.FirFilter`, `diamondback.interfaces.IFrequency.IFrequency`, `diamondback.interfaces.IRate.IRate`

  Complex band pass filter.

  Initialize.

  Arguments :

  > frequency : float - relative to Nyquist in [ -1.0, 1.0 ).

  > rate : float - in [ 0.0, 1.0 ].

  `__eq__`(other: Any) → bool

    Equal.

    Arguments :

    > other : typing.Any.

    Returns :

    > equal : bool.

  `filter`(d: Union[List, numpy.ndarray], x: Optional[Union[List, numpy.ndarray]] = None) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

    Filters an incident signal and produces a reference signal.

    Arguments :

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

    > x : typing.Union[ typing.List, numpy.ndarray ] - incident 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 with phase.

>     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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

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

  Bases: `diamondback.interfaces.IPhase.IPhase`

  Complex exponential filter.

  Initialize.

  Arguments :

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

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

    Filters an incident signal and produces a reference signal.

    Arguments :

    > x : typing.Union[ typing.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 with frequency and rate.

>     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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

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

  Bases: `diamondback.filters.FirFilter.FirFilter`, `diamondback.interfaces.IFrequency.IFrequency`, `diamondback.interfaces.IRate.IRate`

  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

  `filter`(d: Union[List, numpy.ndarray], x: Optional[Union[List, numpy.ndarray]] = None) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

    Filters an incident signal and produces a reference signal.

    Arguments :

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

    > x : typing.Union[ typing.List, numpy.ndarray ] - incident 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.

> \[ \begin{align}\begin{aligned}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}\end{aligned}\end{align} \]

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

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

> A factory is defined to facilitate construction of an instance, defining a forward coefficient array and a state array of a specified order, to satisfy specified constraints. An instance, 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 from a Factory with constraints.

>     obj = DerivativeFilter.Factory.instance( typ = 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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

class `diamondback.filters.DerivativeFilter.` `DerivativeFilter`(b: Union[List, numpy.ndarray] = array([1.000000]))

  Bases: `diamondback.filters.FirFilter.FirFilter`

  Derivative filter.

  Initialize.

  Arguments :

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

  class `Factory`

    Bases: `object`

    Factory.

    classmethod `instance`(typ: type, derivative: int, order: int) → Any

      Constructs an instance.

      Arguments :

      > typ : type - derived from DerivativeFilter.

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

      > order : int.

      Returns :

      > instance : typ( ).

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

    Filters an incident signal and produces a reference signal.

    Arguments :

    > x : typing.Union[ typing.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 factory is defined to facilitate construction of an instance, defining a forward coefficient array, and a state array of a specified order, to realize specified constraints. An instance, classification, frequency, order, count, complement, and gain are specified.

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

> Classification 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 from a Factory with constraints.

>     obj = FirFilter.Factory.instance( typ = FirFilter, classification = '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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

class `diamondback.filters.FirFilter.` `FirFilter`(b: Union[List, numpy.ndarray] = array([1.000000]), s: Union[List, numpy.ndarray] = array([0.000000]))

  Bases: `diamondback.interfaces.IB.IB`, `diamondback.interfaces.IReset.IReset`, `diamondback.interfaces.IS.IS`

  Finite Impulse Response ( FIR ) filter.

  Initialize.

  Arguments :

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

  > s : typing.Union[ typing.List, numpy.ndarray ] - state.

  class `Factory`

    Bases: `object`

    Factory.

    classmethod `instance`(typ: type, classification: str, frequency: float, order: int, count: int = 1, complement: bool = False, gain: float = 1.0) → Any

      Constructs an instance.

      Arguments :

      > typ : type - derived from FirFilter.

      > classification : str - in ( ‘Blackman’, ‘Hamming’, ‘Hann’, ‘Kaiser’ ).

      > frequency : float - relative to Nyquist in ( 0.0, 1.0 ).

      > order : int.

      > count : int.

      > complement : bool.

      > gain : float.

      Returns :

      > instance : typ( ).

  `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 : typing.Union[ typing.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 : typing.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.Factory.instance( WindowFilter, 'Hann', 128 ).b

>     frequency = 0.1

>     # Create an instance from coefficients and frequency.

>     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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

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

  Bases: `diamondback.filters.IirFilter.IirFilter`, `diamondback.interfaces.IFrequency.IFrequency`

  Goertzel filter.

  Initialize.

  Arguments :

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

  > frequency : float - relative to Nyquist in [ -1.0, 1.0 ).

  `__eq__`(other: Any) → bool

    Equal.

    Arguments :

    > other : typing.Any.

    Returns :

    > equal : bool.

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

    Filters an incident signal and produces a reference signal.

    Arguments :

    > x : typing.Union[ typing.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 factory is defined to facilitate construction of an instance, defining a recursive coefficient array, a forward coefficient array, and a state array of a specified order, to realize specified constraints. An instance, classification, frequency, order, count, complement, and gain are specified.

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

> Classification 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 from a Factory with constraints.

>     obj = IirFilter.Factory.instance( typ = IirFilter, classification = '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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

class `diamondback.filters.IirFilter.` `IirFilter`(a: Union[List, numpy.ndarray] = array([0.000000]), b: Union[List, numpy.ndarray] = array([1.000000]), s: Union[List, numpy.ndarray] = array([0.000000]))

  Bases: `diamondback.filters.FirFilter.FirFilter`, `diamondback.interfaces.IA.IA`

  Infinite Impulse Response ( IIR ) filter.

  Initialize.

  Arguments :

  > a : typing.Union[ typing.List, numpy.ndarray ] - recursive coefficient, s-domain.

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

  > s : typing.Union[ typing.List, numpy.ndarray ] - state.

  class `Factory`

    Bases: `object`

    Factory.

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

      Evaluates coefficients.

      Arguments :

      > classification : 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.

    classmethod `instance`(typ: type, classification: str, frequency: float, order: int, count: int = 1, complement: bool = False, gain: float = 1.0) → Any

      Constructs an instance.

      Arguments :

      > typ : type - derived from IirFilter.

      > classification : str - in ( ‘Bessel’, ‘Butterworth’, ‘Chebyshev’ ).

      > frequency : float - relative to Nyquist in ( 0.0, 1.0 ).

      > order : int.

      > count : int.

      > complement : bool.

      > gain : float.

      Returns :

      > instance : typ( ).

  `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 : typing.Union[ typing.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 : typing.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 factory is defined to facilitate construction of an instance, defining a recursive coefficient array, a forward coefficient array, and a state array of a specified order, 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 from a Factory with constraints.

>     obj = IntegralFilter.Factory.instance( typ = 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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

class `diamondback.filters.IntegralFilter.` `IntegralFilter`(a: Union[List, numpy.ndarray] = array([0.000000]), b: Union[List, numpy.ndarray] = array([1.000000]))

  Bases: `diamondback.filters.IirFilter.IirFilter`

  Integral filter.

  Initialize.

  Arguments :

  > a : typing.Union[ typing.List, numpy.ndarray ] - recursive coefficient.

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

  class `Factory`

    Bases: `object`

    Factory.

    classmethod `instance`(typ: type, order: int) → Any

      Constructs an instance.

      Arguments :

      > typ : type - derived from IntegralFilter.

      > order : int.

      Returns :

      > instance : typ( ).

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

    Filters an incident signal and produces a reference signal.

    Arguments :

    > x : typing.Union[ typing.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 with coefficients.

>     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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

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

  Bases: `diamondback.filters.FirFilter.FirFilter`

  Proportional Integral Derivative ( PID ) filter.

  Initialize.

  Arguments :

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

  property `limit`

    float.

    Type

      limit

  `__eq__`(other: Any) → bool

    Equal.

    Arguments :

    > other : typing.Any.

    Returns :

    > equal : bool.

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

    Filters an incident signal and produces a reference signal.

    Arguments :

    > x : typing.Union[ typing.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 with rate and order.

>     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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

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

  Bases: `diamondback.interfaces.IRate.IRate`

  Polynomial rate filter.

  Initialize.

  Arguments :

  > rate : float - ratio of effective frequency in [ 1.0, inf ).

  > order : int - in [ 2 , inf ).

  property `order`

    int - in [ 2, inf ).

    Type

      order

  `__eq__`(other: Any) → bool

    Equal.

    Arguments :

    > other : typing.Any.

    Returns :

    > equal : bool.

  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 : typing.Union[ typing.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 with rate.

>     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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

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

  Bases: `diamondback.interfaces.IB.IB`, `diamondback.interfaces.IRate.IRate`, `diamondback.interfaces.IReset.IReset`, `diamondback.interfaces.IS.IS`

  Polyphase rate filter.

  Initialize.

  Arguments :

  > rate : float - ratio of effective frequency in ( 0.0, 256.0 ].

  property `b`

    numpy.ndarray - forward coefficient.

    Type

      b

  `__eq__`(other: Any) → bool

    Equal.

    Arguments :

    > other : typing.Any.

    Returns :

    > equal : bool.

  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 : typing.Union[ typing.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 with rank and order.

>     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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

class `diamondback.filters.RankFilter.` `RankFilter`(rank: int, order: int)

  Bases: `diamondback.filters.FirFilter.FirFilter`

  Rank filter.

  Initialize.

  Arguments :

  > rank : int - in [ 0, order ].

  > order : int.

  property `rank`

    int - in [ 0, order ].

    Type

      rank

  `__eq__`(other: Any) → bool

    Equal.

    Arguments :

    > other : typing.Any.

    Returns :

    > equal : bool.

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

    Filters an incident signal and produces a reference signal.

    Arguments :

    > x : typing.Union[ typing.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 factory is defined to facilitate construction of an instance, defining a forward coefficient array of a specified order. An instance, classification, order, and normalization are specified.

> Classification 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 from a Factory with constraints.

>     obj = WindowFilter.Factory.instance( typ = WindowFilter, classification = '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 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition

class `diamondback.filters.WindowFilter.` `WindowFilter`(b: Union[List, numpy.ndarray] = array([1.000000]))

  Bases: `diamondback.interfaces.IB.IB`, `diamondback.interfaces.IEqual.IEqual`

  Window filter.

  Initialize.

  Arguments :

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

  class `Factory`

    Bases: `object`

    Factory.

    classmethod `instance`(typ: type, classification: str, order: int, normal: bool = True) → Any

      Constructs an instance.

      Arguments :

      > typ : type - derived from WindowFilter.

      > classification : str - in ( ‘Blackman’, ‘Hamming’, ‘Hann’, ‘Kaiser’ ).

      > order : int.

      > normal : bool.

      Returns :

      > instance : typ( ).

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

    Filters an incident signal and produces a reference signal.

    Arguments :

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

    Returns :

    > y : numpy.ndarray - reference signal.

## Module contents

Description

> Initialize imports.

License

> BSD-3C.

> © 2018 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

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

Definition