diamondback.transforms package — diamondback documentation

# diamondback.transforms package

## Submodules

## diamondback.transforms.ComplexTransform module

Description

  A complex transform converts a three-phase real signal to a complex signal, or converts a complex signal to a three-phase real signal, in equivalent and reversible representations. A neutral condition is specified.

  Singleton.

  \[\gamma = \scriptsize{ \matrix{ 1 & \frac{-1}{2} & \frac{-1}{2}\cr 0 & \frac{3^{0.5}}{2} & \frac{-3^{0.5}}{2}\cr 1 & 1 & 1 } }\]
  \[\alpha = \matrix{\frac{1}{3}}^{0.5}\ e^{\ -j\ \frac{\pi}{6}\ }\]

  Complex - Three-Phase.

  \[y_{n} = \matrix{ x^{T}_{n}\ \gamma\ }\ \scriptsize{[\ \matrix{ 1 & j & 0 }\ ]^{T}}\]
  \[\overline{\scriptsize{Neutral}}\ \qquad\longrightarrow\qquad y_{n} = y_{n}\ \alpha\]

  Three-Phase - Complex.

  \[\overline{\scriptsize{Neutral}}\ \qquad\longrightarrow\qquad x_{n} = \frac{x_{n}}{\alpha}\]
  \[y_{n} = \matrix{\ \matrix{ \gamma^{T}\gamma }^{-1}\ \gamma^{T}\ \scriptsize{[\ \matrix{ real(\ x_{n}\ ) & imag(\ x_{n}\ ) & 0 }\ ]^{T}}}^{T}\]

Example

>     from diamondback import ComplexExponentialFilter, ComplexTransform
>     import numpy

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

>     # Transform an incident signal, forward and inverse.

>     y = ComplexTransform.transform( x, neutral = True )
>     z = ComplexTransform.transform( y, neutral = True )

License

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

Author

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

class diamondback.transforms.ComplexTransform.ComplexTransform

  Bases: `object`

  Complex transform.

  classmethod transform(x: Union[List, numpy.ndarray], neutral: bool = True) → numpy.ndarray

    Transforms a real three-phase or complex incident signal into a complex or three-phase reference signal.

    Arguments :

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

    Returns :

      y : numpy.ndarray - reference signal.

## diamondback.transforms.FourierTransform module

Description

  A Fourier transform converts a real or complex discrete-time incident signal to a complex discrete-frequency reference signal, or a complex discrete-frequency incident signal to a real or complex discrete-time reference signal, in equivalent and reversible representations. A forward coefficient array is specified to define a window filter.

  Singleton.

  \[y_{k} = \frac{1}{N}\ \sum_{n = 0}^{N-1} b_{n} x_{n} e^{\frac{\ -j\ \pi\ k \ n}{N}} = \frac{1}{N}\ fft(\ x_{n}\ )\]
  \[x_{n} = \frac{N}{b_{n}}\ \sum_{k = 0}^{N-1} y_{k} e^{\frac{\ j\ \pi\ k \ n}{N}} = \frac{N}{b_{n}}\ ifft(\ y_{k}\ )\]

  A Fourier transform is normalized by incident signal length and forms a contiguous sequence corresponding to a linear and increasing normalized frequency.

  \[f_{k} = -1\ + \ 2\ \frac{k}{N}\]

  An incident signal length is inversely proportional to a normalized frequency resolution.

  > N = frac{2}{R}

Example

>     from diamondback import ComplexExponentialFilter, FourierTransform
>     import numpy

>     x = ComplexExponentialFilter( 0.0 ).filter( numpy.linspace( 0.12, 0.23, 128 ) ) * numpy.random.rand( 1 )[ 0 ]
>     b = WindowFilter( 'Hann', len( x ) - 1 ).b

>     # Transform an incident signal, forward and inverse.

>     y, f = FourierTransform.transform( x, b = b, inverse = False )
>     z = FourierTransform.transform( y, b = b, inverse = True )[ 0 ]

License

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

Author

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

class diamondback.transforms.FourierTransform.FourierTransform

  Bases: `object`

  Fourier transform.

  static transform(x: Union[List, numpy.ndarray], b: Union[List, numpy.ndarray], inverse: bool = False) → Tuple[numpy.ndarray, numpy.ndarray]

    Transforms a real or complex discrete-time incident signal to a complex discrete-frequency reference signal, or performs an inverse transform. Indices definition depends upon an inverse condition. Forward transform indices define normalized frequency. Inverse transform indices define an integral sequence.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal. b : Union[ List, numpy.ndarray ] - forward coefficient. inverse : bool.

    Returns :

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

