shgpy.core.data_handler module

class shgpy.core.data_handler.DataContainer(iterable, input_angle_units, normal_to_oblique=False)

Bases: object

Contains SHG data in phi-space.

Parameters
iterabledict or array_like

dict which defines the data. Should be in form {‘PP’:array([xdata, ydata]), ‘PS’:…}. Also accepts array_like of form ((‘PP’:array([xdata, ydata])), (‘PS’, …), …).

input_angle_units{‘radians’, ‘degrees’}

Units of xdata.

normal_to_obliquebool, optional

Defaults to False. If True, iterable should have only two elements: one with key ‘PP’ or ‘SS’, and one with key ‘PS’ or ‘SP’. Then, upon initialization, compute the “missing” polarization components by rotating by 90 degrees. The final object has dat.get_keys() = ['PP', 'PS', 'SP', 'SS'].

Notes

The function of the DataContainer class is to hold data which could just as well be contained in a dictionary defined like data = {'PP':array([xdata, ydata]), 'PS':array([xdata, ydata]), ...}. Many of the associated methods involve getting and setting this data like you would in a dictionary. However, putting this data in a predefined objects allows one to keep track of whatever manipulations (scaling, offsetting) have been applied to the data, as well as other attributes like the units with which the data was defined.

get_items(requested_angle_units)

Get a list of (pc, data) pairs.

Equivalent to dict.items().

Parameters
requested_angle_units{‘radians’, ‘degrees’}

Units requested for xdata.

Returns
datalist of (pc, ndarray) tuple

List of data for each polarization combination, each in the form (pc, array([xdata, ydata]))

get_keys()

Get the polarization combinations for this data.

Equivalent to dict.keys().

Returns
pcslist of str
get_maxval()

Get the maximum value of the data.

Returns
mac_pcstr

The polarization combination for which the maximum occurred

maximum_valuefloat

The maximum value attained.

get_minval()

Get the minimum value of the data.

Returns
min_pcstr

The polarization combination for which the minimum occurred.

minimum_valuefloat

The minimum value attained.

get_offset()

Returns the degree to which the data has been offset

get_pc(pc, requested_angle_units)

Get data for single polarization combination.

Parameters
pcstr

Polarization combination of interest.

requested_angle_units{‘radians’, ‘degrees’}

Units requested for xdata.

Returns
datandarray

Data for polarization combination pc in the form array([xdata, ydata]).

get_pc_maxval(pc)

Get the maximum value of a particular polarization combination.

Parameters
pcstr

The polarization combination of interest.

Returns
maximum_valuefloat
get_pc_minval(pc)

Get the minimum value of a particular polarization combination.

Parameters
pcstr

The polarization combination of interest.

Returns
minimum_valuefloat
get_phase_shift(requested_angle_units)

Get the extent to which this data has been phase shifted from the original.

Parameters
requested_angle_units{‘radians’, ‘degrees’}
Returns
phase_shiftfloat
get_scale()

Get the extent to which this data has been scaled from the original.

get_values(requested_angle_units)

Get a list of data (without polarization combination reference)

Equivalent to dict.values().

Parameters
requested_angle_units{‘radians’, ‘degrees’}

Units requested for xdata.

Returns
datalist of ndarray

Data for each polarization combination in the form array([xdata, ydata])

normalize_data(desired_maximum=1)

Normalize the data to a desired maximum.

phase_shift_data(angle, angle_units)

Phase shift the data by a constant amount.

Parameters
anglefloat
angle_units{‘radians’, ‘degrees’}

Units of argument angle.

scale_data(scale_factor)

Scale the data by a constant factor.

subtract_min()

Subtract the minimum from the data.

class shgpy.core.data_handler.FormContainer(iterable)

Bases: object

Contains an SHG formula in phi-space.

Parameters
iterabledict or array_like

dict which defines the formula. Should be in form {‘PP’:sympy.Expr, ‘PS’:…, …}. Also accepts array_like of form ((‘PP’:sympy.Expr), (‘PS’, …), …).

