eispy2d.core package#

Submodules#

eispy2d.core.configuration module#

A module for fixed parameters of problems.

Each problem addressed by a method may share common parameters, such as the number of sources, measuments etc. This module contains a class for storing information which will be shared by different scenarios. We call this problem configuration and it determines information regarding parameters of image and measurement domains.

The Configuration implements the container. In addition, auxiliary routines are provided in order to standardize some kind of information which may be necessary for other modules.

The following class is defined

Configuration
The container of all fixed information shared between scenarios.

The following routines are defined

import_dict()
A function for importing a dictionary with configuration attributes.

compute_wavelength()
Determine the wavelength for a given media and frequency.

compute_frequency()
Determine the frequency for a given media and wavelength.

compute_wavenumber()
Determine the wavenumber for a given media and frequency.

get_angles()
Return angles for a given number of points in S-domain.

get_coordinates_sdomain()
Return rectangular coordinates for a given number of points in S-domain.

get_bounds()
Return the standard bounds of the interval of D-domain for a given axis length.

get_coordinates_ddomain()
Return the standard meshgrid for D-domain.

get_contrast_map()
Return the contrast values for a given mesh of values of relative permittivity and conductivity.

get_greenfunction()
Return the Green function matrix for pulse-based discretization.

solve_frequency()
Estimate the frequency for a given complex media and wavelength.

plot_ddomain_limits()
Return a plot with D-domain bounds.

plot_antennas()
Return a plot with antennas points.

degrees_of_freedom()
Return the degrees of freedom of the problem.

class eispy2d.core.configuration.Configuration(name=None, number_measurements=None, number_sources=None, observation_radius=None, frequency=None, wavelength=None, background_permittivity=1.0, background_conductivity=0.0, image_size=[1.0, 1.0], wavelength_unit=True, magnitude=1.0, perfect_dielectric=False, good_conductor=False, import_filename=None, import_filepath='', path='')#

Bases: object

The container of all fixed information shared between scenarios.

It stores all the information regarding domains sizes, background media and flags for indicating simplifications.

name#: A string naming the problem configuration.

path#: The path where the object file was saved.

NM#: Number of measurements

NS#: Number of sources

Ro#: Radius of observation (S-domain) [m]

Lx#: Size of image domain (D-domain) in x-axis [m]

epsilon_rb#: Background relative permittivity

sigma_b#: Background conductivity [S/m]

frequency#: Linear frequency of operation [Hz]

lambda_b#: Background wavelength [m]

kb#: Background wavenumber [1/m]

perfect_dielectric#: Flag for assuming perfect dielectric objects

good_conductor#: Flag for assuming good conductor objects

E0#: Magnitude of incident field [V/m].

__init__(name=None, number_measurements=None, number_sources=None, observation_radius=None, frequency=None, wavelength=None, background_permittivity=1.0, background_conductivity=0.0, image_size=[1.0, 1.0], wavelength_unit=True, magnitude=1.0, perfect_dielectric=False, good_conductor=False, import_filename=None, import_filepath='', path='')#

Build or import a configuration object.

You may either give the parameters or import information from a save object. In addition, you must give either the frequency of operation or the wavelength.

Parameters:

name (string) – A string naming the problem configuration.
number_measurements (int, default: 10) – Receivers in S-domain.
number_sources (int, default: 10) – Sources in S-domain
observation_radius (float, default: 1.1*sqrt(2)*max([Lx,Ly])) – Radius for circular array of sources and receivers at S-domain [m]
frequency (float) – Linear frequency of operation [Hz]
wavelength (float) – Background wavelength [m]
background_permittivity (float, default: 1.) – Relative permittivity.
background_conductivity (float, default: .0 [S/m])
image_size (2-tuple of int, default: (1., 1.)) – Side length of the image domain (D-domain). It may be given in meters or in wavelengths.
wavelength_unit (boolean, default: True) – If True, the variable image_size will be interpreted as given in wavelegnths. Otherwise, it will be interpreted in meters.
magnitude (float, default: 1.0) – Magnitude of the incident field.
perfect_dielectric (boolean, default: False) – If True, it indicates the assumption of only perfect dielectric objects. Then, only the relative permittivity map will be recovered.
good_conductor (boolean, default: False) – If True, it indicates the assumption of only good conductors objects. Then, only the conductivity map will be recovered.
import_filename (string, default: None) – A string with the name of the pickle file containing the information of a previous Configuration object.
import_filepath (string, default: '') – A string containing the path to the object to be imported.

