# 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. res – The result of the fitting (optimization) 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. res – The result of the optimization. scipy.optimize.OptimizerResult

Note

Only use this after using fit_zpk().

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. res – The result of the optimization. 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. A complex array. 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. zpk – A complex array. 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. tf_args – A 1-D list of numerator and denominator coefficients, from higher order to lower order. 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. tf – The transfer function. 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. cost – The cost. 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. cost – The cost. 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 {}. cost – The cost. 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. noise – The geophone noise frequency series. 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. noise – The LVDT noise frequency series. 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 noise – The piecewise noise array. numpy.ndarray