kontrol.frequency_series package

Primary modules

kontrol.frequency_series.frequency_series module

Frequency series class.

class kontrol.frequency_series.frequency_series.FrequencySeries(f, x)

Bases: object

Frequency series class

f

Frequency axis

Type:array
x

Frequency series data.

Type:array
x_empirical

Frequency series of the empirical model.

Type:array or None
model_empirical

The model function whose first argument is the frequency axis and the rest being an arbitrary number of model parameters to be fit.

Type:func(f, a, b, c, ..) -> array or None
args_empirical_model

The optimized arguments passed to the model_empirical.

Type:array or None
f_zpk

The frequency axis used during ZPK fitting.

Type:array or None
x_zpk

The frequency series data used during ZPK fitting. Note: this is a complex array.

Type:array or None
tf_zpk

The transfer function the best fit the data using ZPK model.

Type:control.xferfcn.TransferFunction or None
args_zpk_model

A 1-D list of zeros, poles, and gain. Zeros and poles are in unit of Hz.

Type:array or None
f_tf

The frequency series data used during transfer function fitting.

Type:array or None
x_tf

The frequency series data used during transfer function fitting. Note: this is a complex array.

Type:array or None
tf

The modeled transfer function.

Type:control.xferfcn.TransferFunction or None
args_tf_model

A 1-D list of numerator and denominator coefficients, from higher order to lower order.

Type:array or None
fit_empirical(model, x0=None, error_func=<function log_mse>, error_func_kwargs={}, optimizer=<function minimize>, optimizer_kwargs={})

Fit frequency series data with an empirical model. (Local optimize)

Parameters:
  • model (func(f, a, b, c, ..) -> array) – The model function whose first argument is the frequency axis and the rest being an arbitrary number of model parameters to be fit.
  • x0 (array, optional) – The initial parameters for fitting. Defaults None. If None, defaults to np.ones()
  • error_func (func(x1: array, x2: array) -> float) – The function that evaluate the error between arrays x1 and x2. Defaults to kontrol.core.math.log_mse, which evaluates the logarithmic mean square error.
  • error_func_kwargs (dict, optional) – Keyword arguments passed to the error function. Use this to specify weighting function {“weight”: weight_func}. Defaults to {}.
  • optimizer (func, optional) – The optimization function which has the signature func(func, args, bounds, **kw) -> scipy.optimize.OptimizeResult. Defaults to scipy.optimize.minimize.
  • optimizer_kwargs (dict, optional) – Keyword arguments passed to the optimization function. Defaults {} but will set to {“method”: “Powell”, “x0”=x0} if optimizer is default.
Returns:

res – The result of the fitting (optimization)
Return type:

scipy.optimize.OptimizeResult
fit_tf(x0=None, log_var=True, error_func=<function log_mse>, error_func_kwargs={}, optimizer=<function minimize>, optimizer_kwargs={})

Fit frequency series with a transfer function model

Parameters:
  • x0 (array or None, optional) – The initial parameters defining the initial transfer function. A 1-D list of numerator and denominator coefficients, from higher order to lower order. Defaults None. If None, will use the result from the ZPK fitting.
  • log_var (boolean, optional) – Optimize the log of variables instead. Useful for variables that have very large dynamic range Defaults True.
  • error_func (func(x1: array, x2: array) -> float, optional) – The function that evaluate the error between arrays x1 and x2. Defaults to kontrol.core.math.log_mse, which evaluates the logarithmic mean square error.
  • error_func_kwargs (dict, optional) – Keyword arguments passed to the error function. Use this to specify weighting function {“weight”: weight_func}. Defaults to {}.
  • optimizer (func, optional) – The optimization function which has the signature func(func, args, bounds, **kw) -> scipy.optimize.OptimizeResult. Defaults to scipy.optimize.minimize.
  • optimizer_kwargs (dict, optional) – Keyword arguments passed to the optimization function. Defaults {} but will set to {“method”: “Powell”, “x0”: x0} if optimizer is default.
Returns:

res – The result of the optimization.
Return type:

scipy.optimize.OptimizerResult

Note

Only use this after using fit_zpk().