Notes

While fitting RA-SHG in Fourier space is usually faster, for simple problems it is acceptable to fit in real space. An instance of the FormContainer class provides a convenient means of storing and manipulating such a formula. It basically acts as a dictionary of {pc:formula} pairs, where pc labels the polarization combination and formula is an instance of the sympy.Expr class.

apply_phase_shift(phase_shift, var_to_shift)

Phase shift the formula.

Parameters
phase_shiftsympy.Expr

Amount to shift by

var_to_shiftsympy.Symbol

Variable to shift

Notes

This method is equivalent to subs([var_to_shift, var_to_shift+phase_shift])

expand()

Apply the sympy.expand method to every polarization combination.

get_free_symbols()

Return a sorted list of the free symbols in the Fourier formula.

get_items()

Get a list of (pc, formula) pairs.

Equivalent to dict.items().

Returns
itemslist of (str, sympy.Expr) tuple

List of data for each polarization combination, each in the form (pc, formula)

get_keys()

Get the polarization combinations for this formula.

Equivalent to dict.keys().

Returns
pcslist of str
get_pc(pc)

Get the formula for single polarization combination.

Parameters
pcstr

Polarization combination of interest.

Returns
formulasympy.Expr

Formula expression for polarization combination pc.

get_values()

Get a list of the formulas (without polarization combination reference)

Equivalent to dict.values().

Returns
valueslist of sympy.Expr
simplify()

Apply the sympy.simplify method to every polarization combination.

subs(subs_array)

Substitute for some variables in the Fourier formula.

Parameters
subs_arrayarray_like of array_like of sympy.Expr

An array of pairs of values. For example, to substitute the expression 2*psi for the variable phi, use subs_array = ((phi, 2*psi)).

shgpy.core.data_handler.dat_add(dat1, dat2)

Add two DataContainer instances.

Parameters
dat1DataContainer

Instance of DataContainer

dat2DataContainer

Instance of DataContainer

Returns
dat_resultDataContainer

Instance of DataContainer containing the contents of dat1+dat2.

shgpy.core.data_handler.dat_subtract(dat1, dat2)

Subtract two DataContainer instances.

Parameters
dat1DataContainer

Instance of DataContainer

dat2DataContainer

Instance of DataContainer

Returns
dat_resultDataContainer

Instance of DataContainer containing the contents of dat1-dat2.

shgpy.core.data_handler.dat_to_fdat(dat, interp_kind='cubic', M=16)

Convert instance of DataContainer to instance of fDataContainer

Parameters
datDataContainer

Instance of DataContainer

interp_kindstr or int, optional

Specifies the kind of interpolation as a string (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, ‘next’, where ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order; ‘previous’ and ‘next’ simply return the previous or next value of the point) or as an integer specifying the order of the spline interpolator to use. Default is ‘cubic’.

Mint, optional

Number of Fourier frequencies, defaults to 16.

Returns
fdatfDataContainer

Instance of fDataContainer

Notes

This function works by taking a DataContainer instance and performing an interpolation so that the points are equally spaced along phi. Then it performs a Fourier transform and returns an fDataContainer instance. The interpolation is necessary because a large portion of the codebase requires equally spaced points in order for the Fourier transform to be well-defined.

class shgpy.core.data_handler.fDataContainer(iterable, M=16)

Bases: object

Contains SHG data in Fourier space.

Parameters
iterabledict or array_like

dict which defines the data. Should be in form {‘PP’:ndarray(…), ‘PS’:…, …}. Also accepts array_like of form ((‘PP’:ndarray(…)), (‘PS’, …), …).

Notes

A central capability of the shgpy package is to be able to fit RA-SHG data in Fourier space. What that amounts to is fitting the Fourier components of a particular fitting formula to the Fourier components of the data. An instance of the fDataContainer class basically acts as a dictionary holding pairs (pc, fdata), where pc is a str label for the polarization combination and fdata is an ndarray of length 2*M+1. The nth element here denotes the (n-M)th fourier component of the data to be fitted.

