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)[source]

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[source]

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][source]

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)[source]

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[source]

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)[source]

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][source]

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[source]

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]))[source]

Bases: diamondback.filters.FirFilter.FirFilter

Derivative filter.

Initialize.

Arguments :

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

class Factory[source]

Bases: object

Factory.

classmethod instance(typ: type, derivative: int, order: int)Any[source]

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[source]

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]))[source]

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[source]

Bases: object

Factory.

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

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][source]

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[source]

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[source]

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][source]

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][source]

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)[source]

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[source]

Equal.

Arguments :

other : typing.Any.

Returns :

equal : bool.

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

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]))[source]

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[source]

Bases: object

Factory.

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

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[source]

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][source]

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[source]

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[source]

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][source]

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][source]

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]))[source]

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[source]

Bases: object

Factory.

classmethod instance(typ: type, order: int)Any[source]

Constructs an instance.

Arguments :

typ : type - derived from IntegralFilter.

order : int.

Returns :

instance : typ( ).

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

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])[source]

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[source]

Equal.

Arguments :

other : typing.Any.

Returns :

equal : bool.

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

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)[source]

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[source]

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[source]

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)[source]

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[source]

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[source]

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[source]

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)[source]

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[source]

Equal.

Arguments :

other : typing.Any.

Returns :

equal : bool.

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

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]))[source]

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

Window filter.

Initialize.

Arguments :

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

class Factory[source]

Bases: object

Factory.

classmethod instance(typ: type, classification: str, order: int, normal: bool = True)Any[source]

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[source]

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.

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