__str__()#: Print object information.

copy(configuration=None)#: Return or set a copy of an object.

draw(epsr=None, sig=None, file_path='', file_format='eps', show=False)#

Draw domain, sources and probes.

Plot an illustration of the problem configuration based on the values defined in the object. You may plot an empty problem or give a map.

Parameters:

epsr (numpy.ndarray, default: None) – A matrix with the relative permittivity map that you may want to draw as example.
sig (numpy.ndarray, default: None) – A matrix with the conductivity [S/m] map that you may want to draw as example.
show (boolean, default: False) – If True, a window with the figure will appear. If False, the figure will be saved as a file.
file_path (string, default: '') – A string indicating the path where you want to save the figure.
file_format (string, default: 'eps') – Format of the saved figure. It must be the same supported formats of matplotlib.pyplot.savefig().

importdata(file_name, file_path='')#: Import data from a saved object.

save(file_path=None)#

Save the problem configuration within a pickle file.

It will only be saved the attribute variables, not the object itself. If you want to load these variables, you may use the constant string variables for a more friendly usage.

eispy2d.core.configuration.compute_frequency(wavelength, epsilon_r=1.0, mu_r=1.0, sigma=0.0)#

Compute frequency.

Parameters:

wavelength (float) – In meters.
epsilon_r (float, default: 1.) – Relative permittivity of the medium.
mu_r (float, default: 1.) – Relative permeability of the medium.
sigma (float, default: .0) – Conductivity of the medium [S/m].

Returns:

frequencyfloat: In Hertz.

eispy2d.core.configuration.compute_wavelength(frequency, epsilon_r=1.0, mu_r=1.0, sigma=0.0)#

Compute wavelength.

Parameters:

frequency (float) – Linear frequency of operation [Hz].
epsilon_r (float, default: 1.) – Relative permittivity of the medium.
mu_r (float, default: 1.) – Relative permeability of the medium.
sigma (float, default: .0) – Conductivity of the medium [S/m].

Returns:

wavelengthfloat: In meters.

eispy2d.core.configuration.compute_wavenumber(frequency, epsilon_r=1.0, mu_r=1.0, sigma=0.0)#

Compute wavenumber.

Parameters:

frequency (float) – Linear frequency of operation [Hz].
epsilon_r (float, default: 1.) – Relative permittivity of the medium.
mu_r (float, default: 1.) – Relative permeability of the medium.
sigma (float, default: .0) – Conductivity of the medium [S/m].

Returns:

wavenumberfloat: In [1/m].

eispy2d.core.configuration.degrees_of_freedom(object_radius, wavenumber=None, epsilon_r=None, wavelength_unit=False, wavelength=None, frequency=None)#

Compute the degrees of freedom of an EIS problem.

The degrees of freedom for electromagnetic inverse scattering problems are the minimum number of measurements and sources. In this routine, it is implemented as follows:

\[M = 4 \times \lceil 2ka \rceil\]

where \(k\) is the wavenumber and \(a\) is the object radius. This formula is similar to [1] except that we are overestimating the number 4 times. Further discussion may be found in [2] and [3].

Parameters:

object_radius (float) – If this number is given in wavelengths, then wavelength_unit should be True. Otherwise, this will be interpreted in meters.
wavenumber (float, default: None)
epsilon_r (float, default: None) – Relative permittivity.
wavelength (float, default: None)
frequency (float, default: None)
*Obs. (either wavenumber or the wavelength or both)
given!* (epsilon_r and frequency must be)

Returns:

Mint: The degrees of freedom of the problem which may be used to set the number of measurements and sources.

References

eispy2d.core.configuration.get_angles(n_samples)#

Compute angles [rad] in a circular array of points equaly spaced.

Parameter#

n_samplesint
Number of samples.

returns:: numpy.ndarray

eispy2d.core.configuration.get_bounds(length)#

Compute the standard bound coordinates.

Parameters:

length (float) – Length of the domain (e.g., Lx or Ly).

Returns:

xmin, xmaxfloat: The lower and upper bounds of the interval.

eispy2d.core.configuration.get_conductivity(chi, omega, epsilon_rb, sigma_b)#

