kontrol.core

kontrol.core.controlutils module

Utility function related to python-control library.

kontrol.core.controlutils.check_tf_equal(tf1, tf2, allclose_kwargs={}, minreal=True)

Check if two transfer functions are approximatedly equal by np.allclose.

Parameters:
  • tf1 (control.xferfcn.TransferFunction) – Transfer function 1.
  • tf2 (control.xferfcn.TrasnferFunction) – Transfer function 2.
  • allclose_kwargs (dict, optional) – Keyword arguments passed to np.allclose(), which is used to compare the list of poles and zeros and dcgain. Defaults {}.
  • minreal (boolean) – Use control.minreal to remove canceling zeros and poles before comparison.
Returns:
Return type:

boolean
kontrol.core.controlutils.clean_tf(tf, tol_order=5, small_number=1e-25)

Remove numerator/denominator coefficients that are small outliers

Parameters:
  • tf (TransferFunction) – The transfer function to be cleaned
  • tol_order (float, optional) – If the coefficient is tol_order order smaller than the rest of the coefficients, then this coefficient is an outlier. Defaults 5.
  • small_number (float, optional) – A small number to be added to the log10 in case 0 is encountered.
Returns:

tf_cleaned – The cleaned transfer function.
Return type:

TransferFunction
kontrol.core.controlutils.clean_tf2(tf, tol_order=5, small_number=1e-25)

Remove zeros/poles that are outliers.

Parameters:
  • tf (TransferFunction) – The transfer function to be cleaned.
  • tol_order (float, optional) – If the frequency of the zero/pole is ``tol_order’’ order away from the mean order, then this zero/pole is an outlier. Defaults 5.
  • small_number (float, optional) – A small number to be added to the log10() in case 0 is encountered
Returns:

tf_cleaned – The cleaned transfer function.
Return type:

TransferFunction
kontrol.core.controlutils.clean_tf3(tf, tol_order=5, small_number=1e-25)

Remove first coefficient if it is much smaller than the second

Parameters:
  • tf (TransferFunction) – Transfer function to be cleaned
  • tol_order (float, optional) – First coefficient is removed if it is ``tol_order’’ order smaller than the second coefficient. Remove only if there exists such coefficient in both numerator and denominator.
  • small_number (float, optional) – A small number to be added to the log10() in case 0 is encountered.
Returns:

tf_cleaned – The cleaned TransferFunction
Return type:

TransferFunction
kontrol.core.controlutils.complex2wq(complex_frequency)

Convert a complex frequency to frequency and Q-factor.

Parameters:complex_frequency (complex) – Complex frequency in rad/s.
Returns:
  • wn (float) – The frequency in rad/s
  • q (float) – The Q factor.
kontrol.core.controlutils.convert_unstable_tf(control_tf)

Convert transfer function with unstable zeros and poles to tf without.

Parameters:control_tf (control.xferfcn.TransferFunction) – The transfer function to be converted.
Returns:tf_new – control_tf with unstable zeros and poles flipped.
Return type:control.xferfcn.TransferFunction

Note

Warning can occur when the order gets high, e.g. 100. This happens due to numerical accuracy, i.e. coefficients get astronomically high when order gets high.

kontrol.core.controlutils.generic_tf(zeros=None, poles=None, zeros_wn=None, zeros_q=None, poles_wn=None, poles_q=None, dcgain=1.0, unit='f')

Construct a generic transfer function object.

Parameters:
  • zeros (array, optional) – List of zeros in frequencies. Defaults [].
  • poles (array, optional) – List of poles. Defaults [].
  • zeros_wn (array, optional) – List of natural frequencies of numerator second-order sections.
  • zeros_q (array, optional.) – List of Q-value of numerator second-order sections.
  • poles_wn (array, optional) – List of natural frequencies of denominator second-order sections.
  • poles_q (array, optional.) – List of Q-value of denominator second-order sections.
  • dcgain (float, optional) – The DC gain of the transfer function. Defaults 1.
  • unit (str, optional) – The unit of the zeros, poles and the natural frequencies. Choose from [“f”, “s”, “Hz”, “omega”]. Defaults “f”.