get_M()

Get the number of Fourier frequencies.

Each fdata array has 2*M+1 elements.

get_items()

Get a list of (pc, fdata) pairs.

Equivalent to dict.items().

Returns
fdatalist of (pc, ndarray) tuple

List of data for each polarization combination, each in the form (pc, array(shape=(2*M+1,)))

get_keys()

Get the polarization combinations for this data.

Equivalent to dict.keys().

Returns
pcslist of str
get_maxval()

Get the maximum value of the data.

Returns
mac_pcstr

The polarization combination for which the maximum occurred

maximum_valuefloat

The maximum value attained.

Notes

Since the elements of the fourier transform are in general complex numbers, this method returns the maximum value of the magnitudes of the different elements.

get_pc(pc)

Get fdata for single polarization combination.

Parameters
pcstr

Polarization combination of interest.

Returns
fdatandarray

Data for polarization combination pc with shape 2*M+1.

get_pc_maxval(pc)

Get the maximum value of a particular polarization combination.

Parameters
pcstr

The polarization combination of interest.

Returns
maximum_valuefloat

Returns maximum of magnitudes of fourier components (see get_maxval())

get_phase_shift(requested_angle_units)

Get the extent to which this data has been phase shifted from the original.

Parameters
requested_angle_units{‘radians’, ‘degrees’}
Returns
phase_shiftfloat
get_scale()

Get the extent to which this data has been scaled from the original.

get_values()

Get a list of data (without polarization combination reference)

Equivalent to dict.values().

Returns
fdatalist of ndarray

Data for each polarization combination in the form array(shape=(2*M+1,))

normalize_fdata(desired_maximum)

Normalize the data to a desired maximum.

phase_shift_fdata(angle, angle_units)

Phase shift the data by a constant amount.

Parameters
anglefloat
angle_units{‘radians’, ‘degrees’}

Units of argument angle.

scale_fdata(scale_factor)

Normalize the fdata by a given amount.

class shgpy.core.data_handler.fFormContainer(iterable, M=16)

Bases: object

Contains an SHG formula in Fourier space.

Parameters
iterabledict or array_like

dict which defines the Fourier formula. Should be in form {‘PP’:ndarray(…), ‘PS’:…, …}. Also accepts array_like of form ((‘PP’:ndarray(…)), (‘PS’, …), …).

Notes

In order to fit RA-SHG data in Fourier space, we need to know the different Fourier components of our fitting formula. An instance of the fFormContainer class provides a convenient means of holding and manipulating such a Fourier formula. It basically acts as a dictionary of {pc:fformula} pairs, where pc labels the polarization combination and fformula is an ndarray of length 2*M+1. Here, the nth element of fformula contains a formula for the (n-M)th Fourier coefficient.

apply_phase_shift(phase_shift)

Phase shift the Fourier formula.

Parameters
phase_shiftsympy.Expr

Notes

This method works simply by multiplying the mth component of the Fourier formula by sympy.exp(1j * m * phase_shift).

get_M()

Get the number of Fourier frequencies.

Each Fourier formula array has 2*M+1 elements.

get_free_symbols()

Return a sorted list of the free symbols in the Fourier formula.

get_items()

Get a list of (pc, fformula) pairs.

Equivalent to dict.items().

Returns
itemslist of (str, ndarray) tuple

List of data for each polarization combination, each in the form (pc, array(shape=(2*M+1,)))

get_keys()

Get the polarization combinations for this Fourier formula.

Equivalent to dict.keys().

Returns
pcslist of str
get_pc(pc)

Get the Fourier formula for single polarization combination.

Parameters
pcstr

Polarization combination of interest.

Returns
fformulandarray

Fourier formula array for polarization combination pc.

get_values()

Get a list of the Fourier formulas (without polarization combination reference)

Equivalent to dict.values().

