Utilitites

impedancefitter.utils.KK_integral_transform(omega, Z)[source]

Kramers-Kronig integral transform.

Parameters:
Returns:

The transformed impedance array.

Return type:

numpy.ndarray, complex

Notes

Implementation following [Urquidi1990]

[Urquidi1990]

Urquidi-Macdonald, M., Real, S., & Macdonald, D. D. (1990). Applications of Kramers-Kronig transforms in the analysis of electrochemical impedance data-III. Stability and linearity. Electrochimica Acta, 35(10), 1559–1566. https://doi.org/10.1016/0013-4686(90)80010-L

impedancefitter.utils.available_file_format()[source]

List available file formats.

Currently available:

XLSX and CSV:

The file is structured like: frequency, real part of impedance, imaginary part of impedance. There may be many different sets of impedance data, i.e. there may be more columns with the real and the imaginary part. Then, the frequencies column must not be repeated. In fact, the number of columns equals the number of impedance data sets plus one (for the frequency).

Note

A single header line is needed in a CSV and XLSX file. It may contain for example frequency, Real Part, Imag Part. Otherwise the read-in function will fail.

CSV_E4980AL:

Read in data that is structured in 5 columns: frequency, real part, imaginary part of the impedance, voltage, current

Note

There is always only one data set in a file.

TXT:

These files contain frequency, real and imaginary part of the impedance (i.e., 3 columns). The TXT files may contain two traces; only one of them is read in. For TXT files you can specify the number of rows to skip. Moreover, the file ending is not strictly enforced here.

DF:

The dataframe is structured like: frequency, real part of impedance, imaginary part of impedance. This is not a file format, so the workflow is different. The ‘directory’ parameter must be set to None and the following parameter must be added to **kwargs: ‘df’, ‘df_freq_column’, ‘df_real_column’ and ‘df_imag_column’. The ‘df’ parameter is the dataframe object, and the other parameters are the column names of the dataframe to be read in.

Note

The dataframe can contain multiple impedance data sets. While the dataframe object and the frequency, real and imaginary columns are not None, the dataframe will be used instead of a file.

See also

impedancefitter.fitter.Fitter

impedancefitter.utils.available_models()[source]

Return list of available models.

impedancefitter.utils.check_parameters(bufdict)[source]

Check parameters for physical correctness.

Parameters:

bufdict (dict) – Contains all parameters and their values

Notes

All parameters are forced to be greater or equal zero. There are only two exceptions.

impedancefitter.utils.convert_diel_properties_to_impedance(omega, eps_r, sigma, c0)[source]

Return impedance from dielectric properties.

Parameters:

  • omega (numpy.ndarray, double) – frequency array

  • eps_r (numpy.ndarray, double) – relative permittivity

  • sigma (numpy.ndarray, double) – conductivity in S/m

  • c0 (double) – unit capacitance of device

Returns:

impedance array

Return type:

numpy.ndarray, complex

Notes

Use that the impedance is

\[Z = (j \omega \varepsilon_\mathrm{r}^\ast c_0)^{-1} ,\]

where \(\varepsilon_\mathrm{r}^\ast\) is the relative complex permittivity (see for instance [Grant1958] for further explanation). Note that the vacuum permittivity \(\varepsilon_0\) is contained in \(c_0\).

In the function, the variable epsc describes the term

\[\omega \varepsilon_\mathrm{r}^\ast\]
impedancefitter.utils.draw_scheme(modelname, show=True, save=False)[source]

Show (and save) SchemDraw drawing.

Parameters:

  • modelname (str) – String representation of the equivalent circuit.

  • show (bool, optional) – Show scheme in matplotlib window.

  • save (bool, optional) – Save scheme to file. File is called scheme.svg.

impedancefitter.utils.dummy(omega)[source]

Dummy function returning only ones.

impedancefitter.utils.get_equivalent_circuit_model(modelname, logscale=False, diel=False)[source]