Returns:

tf – The transfer function.
Return type:

control.xferfcn.TransferFunction

Note

No negative sign is needed for negative zeros and poles. For instance, generic_tf(poles=[1], unit=”s”) means \(\frac{1}{s+1}\).

kontrol.core.controlutils.outlier_exists(tf, f, unit='f')

Checks for zeros and poles outside the frequency range.

Parameters:
  • tf (control.xferfcn.TransferFunction) – The transfer function.
  • f (array) – The frequency axis of interest.
  • unit (str, optional) – The unit of the zeros, poles and the natural frequencies. Choose from [“f”, “s”, “Hz”, “omega”]. Defaults “f”.
Returns:

If there’s any zero or pole outside the frequency range.
Return type:

boolean
kontrol.core.controlutils.outliers(tf, f, unit='f')

Returns a list of zeros and poles outside the frequency range.

Parameters:
  • tf (control.xferfcn.TransferFunction) – The transfer function.
  • f (array) – The frequency axis of interest.
  • unit (str, optional) – The unit of the zeros, poles and the natural frequencies. Choose from [“f”, “s”, “Hz”, “omega”]. Defaults “f”.
Returns:

  • outlier_zeros (array) – Zeros outside the frequency range.
  • outlier_poles (array) – Poles outside the frequency range.

Note

We use the python-control package convention for the returned zeros and poles, so to preserve the type and format as much as possible for further processes.

kontrol.core.controlutils.sos(natural_frequencies=None, quality_factors=None, gain=1.0, unit='f')

Second-order sections transfer fucntion.

Parameters:
  • natural_freuqnecies (array, optional) – List of natural frequencies. Defaults [].
  • quality_factors (list, optional) – List of quality factors. Defaults [].
  • gain (float, optional) – The gain of the transfer function. Defaults 1.
  • unit (str, optional) – The unit of the zeros, poles and the natural frequencies. Choose from [“f”, “s”, “Hz”, “omega”]. Defaults “f”.
Returns:

sos – The product of all second-order sections.
Return type:

control.xferfcn.TransferFunction

Note

\(K\prod\left(s^2+\omega_n/Q\,s+\omega_n^2\right)\).

kontrol.core.controlutils.tf_order_split(tf, max_order=20)

Split TransferFunction objects into multiple ones with fewer order.

Parameters:
  • tf (TransferFunction) – The transfer function
  • max_order (int, optional) – The maxmium order of the split transfer functions. Defaults to 20 (the foton limit).
Returns:

The list of splitted transfer functions.
Return type:

list of TransferFunction.
kontrol.core.controlutils.tfmatrix2tf(sys)

Convert a matrix of transfer functions to a MIMO transfer function.

Parameters:sys (list of (list of control.xferfcn.TransferFunction)) – The transfer function matrix representing a MIMO system. sys[i][j] is the transfer function from the i+1 input port to the j+1 output port.
Returns:The transfer function of the MIMO system.
Return type:control.xferfcn.TransferFunction
kontrol.core.controlutils.zpk(zeros, poles, gain, unit='f', negate=True)

Zero-pole-gain definition of transfer function.

Parameters:
  • zeros (list of floats) – A list of the location of the zeros
  • poles (list of floats) – A list of the location of the poles
  • gain (float) – The static gain of the transfer function
  • unit (str, optional) – The unit of the zeros, poles and the natural frequencies. Choose from [“f”, “s”, “Hz”, “omega”]. Defaults “f”.
  • negate (boolean, optional) – Negate zeros and poles in specification so negative sign is not needed for stable zeros and poles. Default to be True.
Returns:

zpk_tf – The zpk defined transfer function
Return type:

control.xferfcn.TransferFunction

Notes

Refrain from specifying imaginary zeros and poles. Use kontrol.utils.sos() for second-order sections instead. The zero and poles are negated by default.

kontrol.core.math module

Common math library

kontrol.core.math.log_mse(x1, x2, weight=None, small_multiplier=1e-06)

Logarithmic mean square error/Mean square log error