Returns
valueslist of ndarray

Data for each polarization combination in the form array([xdata, ydata])

subs(subs_array)

Substitute for some variables in the Fourier formula.

Parameters
subs_arrayarray_like of array_like of sympy.Expr

An array of pairs of values. For example, to substitute the expression 2*xyz for the variable xxx, use subs_array = ((xxx, 2*xyz)).

shgpy.core.data_handler.fdat_to_dat(fdat, num_points)

Convert instance of fDataContainer to instance of DataContainer

Parameters
fdatfDataContainer

Instance of fDataContainer

num_pointsint

Number of different points to put into the DataContainer.

Returns
datDataContainer

Instance of DataContainer

Notes

This function operates by taking an instance of the fDataContainer class and performing an inverse Fourier transform.

shgpy.core.data_handler.fform_to_dat(fform, subs_dict, num_points)

Convert instance of fFormContainer to instance of DataContainer

Parameters
fformfFormContainer

Instance of fFormContainer

subs_dictdict

Dict of {sympy.Symbol : float} pairs to perform the substitution.

num_pointsint

Number of different points to put into the DataContainer.

Returns
datDataContainer

Instance of DataContainer

Notes

This function operates by taking an instance of the fFormContainer class and substituting for all the relevant sympy.Symbol`s according to `subs_dict. Then it creates a DataContainer instance with num_points points.

shgpy.core.data_handler.fform_to_fdat(fform, subs_dict)

Convert instance of fFormContainer to instance of fDataContainer

Parameters
fformfFormContainer

Instance of fFormContainer

subs_dictdict

Dict of {sympy.Symbol : float} pairs to perform the substitution.

Returns
fdatfDataContainer

Instance of fDataContainer

Notes

This function operates by taking an instance of the fFormContainer class and substituting for all the relevant sympy.Symbol`s according to `subs_dict.

shgpy.core.data_handler.fform_to_form(fform)

Convert instance of fFormContainer to instance of FormContainer

Parameters
fformfFormContainer

Instance of fFormContainer

Returns
formFormContainer

Instance of FormContainer

Notes

This function operates by taking an instance of the fFormContainer class and performing a Fourier transform.

shgpy.core.data_handler.form_to_dat(form, subs_dict, num_points)

Convert instance of FormContainer to instance of DataContainer

Parameters
formFormContainer

Instance of FormContainer

subs_dictdict

Dict of {sympy.Symbol : float} pairs to perform the substitution.

num_pointsint

Number of different points to put into the DataContainer.

Returns
datDataContainer

Instance of DataContainer

Notes

This function operates by taking an instance of the FormContainer class and substituting for all the relevant sympy.Symbol`s according to `subs_dict. Then it creates a DataContainer instance with num_points points.

shgpy.core.data_handler.form_to_fdat(form, subs_dict, M=16)

Convert instance of FormContainer to instance of fDataContainer

Parameters
fformFormContainer

Instance of FormContainer

subs_dictdict

Dict of {sympy.Symbol : float} pairs to perform the substitution.

Returns
fdatfDataContainer

Instance of fDataContainer

Notes

This function operates by taking an instance of the FormContainer, doing a Fourier transform to a fFormContainer instance, and then substituting for all the relevant sympy.Symbol`s according to `subs_dict.

shgpy.core.data_handler.form_to_fform(form, M=16)

Convert instance of FormContainer to instance of fFormContainer

Parameters
formFormContainer

Instance of FormContainer

Mint, optional

Number of Fourier frequencies, defaults to 16.

Returns
fformfFormContainer

Instance of fFormContainer

Notes

This function operates by taking an instance of the FormContainer class and performing a Fourier transform.

shgpy.core.data_handler.load_data(data_filenames_dict, angle_units, normal_to_oblique=False)

Load RA-SHG data from a dict of filenames.