Get LMFIT CompositeModel.

Parameters:

  • modelname (str) – String representation of the equivalent circuit.

  • logscale (bool) – Convert to logscale.

  • diel (bool) – Convert to complex permittivity and fit this instead of impedance.

Returns:

the final model of the entire circuit

Return type:

lmfit.model.CompositeModel or lmfit.model.Model

Notes

The parser is based on Pyparsing. It is sensitive towards extra ( or ) or +. Thus, keep the circuit simple.

impedancefitter.utils.get_labels(params)[source]

return the labels for every parameter in LaTex code.

Parameters:

params (list of string) – list with parameters names (possible prefixes included)

Returns:

labels – dictionary with parameter names as keys and LaTex code as values.

Return type:

dict

impedancefitter.utils.make_eps(omega, c0all)[source]

Compute permittivity.

impedancefitter.utils.return_diel_properties(omega, Z, c0)[source]

Return relative permittivity and conductivity from impedance spectrum in cavity with known unit capacitance.

Notes

Use that the impedance is

\[Z = (j \omega \varepsilon_\mathrm{r}^\ast c_0)^{-1} ,\]

where \(\varepsilon_\mathrm{r}^\ast\) is the relative complex permittivity (see for instance [Grant1958] for further explanation). Note that the vacuum permittivity \(\varepsilon_0\) is contained in \(c_0\).

When the unit capacitance \(c_0\) of the device is known, a direct mapping from impedance to relative complex permittivity is possible:

\[\varepsilon_\mathrm{r}^\ast = (j \omega Z c_0)^{-1} = \frac{\varepsilon^\ast}{\varepsilon_0}\]

The unit capacitance (or air capacitance) of the device is defined as

\[c_0 = \frac{\varepsilon_0 A}{d}\]

for a parallel-plate capacitor with electrode area A and spacing d but can also be measured in a calibration step.

The relative permittivity is the real part of \(\varepsilon_\mathrm{r}^\ast\) and the conductivity is the negative imaginary part times the frequency and the vacuum permittivity.

Parameters:

  • omega (numpy.ndarray, double) – frequency array

  • Z (numpy.ndarray, complex) – impedance array

  • c0 (double) – unit capacitance of device

Returns:

References

[Grant1958] (1,2)

Grant, F. A. (1958). Use of complex conductivity in the representation of dielectric phenomena. Journal of Applied Physics, 29(1), 76–80. https://doi.org/10.1063/1.1722949

impedancefitter.utils.return_dielectric_modulus(omega, Z, c0)[source]

Return dielectric modulus.

Notes

The dielectric modulus is \(M = 1 / \varepsilon_\mathrm{r}^\ast\). See [Bordi2001] for further explanation.

Parameters:

  • omega (numpy.ndarray, double) – frequency array

  • Z (numpy.ndarray, complex) – impedance array

  • c0 (double) – unit capacitance of device

Returns:

References

[Bordi2001]

Bordi, F., & Cametti, C. (2001). Occurrence of an intermediate relaxation process in water-in-oil microemulsions below percolation: The electrical modulus formalism. Journal of Colloid and Interface Science, 237(2), 224–229. https://doi.org/10.1006/jcis.2001.7456

impedancefitter.utils.save_impedance(omega, impedance, format='CSV', filename='impedance')[source]

Save impedance to CSV or XLSX file.

Parameters:

  • omega (numpy.ndarray, double) – frequency array

  • impedance (numpy.ndarray, complex) – impedance array

  • format (str) – use either CSV or XLSX format. Based on the format, the correct ending is chosen.

  • filename (str) – specify a filename (without ending!). The default is impedance.csv or impedance.xlsx

impedancefitter.utils.set_parameters(model, parameterdict=None, emcee=False, weighting_model=False)[source]
Parameters:

  • model (lmfit.model.Model) – The LMFIT model used for fitting.

  • parameterdict (dict, optional) – A dictionary containing parameters for model with min, max, vary info for LMFIT. If it is None (default), the parameters are read in from a yaml-file.

  • emcee (bool, optional) – if emcee is used, an additional __lnsigma parameter will be set

  • weighting_model (bool, optional) – if a weighting model is used, the variance will be fit as well

