Circuit fitting

A collection of functions and classes for fitting equivalent circuits to data sets.

Function

pyimpspec.fit_circuit(circuit, data, method='auto', weight='auto', max_nfev=-1, num_procs=-1, timeout=0, constraint_expressions=None, constraint_variables=None, **kwargs)

Fit a circuit to a data set.

Parameters:

circuit (Circuit) – The circuit to fit to a data set.
data (DataSet) – The data set that the circuit will be fitted to.
method (Union[str, List[str]], optional) – The iteration method(s) to use during fitting. See lmfit’s documentation for valid method names. Note that not all methods supported by lmfit are possible in the current implementation (e.g. some methods may require a function that calculates a Jacobian). If a list of multiple methods (or “auto”) is provided, then multiple methods will be tested and the best result will be returned based on the \(\chi^2_{\rm ps}\) value.
weight (Union[str, List[str]], optional) – The weight function(s) to use when calculating residuals. Currently supported values: “modulus”, “proportional”, “unity”, “boukamp”, and “auto”. If a list of multiple weights (or “auto”) is provided, then multiple weights will be tested and the best result will be returned based on the \(\chi^2_{\rm ps}\) value.
max_nfev (int, optional) – The maximum number of function evaluations when fitting. A value less than one equals no limit.
num_procs (int, optional) – The maximum number of parallel processes to use when performing the fitting with multiple methods and/or weights. A value less than 1 results in an attempt to figure out a suitable value based on, e.g., the number of cores detected. Additionally, a negative value can be used to reduce the number of processes by that much (e.g., to leave one core for a GUI thread).
timeout (int, optional) – The amount of time in seconds that a single fit is allowed to take before being timed out. If this values is less than one, then no time limit is imposed.
constraint_expressions (Optional[Dict[str, str]], optional) – A mapping of the optional constraints to apply.
constraint_variables (Optional[Dict[str, dict]], optional) –
A mapping of variable names to their keyword arguments (see lmfit.Parameters for more information). These variables may be referenced in the optional constraints.
**kwargs

Return type:

FitResult

pyimpspec.generate_fit_identifiers(circuit)

Generate the identifiers that are provided to lmfit when fitting the provided circuit. These identifiers can be used to define optional constraints when calling fit_circuit().

Parameters:: circuit (Circuit) – The circuit to process.
Returns:: A dictionary that maps each element to a FitIdentifiers instance that maps each parameter of that element to the identifier that is used by lmfit during fitting.
Return type:: Dict[Element, FitIdentifiers]

Classes

class pyimpspec.FitIdentifiers

An object that maps an Element’s parameters to the name/identifier used by the corresponding lmfit Parameter. The values can be accessed in two ways:

name: str = identifiers.R
name: str = identifiers["R"]

In this example, the FitIdentifiers instance identifiers was generated based on a Resistor instance. Thus, identifiers has a property called R.

It is also possible to do the following as if identifiers was a dictionary:

{symbol: identifiers[symbol] for symbol in identifiers}
{symbol: name for symbol, name in identifiers.items()}

class pyimpspec.FitResult(circuit, parameters, minimizer_result, frequencies, impedances, residuals, pseudo_chisqr, method, weight)

An object representing the results of fitting a circuit to a data set.

Parameters:

circuit (Circuit) – The fitted circuit.
parameters (Dict[str, Dict[str, FittedParameter]]) – Fitted parameters and their estimated standard errors (if possible to estimate).
minimizer_result (lmfit.MinimizerResult) – The results of the fit as provided by the lmfit.minimize function.
frequencies (Frequencies) – The frequencies used to perform the fit.
impedances (ComplexImpedances) – The impedances produced by the fitted circuit at each of the frequencies.
residuals (ComplexResiduals) – The residuals for the real (eq. 15 in Schönleber et al., 2014) and imaginary (eq. 16 in Schönleber et al., 2014) parts of the fit.
pseudo_chisqr (float) – The pseudo chi-squared value (\(\chi^2_{\rm ps}\), eq. 14 in Boukamp, 1995).
method (str) – The iterative method used during the fitting process.
weight (str) – The weight function used during the fitting process.

get_bode_data(num_per_decade=-1)

Get the data necessary to plot this FitResult as a Bode plot: the frequencies, the absolute magnitudes of the impedances, and the negative phase angles/shifts of the impedances in degrees.

Parameters:: num_per_decade (int, optional) – The number of points per decade. A positive value results in data points being calculated using the fitted circuit within the original frequency range. Otherwise, only the original frequencies are used.
Return type:: Tuple[Frequencies, Impedances, Phases]

get_frequencies(num_per_decade=-1)

Get the frequencies in the fitted frequency range.

Parameters:: num_per_decade (int, optional) – The number of points per decade. A positive value results in frequencies being calculated within the original frequency range. Otherwise, only the original frequencies are used.
Return type:: Frequencies

get_impedances(num_per_decade=-1)

Get the impedance response of the fitted circuit.

Parameters:: num_per_decade (int, optional) – The number of points per decade. A positive value results in data points being calculated using the fitted circuit within the original frequency range. Otherwise, only the original frequencies are used.
Return type:: ComplexImpedances

get_label()

Get the label for this result.

Return type:: str

get_nyquist_data(num_per_decade=-1)

Get the data necessary to plot this FitResult as a Nyquist plot: the real and the negative imaginary parts of the impedances.

Parameters:: num_per_decade (int, optional) – The number of points per decade. A positive value results in data points being calculated using the fitted circuit within the original frequency range. Otherwise, only the original frequencies are used.
Return type:: Tuple[Impedances, Impedances]

get_parameters()

Get information about the the fitted parameters as FittedParameter objects. The outer dictionary has the labels of the elements as keys and the inner dictionary has the symbols of the parameters as keys.

Return type:: Dict[str, Dict[str, FittedParameter]]

get_residuals_data()

Get the data necessary to plot the relative residuals for this result: the frequencies, the relative residuals for the real parts of the impedances in percents, and the relative residuals for the imaginary parts of the impedances in percents.

Return type:: Tuple[Frequencies, Residuals, Residuals]

to_parameters_dataframe(running=False)

Get the fitted parameters and the corresponding estimated errors as a pandas.DataFrame object. :param running: Whether or not to use running counts as the lower indices of elements. :type running: bool, optional

Return type:: pandas.DataFrame
Parameters:: running (bool)

to_statistics_dataframe()

Get the statistics related to the fit as a pandas.DataFrame object.

Return type:: pandas.DataFrame

class pyimpspec.FittedParameter(value, stderr, fixed, unit)

An object representing a fitted parameter.

Parameters:

value (float) – The fitted value.
stderr (float) – The estimated standard error of the fitted value. If the value is numpy.nan, then the standard error could not be estimated.
fixed (bool) – Whether or not this parameter had a fixed value during the circuit fitting.
unit (str) – The parameter’s unit.

get_error()

Get the estimated absolute standard error of this parameter or numpy.nan if it was not possible to provide an estimate.

Return type:: float

get_relative_error()

Get the estimated relative standard error of this parameter or numpy.nan if it was not possible to estimate.

Return type:: float

get_unit()

Get the unit of this parameter if it has one.

Return type:: str

get_value()

Get the fitted value of this parameter.

Return type:: float

is_fixed()

Check whether or not this parameter was fixed during the fitting process.

Return type:: bool