Parameters
data_filenames_dictdict of (str

dict of form (polarization combination : filename).

data_angle_units{‘radians’, ‘degrees’}

Units of xdata

normal_to_obliquebool, optional

Defaults to False. See DataContainer.

Returns
datDataContainer
shgpy.core.data_handler.load_data_and_dark_subtract(data_filenames_dict, data_angle_units, dark_filenames_dict, dark_angle_units, normal_to_oblique=False)

Load RA-SHG data from a dict of filenames and dark subtract.

Parameters
data_filenames_dictdict of (str

dict of form (polarization combination : filename).

data_angle_units{‘radians’, ‘degrees’}

Units of xdata

dark_filenames_dictdict of (str

dict of form (polarization combination : filename).

dark_angle_units{‘radians’, ‘degrees’}

Units of xdata for the dark.

normal_to_obliquebool, optional

Defaults to False. See DataContainer.

Returns
datDataContainer
shgpy.core.data_handler.load_data_and_fourier_transform(data_filenames_dict, data_angle_units, dark_filenames_dict=None, dark_angle_units=None, interp_kind='cubic', M=16, min_subtract=False, scale=1, normal_to_oblique=False)

Load RA-SHG data from a dict of filenames and Fourier transform

Parameters
data_filenames_dictdict of (str

dict of form (polarization combination : filename).

data_angle_units{‘radians’, ‘degrees’}

Units of xdata

dark_filenames_dictdict of (str

dict of form (polarization combination : filename).

dark_angle_units{‘radians’, ‘degrees’}

Units of xdata for the dark.

interp_kindstr or int, optional

Specifies the kind of interpolation as a string (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, ‘next’, where ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order; ‘previous’ and ‘next’ simply return the previous or next value of the point) or as an integer specifying the order of the spline interpolator to use. Default is ‘cubic’ Dict of {sympy.Symbol : float} pairs to perform the substitution.

Mint, optional

Number of Fourier frequencies, defaults to 16.

min_subtractbool

Whether to subtract the minimum before Fourier transforming. Default is False.

normal_to_obliquebool, optional

Defaults to False. See DataContainer.

Returns
datDataContainer
fdatfDataContainer
shgpy.core.data_handler.load_fform(fform_filename)

Creat instance of fFormContainer from a fform_filename.

fform_filename s are generated using the utilities provided in the fformgen module. Those utilities output a pickled fFormContainer-like object which can be loaded into a true fFormContainer instance using this function.

Parameters
fform_filenamestr or file object
shgpy.core.data_handler.merge_containers(containers, mapping)

Merge two contains with new keys according to mapping.

Parameters
containerslist of Container_like

List of Containers (DataContainer, fDataContainer, FormContainer, or fFormContainer). Must be the same type.

mappingfunction(key, index)

Function which maps key of Container and index of a Container in containers to str.

Returns
containerContainer_like

Container object of type type(containers[0]) with items ((k1, v1), (k2, v2), …), where ki are the mapped keys of the containers and vi are the corresponding values.

Examples

>>> xdata = np.linspace(0, 2*np.pi, 1000)
>>> ydata = np.sin(xdata)**2
>>> iterable = {k:np.array([xdata, ydata]) for k in ['PP', 'PS']}
>>> dat1 = DataContainer(iterable)
>>> dat2 = DataContainer(iterable)
>>> def mapping(key, index):
>>>     return key+str(index)
>>> dat3 = merge_containers([dat1, dat2], mapping)
>>> dat3.get_keys():
['PP0', 'PS0', 'PP1', 'PS2']
>>> dat3.get_values():
[array([xdata, ydata]), array([xdata, ydata]), ...]
shgpy.core.data_handler.n2i(n, M=16)

Convert between Fourier index and array index

Returns the index (0-2*M+1) in a Fourier array corresponding to the nth Fourier component

shgpy.core.data_handler.read_csv_file(filename, delimiter=',')

Read a csv file.

Parameters
filenamestr or file object
delimiterstr

Defaults to ','.

Returns
datandarray

Data from csv file of the form array([xdata, ydata]).