Documentation

class AlgDiff.AlgebraicDifferentiator(ts=0.01, alpha=1.0, beta=1.0, N=0, T=1.0, wc=None, display=True, corr=True)

This class implements an algebraic differentiator and all the methods necessary for its use, analysis, tuning, and discretization. The differentiators which are LTI filters can be parametrized to achieve desired filter characteristics: Cutoff frequency and stopband slope. A cutoff frequency \(\omega_{\mathrm{c}}\) or a filter window length \(T\) can be specified. If the filter window length is specified the cutoff frequency is computed. For frequencies lower than the cutoff frequency the amplitude of the Fourier transform is \(0\) dB. For frequencies higher the amplitude falls with \(\mu=\min\{\alpha,\beta\}+1\) dB per decade.

Parameters:

  • ts (float) – Sampling period.

  • alpha (float) – Parameter \(\alpha\) of the weight function of the Jacobi polynomials. This parameter should satisfy \(\alpha>n-1\), with \(n\) the highest derivative to be estimated.

  • beta (float) – Parameter \(\beta\) of the weight function of the Jacobi polynomials. This parameter should satisfy \(\beta>n-1\), with \(n\) the highest derivative to be estimated. The stopband slope is given by \(\mu=\min\{\alpha,\beta\}+1\), i.e., frequencies higher than the cutoff frequency are attenuated by \(20\mu\) dB per decade. Frequencies lower than the cutoff frequency are attenuated by \(0\,\) dB.

  • N (int) – Truncation order of the generalized Fourier series. A delay-free derivative approximation is only possible for \(N\geq 1\). The differentiator is parametrized by default such that the non-zero delay is minimized for the choice \(N\geq 1\). See the method set_theta for more details.

  • T (float) – Filter window length. Takes a positive values if the length has to be specified. The cutoff frequency is then computed automatically. It should take the value None if the cutoff frequency is specified.

  • wc (float) – Cutoff frequency of the differentiator. Takes a positive values if the cutoff frequency has to be specified. The filter window length is then computed automatically. It should take the value None if the filter window length is specified.

  • display (bool) – Boolean variable indicating if all the information characterizing the differentiator should be printed.

  • corr (bool) – Boolean variable that indicates if errors in the DC component of the approximated signal stemming from the discretization should be corrected.

checkParameters(der=None)

Check if window length is too small. Function raises an error if T<ts and gives a warning if aliasing effects are to be expected.

computeTfromWc(wc)

This function computes the filter window length for a desired cutoff frequency.

Parameters:

wc (float) – Cutoff frequency.

discretize(der, method='mid-point', redFilLength=False, redTol=0.01, discreteSpectrum=False)

This function performs the discretization of the filter for the estimation of the derivative of order \(der\). Three discretization schemes are implemented: midpoint, trapezoidal and using the analytical integration. The mid-point and the analytic integration methods uses one filter coefficient less than the remaining. It also reduces the estimation delay by half a sampling period. The analytical integration rules are recommended for small filter window lengths, i.e., in general less than 20 filter coefficients. The error stemming from the discretization is corrected using a correction factor, if the differentiator has been initialized to do so. When the parameters \(\alpha\) and \(\beta\) are large, the filter kernel has very low values at the beginning and the at the end of the filter window. The length of the window can be reduced to save computation time and memory. This can be performed by enabling the redFilterLength parameter and giving a tolerance redTolerance. This tolerance automatically computes the size of the new window such that the truncation is performed symmetrically. If this is enabled, the functions also returns the times at which the filter was truncated.

Parameters:

  • der (int) – Order of the derivative to be estimated.

  • method (string) – Discretization scheme: “mid-point”, “trapezoidal”, “analytic”, “simpson rule”, and “analytic trapezoidal”.

  • reduceFilLength (bool) – Reduce or not the filter window length.

  • redTol (float) – Tolerance to be used when the filter length is reduced.

  • discreteSpectrum (bool) – If it is set, then the parameter \(\theta\) used in the discretization is returned. See survey paper for more details.

