permittivitycalc

Continuous Integration Code Coverage PyPI Package Docs Citation
TravisCI Appveyor Codecov PyPiBadge Documentation Status DOIBadge

Scripts to calculate and plot the complex permittivity (and permeability) from S-parameter data acquired from transmission-line measurements

Overview

permittivitycalc is a Python package made to take S-parameter data output from METAS VNA Tools II (https://www.metas.ch/vnatools) and process it to determine and plot the complex electric permittivity (and magnetic permeability) of a material measured in a coaxial transmission line.

Two analytical calculation methiods are currently implemented:

  • The New Non-iterative Method for permittivity calculation from S-parameters from [Boughriet1997] which assumes that the material is non-magnetic (i.e. mu = 1).
  • The Nicholson-Ross-Weir method to calculate the complex permittivity and permeability of a sample. This method, however, is unstable at multiples of one-half wavelength in the sample [NicolsonRoss1970] [Weir1974].

permittivitycalc can also use MCMC-based Bayesian model fitting/parameter estimation to fit Cole-Cole type models directly to the measured S-parameters to determine the frequency-dependant complex permittivity (and permeability, if desired). Cole-Cole models support multiple relaxation poles as well as a conductivity term.

You can use permittivitycalc to:

  • Input and plot raw S-parameter data in tabular form with or without uncertainties.
  • Calculate and plot the complex permittivity with full propagation of uncertainties.
  • Perform connector de-embedding on the raw S-parameters to extract the sample S-parameters, if necessary. Example: de-embedding washers used to cap the transmission line when measuring powdered samples.
  • Correct for the boundary effect in the transmission line when measuring powdered samples after [Hickson2017].
  • Correct for the air gap when measuring solid samples after [Baker-Jarvis1993].
  • Plot data from multiple measurements together for comparison.
  • Model measured S-parameters directly with a Cole-Cole model using MCMC-based Bayesian model fitting.

Usage

For usage examples and a walkthrough on how to use permittivitycalc, see the Docs

Installation

Requirements

permittivitycalc was written for Python 3 and tested on the following versions of Python:

  • 3.6
  • 3.7

permittivitycalc uses the following packages:

  • tkinter
  • numpy
  • uncertainties
  • scipy
  • matplotlib
  • seaborn
  • cycler
  • lmfit
  • emcee
  • corner

Installing Anaconda

We recommend using Anaconda to manage your Python environments.

  1. Install Anaconda.

  2. Open a terminal window and create a conda virtual environment (name it anything you like, and set the python version to a compatible version in Requirements):

    conda create --name your_env_name anaconda python=3.7

  3. Activate the environment:

    conda activate your_env_name

Quick Install

Install permittivitycalc with pip:

pip install permittivitycalc

Manual Install

  1. (Optional) Fork permittivitycalc on Github

  2. Clone or download the repository.

  3. Navigate to the permittivitycalc root directory and install with:

    python setup.py install

Contributors

permittivitycalc was developed with the aid of these contributors.

References

[Baker-Jarvis1993]Baker-Jarvis, J., Janezic, M. D., Grosvenor Jr, J. H., & Geyer, R. G. (1993). Transmission/reflection and short-circuit line methods for measuring permittivity and permeability. NIST Technical Note 1355-R. Boulder, CO. http://doi.org/10.6028/NIST.TN.1355r
[Boughriet1997]Boughriet, A. H., Legrand, C., & Chapoton, A. (1997). Noniterative stable transmission/reflection method for low-loss material complex permittivity determination. IEEE Transactions on Microwave Theory and Techniques, 45(1), 52–57. http://doi.org/10.1109/22.552032
[Hickson2017]Hickson, D., Sotodeh, S., Daly, M. G., Ghent, R., & Nolan, M. C. (2017). Improvements on effective permittivity measurements of powdered alumina: Implications for bulk permittivity properties of asteroid regoliths. Advances in Space Research, 59(1), 472–482. http://doi.org/10.1016/j.asr.2016.08.011
[NicolsonRoss1970]Nicolson, A. M., & Ross, G. F. (1970). Measurement of the Intrinsic Properties of Materials by Time-Domain Techniques. IEEE Transactions on Instrumentation and Measurement, 19(4), 377–382. http://doi.org/10.1109/TIM.1970.4313932
[Weir1974]Weir, W. B. (1974). Automatic Measurement of Complex Dielectric Constant and Permeability at Microwave Frequencies. Proceedings of the IEEE, 62(1), 33–36. http://doi.org/10.1109/PROC.1974.9382

Scattering Parameter Data and the AirlineData Class

class permittivitycalc.AirlineData(L, airline, dataArray, file, name=None, date=None, freq_cutoff=100000000.0, nrw=False, shorted=False, corr=False, normalize_density=False, norm_eqn='LI', bulk_density=None, solid_dielec=None, solid_losstan=None, particle_diameter=None, particle_density=None, temperature=None, typeA_unc=True)[source]

Use S-parameter data from a METAS VNA Tools II output text file to calculate the complex relative permittivity of a sample in a coaxial transmission line

Parameters:
  • L (float) – Length of airline in cm.
  • airline ({'VAL', 'PAL', 'GAL', '7', 'custom'}) – Name of airline used for measurement.
  • dataArray (array) – Array containing raw measurement data.
  • file (str) – Input file path.
  • corr (array) – Default = False. If True, also correct S-parameter data and produce corrected arrays.
  • nrw (bool, optional) – Default = False. If True, use Nicolson, Rross, Weir (NRW) algorithm to calculate permittivity and magnetic permeability.
  • shorted (bool, optional) –

    Default = False. If True, automatically load Shorted S11 data. File name must have the following format and be in the same folder as original file: file_path/file_name_shorted.txt

    Example:
    • file_path/air_atm.txt
    • file_path/air_atm_shorted.txt
  • normalize_density (bool or float or int, optional) – Default = False. If True, use either Lichtenecker or Landau-Lifshitz-Looyenga equation to normalize the complex permittivity to a constant density of 1.60 g/cm^3. If float or int is given, normalize to the density provided in g/cm^3. Requires that bulk_density be given.
  • norm_eqn ({'LI','LLL'}, optional) – Default = ‘LI’. For use with normalize_density. Equation to be used for normalization. Options are ‘LI’ for the Lichtenecker equation and ‘LLL’ for the Landau-Lifshitz-Looyenga equation. LI used alpha = 1.92 (Olhoeft, 1985) and LLL uses alpha = 0.307 (Hickson et al., 2017, Lunar samples).
  • name (str, optional) – Name of measurement to be used in plots.
  • bulk_density (float, optional) – Bulk density of material.
  • solid_dielec (float, optional) – The solid dielectric constant of the material.
  • solid_losstan (float, optional) – The solid loss tangent of the material.
  • particle_diameter (float, optional) – The average particle diameter in the airline in cm.
  • particle_density (float, optional) – The average (solid) particle density of the material in g/cm^3.
  • temperature (str or float, optional) – Temperature of measurement.
  • date (str, optional) – Date measurement was made.
  • freq_cutoff (float, optional) – Default: 1e8. Starting frequency for forward and reverse difference calculations.
  • freq (array) – Frequency points.
  • s21, s12, s22 (s11,) – Mag and Phase S-Parameters.
  • forward_dielec, reverse_dielec (avg_dielec,) – Real part of the permittivity. Can be avg_dielec, forward_dielec, or reverse_dielec for average, forward (S11,S21), or reverse (S22,S12) permittivity.
  • forward_lossfac, reverse_lossfac (avg_lossfac,) – Imaginary part of the permittivity. Same as above.
  • forward_losstan, reverse_losstan (avg_losstan,) – Loss tangent. Same as above.
  • forward_mu_real, reverse_mu_real (avg_mu_real,) – Real part of the magnetic permeability. Same as above.
  • forward_mu_imag, reverse_mu_imag (avg_mu_imag,) – Imaginary part of the magnetic permeability. Same as above.
  • corr – De-embeded version of S-parameters or electromagnetic data. Only average S-parameters are used for EM calculations with corrected S-parameters. Examples: corr_s11, corr_avg_losstan, corr_avg_mu_real. Only created if corr = True.
  • norm (array) – Bulk density normalized permittivity data. Uses averaged permittivity data. Only created if normalize_density = True.
  • res_freq (array) – Resonant frequencies in the sample.
  • airline_dimensions (dict) – Dimensions of the airline in cm. D1 is the diameter of the inner conductor and D4 is the diameter of the outer conductor. D2 and D3 bound the sample-airline boundary regions if particle_diameter is provided. airline_dimensions is generated automatically for airlines VAL, PAL, and GAL. Empty otherwise.
  • bcorr (complex array) – Avg complex permittivity corrected for boundary effects. Computed automatically if solid_dielec, particle_diameter, particle_density, and bulk_density are present. solid_losstan is optional.
  • imag_part_diff_array (real_part_diff_array,) – Absolute difference of forward and reverse results for the real and imaginary parts of the permittivity.
  • max_imag_diff, min_real_diff, min_imag_diff (max_real_diff,) – Maximum and minimum differences of the forward and reverse results for the real and imaginary parts of the permittivity.
_absdiff()[source]

Calculate the absolute max and median differences in calculated forward (S11,S21) and reverse (S22,S12) permittivity. Use corrected S-parameters if present.

_air_gap_correction(D2, D3)[source]

Calculates air gap corrected complex permittivity for solid samples.

Follows Baker-Jarvis et al., 1993 and Rhode & Schwarz Application Note RAC0607-0019_1_4E

Parameters:
  • Ds2 (float) – The inner diameter (cm) of the solid toroid sample to be specified by user
  • Ds3 (float T) – The outer diameter (cm) of the solid toroid sample to be specified by user
Returns:

  • corr_dielec (array) – Corrected real part of measured permittivity
  • corr_lossfac (array) – Corrected imaginary part of measured permittivity
  • corr_losstan (array) – Corrected loss tangent
_boundary_correct()[source]

Correct calculated sprams for boundary effects in the airline after Hickson et al., 2017. Requires the effective solid permittivity of the material, the average particle size in the airline, and the average particle (solid) density to be supplied to the class instance. Uses the Looyenga mixing model to calculate the permittivity in the boundary region.

As of now, produces dubious results for the imaginary part.

_calc_uncertainties(s_param, nrows, sign, x, s_reflect, s_trans, gam, lam_og, new_t, mu_eff, ep_eff, lam_0, dielec, lossfac, losstan, corr)[source]

Calculates permittivity uncertainties from Boughriet et al.

Returns:
  • delta_dielec (array) – Uncertainty in real part.
  • delta_lossfac (array) – Uncertainty in imaginary part.
_calc_uncertainties_NRW(s_param, nrows, sign, x, s_reflect, s_trans, gam, lam_og, new_t, complex_mu, ep_r, lam_0, dielec, lossfac, losstan, corr)[source]

Calculates nrw uncertainties from Baker-Jarvis et al. (1993). Transmission/reflection and short-circuit line methods for measuring permittivity and permeability. NIST Technical Note 1355-R. Boulder, CO: National Institute of Standards and Technology. http://doi.org/10.6028/NIST.TN.1355r

Returns:
  • delta_dielec (array) – Uncertainty in real part.
  • delta_lossfac (array) – Uncertainty in imaginary part.
  • delta_mu (complex array) – Uncertainty in complex permeability.
_de_embed()[source]

Perform S-parameter de-embedding to remove influence of washers on measurement.

_freq_avg()[source]

Calculate an average dielectric constant and loss tangent across all measured frequencies from midpoint frequency values between resonant frequencies as described in Hickson et al., 2018

Returns:
  • freq_avg_dielec (uncertainties.core.AffineScalarFunc) – Average dielectric constant calculated from midpoint frequency values between resonant frequencies. Skips first two values due to large uncertainty.
  • freq_avg_dielec_std (float) – Standard deviation of freq_avg_dielec from above.
  • freq_avg_losstan (uncertainties.core.AffineScalarFunc) – Average loss tangent calculated from midpoint frequency values between resonant frequencies. Skips first two values due to large uncertainty.
  • freq_avg_losstan_std (float) – Standard deviation of freq_avg_losstan from above.
_permittivity_calc(s_param, corr=False)[source]

Return the complex permittivity and loss tangent from S-parameters and their uncertainties (if present).

Uses the New Non-iterative method described in Boughriet, A.H., Legrand, C. & Chapoton, A., 1997. Noniterative stable transmission/reflection method for low-loss material complex permittivity determination. IEEE Transactions on Microwave Theory and Techniques, 45(1), pp.52–57.

Assumes the magnetic permeability of the sample = 1 (i.e non-magnetic).

Parameters:s_param (str) – Calculates complex permittivity using either the forward (‘f’) (S11,S21), or the reverse (‘r’) (S22 S12) S-Parameters.
Returns:
  • f_0 (array) – Array of measured frequency values.
  • dielec (array) – Real part of the complex relative permittivity.
  • lossfac (array) – Imaginary part of the complex permittivity.
  • losstan (array) – Loss tangent. Defined as the ratio of the imaginary and the real part of the complex permittivity.
_resonant_freq()[source]

Calculate and return array of resonant frequencies from complex permittivity and/or permeability measurement.

Follows David Stillman PhD Thesis

difference_plot()[source]

Plot the absolute difference between both ε′ and ε′′ calculated from forward (S11,S21) and reverse (S22,S12) S-Paramaters.

draw_plots(default_settings=True, publish=False, log_y_axis=False, xticks=None, yticks=None, corr=False, normalized=False, **kwargs)[source]

Plots permittivity data using make_plot from permittivity_plot.

If freq_cutoff exists, all frequency points lower than freq_cutoff will not be plotted.

Parameters:
  • default_settings (bool) – Default: True. If True, plots average real part of the permittivity, imaginary part of the permittivity and loss tangent. If corrected or normalized data exist, it will be used in the plot. If False prompts user to determine whether to plot, Average, Forward, Reverse, or All results.
  • publish (bool) – Default: False. If True, save figures.
  • log_y_axis (bool) – Default: False. If True, plot log y-axis. yticks must be provided if True.
  • xticks (list, optional) – Use to manually set y-axis tick make locations. Must be a list containing tick mark locations.
  • yticks (list of lists, optional) – Use to manually set y-axis tick make locations. Must be a list of lists containing tick mark locations for each individual plot in the following order: real part, imaginary part, loss tangent. If nrw=True, must additionaly provide: real part of mu, imaginary part of mu. Required if log_y_axis=True.
  • corr (bool, optional) – Can be used when default_settings is False. Can be used with any of the plot types. If True, use corrected sparam data, otheriwse use uncorrected data.
  • normalized (bool, optional) – Can be used when default_settings is False. Can only be used with Average plots. If True, use normalized permittivity data. Supersedes corr if True.
s_param_plot(corr=False)[source]

Plot raw S-Parameter data using make_sparam_plot from permittivity_plot

get_METAS_data

permittivitycalc.get_METAS_data(airline=None, file_path=None)[source]

Return data arrays from METAS VNA Tools II text file based on user input Frequencies must be in Hz. Recomeneded precision in VNA Tools II is f9.

Returns the first four arguments required by the AirlineData class.

Parameters:
  • airline (str) – Airline used for measurement. Options are: ‘VAL’, ‘PAL’, ‘GAL’, ‘7’. If not provided, will prompt user. Prompt will allow user to input a custom airline length.
  • file_path (str) – If a path is not given, will prompt user for file. Default: None
Returns:

  • L (float) – Length of airline in cm.
  • airline (str) – Name of the airline used.
  • dataArray (array) – S-parameters and their uncertainties (if present).
  • file (str) – File path.

run_default

permittivitycalc.run_default(airline_name='VAL', file_path=None, **kwargs)[source]

Run AirlineData on get_METAS_data with all the prompts and return the instance. Optional AirlineData kwargs can be provided (Example: shorted=True).

multiple_meas

permittivitycalc.multiple_meas(file_path=None, airline_name=None)[source]

Generate an instance of AirlineData for every file in a directory. Store the intances in a list, and plot them all using perm_compare.

Parameters:
  • file_path (str, optional) – Full path of any file in the source directory. Will produce file dialog box if not provided.
  • airlne (str, optional) – Name of airline used. Every measurement must have been made in the same airline. Will prompt if not provided.
Returns:

class_list – List of generated class instances of AirlineData.
Return type:

lst

perm_compare

permittivitycalc.perm_compare(classlist, allplots=False, **kwargs)[source]

Given a list of AirlineData instances, plot their permittivity results together using permittivity_plot. Fot each item in the list, will plot the first available data type out of: normalized data, corrected (de-embeded) data, uncorrected data.

Will use the smallest freq_cutoff value in the list (if avaialbe) for plotting.

Can provide permittivity_plot.make_plot kwargs.

Parameters:
  • classlist – List of instances of AirlineData.
  • allplots (bool) – Default: False. If True plot all of real and imaginary parts of the permittivity and the loss tangent. If Flase plot only the real part and the loss tangent.

Plotting Fucntions

Fucntions to plot permittivity and permeability results and S-parameters.

permittivitycalc.permittivity_plot.make_plot(xval, yval, plot_type='d', y_axis_type='normal', legend_label=None, name=None, plot_title=None, ylabel=None, xlabel=None, xticks=None, yticks=None, figure_size=(16, 10), freq_cutoff=None, publish=False)[source]

Takes input from sparam_data and plots calculated permittivity. Can handle multiple data sets. Plots uncertainty countour if plotting single dataset with uncertainty present and plots error bars every 25 points when plotting multiple datasets.

Parameters:
  • xval (array or list) – x-axis data. Multiple data sets must be in a list.
  • yval (array or list) – y-axis data. Multiple data sets must be in a list.
  • plot_type (str) – Flag for default plot types. Can be set to ‘d’ for the real part of epsilon, ‘lf’ for the imaginary part of epsilon, ‘lt’ for dielectric loss tangent, ‘ur’ for the real part of mu, ‘ui’ for the imaginary part of mu, or ‘c’ for Custom. If ‘c’ is used, xticks and yticks must be provided.
  • y_axis_type (str, optional) – Flag for type of axis to use for the y-axis. Can be either ‘normal’ (default) or ‘log’ for a log axis. If set to log, y tick postions must be manually provided to yticks.
  • legend_label (list of str, optional) – Plot legend label. Each dataset much have it’s own label. Stings must be in a list.
  • name (str, optional) – Required when publish=True. Used in file name of saved figure.
  • plot_title (str, optional) – For use when plot_type=’c’. Title of the plot.
  • ylabel (str, optional) – For use when plot_type=’c’. Y-axis label.
  • xlabel (str, optional) – For use when plot_type=’c’. X-axis label.
  • xticks (list, optional) – Manually set x-axis tick locations. Required when plot_type=’c’.
  • yticks (list, optional) – Manually set y-axis tick locations. Required when plot_type=’c’ and when y_axis_type=’log’.
  • figure_size (tuple or int, optional) – Set the matplotlib figsize. Default: (16,10).
  • freq_cutoff (float, optional) – Data points lower than freq_cutoff will not be plotted.
  • publish (bool, optional) – If True save figure as .eps file. Default: False.
permittivitycalc.permittivity_plot.make_sparam_plot(freq, s11, s22, s21, s12, label=None, shorted=False, s11_short=None)[source]

Plot raw S-Parameter data from S_Param_Script_V5. Supports multiple datasets for comparisson. Multilple datasets much be stored in a list and muct have same frequency array and number of data points.

Parameters:
  • freq (array) – Frequency points.
  • s11,s22,s21,s12 (array or list of arrays) – Mag and Phase S-Parameter data.
  • label (list, optional) – List of labels. Default: None

MCMC-based Permittivity/Permeability Determination

permittivitycalc.piter

alias of permittivitycalc.iter_data.AirlineIter

class permittivitycalc.iter_data.AirlineIter(data_instance, trial_run=True, number_of_poles=1, fit_mu=False, number_of_poles_mu=1, fit_conductivity=False, optimization_fit=False, number_of_fits=1, start_freq=None, end_freq=None, initial_parameters=None, nsteps=1000, nwalkers=100, nburn=500, nthin=1, nworkers=1, publish=False, name=None)[source]

Iterative fit to measured S-parameters using a Cole-Cole model. Can fit both 2-port and 2-port + shorted measurements. A flat model can also be used for samples with no measurable frequency dispersion.

To determine an initial guess for the fit, first fit a Cole-Cole model to analytical results: either New Non-iterative, NRW, or both. This provides an initial guess for the Cole-Cole model parameters. Then use the emcee package with lmfit to perform a Bayesian fit to the S-Parameters. This finds the Cole-Cole model which produces the best fit model S-parameters.

Parameters:
  • data_instance (permittivitycalc.AirlineData) – AirlineData class instance containing raw S-parameters to be iterated over. If data_instance contains corrected data, it will be automatically used.
  • trial_run (bool) – If True only fit Cole-Cole model to analytical results and plot the results. Useful for determining the number of poles to be used in the Cole-Cole model before perfoming the more time consuming final fit to the S-parameters (Default: True).
  • number_of_poles (int) – Number of poles to be used in the Cole-Cole model for epsilon. When number_of_poles is 0, a flat model will be used instead of a Cole-Cole model (epsilon* = epsilon_real - 1j*epsilon_imag) (Default: 1).
  • fit_mu (bool) – If True, fit both permittivity and permeability (Default: False).
  • number_of_poles_mu (int) – Number of poles to be used in the Cole-Cole model for mu. When number_of_poles_mu is 0, a flat model will be used instead of a Cole-Cole model (mu* = mu_real - 1j*mu_imag) (Default: 1).
  • fit_conductivity (bool) – If True, include a seperate real conductivity term in the Cole-Cole model for epsilon. Can be ignored for materials with very low conductivity (Default: False).
  • optimization_fit (bool) – If True, perform a typical non-linear least squares optimization fit using Levenberg–Marquardt instead of a Bayesian fit with MCMC (Default: False).
  • number_of_fits (int) – Number of default emcee fits to perform beofre final fit. Subsequent fits will use the results from the pervious iteration as initial values. Generally, using more steps is preferable to initializing a new fit (Default: 1).
  • start_freq (float or int, optional) – Start frequency in Hz for iteration. If None, will use the starting frequency of the data instance (Default: None).
  • end_freq (float or int, optional) – End frequency in Hz for iteration (Default: None).
  • initial_parameters (dict, optional) – A dictionary containing custom initial values for the iteration. Default values will be automatically generated if none are provided. The dictionary must contain initial values for all parameters in the iteration and each parameter much have the exact name as the ones used in the iteration. See documnetation for the _colecole and _iteration_parameters for parameter naming conventions.
  • nsteps (int, optional) – Number of steps to be used by emcee for iteration when trial_run is False. See lmfit and emcee documentation for details (Default: 1000).
  • nwalkwers (int, optional) – Number of walkers to be used by emcee for iteration when trial_run is False. See lmfit and emcee documentation for details (Default: 100).
  • nburn (int, optional) – Number of steps for burn-in phase to be used by emcee for iteration when trial_run is False. See lmfit and emcee documentation for details (Default: 500).
  • nthin (int, optional) – Only accept every nthin samples in emcee for iteration when trial_run is False. See lmfit and emcee documentation for details (Default: 1).
  • nworkers (int or pool, optional) – Number of workers or pool object for paralelization (Default: 1).
  • epsilon_iter (array) – Complex array containing the results of the iterrative fit for epsilon. trail_run must be set to False.
  • mu_iter (array) – Complex array containing the results of the iterative fit for mu. trial_run must be set to False and fit_mu must be set to True.
  • param_results (dict) – Model parameters for epsilon and mu (if fit_mu is True).
  • lmfit_results (lmfit.minimizer.MinimizerResult object) – Results from lmfit. See lmfit documentation.
  • publish (bool, optional) – If True save figure as .eps file. Default: False.
  • name (str, optional) – Required when publish=True. Used in file name of saved figure.

Basic Usage

Everything you need to know about using permittivitycalc: github.com/boivinalex/permittivitycalc.

Housekeeping

For information on what permittivitycalc is for and how to install it see the README on github.

Issues with or questions about this tutorial or permittivitycalc itself can be reported on the issue tracker.

Introduction

permittivitycalc works by storing input S-parameter data and associated processed data in a Python Class called AirlineData. When data is input into permittivitycalc, a new instance of the AirlineData Class is created.

The AirlineData Class contains several data attributes and methods.

Data attributes store the raw S-parameter data, processed (complex permittivity, permeability) data, as well as variables. Some variables are mandatory such as the length of the transmission line (L), and some are optional such as the bulk density of the sample measured (bulk_density).

Methods are functions which either automatically process the input data, can be called to process data if an argument is given to the AirlineData Class Instance, or must be called manually.

In addition to the class methods, permittivitycalc also has additional helper functions which are used to input data (either manually or via file dialog), to plot both the permittivity data and the raw S-parameter data, and to plot multiple permittivity datasets together.

This tutorial is intended to demonstrate the features of permittivitycalc starting with basic usage and moving on to more advanced, custom, or minor features.

Tutorial

Basic Usage
0.9.14
3.0rc2

permittivitycalc contains two example datasets:

Rexolite
The maximum precentage difference between forward (S11/S21) and reverse (S22/S12) calculated permittivity is:
ε′: 0.35% ε′′: 277.82% tanδ: 277.81%
The median precentage difference between forward (S11/S21) and reverse (S22/S12) calculated permittivity is:
ε′: 0.02% ε′′: 18.24% tanδ: 18.22%


Serpentine
The maximum precentage difference between forward (S11/S21) and reverse (S22/S12) calculated permittivity is:
ε′: 1.20% ε′′: 129.94% tanδ: 130.00%
The median precentage difference between forward (S11/S21) and reverse (S22/S12) calculated permittivity is:
ε′: 0.10% ε′′: 5.69% tanδ: 5.60%

Each dataset is stored as an individual AirlineData instance. We can quickly get information about individual AirlineData instances like so:

Serpentine measured in VAL (L = 14.989) with a bulk density of 1.6 g/cm^3 from file:
/anaconda/envs/permittivitycalc/lib/python3.7/site-packages/permittivitycalc-0.6.0-py3.7.egg/permittivitycalc/data/serpentine_dry.txt

Similarly, we can get a Python readable expression which can be used to re-create the instance like so:

pc.AirlineData(*pc.get_METAS_data(airline='VAL',file_path='/anaconda/envs/permittivitycalc/lib/python3.7/site-packages/permittivitycalc-0.6.0-py3.7.egg/permittivitycalc/data/serpentine_dry.txt'),bulk_density=1.6,temperature=None,name='Serpentine',date=None,corr=False,solid_dielec=None,solid_losstan=None,particle_diameter=None,particle_density=None,nrw=False,normalize_density=False,norm_eqn='LI',shorted=False,freq_cutoff=100000000.0)

The S-parameters in the instance can be plotted like so:

_images/output_11_0.png

The calculated real part of the permittivity, imaginary part of the permittivity, and loss tangent can be plotted like so:

_images/output_13_0.png _images/output_13_1.png _images/output_13_2.png

Two or more AirlineData instances can be compared to one another using the perm_compare function.

perm_compare requires a list of AirlineData instances to run. When more than one data set is being plotted, errorbars are shown every 25 points.

_images/output_15_0.png _images/output_15_1.png
Basic File Input

permittivitycalc expects a tab delimited .txt file produced by saving the data table created in VNA Tools II. permittivitycalc will automatically determine whether the file contains uncertainties or not and propagate them automatically if they are present.

Note: File input is done via the helper function ``get_METAS_data`` and file in unpacked into in components by the ``_unpack`` method in AirlineData. If you want to input a file not produced in VNA Tools II, you will need to edit ``get_METAS_data`` and ``_unpack``.

The run_default function is the simplest way to input a file into permittivitycalc. run_default needs an airline_name to run (Default: 'VAL'). The default corresponds to the GR900-LZ15 transmission line. Running run_default will produce a File Dialog Prompt using tkinter.

instance_name = pc.run_default()

To use a different airline definition, simply set the airline_name. Currently, the options are ‘VAL’, ‘PAL’, ‘GAL’, ‘7’, or ‘custom’. Using ‘custom’ will prompt you to input an airline length L in cm.

instance_name = pc.run_default(airline_name='custom')

Note: To create your own airline length definitions, edit the helper functions ``get_METAS_data`` and ``_get_file``

To open multiple files at once, the function multiple_meas can be used.

list_of_instances = pc.multiple_meas()

multiple_meas will ask you which airline you are using. The name must be given as a string. Once the airline_name is given a file dialog will open. Selecting any .txt file in a folder will open all other .txt files in that folder. All measurements must have been made in the same airline.

The airline name can also be supplied directly:

list_of_instances = pc.multiple_meas(airline_name='custom')

multple_meas returns a list of AirlineData instances and plots all input data together using perm_compare. Individual instances can be accessed with indexing.

Example:

individual_instance = list_of_instances[0]

Saving Plots

Permittivity plots can be saved to the /Figues/ folder (folder will be automatically created if it does not exist) by using the publish argument. This feature does not currently exist for the S-parameter plots.

Note: Currently, plots are saved as 300 dpi .eps files. These settings can be changed by editing the ``make_plot`` function in ``permittivity_plot.py``.

Example:

rexolite_example.draw_plots(publish=True)

Plots of multiple measurements can also be saved as long as a name is provided for the plots:

pc.perm_compare(multi_examples,name='save_name',publish=True)

Bulk Density Corrections

To correct powder measurements for bulk destiny, the bulk_density in g/cm3 must be provided, normalize_density must be set to True and, norm_eqn must be set to a valid string representing an equation (Default: 'LI').

Currently, two equations are available for density normalization: - The Lichtenecker equation ('LI') - Landau-Lifshitz-Looyenga equation ('LLL')

For information on how to use these equations see (Hickson, 2017)

Example:

instance_name = pc.run_default(bulk_density=1.8,normalize_density=True,norm_eqn='LLL')

Nicholson-Rross-Weir (NRW) Algorithm

By default, permittivity-plot uses the New Non-Iterative Method to calculate the complex permittivity from S-parameters (Boughriet, 1997) which assumes \(\mu\) = 1 (non-magnetic). To use the NRW algorithm instead (Nicolson & Ross, 1970;Weir, 1974), nrw must be set to True.

instance_name = pc.run_default(nrw=True)

Accessing The Data

When no uncertainties are provided in the input file, data in the AirlineData instance are stored as numpy arrays and can easily be accessed.

When uncertainties are provided, data are stored as unumpy.uarray objects where each value in the uarray has an uncertainty associated with it.

For example, the computed permittivity arrays are stored as avg_dielec, avg_lossfac, and avg_losstan.

Creating a copy of a data array simply requires accessing the relevant data attribute. For example:

For data when uncertainties, the nominal values can be extracted with unp.nominal_values() and the uncertainties can be extracted with unp.std_devs().

Indices and tables