kontrol.curvefit

Primary modules

kontrol.curvefit.curvefit

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 or None, optional) – 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 (callable or None, optional) – The model used to fit the data. The callable has a signature of func(x: array, args: array, **kwargs) -> array. 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 callable) – Cost function. The callable has a signature of func(args, model, xdata, ydata) -> array. 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.

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

Return type

scipy.optimizer.OptimizeResult

property model

The model used to fit the data.

property model_kwargs

Keyword arguments passed to the model.

property optimize_result

Optimization Result

property optimized_args

The optimized arguments

property optimizer

The optimizer function to be used to fit the data.

property optimizer_kwargs

Keyword arguments passed to the optimizer function.

prefit()

Something to do before fitting.

property xdata

The independent variable data.

property ydata

The dependent variable data

property yfit

The fitted y values

kontrol.curvefit.transfer_function_fit

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: 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 callable) – Cost function. The callable has a signature of func(args, model, xdata, ydata) -> array. 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.

property options

Option arguments passed to optimizer

property weight

Weighting function

property x0

Initial guess

Secondary modules

kontrol.curvefit.cost

Cost function base class

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

Bases: object

Cost function base class.

property error_func

The error function.

property error_func_kwargs

Keyword arguments passed to error_func

kontrol.curvefit.error_func

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

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

property args

Model parameters

property 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: 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)}\]

property args

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

property fn_pole

List of resonance frequencies of complex poles.

property fn_zero

List of resonance frequencies of complex zeros.

property gain

Static gain.

property npole_pairs

Number of complex pole pairs

property nzero_pairs

Number of complex zero pairs

property q_pole

List of quality factors of the complex poles

property q_zero

List of quality factors of the complex zeros

property tf

Returns a TransferFunction object of this ZPK model

class kontrol.curvefit.model.transfer_function_model.CoupledOscillator

Bases: TransferFunctionModel

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

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

property args

Model parameters

property damped_oscillator_args

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

property fn

Resonance frequency

property gain

DC gain

property q

Q factor

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

Bases: 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)}\]

property args

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

property gain

Static gain

property npole

Number of complex pole pairs

property nzero

Number of simple zeros

property pole

List of poles

property tf

Returns a TransferFunction object of this ZPK model

property zero

List of zeros

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

Bases: 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}\]

property den

Denominator array

property npole

Number of zeros

property num

Numerator array

property nzero

Number of zeros

property tf

The Transfer Function object.

Basic mathematical models

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

Bases: 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

property amplitude

Peak to Peak amplitude of the error function.

property slope

Slope at the inflection point.

property x_offset

x offset

property y_offset

y offset

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

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

property intercept

The y-intercept of the line

property slope

The slope of the line