Returns:

params – LMFIT Parameters object.

Return type:

lmfit.parameter.Parameters

impedancefitter.fra.bode_csv_to_impedance(filename, devicename, R_device=1000000.0)[source]

Convert Bode output (Attenuation and phase) to Impedance and save as CSV.

Parameters:

  • filename (string) – relative path to csv file with Bode info

  • devicename (string) – “MokuGo” and “R&S” are supported (devices/xx.json), or provide own device

  • R_device (float) – Input impedance of the device. Default is 1 MegOhm.

Returns:

impedancefitter.fra.bode_to_impedance(frequency, attenuation, phase, R_device=1000000.0)[source]

Bode diagram (Attenuation and phase) to Impedance calculator.

Parameters:
Returns:

Notes

Given the expression for the magnitude of a voltage in dB is

\[M_{db} = 20 \log{\frac{V_1}{V_{ref}}}\]

we calculate the voltage ratio from the attenuation in dB as

\[ratio_{voltage} = 10^{M_{dB} / 20}\]

Then, the voltage divider rule results in the magnitude of the impedance as

\[Z_{dut} = ratio * R_{shunt} - R_{shunt}\]
class impedancefitter.fra.fra_device(devicefile)[source]

Class containing FRA device specifications.

impedancefitter.fra.mag_phase_to_complex(Z_mag, phase)[source]

Convert Bode form to complex numbers.

impedancefitter.fra.neisys_to_impedance(filename, header=2)[source]

Convert neisys format to impedance.

impedancefitter.fra.open_short_compensation(Z_meas, Z_open, Z_short)[source]

compensates the measured impedance with open and short reference measurements.

please make sure the parameters stayed the same for all measurements

Parameters:

  • Z_meas (int or float or numpy.ndarray) – measured impedance of the DUT

  • Z_open, Z_short (int or float or numpy.ndarray) – reference measurements with open / short circuit

Returns:

impedance of Z_dut compensated

Return type:

input dependent,

impedancefitter.fra.parallel(val_list)[source]
Convenience function to calculate the value of a list

of resistors in parallel (or capacitors in series).

May be used to set R_device if a shunt resistor is used in parallel to device input

Parameters:

val_list (list of float) – values of the individual resistors in parallel

Returns:

apparent value of the parallel resistors

Return type:

float

impedancefitter.fra.read_bode_csv(filename, devicename)[source]

CSV to Bode Plot Parser.

Parameters:

  • filename (string) – relative path to csv file

  • devicename (string) – specify json file which will load device parameters

  • output (Bode Plot)

  • format (Frequency, Attenuation, Phase)

Notes

This function was tested for a MokuGo (Liquid Instruments) and an Rohde & Schwarz oscilloscope RTB2004

impedancefitter.fra.read_bode_csv_dev(filename, devicesettings)[source]

special funtion to generate appr. format from provided device csv-files.

Parameters:

  • filename (string) – relative path to csv file

  • devicesettings (dict) – information about device

Returns:

impedancefitter.fra.wrap_phase(phase)[source]

wraps the phase to -90deg to 90deg TODO: maybe there is a python function for this.

impedancefitter.suspensionmodels.F(root, epsi_p, epsi_med, p)[source]

F factor.

impedancefitter.suspensionmodels.Lk(Rx, Ry, Rz, k)[source]

Depolarization factor for ellipsoids.

Notes

The depolarization factor is given as [Asami2002]

\[L_k = \frac{R_x R_y R_z}{2} \int_0^\infty \frac{\mathrm{d} s}{(R_k^2 + s)R_s}\]

with

\[R_s = \sqrt{(R_x^2 + s)(R_y^2 + s)(R_z^2 + s)}\]

