kontrol.curvefit package¶

Primary modules¶

kontrol.curvefit.curvefit module¶

Base class for curve fitting

class kontrol.curvefit.curvefit.CurveFit(xdata=None, ydata=None, model=None, model_kwargs=None, cost=None, optimizer=None, optimizer_kwargs=None)¶

Bases: object

Base class for curve fitting

Parameters:

xdata (array, ydata: array) -> float) – The independent variable data / data on the x axis. Defaults to None.
ydata (array or None, optional) – The dependent variable data / data on the y axis. Defaults to None.
model (func(x: array, args: array, **kwargs) -> array, or None, optional) – The model used to fit the data. args in model is an array of parameters that define the model. Defaults to None
model_kwargs (dict or None, optional) – Keyword arguments passed to the model. Defaults to None.
cost (kontrol.curvefit.Cost or func(args, model, xdata, ydata) -> array) – Cost function.
xdata – The cost function to be used to fit the data. First argument is a list of parameters that will be passed to the model. This must be pickleable if multiprocessing is to be used. Defaults to None.
optimizer (func(func, **kwargs) -> OptimizeResult, or None, optional) – The optimization algorithm use for minimizing the cost function.
optimizer_kwargs (dict or None, optional) – Keyword arguments passed to the optimizer function. Defaults to None.

cost¶: The cost function to be used to fit the data.

fit(model_kwargs=None, cost_kwargs=None, optimizer_kwargs=None)¶

Fit the data

Sets self.optimized_args and self.optimize_result.

Parameters:	model_kwargs (dict or None, optional) – Overriding keyword arguments in self.model_kwargs. Defaults to None. cost_kwargs (dict or None, optional) – Overriding keyword arguments in self.cost_kwargs. Defaults to None. optimizer_kwargs (dict or None, optional) – Overriding keyword argumetns in self.optimizer_kwargs. Defaults to None.
Returns:
Return type:	scipy.optimizer.OptimizeResult

model¶: The model used to fit the data.

model_kwargs¶: Keyword arguments passed to the model.

optimize_result¶: Optimization Result

optimized_args¶: The optimized arguments

optimizer¶: The optimizer function to be used to fit the data.

optimizer_kwargs¶: Keyword arguments passed to the optimizer function.

prefit()¶: Something to do before fitting.

xdata¶: The independent variable data.

ydata¶: The dependent variable data

yfit¶: The fitted y values

kontrol.curvefit.transfer_function_fit module¶

Transfer function fitting class

class kontrol.curvefit.transfer_function_fit.TransferFunctionFit(xdata=None, ydata=None, model=None, model_kwargs=None, cost=None, weight=None, error_func_kwargs=None, optimizer=None, optimizer_kwargs=None, options=None, x0=None)¶

Bases: kontrol.curvefit.curvefit.CurveFit

Transfer function fitting class

This class is basically a CurveFit class with default cost functions and optimizer that is designed for fitting a transfer function. By default, the error function is kontrol.curvefit.error_func.tf_error(). The default optimizer is scipy.optimize.minimize( ...,method="Nelder-Mead",...), with options = {"adaptive": True, "maxiter": N*1000}, where N is the number of variables. All of these can be overridden if specified.

Parameters:

xdata (array or None, optional) – Independent variable data. Defaults to None.
ydata (array or None, optional) – Transfer function frequency response in complex numbers. Defaults to None.
model (func(x: ``array, args: array, **kwargs)`` -> array, or None, optional) – The model used to fit the data. args in model is an array of parameters that define the model. Defaults to None
model_kwargs (dict or None, optional) – Keyword arguments passed to the model. Defaults to None.
cost (kontrol.curvefit.Cost or func(args, model, xdata, ydata) -> array, optional) – Cost function. The cost function to be used to fit the data. First argument is a list of parameters that will be passed to the model. This must be pickleable if multiprocessing is to be used. Defaults to None.
weight (array or None, optional) – Weighting function. Defaults None.
error_func_kwargs (dict or None, optional) – Keyword arguments the will be passed to error_func, which is passed to the construct the cost function. Defaults to None.
optimizer (func(func, **kwargs) -> OptimizeResult, or None, optional) – The optimization algorithm use for minimizing the cost function.
optimizer_kwargs (dict or None, optional) – Keyword arguments passed to the optimizer function. Defaults to None.
options (dict or None, optional) – The option arguments passed to the optimizer
x0 (array, optional) – Inital guess. Defaults to None.

options¶: Option arguments passed to optimizer

weight¶: Weighting function

x0¶: Initial guess

Secondary modules¶

kontrol.curvefit.cost module¶

Cost function base class

class kontrol.curvefit.cost.Cost(error_func, error_func_kwargs=None)¶

Bases: object

Cost function base class.

error_func¶: The error function.

error_func_kwargs¶: Keyword arguments passed to error_func

kontrol.curvefit.error_func module¶

Error functions for curve fitting

kontrol.curvefit.error_func.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.curvefit.error_func.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.curvefit.error_func.noise_error(noise1, noise2, weight=None, small_number=1e-06, norm=2)¶

