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.

Returns:

T (float) - filter window length

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 rule uses one filter coefficient less than the trapezoidal rule. It also reduces the estimation delay by half a sampling period. The analytical integration rule is recommended for small filter window lengths, i.e., in general less than 20 filter coefficients. This discretization method can only be used for the first order or any higher derivative. 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”.
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 array) – Signal whose derivative has to be estimated.
conv (string) – Parameter to specify the type of convolution the numpy conv function does. See the numpy documentation for more details.
method (string) – 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 (numpy array) – Time instants where the kernel should be evaluated.
Returns:: Evaluated kernel in a numpy array 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.

get_N()

This function returns the parameter \(N\).

Returns:: \(N\) as a float.

get_T()

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

Returns:: Filter window length as a float.

get_alpha()

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

Returns:: \(\alpha\) as a float.

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\) as a float.

get_cutoffFreq()

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

Returns:: Cutoff frequency as a float.

get_degreeExactness(n)

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

Returns:: Degree of exactness as an integer.

get_delay()

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

Returns:: \(\delta_t\) as a float

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 (integer) – Order of derivative to be estimated.
Omega (float) – Upper bound of integration interval.
n (integer) – The interval \([0,\Omega]\) is divided into n parts.

Returns:

cost function \(\mathcal{J}\)

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 of natural numbers) – Orders of derivatives to be estimated.
Returns:: \(k_N\) in a numpy array 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 array) – Time instants where the step response should be evaluated.
Returns:: Evaluated step response in a numpy array.

get_theta()

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

Returns:: \(\vartheta\) as a float.

get_ts()

This function returns the sampling period.

Returns:: Sampling period as a float.

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 array) - Distribution function used for the truncation.
t (numpy array) - 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.