TODO: watch units!

impedancefitter.suspensionmodels.Lk_body(s, Rk, Rx, Ry, Rz)[source]

Formula for Lk.

impedancefitter.suspensionmodels.bh_eps_model(epsi_med, epsi_p, p)[source]

Complex permittvitiy of double shell model by Bruggeman-Hanai approach.

Parameters:

  • epsi_med (numpy.ndarray, complex) – Complex permittivity array of medium

  • epsi_p (numpy.ndarray, complex) – Complex permittivity array of suspended particles

  • p (double) – volume fraction

Returns:

Complex permittivity array

Return type:

numpy.ndarray, complex

Notes

The implementation follows [Cottet2019]. Note that the approach here might not be numerically as accurate as the cubic equation solver (impedancefitter.suspensionmodels.bhcubic_eps_model()). In the respective unit test, the deviation is below 1%, though.

References

[Cottet2019]

Cottet, J., Fabregue, O., Berger, C., Buret, F., Renaud, P., & Frénéa-Robin, M. (2019). MyDEP: A New Computational Tool for Dielectric Modeling of Particles and Cells. Biophysical Journal, 116(1), 12–18. https://doi.org/10.1016/j.bpj.2018.11.021

See also

impedancefitter.suspensionmodels.bhcubic_eps_model()

impedancefitter.suspensionmodels.bhcubic_eps_model(epsi_med, epsi_p, p)[source]
Complex permittvitiy of concentrated suspension

model by Bruggeman-Hanai approach.

Parameters:

  • epsi_med (numpy.ndarray, complex) – Complex permittivity array of medium

  • epsi_p (numpy.ndarray, complex) – Complex permittivity array of suspended particles

  • p (double) – volume fraction

Returns:

Complex permittivity array

Return type:

numpy.ndarray, complex

Notes

The complex permittivity of the suspension \(\varepsilon_\mathrm{sus}^\ast\) is given by [Hanai1979]

\[\frac{\varepsilon_\mathrm{sus}^\ast - \varepsilon_\mathrm{p}^\ast} {\varepsilon_\mathrm{med}^\ast - \varepsilon_\mathrm{p}^\ast} \left(\frac{\varepsilon_\mathrm{med}^\ast}{\varepsilon_\mathrm{sus}^\ast}\right)^{1/3} = 1 - p \enspace ,\]

with \(\varepsilon_\mathrm{med}^\ast\) being the permittivity of the liquid medium and \(\varepsilon_\mathrm{p}^\ast\) the permittivity of the suspended particle (e.g., cells).

Cubing the equation yields a cubic equation. The cubic roots (three in total) are the possible solutions for the complex permittivity of the suspension. Only one of them is physical, which can be found by substituting the cubic roots into another function [Hanai1979].

A numerical solution is implemented in impedancefitter.suspensionmodels.bh_eps_model()

References

[Hanai1979] (1,2)

Hanai, T., Asami, K., & Korzumi, N. (1979). Dielectric Theory of Concentrated Suspensions of Shell-Spheres in Particular Reference to the Analysis of Biological Cell Suspensions. Bull. Inst. Chem. Res., Kyoto Univ, 57(4), 297–305. http://hdl.handle.net/2433/76842

See also

impedancefitter.suspensionmodels.bh_eps_model()

impedancefitter.suspensionmodels.eps_sus_MW(epsi_med, epsi_p, p)[source]

Maxwell-Wagner mixture model for dilute suspensions of spherical particles:w.

Parameters:

  • epsi_med (numpy.ndarray, complex) – complex permittivities of medium

  • epsi_p (numpy.ndarray, complex) – complex permittivities of suspension phase (cells, particles…)

  • p (double) – volume fraction

Returns:

Complex permittivity array

Return type:

numpy.ndarray, complex

Notes

The complex permittivity of the suspension \(\varepsilon_\mathrm{sus}^\ast\) is given by