Parameters:
  • x1 (array) – Array
  • x2 (array) – Array
  • weight (array or None, optional) – weighting function. If None, defaults to np.ones_like(x1)
  • small_multiplier (float, optional) – x1 will be modified by x1`+`small_multiplier`*`np.min(x2) if 0 exists in x1. Same goes to x2. If 0 both exists in x1 and x2, raise.
Returns:

Logarithmic mean square error between arrays x1 and x2.
Return type:

float
kontrol.core.math.mse(x1, x2, weight=None)

Mean square error

Parameters:
  • x1 (array) – Array
  • x2 (array) – Array
  • weight (array or None, optional) – weighting function. If None, defaults to np.ones_like(x1)
Returns:

Mean square error between arrays x1 and x2.
Return type:

float
kontrol.core.math.polyval(p, x)
kontrol.core.math.quad_sum(*spectra)

Takes any number of same length spectrum and returns the quadrature sum.

Parameters:*spectra – Variable length argument list of the spectra.
Returns:qs – The quadrature sum of the spectra.
Return type:np.ndarray

kontrol.core.spectral module

Spectral analysis related function library.

kontrol.core.spectral.asd2rms(asd, f=None, df=1.0, return_series=True)

Calculate root-mean-squared value from amplitude spectral density

Parameters:
  • asd (array) – The amplitude spectral density
  • f (array, optional) – The frequency axis. Defaults None.
  • df (float, optional) – The frequency spacing. Defaults 1.
  • return_series (bool, optional) – Returns the RMS as a frequency series, where each value is the integrated RMS from highest frequency. If False, returns a single RMS value for the whole spectrum. Defaults True.
Returns:

  • array – The integrated RMS series, if return_series==True.
  • float – The integrated RMS value, if return_series==False.

Notes

The integrated RMS series is defined as