## diamondback.transforms.PowerSpectrumTransform module

Description

  A power spectrum transform converts a real or complex discrete-time incident signal to a real discrete-frequency reference signal, which estimates a mean power density in the incident signal relative to frequency. A forward coefficient array is specified to define a window filter.

  Singleton.

  A power spectrum transform is constructed by estimating a mean power from a collection of Fourier transforms of an incident signal, over a sliding window defined by a forward coefficient array which defines a window filter. An index specifies a sample interval, or a non-overlapping stride, between successive operations.

  \[v_{i,k} = \frac{1}{N}\ \sum_{n = 0}^{N-1} b_{n} x_{n+i\ I} e^{ \frac{\ -j\ \pi\ k \ n}{N} }\]
  \[y_{k} = \frac{1}{C}\ \sum_{i = 0}^{C-1} v_{i,k} v^{*}_{i,k}\]

  A power spectrum transform is normalized by incident signal length and forms a contiguous sequence corresponding to a linear and increasing normalized frequency.

  \[f_{k} = -1\ + \ 2\ \frac{k}{N}\]

  An incident signal length is inversely proportional to a normalized frequency resolution.

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

Example

>     from diamondback import ComplexExponentialFilter, PowerSpectrumTransform
>     import numpy

>     x = ComplexExponentialFilter( 0.0 ).filter( numpy.linspace( 0.12, 0.23, 1024 ) ) * numpy.random.rand( 1 )[ 0 ]
>     b = WindowFilter( 'Hann', 128 - 1 ).b

>     # Transform an incident signal.

>     y, f = PowerSpectrumTransform.transform( x, b = b, index = len( b ) // 2 )

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.transforms.PowerSpectrumTransform.PowerSpectrumTransform

  Bases: `object`

  Power spectrum transform.

  static transform(x: Union[List, numpy.ndarray], b: Union[List, numpy.ndarray], index: int) → Tuple[numpy.ndarray, numpy.ndarray]

    Transforms a real or complex discrete-time incident signal to a real discrete-frequency reference signal.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal. b : Union[ List, numpy.ndarray ] - forward coefficient. index : int.

    Returns :

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

## diamondback.transforms.WaveletTransform module

Description

  A wavelet transform realizes a temporal spatial frequency transformation in the form of analysis and synthesis filters with a complementary frequency response, combined with downsampling and upsampling operations to facilitate frequency-dependent decomposition and reconstruction, consuming an incident signal and producing a reference signal.

  Analysis decomposes an incident signal into segments with specified operation count, applying complementary low pass and high pass analysis filters to an incident signal, downsampling and discarding alternate samples, and concatenating the paths to produce a reference signal. Analysis is repeated on the low pass portion of a reference signal for each segment, with decomposition into regions of varying temporal resolution, and a specific spatial frequency range. An incident signal has one or two dimensions, and a length in each dimension which is unity or an integral multiple of 2**count.

  \[y_{i,0:\frac{C}{2}-1} = \matrix{\downarrow(\ filter_{b_{A,L}}(\ x_{i,0:C-1}\ ),\ 2\ ) & y_{i,\frac{C}{2}:C-1} = \downarrow(\ filter_{b_{A,H}}(\ x_{i,0:C-1}\ ),\ 2\ ) & i \in \scriptsize{[\ 0,\ R\ )}}\]
  \[y_{0:\frac{R}{2}-1,j} = \matrix{\downarrow(\ filter_{b_{A,L}}(\ x_{0:R-1,j}\ ),\ 2\ ) & y_{\frac{R}{2}:R-1,j} = \downarrow(\ filter_{b_{A,H}}(\ x_{0:R-1,j}\ ),\ 2\ ) & j \in \scriptsize{[\ 0,\ C\ )}}\]

  Synthesis reconstructs an incident signal from a specified operation count, scaling and upsampling alternate samples, applying complementary low pass and high pass synthesis filters to a reference signal, and adding the constituents to produce an incident signal. Synthesis is repeated on the low pass portion of a reference signal for each segment, with reconstruction from regions of varying temporal resolution, and a specific spatial frequency range. A reference signal has one or two dimensions, and a length in each dimension which is unity or an integral multiple of 2**count.

  \[x_{0:R-1,j} = \matrix{filter_{b_{S,L}}(\ 2\ \uparrow(\ y_{0:\frac{R}{2}-1,j},\ 2\ )\ ) ) + filter_{b_{S,H}}(\ 2\ \uparrow(\ y_{\frac{R}{2}:R-1,j},\ 2\ ) )\ ) & j \in \scriptsize{[\ 0,\ C\ )}}\]
  \[x_{i,0:C-1} = \matrix{filter_{b_{S,L}}(\ 2\ \uparrow(\ y_{i,0:\frac{C}{2}-1},\ 2\ )\ ) + filter_{b_{S,H}}(\ 2\ \uparrow(\ y_{i,\frac{C}{2}:C-1},\ 2\ )\ ) & i \in \scriptsize{[\ 0,\ R\ )}}\]

  Analysis filters and synthesis filters of a specified order are defined to satisfy specified constraints. A style and order are specified.

  Style is in ( ‘Coiflet’, ‘Daubechies’, ‘Haar’, ‘Symmlet’ ).

  - ‘Coiflet’ is asymmetric, very high quality, with order in [ 5 : 29 : 6 ].
  - ‘Daubechies’ is asymmetric, high quality, with order in [ 3 : 19 : 2 ].
  - ‘Haar’ is symmetric, perfect reconstruction, with order in [ 1 ].
  - ‘Symmlet’ is nearly symmetric, high quality, with order in [ 7 : 19 : 2 ].