Returns:

  • coeff (dictionary) - Discretized filter in a dict where the keys are the derivative for which a filter has been discretized. Each element is a dict. with keys the used discretization methods. If the correction of the DC component has been enabled with the parameter corr of the class initialization, this output contains the corrected filter coefficients.

  • tau_1 (float) - If redFilLength is set, tau_1 is the time where the filter window is reduced before at the left side of the interval. The estimation delay is reduced by tau_1.

  • tau_2 (float) - If redFilLength is set, tau_2 is the time where the filter window is reduced before at the right side of the interval. This value does not affect the delay.

  • theta (float) - If discreteSpectrum is set then the parameter \(\theta\) is also returned.

estimateDer(k, x, method='mid-point', conv='same', redFilLength=False, redTol=0.01)

This function estimates the derivative of order \(k\geq0\) using the discretization method given. If the filter was not discretized before the function performs the discretization. See the method discretize for more details on the discretization.

Parameters:

  • k (int) – Order of the derivative to be estimated.

  • x (numpy.ndarray) – Signal whose derivative has to be estimated.

  • conv (str) – Parameter to specify the type of convolution the numpy conv function does. See the numpy documentation for more details.

  • method (str) – Discretization method: “mid-point”, “trapezoidal”, “analytic”

  • reduceFilterLength (bool) – Specify whether or not the filter window length should be reduced or not. See the discretize method for more details.

  • redTol (float) – Tolerance to be used when the filter length is reduced

Returns:

Estimated derivative in a numpy array with the same dimensions as the variable x

evalKernel(t)

This function evaluates the kernel of the algebraic differentiator at times t. It corresponds to the impulse response of the filter.

Parameters:

t – Time instants where the kernel should be evaluated.

Returns:

  • g (numpy.ndarray) - Evaluated kernel in a with same dimensions as t.

evalKernelDer(t, k)

This function evaluates the derivative of order \(k\) of the algebraic differentiator at times t. If \(k=0\) the kernel itself is evaluated.

Parameters:

  • t (numpy array) – Time instants where the derivative should be evaluated.

  • k (int) – Order of the derivative to be evaluated.

Returns:

Evaluated derivative in a numpy array with same dimensions as t.

exportFilterCoefficients2Ccode(n, method='mid-point', filename='g', header='G')

Export the filter coefficients to a C header file.

This method exports the filter coefficients computed by the AlgebraicDifferentiator object to a C header file. The filter coefficients are discretized using the specified method and written to a C array in the header file. The sampling period and the filter coefficients are hard coded. The user should not adjust the filter coefficients in the header file. Instead, the filter coefficients should be adjusted in the Python code and the header file should be regenerated. For an algebraic differentiator with window length T=20*ts, with ts the sampling period, the function exportFilterCoefficients2Ccode generates for n=1 the following header file:

#ifndef G1_H
#define G1_H

#define WINDOW_LENGTH_G1 20
#define TS_AlgDiff 0.0100000000

static const double g1[] = {
    0.123456789012345678901234567890,
    0.234567890123456789012345678901,
    // More coefficients...
};

#endif // G1_H
Parameters:

  • n (int) – The filter length.

  • method (str, optional) – The discretization method. Defaults to ‘mid-point’.

  • filename (str, optional) – The base name of the header file. Defaults to ‘g’.

  • header (str, optional) – The prefix for the header guard. Defaults to ‘G’.

Returns:

None

get_N()

This function returns the parameter \(N\).

Returns:

  • \(N\) (float) - The parameter \(N\).

get_T()

This function returns the filter window length of the algebraic differentiator.

Returns:

  • \(T\) (float) - The filter window length \(T\).

get_alpha()

This function returns the parameter \(\alpha\).

Returns:

  • \(\alpha\) (float) - The parameter \(\alpha\).

get_ampAndPhaseFilter(omega)

This function evaluates the amplitude and the phase of the Fourier transform of the algebraic differentiator at the frequencies omega.

Parameters:

omega (numpy array) – Frequencies where the amplitude and phase should be evaluated

Returns:

  • amp (numpy array) - Amplitude of the Fourier transform of the filter.

  • phase (numpy array) - Phase of the Fourier transform of the filter.