fit_zpk(order, fit='x_empirical', padding=False, padding_order=1.0, error_func=<function log_mse>, error_func_kwargs={}, optimizer=<function differential_evolution>, optimizer_kwargs={})

Fit frequency series with a zpk model.

Parameters:
  • order (int) – The order of the ZPK model to be used.
  • fit (str, optional) – Choose the data to be fit, choose from [“x”, “x_empirical”].
  • padding (boolean, optional) – Pad the data by continuous white noise. Defaults False.
  • padding_order (float, optional) – The number of decades to be padded on both sides of the series. Defaults to 1.
  • error_func (func(x1: array, x2: array) -> float) – The function that evaluate the error between arrays x1 and x2. Defaults to kontrol.core.math.log_mse, which evaluates the logarithmic mean square error.
  • error_func_kwargs (dict, optional) – Keyword arguments passed to the error function. Use this to specify weighting function {“weight”: weight_func}. Defaults to {}.
  • optimizer (func, optional) – The optimization function which has the signature func(func, args, bounds, **kw) -> scipy.optimize.OptimizeResult. Defaults to scipy.optimize.differential_evolution.
  • optimizer_kwargs (dict, optional) – Keyword arguments passed to the optimization function. Defaults {} but will set to {“workers”: -1, “updating”:”deferred”} if optimizer is default.
Returns:

res – The result of the optimization.
Return type:

scipy.optimize.OptimizerResult

Note

For now, we support models with equal number of zeros and poles only.

Best use with log-space frequency series or after using fit_empirical().

Secondary modules

kontrol.frequency_series.conversion module

Conversion functions for frequency series fitting.

This is a lower level module which users are not expect to use.

kontrol.frequency_series.conversion.args2controltf(zpk_args)

Convert a list of zeros, poles, and gain to control.tf

Parameters:zpk_args (array) – A 1-D list of zeros, poles, and gain. Zeros and poles are in unit of Hz.
kontrol.frequency_series.conversion.args2tf(f, tf_args)

Returns an array of transfer function evaluted at frequency f.

Parameters:
  • f (array) – The frequency axis.
  • tf_args (array) – A 1-D list of numerator and denominator coefficients, from higher order to lower order.
Returns:

A complex array.
Return type:

array
kontrol.frequency_series.conversion.args2zpk(f, zpk_args)

Returns an array of ZPK defined transfer function evaluted at frequency f.

Parameters:
  • f (array) – The frequency axis.
  • zpk_args (array) – A 1-D list of zeros, poles, and gain. Zeros and poles are in unit of Hz.
Returns:

zpk – A complex array.
Return type:

array
kontrol.frequency_series.conversion.tf2tf_args(tf)

Returns an array of tf_args used for fitting.

Parameters:tf (control.xferfcn.TransferFunction) – The transfer function.
Returns:tf_args – A 1-D list of numerator and denominator coefficients, from higher order to lower order.
Return type:array
kontrol.frequency_series.conversion.tf_args2tf(tf_args)

Returns a transfer function from tf_args.

Parameters:tf_args (array) – A 1-D list of numerator and denominator coefficients, from higher order to lower order.
Returns:tf – The transfer function.
Return type:control.xferfcn.TransferFunction

kontrol.frequency_series.costs module

Cost functions for fitting

kontrol.frequency_series.costs.cost_empirical_fit(args, f, x, model, error_func=<function log_mse>, error_func_kwargs={})

Cost function for frequency series empirical fitting.

Parameters:
  • args (array) – Empirical model parameters.
  • f (array) – Frequency axis.
  • x (array) – Frequency series data.
  • model (func(f, a, b, c, ..) -> array) – The model function whose first argument is the frequency axis and the rest being an arbitrary number of model parameters to be fit.
  • error_func (func(x1: array, x2: array) -> float) – The function that evaluate the error between arrays x1 and x2. Defaults to kontrol.core.math.log_mse, which evaluates the logarithmic mean square error.
  • error_func_kwargs (dict) – Keyword arguments passed to the error function.
Returns:

cost – The cost.
Return type:

float
kontrol.frequency_series.costs.cost_tf_fit(tf_args, f, x, error_func=<function log_mse>, error_func_kwargs={}, log_var=True)

The cost funcion for gitting a frequency series with transfer function.

Parameters:
  • tf_args (array) – A 1-D list of numerator and denominator coefficients, from higher order to lower order.
  • f (array) – The frequency axis.
  • x (array) – The frequecy series data.
  • error_func (func(x1: array, x2: array) -> float, optional) – The function that evaluate the error between arrays x1 and x2. Defaults to kontrol.core.math.log_mse, which evaluates the logarithmic mean square error.
  • error_func_kwargs (dict, optional) – Keyword arguments passed to the error function. Defaults {}.
  • log_var (boolean, optional) – Optimize the log of variables instead. Useful for variables that have very large dynamic range Defaults True.
Returns:

cost – The cost.
Return type:

float
kontrol.frequency_series.costs.cost_zpk_fit(zpk_args, f, x, error_func=<function log_mse>, error_func_kwargs={})

The cost function for fitting a frequency series with zero-pole-gain.

Parameters:
  • zpk_args (array) – A 1-D list of zeros, poles, and gain. Zeros and poles are in unit of Hz.
  • f (array) – The frequency axis.
  • x (array) – The frequecy series data.
  • error_func (func(x1: array, x2: array) -> float) – The function that evaluate the error between arrays x1 and x2. Defaults to kontrol.core.math.log_mse, which evaluates the logarithmic mean square error.
  • error_func_kwargs (dict, optional) – Keyword arguments passed to the error function. Defaults {}.
Returns:

cost – The cost.
Return type:

float

kontrol.frequency_series.noise_models module

Noise models for empirical fitting.

kontrol.frequency_series.noise_models.geophone_noise(f, n0=2e-06, fc=0.9, exp1=-3.5, exp2=-1.0)

Geophone noise model.

Parameters:
  • f (array) – Frequency axis
  • n0 (float, optional) – The noise level at 1 Hz with the first exponent. In um/rtHz. Defaults to the typical value 2e-6.
  • fc (float, optional) – The corner frequency at which the exponent changes. Defaults to the typical value 0.9.
  • exp1 (float, optional) – The exponent of the frequency dependency before the corner frequency. Defaults -3.5.
  • exp2 (float, optional) – The exponent of the frequency dependency after the corner frequency. Defaults -1.
Returns:

noise – The geophone noise frequency series.
Return type:

numpy.ndarray

Notes

The geophone noise noise typically has a \(f^{-3.5}\) dependency before the corner frequency and has a \(f^{-1}\) dependency after that.

kontrol.frequency_series.noise_models.lvdt_noise(f, n0=0.008, fc=4.5, exp1=-0.5, exp2=0.0)

LVDT noise model.

Parameters:
  • f (array) – Frequency axis.
  • n0 (float, optional.) – The noise level at 1 Hz with the first exponent. In um/rtHz. Defaults to the typical value 8e-3.
  • fc (float, optional.) – Defaults to the typical value 4.5 Hz. The corner frequency at which the exponent changes.
  • exp1 (float, optional) – The exponent of the frequency dependency before the corner frequency. Defaults -0.5.
  • exp2 (float, optional) – The exponent of the frequency dependency after the corner frequency. Defaults 0.
Returns:

noise – The LVDT noise frequency series.
Return type:

numpy.ndarray

Notes

The LVDT noise noise typically has a \(f^{-0.5}\) dependency before the corner frequency and is flat after that.

kontrol.frequency_series.noise_models.piecewise_noise(f, n0, exp=[0], fc=[0])

Piecewise noise specified corner frequencies and exponents

Parameters:
  • f (list of int/float or numpy.ndarray) – The frequency axis of the noise.
  • n0 (int/float) – The noise level at 1 Hz with the first exponent.
  • exp (list of int/float) – The list of exponents of each section of noise separated by the corner frequencies.
  • fc (list of int/float) – The list of corner frequencies in increaing order. The length of fc must be 1 less then the length of exp
Returns:

noise – The piecewise noise array.
Return type:

numpy.ndarray