\[\varepsilon_\mathrm{sus}^\ast = \varepsilon_\mathrm{med}^\ast \frac{(2\varepsilon_\mathrm{med}^\ast+\varepsilon_\mathrm{p}^\ast) -2p(\varepsilon_\mathrm{med}^\ast-\varepsilon_\mathrm{p}^\ast)} {(2\varepsilon_\mathrm{med}^\ast+\varepsilon_\mathrm{p}^\ast)+ p(\varepsilon_\mathrm{med}^\ast-\varepsilon_\mathrm{p}^\ast)} \enspace ,\]

with \(\varepsilon_\mathrm{med}^\ast\) being the permittivity of the liquid medium and \(\varepsilon_\mathrm{p}^\ast\) the permittivity of the suspended particle (e.g., cells).

impedancefitter.suspensionmodels.eps_sus_ellipsoid_MW(epsi_med, epsi_px, epsi_py, epsi_pz, p, Rx, Ry, Rz)[source]

Maxwell-Wagner mixture model for dilute suspensions of ellipsoidal particles:w.

Parameters:

  • epsi_med (numpy.ndarray, complex) – complex permittivities of medium

  • epsi_px (numpy.ndarray, complex) – complex permittivities of suspension phase in x-direction (cells, particles…)

  • epsi_py (numpy.ndarray, complex) – complex permittivities of suspension phase in y-direction (cells, particles…)

  • epsi_pz (numpy.ndarray, complex) – complex permittivities of suspension phase in z-direction (cells, particles…)

  • p (double) – volume fraction

  • Rx (double) – radius for x-semiaxis, value for \(R_\mathrm{x}\)

  • Ry (double) – radius for y-semiaxis, value for \(R_\mathrm{y}\)

  • Rz (double) – radius for z-semiaxis, value for \(R_\mathrm{z}\)

Returns:

Complex permittivity array

Return type:

numpy.ndarray, complex

Notes

The complex permittivity of the suspension \(\varepsilon_\mathrm{sus}^\ast\) is given by

\[\varepsilon_\mathrm{sus}^\ast = \frac{\varepsilon_\mathrm{med}^\ast(1 + 2 K)} {1-K} \enspace ,\]

where

\[K = \frac{p}{9} \sum_{k=x,y,z} \frac{\varepsilon_\mathrm{p}^\ast - \varepsilon_\mathrm{med}^\ast} {\varepsilon_\mathrm{med}^\ast + (\varepsilon_\mathrm{p}^\ast - \varepsilon_\mathrm{med}^\ast)L_k}\]

with \(\varepsilon_\mathrm{med}^\ast\) being the permittivity of the liquid medium and \(\varepsilon_\mathrm{p}^\ast\) the permittivity of the suspended particle (e.g., cells). The depolarization factor \(L_k\) is implemented in Lk().

Note that this approximation is valid only for \(p \ll 1\). An overview of alternative approaches can, for example, be found in [Asami2002] (e.g., in Table 2 therein).

References

[Asami2002] (1,2)

Asami, K. (2002). Characterization of heterogeneous systems by dielectric spectroscopy. Progress in Polymer Science, 27(8), 1617–1659. https://doi.org/10.1016/S0079-6700(02)00015-1

impedancefitter.cubic_roots.get_cubic_roots(a, b, c)[source]

Get the roots of a cubic equation.

Parameters:

  • a (complex) – polynomial coefficient

  • b (complex) – polynomial coefficient

  • c (complex) – polynomial coefficient

Returns:

Complex permittivity array

Return type:

numpy.ndarray, complex

Notes

Return the roots of an expression

\[z^3 + a z^2 + b z + c = 0\]

More details can be found in [Press2007].

References

[Press2007]

Press, W.H., Teukolsky, S.A., Vetterling, W.T., and Flannery, B.P. (2007) Numerical recipes : the art of scientific computing. Cambridge Univ. Press, USA, 3rd edition