get_ampSpectrumDiscreteFilter(omega, n, method='mid-point')

This function computes the amplitude spectrum of the discretized filter for the estimation of the \(n\) -th derivative at the frequencies \(\omega\). The filter is discretized using the given method. See the discretize method for more details.

Parameters:

  • omega (numpy array) – Frequencies where the amplitude should be evaluated.

  • n (integer) – Derivative to be estimated.

  • method (string) – Method used for the discretization: “mid-point”, “trapezoidal”, “analytic”.

Returns:

  • amplitude (numpy array) - Amplitude of the Fourier transform of the discretized filter evaluated at omega.

  • phase (numpy array) - Phase of the Fourier transform of the discretized filter evaluated at omega.

get_asymptotesAmpFilter(omega)

This function evaluates the upper and lower bounds of the amplitude of the Fourier transform of the algebraic differentiator at the frequencies omega. Note that these bounds hold only for frequencies greater than the cutoff frequency.

The function also return the approximation as a low pass filter.

Parameters:

omega (numpy array) – Frequencies where the bounds should be evaluated

Returns:

  • ub - (numpy array) - Upper bound for the amplitude spectrum evaluated at omega..

  • lb - (numpy array) - Lower bound for the amplitude spectrum evaluated at omega..

  • mb - (numpy array) - Lowpass approximation of the filter evaluated at omega..

get_beta()

This function returns the parameter \(\beta\).

Returns:

  • \(\beta\) (float) - The parameter \(\beta\).

get_cutoffFreq()

This function returns the cutoff frequency \(\omega_c\) of the algebraic differentiator.

Returns:

  • \(\omega_c\) (float) - The cutoff frequency \(\omega_c\).

get_degreeExactness(n)

This function returns the degree of exactness \(\gamma\) when the \(n\)-th derivative is approximated.

Returns:

  • \(\gamma\) (int) - The degree of exactness \(\gamma\).

get_delay()

This function returns the estimation delay \(\delta_t\) of the the algebraic differentiator.

Returns:

  • \(\delta_t\) (float) - The delay \(\delta_t\) of the continuous time differentiator

get_delayDiscrete()

This function returns the estimation delay \(\delta_{t,\mathrm{d}}\) of the discrete algebraic differentiator. The delay can vary depending on the used discretization method.

Returns:

Dictionary with keys the used discretization schemes. for each key a value of the delay is provided.

get_discretizationError(k, Omega, n=1000, method='mid-point')

This function computes the error \(\mathcal{J}=\frac{\int_{0}^{\Omega}\left|{\mathcal{F}\left\{g^{(n)}-\hat{g} ^{(n)}\right\}(\omega)}\right|^2\mathrm{d}\omega} {\int_{0}^{\Omega}\left|{\mathcal{F}\left\{g^{(n)}\right\}(\omega)}\right|^2\mathrm{d}\omega}\). Therein \(g\) and \(\hat{g}\) are the continuous and discrete time differentiators, respectively. A reasonable choice for \(\Omega_N\) is the Nyquist frequency \(\pi/t_s\). The integral is approximated using the trapezoidal rule.

Parameters:

  • k (int) – Order of derivative to be estimated.

  • Omega (float) – Upper bound of integration interval.

  • n (int) – The interval \([0,\Omega]\) is divided into n parts.

Returns:

cost function \(\mathcal{J}\)

get_integralKernel(t, nested=1)

This function returns the nested integral of the kernel of the algebraic with respect to the time variable. The integration is performed from 0 to t. Raises and error if the order of the nested integral is higher than 2.

Parameters:

  • t (numpy.ndarray) – Time instants where the step response should be evaluated.

  • nested (int) – order of nested integrals

Returns:

  • The value of the integral (float) - The value of the integral.

get_ratioNyquistCutoff(k)

This function computes the ratio \(k_N=20\log_{10}\left(\frac{\omega_N^k\big|\mathcal{G}(\omega_N)\big|}{\omega_c^k\Big|\mathcal{G}(\omega_c)\Big|}\right)\), with \(\omega_N=\pi/t_s\), the Nyquist frequency and \(\omega_c\) the cutoff frequency.