Example

>     from diamondback import WaveletTransform
>     import numpy

>     # Create an instance.

>     obj = WaveletTransform( style = 'Haar', order = 1 )

>     # Transform an incident signal, forward and inverse.

>     count = 3
>     x = numpy.random.rand( 2**( count + 3 ), 2**( count + 3 ) )
>     y = obj.transform( x, count, False )
>     z = obj.transform( y, count, True )

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.transforms.WaveletTransform.WaveletTransform(style: str, order: int)

  Bases: `object`

  Wavelet transform.

  Initialize.

  Arguments :

    style : str - in ( ‘Coiflet’, ‘Daubechies’, ‘Haar’, ‘Symmlet’ ). order : int.

  property b

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

    Type

      b

  transform(x: Union[List, numpy.ndarray], count: int, inverse: bool = False) → numpy.ndarray

    Transforms an incident signal and produces a reference signal, performing analysis or synthesis operations. Incident and reference signals have two dimensions. Dimension lengths must be unity or an integral multiple of 2**count.

    Arguments :

      x : Union[ List, numpy.ndarray ] - incident signal. count : int. inverse : bool.

    Returns :

      y : numpy.ndarray - reference signal.

## diamondback.transforms.ZTransform module

Description

  A z transform converts a continuous s-domain differential equation to a discrete z-domain difference equation as a function of a recursive coefficient array and a forward coefficient array of a specified order. A normalized frequency and bilinear condition are specified.

  Singleton.

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

  A frequency response is expressed as a function of a recursive coefficient array and a forward coefficient array, in s-domain and z-domain.

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

Example

>     from diamondback import ZTransform
>     import math
>     import numpy

>     frequency, order, ripple = 0.1, 2, 0.125
>     u = numpy.array( [ numpy.exp( 1j * math.pi * x / ( 2.0 * order ) ) for x in range( 1, 2 * order, 2 ) ] )
>     v = math.asinh( 1.0 / ( ( 10.0 ** ( 0.1 * ripple ) - 1.0 ) ** 0.5 ) ) / order
>     a = ( numpy.poly( ( -math.sinh( v ) * u.imag + 1j * math.cosh( v ) * u.real ) * 2.0 * math.pi ) ).real
>     a /= a[ -1 ]

>     # Transform z-domain coefficients with s-domain coefficients, frequency, and bilinear.

>     a, b = ZTransform.transform( a = a, b = [ 1.0 ], frequency = frequency, bilinear = True )

>     # Define zeros and normalize gain.

>     b = numpy.poly( -numpy.ones( order ) )
>     b = b * ( 1.0 - sum( a ) ) / sum( b )

License

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

Author

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

class diamondback.transforms.ZTransform.ZTransform

  Bases: `object`

  Z transform realizes continuous s-domain to discrete z-domain transformation, through application of bilinear or impulse invariant methods.

  static transform(u: Union[List, numpy.ndarray], v: Union[List, numpy.ndarray], frequency: float, bilinear: bool = True) → Tuple[numpy.ndarray, numpy.ndarray]

    Transforms continuous s-domain coefficient arrays and produces discrete z-domain coefficient arrays.

    Arguments :

      u : Union[ List, numpy.ndarray ] - recursive coefficient, s-domain. v : Union[ List, numpy.ndarray ] - forward coefficient, s-domain. frequency : float - relative to Nyquist in ( 0.0, 1.0 ). bilinear : bool.

    Returns :

      a : numpy.ndarray - recursive coefficient, z-domain. b : numpy.ndarray - forward coefficient, z-domain.

## 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.