pymultieis
pymultieis.multieis module
- class pymultieis.multieis.Multieis(p0: tensor, freq: tensor, Z: tensor, bounds: Sequence[Union[int, float]], smf: tensor, func: Callable[[float, float], float], immittance: str = 'impedance', weight: Optional[Union[str, tensor]] = None)[source]
An immittance batch processing class
- Parameters
p0 – A 1D or 2D tensor of initial guess
freq – An (m, ) 1D tensor containing the frequencies. Where m is the number of frequencies
Z – An (m, n) 2D tensor of complex immittances. Where m is the number of frequencies and n is the number of spectra
bounds – A sequence of (min, max) pairs for each element in p0. The values must be real
smf – A tensor of real elements same size as p0. when set to inf, the corresponding parameter is kept constant
func – A model e.g an equivalent circuit model (ECM) or an arbitrary immittance expression composed as python function
weight – A string representing the weighting scheme or an (m,n) 2-D tensor of real values containing the measurement standard deviation. Defaults to unit weighting if left unspecified.
immittance – A string corresponding to the immittance type
- Returns
A Multieis instance
- complex_to_real(z: tensor) tensor[source]
- Parameters
z – complex vector of length n where n is the number of frequencies
- Returns
Returns a real vector of length 2n
- compute_aic(p: tensor, f: tensor, z: tensor, zerr_re: tensor, zerr_im: tensor) tensor[source]
Computes the Akaike Information Criterion according to M. Ingdal et al
- Parameters
p – A 1D tensor of parameter values
f – A 1D tensor of frequency
z – A 1D tensor of complex immittances
zerr_re – A 1D tensor of weights for the real part of the immittance
zerr_im – A 1D tensor of weights for the imaginary part of the immittance
- Returns
A value for the AIC
- compute_jac(p: tensor, f: tensor, z: tensor, zerr_re: tensor, zerr_im: tensor, lb: tensor, ub: tensor) tensor[source]
Computes the Jacobian of the least squares objective function w.r.t the parameters
- Parameters
p – A 1D tensor of parameter values
f – A 1D tensor of frequency
z – A 1D tensor of complex immittance
zerr_re – A 1D tensor of weights for the real part of the immittance
zerr_im – A 1D tensor of weights for the imaginary part of the immittance
lb – A 1D tensor of values for the lower bounds (for the total parameters)
ub – A 1D tensor of values for the upper bounds (for the total parameters)
- Returns
Returns the Jacobian matrix
- compute_perr(P: tensor, F: tensor, Z: tensor, Zerr_Re: tensor, Zerr_Im: tensor, LB: tensor, UB: tensor, smf: tensor) tensor[source]
Computes the error on the parameters resulting from the batch fit using the hessian inverse of the parameters at the minimum computed via automatic differentiation
- Parameters
P – A 2D tensor of parameter values
F – A 1D tensor of frequency
Z – A 2D tensor of complex immittances
Zerr_Re – A 2D tensor of weights for the real part of the immittance
Zerr_Im – A 2D tensor of weights for the imaginary part of the immittance
LB – A 1D tensor of values for the lower bounds (for the total parameters)
UB – A 1D tensor of values for the upper bounds (for the total parameters)
smf – A tensor of real elements same size as p0. when set to inf, the corresponding parameter is kept constant
- Returns
A 2D tensor of the standard error on the parameters
- compute_perr_QR(P: tensor, F: tensor, Z: tensor, Zerr_Re: tensor, Zerr_Im: tensor) tensor[source]
Computes the error on the parameters resulting from the batch fit using QR decomposition
- Parameters
P – A 2D tensor of parameter values
F – A 1D tensor of frequency
Z – A 2D tensor of complex immittances
Zerr_Re – A 2D tensor of weights for the real part of the immittance
Zerr_Im – A 2D tensor of weights for the imaginary part of the immittance
- Returns
A 2D tensor of the standard error on the parameters
Notes
Bates, D. M., Watts, D. G. (1988). Nonlinear regression analysis and its applications. New York [u.a.]: Wiley. ISBN: 0471816434
- compute_perr_mc(n_boots: int = 500) Tuple[tensor, tensor, tensor, tensor, tensor][source]
The bootstrap approach used here is similar to the fixed-X resampling. In this approach we construct bootstrap observations from the fitted values and the residuals. The assumption that the functional form of the model is implicit in this method. We also assume that the errors are identically distributed with constant variance. (Bootstrapping Regression Models - J Fox)
- Parameters
n_boots – Number of bootstrap samples
- Returns
A tuple containing the optimal parameters (popt), the standard error of the parameters (perr), the objective function at the minimum (chisqr), the total cost function (chitot) and the AIC
- compute_rss(p: tensor, f: tensor, z: tensor, zerr_re: tensor, zerr_im: tensor, lb, ub) tensor[source]
Computes the vector of weighted residuals. This is the objective function passed to the least squares solver.
- Parameters
p – A 1D tensor of parameter values
f – A 1D tensor of frequency
z – A 1D tensor of complex immittances
zerr_re – A 1D tensor of weights for the real part of the immittance
zerr_im – A 1D tensor of weights for the imaginary part of the immittance
lb – A 1D tensor of values for the lower bounds
ub – A 1D tensor of values for the upper bounds
- Returns
A vector of residuals
- compute_total_obj(P: tensor, F: tensor, Z: tensor, Zerr_Re: tensor, Zerr_Im: tensor, LB: tensor, UB: tensor, smf: tensor) tensor[source]
This function computes the total scalar objective function to minimize which is a combination of the weighted residual sum of squares and the (second derivative of the params + smoothing factor)
- Parameters
P – A 1D tensor of parameter values in log scale
F – A 1D tensor of frequency
Z – A 2D tensor of complex immittances
Zerr_Re – A 2D tensor of weights for the real part of the immittance
Zerr_Im – A 2D tensor of weights for the imaginary part of the immittance
LB – A 1D tensor of values for the lower bounds (for the total parameters)
UB – A 1D tensor of values for the upper bounds (for the total parameters)
smf – A tensor of real elements same size as p0. when set to inf, the corresponding parameter is kept constant
- Returns
A scalar value of the total objective function
- compute_wrms(p: tensor, f: tensor, z: tensor, zerr_re: tensor, zerr_im: tensor) tensor[source]
Computes the weighted residual mean square
- Parameters
p – A 1D tensor of parameter values
f – A 1D tensor of frequency
z – A 1D tensor of complex immittance
zerr_re – A 1D tensor of weights for the real part of the immittance
zerr_im – A 1D tensor of weights for the imaginary part of the immittance
- Returns
A scalar value of the weighted residual mean square
- compute_wrss(p: tensor, f: tensor, z: tensor, zerr_re: tensor, zerr_im: tensor) tensor[source]
Computes the scalar weighted residual sum of squares (aka scaled version of the chisquare or the chisquare itself)
- Parameters
p – A 1D tensor of parameter values
f – A 1D tensor of frequency
z – A 1D tensor of complex immittances
zerr_re – A 1D tensor of weights for the real part of the immittance
zerr_im – A 1D tensor of weights for the imaginary part of the immittance
- Returns
A scalar value of the weighted residual sum of squares
- convert_to_external(P: tensor) tensor[source]
Converts A tensor of parameters from an internal to an external coordinates
- Parameters
p – A 1D tensor of parameter values
- Returns
Parameters in normal scale
- convert_to_internal(p: tensor) tensor[source]
Converts A tensor of parameters from an external to an internal coordinates (log10 scale)
- Parameters
p – A 1D or 2D tensor of parameter values
- Returns
Parameters in log10 scale
- create_dir(dir_name: str)[source]
Creates a directory. equivalent to using mkdir -p on the command line
- Parameters
dir_name – Name assigned to the directory
- decode(p: tensor, lb: tensor, ub: tensor) tensor[source]
Converts internal parameters to external parameters
- Parameters
p – A 1D tensor of parameter values
lb – A 1D tensor of values for the lower bounds (for the total parameters)
ub – A 1D tensor of values for the upper bounds (for the total parameters)
- Returns
Returns the parameter vector in normal scale (external coordinates)
- do_minimize(p: tensor, f: tensor, z: tensor, zerr_re: tensor, zerr_im: tensor, lb: tensor, ub: tensor, smf: tensor)[source]
Fitting routine used in the bootstrap Monte Carlo procedure
- Parameters
p – A 1D tensor of parameter values
f – A 1D tensor of frequency
z – A 1D tensor of complex immittances
zerr_re – A 1D tensor of weights for the real part of the immittance
zerr_im – A 1D tensor of weights for the imaginary part of the immittance
lb – A 1D tensor of values for the lower bounds (for the total parameters)
ub – A 1D tensor of values for the upper bounds (for the total parameters)
smf – A tensor of real elements same size as p0. when set to inf, the corresponding parameter is kept constant
- do_minimize_ls(p: tensor, f: tensor, z: tensor, zerr_re: tensor, zerr_im: tensor, lb: tensor, ub: tensor) Tuple[tensor, tensor][source]
Least squares routine - uses compute_rss
- Parameters
p – A 1D tensor of parameter values
f – A 1D tensor of frequency
z – A 1D tensor of complex immittance
zerr_re – A 1D tensor of weights for the real part of the immittance
zerr_im – A 1D tensor of weights for the imaginary part of the immittance
lb – A 1D tensor of values for the lower bounds (for the total parameters)
ub – A 1D tensor of values for the upper bounds (for the total parameters)
- Returns
Returns the log-scaled optimal parameters and the weighted residual mean square
- encode(p: tensor, lb: tensor, ub: tensor) tensor[source]
Converts external parameters to internal parameters
- Parameters
p – A 1D tensor of parameter values
lb – A 1D tensor of values for the lower bounds (for the total parameters)
ub – A 1D tensor of values for the upper bounds (for the total parameters)
- Returns
Returns the parameter vector in log scale (internal coordinates)
- fit_sequential(indices: Optional[Sequence[int]] = None) Tuple[tensor, tensor, tensor, tensor, tensor][source]
Fits each spectra individually using the L-M least squares method
- Params indices
List containing the indices of spectra to plot. If set to None, all spectra are fitted sequentially
- Returns
A tuple containing the optimal parameters (popt), the standard error of the parameters (perr), the objective function at the minimum (chisqr), the total cost function (chitot) and the AIC
- fit_simultaneous(method: str = 'bfgs', n_iter: int = 5000) Tuple[tensor, tensor, tensor, tensor, tensor][source]
Simultaneous fitting routine with an arbitrary smoothing factor..
- Params method
Solver to use (must be one of “‘TNC’, ‘BFGS’ or ‘L-BFGS-B’”)
- Params n_iter
Number of iterations
- Returns
A tuple containing the optimal parameters (popt), the standard error of the parameters (perr), the objective function at the minimum (chisqr), the total cost function (chitot) and the AIC
- fit_simultaneous_zero(method: str = 'bfgs', n_iter: int = 5000) Tuple[tensor, tensor, tensor, tensor, tensor][source]
Fitting routine with the smoothing factor set to zero.
- Params method
Solver to use (must be one of “‘TNC’, ‘BFGS’ or ‘L-BFGS-B’”)
- Parameters
n_iter – Number of iterations
- Returns
A tuple containing the optimal parameters (popt), the standard error of the parameters (perr), the objective function at the minimum (chisqr), the total cost function (chitot) and the AIC
- fit_stochastic(lr: float = 0.001, num_epochs: int = 100000.0) Tuple[tensor, tensor, tensor, tensor, tensor][source]
Fitting routine which uses the Adam optimizer. It is important to note here that even stocahstic search procedures, although applicable to large scale problems do not find the global optimum with certainty (Aster, Richard pg 249)
- Parameters
lr – Learning rate
num_epochs – Number of epochs
- Returns
A tuple containing the optimal parameters (popt), the standard error of the parameters (perr), the objective function at the minimum (chisqr), the total cost function (chitot) and the AIC
- get_bounds_vector(lb: tensor, ub: tensor) Tuple[tensor, tensor][source]
Creates vectors for the upper and lower bounds which are the same length as the number of parameters to be fitted.
- Parameters
lb – A 1D tensor of lower bounds
ub – A 1D tensor of upper bounds
- Returns
A tuple of bounds vectors
- get_fd()[source]
Computes the finite difference stencil for a second order derivative. The derivatives at the boundaries is calculated using special finite difference equations derived specifically for just these points (aka higher order boundary conditions). They are used to handle numerical problems that occur at the edge of grids.
- Returns
Finite difference stencil for a second order derivative
- model_prediction(P: tensor, F: tensor) Tuple[tensor, tensor][source]
Computes the predicted immittance and its inverse
- Parameters
P – A 2D tensor of optimal parameters
Z – A 1D tensor of complex immittances
- Returns
The predicted immittance (Z_pred) and its inverse(Y_pred)
- plot_bode(steps: int = 1, **kwargs)[source]
Creates the Bode plots The Bode plot shows the phase angle of a capacitor’s or inductors opptosition to current. A capacitor’s opposition to current is -90°, which means that a capacitor’s opposition to current is a negative imaginary quantity.
- Parameters
steps – Spacing between plots. Defaults to 1.
- Keyword Arguments
fpath – Additional keyword arguments passed to plot (i.e file path)
- Returns
The bode plots.
Notes
\[\theta = arctan2 (\frac{\Im{Z}}{\Re{Z}} \frac{180}{\pi})\]
- plot_nyquist(steps: int = 1, **kwargs)[source]
Creates the complex plane plots (aka Nyquist plots)
- Parameters
steps – Spacing between plots. Defaults to 1
- Keyword Arguments
fpath1 – Additional keyword arguments passed to plot (i.e file path)
fpath2 – Additional keyword arguments passed to plot (i.e file path)
- Returns
The complex plane plots.
- plot_params(show_errorbar: bool = False, labels: Optional[Dict[str, str]] = None, **kwargs) None[source]
Creates the plot of the optimal parameters as a function of the index
- Parameters
show_errorbar – If set to True, the errorbars are shown on the parameter plot.
labels – A dictionary containing the circuit elements as keys and the units as values e.g labels = { “Rs”:”$Omega$”, “Qh”:”$F$”, “nh”:”-“, “Rct”:”$Omega$”, “Wct”:”$Omegacdot^{0.5}$”, “Rw”:”$Omega$” }
- Keyword Arguments
fpath – Additional keyword arguments passed to plot (i.e file path)
- Returns
The parameter plots
- real_to_complex(z: tensor) tensor[source]
- Parameters
z – real vector of length 2n where n is the number of frequencies
- Returns
Returns a complex vector of length n.
- save_plot_bode(steps: int = 1, *, fname: Optional[str] = None) None[source]
Saves the Bode plots in the current working directory with the fname provided
- Parameters
steps – Spacing between plots. Defaults to 1.
- Keyword Arguments
fname – Name assigned to the directory, generated plots and data
- Returns
A .png image of the the bode plot
- save_plot_nyquist(steps: int = 1, *, fname: Optional[str] = None) None[source]
Saves the Nyquist plots in the current working directory with the fname provided.
- Parameters
steps – Spacing between plots. Defaults to 1.
- Keyword Arguments
fname – Name assigned to the directory, generated plots and data
- Returns
A .png image of the the complex plane plots
- save_plot_params(show_errorbar: bool = False, labels: Optional[Dict[str, str]] = None, *, fname: Optional[str] = None) None[source]
Saves the parameter plots in the current working directory with the fname provided.
- Parameters
show_errorbar – If set to True, the errorbars are shown on the parameter plot.
labels – A dictionary containing the circuit elements as keys and the units as values e.g labels = { “Rs”:”$Omega$”, “Qh”:”$F$”, “nh”:”-“, “Rct”:”$Omega$”, “Wct”:”$Omegacdot^{0.5}$”, “Rw”:”$Omega$” }
- Keyword Arguments
fname – Name assigned to the directory, generated plots and data
- Returns
A .png image of the the parameter plot