Compute the conductvity for a given contrast value.

Parameters:

chi (float or numpy.ndarray) – Contrast value or array.
omega (float) – Angular frequency [rad/s].
epsilon_rb (float) – Background relative permittivity
sigma_b (float) – Background conductivity

eispy2d.core.configuration.get_contrast_map(epsilon_r=None, sigma=None, epsilon_rb=None, sigma_b=None, omega=None, configuration=None)#

Compute the contrast function for a given image.

Parameters:

epsilon_r (numpy.ndarray) – A matrix with the relative permittivity map.
sigma (numpy.ndarray) – A matrix with the conductivity map [S/m].
epsilon_rb (float) – Background relative permittivity of the medium.
sigma_b (float) – Background conductivity of the medium [S/m].
omega (float) – Angular frequency of operation [rad/s].
configuration (Configuration) – A configuration object that may replace epsilon_rb, sigma_b and omega.

eispy2d.core.configuration.get_coordinates_ddomain(configuration=None, resolution=None, dx=None, dy=None, xmin=None, xmax=None, ymin=None, ymax=None)#

Return the meshgrid of the image domain.

Examples

The function must be called in only one of the two different ways:

>>> config = Configuration(name='example', wavelength=1.0)
>>> get_coordinates_ddomain(configuration=config, resolution=(100, 100))

>>> get_coordinates_ddomain(dx=.1, dy=.1, xmin=-1., xmax=1.,
                            ymin=-1., ymax=1.)

Parameters:

configuration (Configuration) – A configuration object.
resolution (2-tuple of int) – Discretization size in y- and x-coordinates (Ny, Nx) (this order).
dx (float) – Cell size.
dy (float) – Cell size.
xmin (float) – Limits of the interval in x-axis.
xmax (float) – Limits of the interval in x-axis.
ymin (float) – Limits of the interval in y-axis.
ymax (float) – Limits of the interval in y-axis.

Notes

The D-domain are such that (x,y) in [xmin,xmax] times [ymin, ymax]. The coordinates are positioned at the center of the cells.

eispy2d.core.configuration.get_coordinates_sdomain(radius, n_samples, shift=0.0)#

Compute coordinates of points in a circular array equaly spaced.

Parameters:

radius (float) – Observation radius [m].
n_samples (int) – Number of sampled points.
shift (float, default: .0) – A radial shift in array position.

Returns:

x, y: Coordinates of the sampled points.

eispy2d.core.configuration.get_relative_permittivity(chi, epsilon_rb)#

Compute the relative permittivity for a given contrast value.

Parameters:

chi (float or numpy.ndarray) – Contrast value or array.
epsilon_rb (float) – Background relative permittivity

eispy2d.core.configuration.import_dict(file_name, file_path='')#

Import dictionary with configuration data.

Parameters:

file_name (str) – Name of the pickle file.
file_path (str, default: '') – Path to the file.

Returns:

datadict: Dictionary with configuration attributes.

eispy2d.core.configuration.plot_antennas(axes, x, y, wavelength, color, label)#

Plot antennas array.

Parameters:

axes (matplotlib.pyplot.Axes) – Axes object.
x (numpy.ndarray) – Array with the x-coordinates.
y (numpy.ndarray) – Array with the y-coordinates.
wavelength (float) – Wavelength in meters (used for scaling).
color ({'r', 'g'}) – Color of the points.
label (str) – Name of the antenna array.

Returns:

matplotlib.lines.Line2D: The plotted line object.

eispy2d.core.configuration.plot_ddomain_limits(axes, bounds)#

Plot lines of D-domain limits.

Parameters:

axes (matplotlib.pyplot.Axes) – Axes object.
bounds (4-tuple of float) – (xmin, xmax, ymin, ymax) bounds.

eispy2d.core.configuration.solve_frequency(lambda_b, mu_r, epsilon_r, sigma)#

Approximate the frequency.

The routine estimates the corresponding frequency for a given combination of wavelength [m], relative permeability, relative permittivity and conductivity [S/m] values.

Parameters:

lambda_b (float) – Wavelength [m].
mu_r (float) – Relative permeability.
epsilon_r (float) – Relative permittivity.
sigma (float) – Conductivity [S/m].

Notes

The estimation is based on the Golden Section Method for unidimensional problems. The solution is the one which minimizes the following objective-function:

\[\phi(f) = \lambda_b - \frac{1}{f \Re\left\{ \sqrt{\mu\left(\epsilon - j\frac{\sigma}{2\pi f}\right)} \right\}}\]

eispy2d.core.error module#

Error classes which may be risen.

exception eispy2d.core.error.EmptyAttribute(class_name, attribute_name)#

Bases: Error

Exception for empty class attribute.

class_name#

Name of the class.

Type:: str

attribute_name#

Name of the empty attribute.

Type:: str

message#

Explanation of the error.

Type:: str

__init__(class_name, attribute_name)#: Store exception information.

exception eispy2d.core.error.Error#

Bases: Exception

Base class for exceptions in this module.

exception eispy2d.core.error.ExcessiveInputsError(function_name, input_names)#

Bases: Error

An error exception for excessive inputs.

function_name#

A string with the name of the function.

Type:: str

input_names#

A list of strings with the input names.

Type:: list of str

__init__(function_name, input_names)#: Save the name of the function and inputs.

exception eispy2d.core.error.MissingAttributesError(class_name, attribute_name)#

Bases: Error

Exception raised when some attribute is missing within an object.

class_name#

A string with the name of the class.

Type:: str

attribute_name#

The name of the missing attribute.

Type:: str

__init__(class_name, attribute_name)#: Save the class of the object and the missing attribute.

exception eispy2d.core.error.MissingInputError(function_name, input_names)#

Bases: Error

Exception raised for errors in the input.

function_name#

A string containing the name of the function.

Type:: str

input_names#

A string or a list of strings with the names of the missing inputs.

Type:: str or list of str

message#

Explanation of the error.

Type:: str

__init__(function_name, input_names)#: Save the name of the function and the missing inputs.

exception eispy2d.core.error.WrongTypeInput(function_name, input_name, right_type, wrong_type)#

Bases: Error

Exception raised when some argument is passed in wrong type.

function_name, input_name

Names of the function/method and the name of the input.

Type:: str

right_type, wrong_type

Names of the expected and given type, respectively.

Type:: str

__init__(function_name, input_name, right_type, wrong_type)#: Save the basic information.

exception eispy2d.core.error.WrongValueInput(function_name, input_name, expect_values, given_value)#

Bases: Error

Exception raised when some argument is given with wrong value.

function_name, input_name

Names of the function and input.

Type:: str

expected_values#

A string with the rule or options of inputs.

Type:: str

given_value#

A string with the given value impressed.

Type:: str

__init__(function_name, input_name, expect_values, given_value)#: Save the basic information.

Module contents#

Core module for eispy2d.

Contains fundamental classes and utilities used throughout the library: - Configuration: Problem domain configuration - Error: Custom exception classes

class eispy2d.core.Configuration(name=None, number_measurements=None, number_sources=None, observation_radius=None, frequency=None, wavelength=None, background_permittivity=1.0, background_conductivity=0.0, image_size=[1.0, 1.0], wavelength_unit=True, magnitude=1.0, perfect_dielectric=False, good_conductor=False, import_filename=None, import_filepath='', path='')#

Bases: object

The container of all fixed information shared between scenarios.

It stores all the information regarding domains sizes, background media and flags for indicating simplifications.

name#: A string naming the problem configuration.

path#: The path where the object file was saved.

NM#: Number of measurements

NS#: Number of sources

Ro#: Radius of observation (S-domain) [m]

Lx#: Size of image domain (D-domain) in x-axis [m]

epsilon_rb#: Background relative permittivity

sigma_b#: Background conductivity [S/m]

frequency#: Linear frequency of operation [Hz]

lambda_b#: Background wavelength [m]

kb#: Background wavenumber [1/m]

perfect_dielectric#: Flag for assuming perfect dielectric objects

good_conductor#: Flag for assuming good conductor objects

E0#: Magnitude of incident field [V/m].

Build or import a configuration object.

You may either give the parameters or import information from a save object. In addition, you must give either the frequency of operation or the wavelength.

Parameters:

name (string) – A string naming the problem configuration.
number_measurements (int, default: 10) – Receivers in S-domain.
number_sources (int, default: 10) – Sources in S-domain
observation_radius (float, default: 1.1*sqrt(2)*max([Lx,Ly])) – Radius for circular array of sources and receivers at S-domain [m]
frequency (float) – Linear frequency of operation [Hz]
wavelength (float) – Background wavelength [m]
background_permittivity (float, default: 1.) – Relative permittivity.
background_conductivity (float, default: .0 [S/m])
image_size (2-tuple of int, default: (1., 1.)) – Side length of the image domain (D-domain). It may be given in meters or in wavelengths.
wavelength_unit (boolean, default: True) – If True, the variable image_size will be interpreted as given in wavelegnths. Otherwise, it will be interpreted in meters.
magnitude (float, default: 1.0) – Magnitude of the incident field.
perfect_dielectric (boolean, default: False) – If True, it indicates the assumption of only perfect dielectric objects. Then, only the relative permittivity map will be recovered.
good_conductor (boolean, default: False) – If True, it indicates the assumption of only good conductors objects. Then, only the conductivity map will be recovered.
import_filename (string, default: None) – A string with the name of the pickle file containing the information of a previous Configuration object.
import_filepath (string, default: '') – A string containing the path to the object to be imported.

__str__()#: Print object information.

copy(configuration=None)#: Return or set a copy of an object.

draw(epsr=None, sig=None, file_path='', file_format='eps', show=False)#

Draw domain, sources and probes.

Plot an illustration of the problem configuration based on the values defined in the object. You may plot an empty problem or give a map.

Parameters:

epsr (numpy.ndarray, default: None) – A matrix with the relative permittivity map that you may want to draw as example.
sig (numpy.ndarray, default: None) – A matrix with the conductivity [S/m] map that you may want to draw as example.
show (boolean, default: False) – If True, a window with the figure will appear. If False, the figure will be saved as a file.
file_path (string, default: '') – A string indicating the path where you want to save the figure.
file_format (string, default: 'eps') – Format of the saved figure. It must be the same supported formats of matplotlib.pyplot.savefig().

importdata(file_name, file_path='')#: Import data from a saved object.

save(file_path=None)#

Save the problem configuration within a pickle file.

It will only be saved the attribute variables, not the object itself. If you want to load these variables, you may use the constant string variables for a more friendly usage.

exception eispy2d.core.EmptyAttribute(class_name, attribute_name)#

Bases: Error

Exception for empty class attribute.

class_name#

Name of the class.

Type:: str

attribute_name#

Name of the empty attribute.

Type:: str

message#

Explanation of the error.

Type:: str

__init__(class_name, attribute_name)#: Store exception information.

exception eispy2d.core.Error#

Bases: Exception

Base class for exceptions in this module.

exception eispy2d.core.ExcessiveInputsError(function_name, input_names)#

Bases: Error

An error exception for excessive inputs.

function_name#

A string with the name of the function.

Type:: str

input_names#

A list of strings with the input names.

Type:: list of str

__init__(function_name, input_names)#: Save the name of the function and inputs.

exception eispy2d.core.MissingAttributesError(class_name, attribute_name)#

Bases: Error

Exception raised when some attribute is missing within an object.

class_name#

A string with the name of the class.

Type:: str

attribute_name#

The name of the missing attribute.

Type:: str

__init__(class_name, attribute_name)#: Save the class of the object and the missing attribute.

exception eispy2d.core.MissingInputError(function_name, input_names)#

Bases: Error

Exception raised for errors in the input.

function_name#

A string containing the name of the function.

Type:: str

input_names#

A string or a list of strings with the names of the missing inputs.

Type:: str or list of str

message#

Explanation of the error.

Type:: str

__init__(function_name, input_names)#: Save the name of the function and the missing inputs.

exception eispy2d.core.WrongTypeInput(function_name, input_name, right_type, wrong_type)#

Bases: Error

Exception raised when some argument is passed in wrong type.

function_name, input_name

Names of the function/method and the name of the input.

Type:: str

right_type, wrong_type

Names of the expected and given type, respectively.

Type:: str

__init__(function_name, input_name, right_type, wrong_type)#: Save the basic information.

exception eispy2d.core.WrongValueInput(function_name, input_name, expect_values, given_value)#

Bases: Error

Exception raised when some argument is given with wrong value.

function_name, input_name

Names of the function and input.

Type:: str

expected_values#

A string with the rule or options of inputs.

Type:: str

given_value#

A string with the given value impressed.

Type:: str

__init__(function_name, input_name, expect_values, given_value)#: Save the basic information.