Mean log error between two noise spectrums.

Parameters:	noise1 (array) – Noise spectrum 1. noise2 (array) – Noise spectrum 2. weight (array or None, optional) – Weighting function. Defaults None. small_number (float, optional) – A small number to be added in before evaluating np.log10 to prevent error. Defaults to 1e-6. norm (int, optional) – The type of norm used to estimate the error. Choose `1` for $mathcal{L}_1$ norm and `2` for $mathcal{L}_2$ norm. Other norms are are possible but not encouraged unless there’s a specifiy reason. Defaults 2.
Returns:	The mean log error.
Return type:	float

Notes

$mathcal{L}_1$ norm is more robust while $mathcal{L}_2$ norm is more susceptible to outliers, but fits data with large dynamic range well.

kontrol.curvefit.error_func.spectrum_error(spectrum1, spectrum2, weight=None, small_number=1e-06, norm=2)¶

Mean log error between two spectrums. Alias of noise_error().

Parameters:	spectrum1 (array) – Spectrum 1. spectrum2 (array) – Spectrum 2. weight (array or None, optional) – Weighting function. Defaults None. small_number (float, optional) – A small number to be added in before evaluating np.log10 to prevent error. Defaults to 1e-6. norm (int, optional) – The type of norm used to estimate the error. Choose `1` for $mathcal{L}_1$ norm and `2` for $mathcal{L}_2$ norm. Other norms are are possible but not encouraged unless there’s a specifiy reason. Defaults 2.
Returns:	The mean log error.
Return type:	float

Notes

$mathcal{L}_1$ norm is more robust while $mathcal{L}_2$ norm is more susceptible to outliers, but fits data with large dynamic range well.

kontrol.curvefit.error_func.tf_error(tf1, tf2, weight=None, small_number=1e-06, norm=2)¶

Mean log error between two transfer functions frequency response

Parameters:	tf1 (array) – Frequency response of transfer function 1, in complex values. tf2 (array) – Frequency response of transfer function 2, in complex values. weight (array or None, optional) – Weighting function. Defaults None. small_number (float, optional) – A small number to be added in before evaluating np.log10 to prevent error. Defaults to 1e-6. norm (int, optional) – The type of norm used to estimate the error. Choose `1` for $mathcal{L}_1$ norm and `2` for $mathcal{L}_2$ norm. Other norms are are possible but not encouraged unless there’s a specifiy reason. Defaults 2.
Returns:	Mean log error between two transfer function.
Return type:	float

Notes

$mathcal{L}_1$ norm is more robust while $mathcal{L}_2$ norm is more susceptible to outliers, but fits data with large dynamic range well.

Subpackages¶

kontrol.curve.model subpackage¶

Model base class for curve fitting.

class kontrol.curvefit.model.model.Model(args=None, nargs=None, log_args=False)¶

Bases: object

Model base class for curve fitting

args¶: Model parameters

nargs¶: Number of model parameters

Transfer function models for transfer function fitting.

class kontrol.curvefit.model.transfer_function_model.ComplexZPK(nzero_pairs, npole_pairs, args=None, log_args=False)¶

Bases: kontrol.curvefit.model.model.Model

ZPK model with complex poles and zeros.

Parameters:

nzero_pairs (int) – Number of complex zero pairs.
npole_pairs (int) – Number of complex pole pairs.
args (array, optional) – The model parameters defined as args = [f1, q1, f2, q2,..., fi, qi,..., fn, qn, k], where f are resonance frequencies of the complex zero/pole pairs, q are the quality factors, and k is the static gain, i is the number of complex zero pairs, and n-i is the number of of complex pole pairs.
log_args (boolean, optional) – If true, model parameters passed to the model are assumed to be passed through a log10() function. So, when the real parameters will be assumed to be 10**args instead. Defaults to False.

fn_zero¶

List of resonance frequencies of the complex zeros.

Type:	array

fn_pole¶

List of resonance frequencies of the complex poles.

Type:	array

q_zero¶

List of Q-factors of the complex zeros.

Type:	array

q_pole¶

List of Q-factors of the complex poles.

Type:	array

Notes

The complex ZPK model is defined by:

\[G(s; f_i, q_i,k) =k\frac{\prod_i(\frac{s^2}{(2\pi f_i)^2} + \frac{1}{2\pi f_i q_i}s + 1)} {\prod_j(\frac{s^2}{(2\pi f_j)^2} + \frac{1}{2\pi f_j q_j}s + 1)}\]

args¶: Model parameters in ZPK [f1, q1, f2, q2,…, fn, qn, k] format

fn_pole: List of resonance frequencies of complex poles.

fn_zero: List of resonance frequencies of complex zeros.

gain¶: Static gain.

npole_pairs¶: Number of complex pole pairs

nzero_pairs¶: Number of complex zero pairs

q_pole: List of quality factors of the complex poles

q_zero: List of quality factors of the complex zeros

tf¶: Returns a TransferFunction object of this ZPK model

class kontrol.curvefit.model.transfer_function_model.CoupledOscillator¶: Bases: kontrol.curvefit.model.transfer_function_model.TransferFunctionModel