Parameters:

k (list) – Orders of derivatives to be estimated. Must be a list of natural numbers.

Returns:

-\(k_N\) (numpy.ndarray) - \(k_N\) with same dimensions as the variable k

get_stepResponse(t)

This function returns the step response of the differentiator evaluated at the time instants in t.

Parameters:

t (numpy.ndarray) – Time instants where the step response should be evaluated.

Returns:

get_theta()

This function returns the parameter \(\vartheta\).

Returns:

  • \(\vartheta\) (float) - The parameter \(\vartheta\).

get_ts()

This function returns the sampling period.

Returns:

  • \(t_{s}\) (float) - The sampling period \(t_{s}\).

printParam()

This function prints all the parameters of the algebraic differentiator.

reduceFilterLength(der, tol=0.01)

This function returns a distribution function that can be used to reduce the filter window length. The length is reduced such that the truncation is of the same amount on both sides of the filter window.

Parameters:

  • der (int) – The sought derivative.

  • tol (float) – The tolerance that for reducing the filter length

Returns:

  • tau1 (float) - New starting point of the window. The value 0, i.e., the old

    starting point, is taken as the reference.

  • tau2 (float) - New end point of the window. The value 0, i.e., the old starting

    point, is taken as the reference.

  • d (numpy.ndarray) - Distribution function used for the truncation.

  • t (numpy.ndarray) - Times instants where distribution function has been evaluated.

  • n (int) - Factor relating the sampling rate of the measurements and the

    sampling rate used for the evaluation of the distribution function.

set_N(N)

This function sets the parameter \(N\) of the algebraic differentiator to the value N. If a filter was discretized earlier, the functions computes the discretized filter with this new parameter.

Parameters:

N (int) – Order of the approximating polynomial.

set_T(T)

This function sets the parameter \(T\) of the window length of the algebraic differentiator to the value T.

Parameters:

T (float) – Filter window length.

set_alpha(alpha)

This function sets the parameter \(\alpha\) of the weight function of the algebraic differentiator to the value alpha. The value must satisfy \(\alpha>n-1\), with \(n\) the highest derivative to be estimated.

Parameters:

alpha (float) – Parameter of the weight function.

set_beta(beta)

This function sets the parameter \(\beta\) of the weight function of the algebraic differentiator to the value beta. The value must satisfy \(\beta>n-1\), with \(n\) the derivative to be estimated. If a filter was discretized earlier, the functions computes the discretized filter with this new parameter.

Parameters:

beta (float) – Parameter of the weight function.

set_samplingPeriod(ts)

This function sets the sampling period \(t_s\) of the discrete measurements.

Parameters:

ts (float) – Sampling period.

set_theta(theta, rootJacobiPol)

This function sets the parameter \(\vartheta\) of the algebraic differentiator to the value theta. The differentiator is parametrized by default such that \(\vartheta\) is the largest zero of the Jacobi polynomial of degree \(N+1\). Thus, the delay is minimized. For a delay-free approximation the choice \(\vartheta=1\) is required. If a filter was discretized earlier, the functions computes the discretized filter with this new parameter.

Parameters:

  • theta (float) – Parameter \(\vartheta\) of the algebraic differentiator.

  • rootJacobiPol (bool) – True if the value theta is equal to a zero of the jacobi polynomial of order \(N+1\). For the delay-free approximation use False, since \(1\) is not a zero.

timeShift(t)

This function computes the time transformation \(\theta(t)=1-2/T\), with \(T\) the window length of the filter.

Parameters:

t (numpy array) – Time instants where the transformation should be evaluated.

Returns:

Evaluated transformation with the same type as the variable t.

weightFcn(a, b, t)

This function evaluates the weight function of the algebraic differentiator at the time instants \(t\).

Parameters:

  • a (float) – Parameter \(\alpha>-1\) of the weight function

  • b (float) – Parameter \(\beta>-1\) of the weight function

  • t (numpy array) – Time instants where weight function should be evaluated.

Returns:

Evaluated weight function in a numpy array.