\[x_\mathrm{RMS}(f) = \int_\infty^{f}\,x(f')^2\,df'\,,\]

where \(x(f)\) is the amplitude spectral density.

When return_series is False, only \(x_\mathrm{RMS}(0)\) is returned.

kontrol.core.spectral.asd2ts(asd, f=None, fs=None, t=None, window=None, zero_mean=True)

Simulate time series from amplitude spectral density

Parameters:
  • asd (array) – The amplitude spectral density.
  • f (array, optional) – The frequency axis of the amplitude spectral density. This is used to calculate the sampling frequency. If fs is not specified, f must be specified. Defaults None.
  • fs (float, optional) – The sampling frequency in Hz. If f is specified, the last element of f will be treated as the Nyquist frequency so the double of it would be the sampling frequency. Defaults None.
  • t (array, optional) – The desired time axis for the time series. If t is specified, then the time series will be interpolated using numpy.interp() assuming that the time series is periodic. Default None.
  • window (array, optional) – The FFT window used to compute the amplitude spectral density. Defaults None.
  • zero_mean (boolean, optional) – Returns a time series with zero mean. Defaults True.
Returns:

  • t (array) – Time axis.
  • time_series (array) – The time series

Notes

Using a custom time axis is not recommended as interpolation leads to distortion of the signal. To extend the signal in time, it’s recommended to repeat the original time series instead.

kontrol.core.spectral.pad_above_maxima(series, pad_index=-1, **kwargs)

Pad series above local maxima

Parameters:
  • series (array) – The series to be padded.
  • pad_index (int, optional) – The index of the local maxima. Defaults to -1.
  • **kwargs – Keyword arguments passed to scipy.signal.argrelmin()
Returns:

series_padded – The padded series
Return type:

array
kontrol.core.spectral.pad_above_minima(series, pad_index=-1, **kwargs)

Pad series above local minima

Parameters:
  • series (array) – The series to be padded.
  • pad_index (int, optional) – The index of the local minima. Defaults to -1.
  • **kwargs – Keyword arguments passed to scipy.signal.argrelmin()
Returns:

series_padded – The padded series
Return type:

array
kontrol.core.spectral.pad_below_maxima(series, pad_index=0, **kwargs)

Pad series below local maxima

Parameters:
  • series (array) – The series to be padded.
  • pad_index (int, optional) – The index of the local maxima. Defaults to 0.
  • **kwargs – Keyword arguments passed to scipy.signal.argrelmin()
Returns:

series_padded – The padded series
Return type:

array
kontrol.core.spectral.pad_below_minima(series, pad_index=0, **kwargs)

Pad series below local minima

Parameters:
  • series (array) – The series to be padded.
  • pad_index (int, optional) – The index of the local minima. Defaults to 0.
  • **kwargs – Keyword arguments passed to scipy.signal.argrelmin()
Returns:

series_padded – The padded series
Return type:

array
kontrol.core.spectral.three_channel_correlation(psd1, psd2=None, psd3=None, csd12=None, csd13=None, csd21=None, csd23=None, csd31=None, csd32=None, returnall=True)

Noise estimation from three sensors’ readouts.

Parameters:
  • psd1 (array) – The power spectral density of the readout of the first sensor.
  • psd2 (array, optional) – The power spectral density of the readout of the second sensor. Defaults None.
  • psd3 (array, optional) – The power spectral density of the readout of the third sensor. Defaults None.
  • csd12 (array, optional) – Cross power spectral density between readout 1 and 2. If not specified, this will be estimated as psd1*psd2/csd21. Default None.
  • csd13 (array, optional) – Cross power spectral density between readout 1 and 3. If not specified, this will be estimated as psd1*psd3/csd31. Default None.
  • csd21 (array, optional) – Cross power spectral density between readout 2 and 1. If not specified, this will be estimated as psd2*psd1/csd12. Default None.
  • csd23 (array, optional) – Cross power spectral density between readout 2 and 3. If not specified, this will be estimated as psd2*psd3/csd32. Default None.
  • csd31 (array, optional) – Cross power spectral density between readout 3 and 1. If not specified, this will be estimated as psd1*psd3/csd13. Default None.
  • csd32 (array, optional) – Cross power spectral density between readout 3 and 1. If not specified, this will be estimated as psd3*psd2/csd23. Default None.
  • returnall (boolean, optional) – If True, return all three noise estimations. If False, return noise estimation of first sensor only. Defaults True.
Returns:

  • noise1 (array) – Power spectral density of the estimated noise in psd1.
  • noise2 (array, optional) – Power spectral density of the estimated noise in psd2. Returns only if returnall==True
  • noise3 (array, optional) – Power spectral density of the estimated noise in psd3. Returns only if returnall==True

Notes

The PSD of the noise in psd1 is then computed as

\[P_{n_1n_1}(f) = \left\lvert P_{x_1x_1}(f) - \frac{P_{x_1x_3}(f)}{P_{x_2x_3}(f)}P_{x_2x_1}\right\vert\,,\]

If returnall is True, at least psd1, psd2, psd3, (csd13 or csd31), (csd23 or csd32), and (csd12 and csd21) must be provided.

References

[2]R. Sleeman, A. Wettum, and J. Trampert. Three-channel correlation analysis: A new technique to measure instrumental noise of digitizers and seismic sensors. Bulletin of the Seismological Society of America, 96:258–271, 2006.
kontrol.core.spectral.two_channel_correlation(psd, coh)

Noise estimation from two identical sensors’ readouts.

Parameters:
  • psd (array) – The power spectral density of the readout of the sensor
  • coh (array) – The coherence between readout of the sensor and another identical sensor.
Returns:

noise – Power spectral density of the estimated noise.
Return type:

array

Notes

The PSD of the noise is computed as

\[P_{nn}(f) = P_{x_1x_1}(f)\left(1-C_{x_1x_2}(f)^{\frac{1}{2}}\right)\,,\]

where \(P_{x_1x_1}(f)\) is the power spectral density of the readout and \(C_{x_1x_2}(f)\) is the coherence between the two sensor readouts.

References

[1]Aaron Barzilai, Tom VanZandt, and Tom Kenny. Technique for measurement of the noise of a sensor in the presence of large background signals. Review of Scientific Instruments, 69:2767–2772, 07 1998.

kontrol.core.foton module

KAGRA/LIGO Foton related utilities.

kontrol.core.foton.foton2tf(foton_string)

Convert a Foton string to TransferFunction

Parameters:foton_string (str) – The Foton string, e.g. zpk([0], [1; 1], 1, “n”).
Returns:tf – The transfer function.
Return type:TransferFunction
kontrol.core.foton.notch(frequency, q, depth, significant_figures=6)

Returns the foton expression of a notch filter.

Parameters:
  • frequency (float) – The notch frequency (Hz).
  • q (float) – The quality factor.
  • depth (float) – The depth of the notch filter (magnitude).
  • significant_figures (int, optional) – Number of significant figures to print out. Defaults to 6.
Returns:

The foton representation of this notch filter.
Return type:

str
kontrol.core.foton.rpoly2tf(foton_string)

Converts rpoly Foton strings to TransferFunction

Parameters:foton_string (str) – The rpoly Foton string. E.g. rpoly([1; 2; 3], [2; 3; 4], 5)
kontrol.core.foton.tf2foton(tf, expression='zpk', root_location='s', significant_figures=6, itol=1e-25, epsilon=1e-25)

Convert a single transfer function to foton expression.

Parameters:
  • tf (TransferFunction) – The transfer function object.
  • expression (str, optional) – Format of the foton expression. Choose from [“zpk”, “rpoly”]. Defaults to “zpk”.
  • root_location (str, optional) – Root location of the zeros and poles for expression==”zpk”. Choose from [“s”, “f”, “n”]. “s”: roots in s-plane, i.e. zpk([…], […], …, “s”). “f”: roots in frequency plane, i.e. zpk([…], [,,,], …, “f”). “n”: roots in frequency plane but negated and gains are normalized, i.e. real parts are positive zpk([…], […], …, “n”). Defaults to “s”.
  • significant_figures (int, optional) – Number of significant figures to print out. Defaults to 6.
  • itol (float, optional) – Treating complex roots as real roots if the ratio of the imaginary part and the real part is smaller than this tolerance Defaults to 1e-25.
  • epsilon (float, optional) – Small number to add to denominator to prevent division error. Defaults to 1e-25.
Returns:

foton_expression – The foton expression in selected format.
Return type:

str
kontrol.core.foton.tf2rpoly(tf, significant_figures=6)

Convert a transfer function to foton rpoly expression.

Parameters:
  • tf (TransferFunction) – The transfer function object
  • significant_figures (int, optional) – Number of significant figures to print out. Defaults to 6.
Returns:

Foton express in foton rpoly expression.
Return type:

str

Notes

Only works for transfer functions with less than 20 orders.

kontrol.core.foton.tf2zpk(tf, root_location='s', significant_figures=6, itol=1e-25, epsilon=1e-25)

Convert a single transfer function to foton zpk expression.

Parameters:
  • tf (TransferFunction) – The transfer function object.
  • root_location (str, optional) – Root location of the zeros and poles. Choose from [“s”, “f”, “n”]. “s”: roots in s-plane, i.e. zpk([…], […], …, “s”). “f”: roots in frequency plane, i.e. zpk([…], [,,,], …, “f”). “n”: roots in frequency plane but negated and gains are normalized, i.e. real parts are positive zpk([…], […], …, “n”). Defaults to “s”.
  • significant_figures (int, optional) – Number of significant figures to print out. Defaults to 6.
  • itol (float, optional) – Treating complex roots as real roots if the ratio of the imaginary part and the real part is smaller than this tolerance Defaults to 1e-25.
  • epsilon (float, optional) – Small number to add to denominator to prevent division error. Defaults to 1e-25.
Returns:

The foton zpk expression in selected format.
Return type:

str

Notes

Only works for transfer functions with less than 20 orders.

kontrol.core.foton.zpk2tf(foton_string)

Convert a Foton ZPK string to TransferFunction

foton_string : str
The Foton ZPK string, e.g. zpk([0], [1; 1], 1, “n”).
Returns:tf – The transfer function.
Return type:TransferFunction