class kontrol.curvefit.model.transfer_function_model.DampedOscillator(args=None)¶

Bases: kontrol.curvefit.model.transfer_function_model.TransferFunctionModel

Transfer function model for a damped oscillator.

Parameters:	args (array or None, optional.) – The model parameters with three numbers. Structured as follows: `args = [k, fn, q]`, where `k` is the DC gain of the transfer function, `fn` is the resonance frequency in Hz, and `q` is the Q-factor. Defaults to None.

Notes

The model is definded as

\[G(s; k, \omega_n, q) = k\frac{\omega_n^2}{s^2 + \frac{\omega_n}{q}s + \omega_n^2}\]

where $k$ is the DC gain of the transfer function, $\omega_n$ is the resonance frequency of the oscillator, and $q$ is the Q-factor if the damped oscillator.

args¶: Model parameters

damped_oscillator_args¶: The model parameters with three numbers [k, fn, q]

fn¶: Resonance frequency

gain¶: DC gain

q¶: Q factor

class kontrol.curvefit.model.transfer_function_model.SimpleZPK(nzero, npole, args=None, log_args=False)¶

Bases: kontrol.curvefit.model.model.Model

ZPK model with simple poles and zeros.

Parameters:

nzero (int) – Number of simple zeros.
npole (int) – Number of simple poles.
args (array, optional) – The model parameters defined as args = [z1, z2,..., p1, p2,..., k] where z are the locations of the zeros in Hz, p are the locations of the pole in Hz, and k is the static gain,
log_args (boolean, optional) – If true, model parameters passed to the model are assumed to be passed through a log10() function. So, when the real parameters will be assumed to be 10**args instead. Defaults to False.

zero¶

List of zeros.

Type:	array

pole¶

List of poles.

Type:	array

gain¶

Static gain.

Type:	float

tf¶

The transfer function representation of this ZPK model

Type:	kontrol.TranserFunction

Notes

The simple ZPK model is defined as

\[G(s; z_1, z_2,..., p_1, p_2, ..., k) = k\frac{\prod_i(\frac{s}{2\pi z_i}+1)}{\prod_j(\frac{s}{2\pi p_j}+1)}\]

args¶: Model parameters in ZPK [z1, z2,…, p1, p2,…, k] format

gain: Static gain

npole¶: Number of complex pole pairs

nzero¶: Number of simple zeros

pole: List of poles

tf: Returns a TransferFunction object of this ZPK model

zero: List of zeros

class kontrol.curvefit.model.transfer_function_model.TransferFunctionModel(nzero, npole, args=None, log_args=False)¶

Bases: kontrol.curvefit.model.model.Model

Transfer function model class defined by numerator and denominator

Parameters:	nzero (int) – Number of zeros. npole (int) – Number of poles. args (array or None, optional.) – The model parameters. Structured as follows: [b_n, b_n-1,…, b_1, b_0, a_m, a_m-1,…, a_1, a_0], where b and a are the coefficients of the numerator and denominator respectively, ordered from higher-order to lower-order. Defaults to None.

tf¶

The last evaluted transfer function.

Type:	kontrol.TransferFunction

Notes

The transfer function model is defined as

\[G(s, b_n, b_{n-1},..., b_1, b_0, a_m, a_{m-1},..., a_1, a_0) = \frac{\sum_{i=0}^{n} b_i s^i}{\sum_{j=0}^{m} a_j s^j}\]

den¶: Denominator array

npole¶: Number of zeros

num¶: Numerator array

nzero¶: Number of zeros

tf: The Transfer Function object.

Basic mathematical models

class kontrol.curvefit.model.math_model.Erf(args=None)¶

Bases: kontrol.curvefit.model.model.Model

The error function erf(x)

Parameters:	args (array, optional) – The model parameters structured as [amplitude, slope, x0, y0]. Defaults to None.

Notes

The function is defined as

\[f(x; a, m, x_0, y_0) = a\,\mathrm{erf}(m(x-x_0)) + y_0\,,\]

where $\mathrm{erf}(x)$ is the error function [1], $a$ is the peak to peak amplitude, $m$ is the slope at the inflection point, $x_0$ is the $x$ offset , and $y_0$ is the $y$ offset.

References

[1]	https://en.wikipedia.org/wiki/Error_function

amplitude¶: Peak to Peak amplitude of the error function.

slope¶: Slope at the inflection point.

x_offset¶: x offset

y_offset¶: y offset

class kontrol.curvefit.model.math_model.StraightLine(args=None)¶

Bases: kontrol.curvefit.model.model.Model

Simply a straight line.

Parameters:	args (array, optional) – The model parameters structued as: [slope, y-intercept]. Defaults to None.

slope¶

The slope of the line.

Type:	float

intercept¶

The y-intercept of the line.

Type:	float

Notes

The straight line is defined as

\[y(x; m, c) = mx + c\,,\]

where $m$ is the slope and $c$ is the y-intercept.

intercept: The y-intercept of the line

slope: The slope of the line