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.

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.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