1.4. py_pol.stokes module

Stokes objects describe light polarization states in the Mueller-Stokes formalism.

Class fields

• M: 2xN array containing all the Stokes vectors.

• global_phase: Global phase of the light state.

• name: Name of the object for print purposes.

• shape: Shape desired for the outputs.

• size: Number of stores Stokes vectors.

• type: Type of the object (‘Jones_vector’). This is used for determining the object class as using isinstance may throw unexpected results in .ipynb files.

• parameters: Object of class Parameters_Jones_vector.

• checks: Object of class Checks_Jones_vector.

Parent methods

• clear: Removes data and name form Jones vector.

• copy: Creates a copy of the Jones_vector object.

• stretch: Stretches a Jones vector of size 1.

• shape_like: Takes the shape of another object to use as its own.

• reshape: Changes the shape of the object.

• flatten: Transforms N-D objects into 1-D objects (0-D if only 1 element).

• flip: Flips the object along some dimensions.

• get_list: Creates a list with single elements.

• from_list: Creates the object from a list of single elements.

• concatenate: Canocatenates several objects into a single one.

• draw: Draws the components of the object.

• clear: Clears the information of the object.

Generation methods

• from_components: Creates Stokes vectors directly from the 4 elements $S_0$, $S_1$, $S_2$, $S_3$.

• from_matrix: Creates Stokes vectors from an external 4 x shape numpy array.

• from_list: Creates a Jones_vector object directly from a list of 4 or 4x1 numpy arrays.

• from_Jones: Creates Stokes vectors from a Jones_vector object.

• linear_light: Creates Stokes vectors for pure linear polarizer light.

• circular_light: Creates Stokes vectors for pure circular polarizer light.

• elliptical_light Creates Stokes vectors for polarizer elliptical light.

• general_charac_angles Creates Stokes vectors given by their characteristic angles.

• general_azimuth_ellipticity Creates Stokes vectors given by their azimuth and ellipticity.

Manipulation methods

• simplify: Simplifies the Stokes vectors in several ways.

• rotate: Rotates the Stokes vectors.

• sum: Calculates the summatory of the Stokes vectors in the object.

• reciprocal: Calculates the Stokes vectors that propagates backwards.

• orthogonal: Calculates the orthogonal Stokes vectors.

• normalize: Normalize the electric field to be normalized in electric field amplitude or intensity.

• rotate_to_azimuth: Rotates the Stokes vectors to have a certain azimuth.

• remove_global_phase: Calculates the global phase of the electric field (respect to the X component) and removes it.

• add_global_phase: Adds a global phase to the Stokes vectors.

• set_global_phase: Sets the global phase of the Stokes vectors.

• set_depolarization: Sets the degree of depolarization.

• add_depolarization: Increases the degree of depolarization.

Drawing methods

• draw_ellipse: Draws the polarization ellipse of the Stokes vectors.

• draw_poincare: Draws the Stokes vectors in the Poincare sphere.

Parameters subclass methods

• matrix: Gets a numpy array with the Stokes vectors.

• components: Calculates the electric field components of the Stokes vectors.

• amplitudes: Calculates the electric field amplitudes of the Stokes vectors.

• intensity: Calculates the intensity of the Stokes vectors.

• irradiance: Calculates the irradiance of the Stokes vectors.

• alpha: Calculates the ratio between electric field amplitudes ($E_x$/$E_y$).

• delay / delta: Calculates the delay (phase shift) between Ex and Ey components of the electric field.

• charac_angles: Calculates both alpha and delay, the characteristic angles of the Stokes vectors.

• azimuth: Calculates azimuth, that is, the orientation angle of the major axis.

• ellipticity_angle: Calculates the ellipticity angle.

• azimuth_ellipticity: Calculates both azimuth and ellipticity angles.

• ellipse_axes: Calculates the length of major and minor axis (a,b).

• ellipticity_param: Calculates the ellipticity parameter, b/a.

• eccentricity: Calculates the eccentricity, the complementary of the ellipticity parameter.

• global_phase: Calculates the global phase of the Stokes vectors (respect to the X component of the electric field).

• degree_polarization: Calculates the degree of polarization of the Stokes vectors.

• degree_depolarization: Calculates the degree of depolarization of the Stokes vectors.

• degree_linear_polarization: Calculates the degree of linear polarization of the Stokes vectors.

• degree_circular_polarization: Calculates the degree of circular polarization of the Stokes vectors.

• norm: Calculates the norm of the Stokes vectors.

• polarized_unpolarized: Divides the Stokes vector in Sp+Su, where Sp is fully-polarized and Su fully-unpolarized.

• get_all: Returns a dictionary with all the parameters of Stokes vectors.

Checks subclass methods

• is_physical: Checks if the Stokes vectors are physically realizable.

• is_linear: Checks if the Stokes vectors are lienarly polarized.

• is_circular: Checks if the Stokes vectors are circularly polarized.

• is_right_handed: Checks if the Stokes vectors rotation direction are right handed.

• is_left_handed: Checks if the Stokes vectors rotation direction are left handed.

• is_polarized: Checks if the Stokes vectors are at least partially polarized.

• is_totally_polarized: Checks if the Stokes vectors are totally polarized.

• is_depolarized: Checks if the Stokes vectors are at least partially depolarized.

• is_totally_depolarized: Checks if the Stokes vectors are totally depolarized.

• get_all: Returns a dictionary with all the checks of Stokes vectors.

Analysis subclass methods

• filter_physical_conditions: Forces the Stokes vectors to be physically realizable.

• density: Calculates the density of states around the Poincaré sphere.

• existence: Checks the existence of states around the Poincaré sphere.

py_pol.stokes.create_Stokes(name='S', N=1, out_object=True)

Function that creates several Stokes objects at the same time from a list of names or a number.

Parameters:

• names (str, list or tuple) – name of vector for string representation. If list or tuple, it also represents the number of objects to be created. Default: ‘S’.

• N (int) – Number of elements to be created. This parameter is overrided if name is a list or tuple. Defeult: 1.

• out_object (bool) – If True and the result is a list of length 1, return a Stokes object instead. Default: True.

Returns:

List of Stokes vectors

Return type:

S (Stokes or list)

py_pol.stokes.set_printoptions(N_list=None, list_spaces=None)

Function that modifies the global print options parameters.

TODO: Single global function for all modules.

Parameters:

• N_list (int) – Number of matrices that will be printed as a list if the shape of the object is 1D. Default: None.

• list_spaces (int) – Number of spaces between matrices if they are printed as a list. Default: None.

class py_pol.stokes.Stokes(name='S')

Bases: Py_pol

Class for Stokes vectors

Parameters:

• M (float or numpy.ndarray) – 4xN array containing all the Stokes vectors.

• name (string) – Name of the object for print purposes.

• shape (tuple or list) – Shape desired for the outputs.

• size (int) – Number of stored Stokes vectors.

• ndim (int) – Number of dimensions for representation purposes.

• global_phase (float or numpy.ndarray) – Global phase of the Stokes vector. If it is a numpy.ndarray, it must have the same number of elements than self.size. It is used for addition and substraction.

• type (string) – Type of the object (‘Stokes’). This is used for determining the object class as using isinstance may throw unexpected results in .ipynb files.

self.parameters

Class containing the measurable parameters of Stokes vectors.

Type:

class

self.checks

Class containing the methods that check something about the Stokes vectors.

Type:

class

self.analysis

Class containing the methods to analyze the Stokes vectors.

Type:

class

property global_phase

sum(axis=None, keep=False, change_name=True)

Calculates the sum of Stokes vectors stored in the object.

Parameters:

• axis (int, list or tuple) – Axes along which the sum is performed. If None, all vectors are summed. Default: None.

• keep (bool) – If True, the original element is not updated. Default: False.

• change_name (bool) – If True, changes the object name adding Sum of at the beggining of the name. Default: True.

Returns:

Modified object.

rotate(angle=0, keep=False, change_name=True)

Rotates a jones vector a certain angle.

M_rotated = rotation_matrix_Jones(-angle) * self.M

Parameters:

• angle (float) – Rotation angle in radians. Default: 0.

• keep (bool) – If True, the original element is not updated. Default: False.

• change_name (bool) – If True and angle is of size 1, changes the object name adding @ XX deg, being XX the total rotation angle. Default: True.

Returns:

Rotated object.

Return type:

(Stokes)

set_depolarization(degree_pol, degree_depol=None, ratio=array([1., 1., 1.]), keep=True, change_name=True)

Function that reduces de polarization degree of a Stokes vector among the three last components.

Parameters:

• degree_pol (float) – Polarization degree.

• degree_depol (float) – Depolarization degree. Overrides degree_pol if different than None. Default: None.

• ratio (np.array) – Ratio between the three components of the depolarization degree. When different from [1, 1, 1]. Default: [1, 1, 1].

• keep (bool) – If True, the original element is not updated. Default: True.

• change_name (bool) – If True, changes the object name adding Normalized of at the end of the name. Default: True.

Returns:

Result.

Return type:

(Stokes)

add_depolarization(degree_pol, degree_depol=None, ratio=array([1., 1., 1.]), keep=True, change_name=True)

Function that reduces de polarization degree of a Stokes vector among the three last components.

Parameters:

• degree_pol (float) – Polarization degree.

• degree_depol (float) – Depolarization degree. Overrides degree_pol if different than None. Default: None.

• ratio (np.array) – Ratio between the three components of the depolarization degree. When different from [1, 1, 1]. Default: [1, 1, 1].

• keep (bool) – If True, the original element is not updated. Default: True.

• change_name (bool) – If True, changes the object name adding Normalized of at the end of the name. Default: True.

Returns:

Result.

Return type:

(Stokes)

normalize(keep=False, change_name=True)

Function that normalizes the Stokes vectors to have Intensity = 1.

Parameters:

• keep (bool) – If True, the original element is not updated. Default: False.

• change_name (bool) – If True, changes the object name adding Normalized of at the end of the name. Default: True.

Returns:

Result.

Return type:

(Stokes)

add_global_phase(phase=0, unknown_as_zero=False, keep=False)

Function that adds a phase to the Stokes object.

Parameters:

• phase (float or np.ndarray) – Phase to be added to the Stokes vectors. Default: 0.

• unknown_as_zero (bool) – If True, takes unknown phase as zero. Default: False.

• keep (bool) – If True, self is not updated. Default: False.

Returns:

Recalculated Stokes object.

Return type:

(Stokes)

set_global_phase(phase=0, keep=False, length=1, shape_like=None, shape=None)

Function that sets the phase to the Stokes object.

Parameters:

• phase (float or np.ndarray) – Phase to be added to the Stokes vectors. Default: 0.

• keep (bool) – If True, self is not updated. Default: False.

• length (int) – If amplitude and azimuth are not specified, it is created a 4 x length array of jones vectors. Default: 1.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Recalculated Stokes object.

Return type:

(Stokes)

remove_global_phase(keep=False)

Function that removes the phase to the Stokes object.

Parameters:

keep (bool) – If True, self is not updated. Default: False.

Returns:

Recalculated Stokes object.

Return type:

(Stokes)

rotate_to_azimuth(azimuth=0, keep=False)

Function that rotates the Stokes vectors to have a certain azimuth.

Parameters:

• azimuth (string or np.ndarray) – Azimuth of the Stokes vectors. ‘X’, ‘Y’, ‘-X’ and ‘-Y’ are the same as 0, 90, 180 and 270 degrees respectively. Default: 0.

• keep (bool) – If True, self is not updated. Default: False.

Returns:

Normalized Stokes vectors.

Return type:

(Stokes)

rotate_Poincare(x_angle=0, y_angle=0, z_angle=0, rot_vector=None, angle=None, keep=False)

Function to rotate the states in the Poincare sphere around X, Y and Z axes (in that order) if no rotation vector is specified. Rotation angle sign is defined using the right hand rule.

Parameters:

• x_angle (int) – Angle around axis X. Default: 0.

• y_angle (int) – Angle around axis Y. Default: 0.

• z_angle (int) – Angle around axis Z. Default: 0.

• rot_vector (iterable) – 3xN iterable with the rotation vector. Default: None.

• angle (iterable) – rotation angles around the rotation vector. Default: None.

• keep (bool) – If True, self is not updated. Default: False.

Returns:

Rotated Stokes vectors.

Return type:

(Stokes)

rotate_Poincare_orig(x_angle=0, y_angle=0, z_angle=0, angles=None, keep=False)

Function to rotate the states in the Poincare sphere around X, Y and Z axes (in that order). Rotation angle sign is defined using the right hand rule.

Parameters:

• x_angle (int) – Angle around axis X. Default: 0.

• y_angle (int) – Angle around axis Y. Default: 0.

• z_angle (int) – Angle around axis Z. Default: 0.

• angles (iterable) – 3xN iterable which overrides x_angle, y_angle and z_angle. Default: None.

• keep (bool) – If True, self is not updated. Default: False.

Returns:

Rotated Stokes vectors.

Return type:

(Stokes)

from_components(components, degree_pol=1, degree_depol=None, global_phase=0, length=1, shape_like=None, shape=None)

Creates Stokes vectors directly from the 4 elements [s0, s1, s2, s3]

Parameters:

• components (tuple) – A 4 element tuple containing the 4 components of the Stokes vectors (S0, S1, S2, S3).

• degree_pol (float) – Polarization degree. Default: 1

• degree_depol (float) – Depolarization degree. Overrides degree_pol if different than None. Default: None.

• global_phase (numpy.ndarray) – Adds a global phase to the Stokes object. Default: 0.

• length (int) – If amplitude and azimuth are not specified, it is created a 4 x length array of stokes vectors. Default: 1.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Created object.

Return type:

(Stokes)

from_matrix(M, degree_pol=1, degree_depol=None, global_phase=0, shape_like=None, shape=None)

Creates a Stokes object from an external array.

Parameters:

• M (numpy.ndarray) – New matrix. At least one dimension must be of size 4.

• degree_pol (float) – Polarization degree. Default: 1

• degree_depol (float) – Depolarization degree. Overrides degree_pol if different than None. Default: None.

• global_phase (numpy.ndarray) – Adds a global phase to the Stokes object. Default: 0.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Created object.

Return type:

(Stokes)

from_distribution(Ex, Ey, ind_d=-1, method='direct', N_periods=1, shape_like=None, shape=None)

Determine the Stokes vectors from a temporal or spatial electric field distribution [(Ex(t), Ey(t)].

Parameters:

• Ex (numpy.ndarray or float) – X component of the electric field.

• Ey (numpy.ndarray or float) – Y component of the electric field.

• ind_d (int) – Index of the spatial or temporal dimension. Default: -1.

• method (string) – Method for calculating the field amplitude and delay: DIRECT or FIT. Default: direct.

• N_periods (float) – Number of periods in the representation data. It is used by the fit algorithm (real case only) for calculating the frequency. If the value is not exact, convergency may decrease. Default: 1.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Created object.

Return type:

(Jones_vector)

from_Jones(E, degree_pol=1, degree_depol=None, length=1, shape_like=None, shape=None)

Creates a Stokes object from a Jones vectors object or a matrix corresponding to a Jones vectors.

\[s_0 = abs(E_x)^2 + abs(E_y)^2\]

\[s_1 = (abs(E_x)^2 - abs(E_y)^2) p_1\]

\[s_2 = 2 real(E_x E_y^*) p_1\]

\[s_3 = -2 imag(E_x E_y^*) p_2\]

Parameters:

• E (Jones_vector object) – Jones vectors.

• degree_pol (float or numpy.ndarray) – Degree of polarization of the new Stokes vector. Default: 1.

• length (int) – If final object is of size 1, it is stretched to match this size. Default: 1.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Created object.

Return type:

(Stokes)

linear_light(intensity=1, azimuth=0, amplitude=None, degree_pol=1, degree_depol=None, global_phase=0, length=1, shape_like=None, shape=None)

Creates a Stokes vector of linear polarizer light.

Parameters:

• intensity (numpy.array or float) – Array of intensity. Default: 1.

• azimuth (numpy.array or float) – Array of azimuths. Default: 0.

• amplitude (numpy.array or float) – Array of electric field amplitude. Overrides intensity if it is different than None. Default: None.

• degree_pol (numpy.array or float) – Array of polarization degree. Default: 1.

• degree_depol (float) – Depolarization degree. Overrides degree_pol if different than None. Default: None.

• global_phase (float or numpy.ndarray) – Adds a global phase to the Stokes object. Default: default_phase.

• length (int) – If final object is of size 1, it is stretched to match this size. Default: 1.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Created object.

Return type:

(Stokes)

circular_light(kind='d', intensity=1, amplitude=None, degree_pol=1, degree_depol=None, global_phase=0, length=1, shape_like=None, shape=None)

Creates Stokes vectors for pure circular polarizer light.

Parameters:

• kind (str) – ‘d’,’r’ - right, dextro. ‘l’, ‘i’ - left, levo.

• intensity (numpy.array or float) – Array of intensity. Default: 1.

• amplitude (numpy.array or float) – Array of electric field amplitude. Overrides inetnsity if it is different than None. Default: None.

• degree_pol (numpy.array or float) – Array of polarization degree. Default: 1.

• degree_depol (float) – Depolarization degree. Overrides degree_pol if different than None. Default: None.

• global_phase (float or numpy.ndarray) – Adds a global phase to the Stokes object. Default: default_phase.

• length (int) – If final object is of size 1, it is stretched to match this size. Default: 1.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Created object.

Return type:

(Stokes)

elliptical_light(a=1, b=1, kind='r', azimuth=0, degree_pol=1, degree_depol=None, global_phase=0, length=1, shape_like=None, shape=None)

Stokes object of the most general light calculated from the polarization ellipse parameters.

Parameters:

• a (numpy.array or float) – Array of electric amplitude of x axis. Default: 1.

• b (numpy.array or float) – Array of electric amplitude of y axis. Default: 1.

• kind (str) – ‘d’,’r’ - right, dextro. ‘l’, ‘i’ - left, levo.

• azimuth (numpy.array or float) – Angle of the a axis respect to the x axis. Default: 0.

• degree_pol (float) – Polarization degree. Default: 1

• degree_depol (float) – Depolarization degree. Overrides degree_pol if different than None. Default: None.

• global_phase (float or numpy.ndarray) – Adds a global phase to the Stokes object. Default: default_phase.

• length (int) – If final object is of size 1, it is stretched to match this size. Default: 1.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Created object.

Return type:

(Stokes)

general_charac_angles(alpha=0, delay=0, intensity=1, amplitude=None, degree_pol=1, degree_depol=None, global_phase=0, length=1, shape_like=None, shape=None)

Creates Stokes vectors given by their characteristic angles.

References

J.J. Gil, R. Ossikovsky “Polarized light and the Mueller Matrix approach”, CRC Press (2016),pp 137.

Parameters:

• alpha (float) – [0, pi]: tan(alpha) is the ratio between field amplitudes of X and Y components. Default: 0

• delay (float) – [0, 2*pi]: phase difference between X and Y field components. Default: 0

• intensity (numpy.array or float) – Array of intensity. Default: 1.

• amplitude (numpy.array or float) – Array of electric field amplitude. Overrides intensity if it is different than None. Default: None.

• degree_pol (numpy.array or float) – Array of polarization degree. Default: 1.

• degree_depol (float) – Depolarization degree. Overrides degree_pol if different than None. Default: None.

• global_phase (float or numpy.ndarray) – Adds a global phase to the Stokes object. Default: default_phase.

• length (int) – If final object is of size 1, it is stretched to match this size. Default: 1.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Stokes vector.

Return type:

S (4x1 numpy.matrix)

general_azimuth_ellipticity(azimuth=0, ellipticity=0, intensity=1, amplitude=None, degree_pol=1, degree_depol=None, global_phase=0, length=1, shape_like=None, shape=None)

Creates Stokes vectors given by their azimuth and ellipticity.

References

J.J. Gil, R. Ossikovsky “Polarized light and the Mueller Matrix approach”, CRC Press (2016), pp 137.

Parameters:

• azimuth (float) – [0, pi]: azimuth. Default: 0

• ellipticity (float) – [-pi/4, pi/4]: ellipticity. Default: 0

• intensity (numpy.array or float) – Array of intensity. Default: 1.

• amplitude (numpy.array or float) – Array of electric field amplitude. Overrides intensity if it is different than None. Default: None.

• degree_pol (numpy.array or float) – Array of polarization degree. Default: 1.

• degree_depol (float) – Depolarization degree. Overrides degree_pol if different than None. Default: None.

• global_phase (float or numpy.ndarray) – Adds a global phase to the Stokes object. Default: default_phase.

• length (int) – If final object is of size 1, it is stretched to match this size. Default: 1.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

Stokes vector.

Return type:

S (4x1 numpy.matrix)

draw_poincare(*args, **kwargs)

“Draws stokes vector.

Parameters:

• S (Jones_vector or Stokes) – Object to be represented.

• fig (plotly.graph_objects.Figure) – Figure to plot the data. Default: None

• figsize (2-element iterable) – Figure size. Default: (6,6)

• draw_axes (bool) – If True, it draws the three axes of the Poincare space. Default: True

• draw_guides (bool) – If True, it draws the circles of S1, S2 and S3 = 0. Default: True

• kind (str) – Choose between ‘scatter’, ‘line’, ‘scatterline’ or ‘surf’ to represent the data. If surf, the object must be 2D, 3D or 4D. Else, it must be 0D, 1D, 2D or 3D. Default: ‘scatter’.

• depol (bool) – If True, the depolarization is taking into account for scatter and line plots shrinking the radius below 1. Default: False.

• param (str, np.ndarray or None) – If str, parameter to use as information for the color. Must be a method of Parameters class which returns a single variable. If np.ndarray, must have the same shape as S. Default: None.

• subplots (bool) – If True, it tries to use the first two dimensions as rows and columns. If method == ‘surf’, this is mandatory. Default: False.

• in_degrees (bool) – If True, transforms the parameters to degrees. Default: False.

• log (bool) – If True, it calculates it in logarithmic scale. Default: False.

• hover (str) – Choose between ‘components’ (S1, S2, S3) or ‘angles’ (azimuth, ellipticity). Default: ‘components’.

• colormap (str) – Colormap of the plots. Default: ‘Blackbody’.

• show_fig (bool) – If True, the figure is inmediately plotted. Default: False.

Returns:

Plotly figure.

Return type:

fig (go.Figure)

draw_ellipse(*args, **kwargs)

Draws polarization ellipse of Stokes vector.

Parameters:

• E (Jones_vector or Stokes) – Light object.

• N_angles (int) – Number of angles to plot the ellipses. Default: 91.

• filename (str) – name of filename to save the figure.

• figsize (tuple) – A tuple of length 2 containing the figure size. Default: (8,8).

• limit (float) – limit for drawing. If empty, it is obtained from amplitudes.

• draw_arrow (bool) – If True, draws an arrow containing the turning sense of the polarization. Does not work with linear polarization vectors. Default: True.

• depol_central (bool) – If True, draws a central circle containing the unpolarized field amplitude. Default: False.

• depol_contour (bool) – If True, draws a line enveloping the polarization ellipse in order to plot the depolarization. Default: False.

• depol_prob (bool) – If True, plots the probability distribution of the electric field. Default: False.

• subplots (string, tuple or None) – If AS_SHAPE, divides the figure in several subplots as the shape of the py_pol object. If INDIVIDUAL, each vector is represented in its own subaxis, trying to use a square grid. If tuple, divides the figure in that same number of subplots. If None, all ellipses are plot in the same axes. Default: None.

• N_prob (int) – Number of points in each dimension for probability distributions. Default: 256.

• contour_levels (float, np.ndarray, tuple or list) – Contains the contour levels (normalized to 1). Default: 0.9.

• cmap (str or color object) – Default colormap for probability distributions. Default: hot.

Returns:

handle to axis. fig (handle): handle to figure.

Return type:

ax (handle)

class py_pol.stokes.Parameters_Stokes_vector(Stokes)

Bases: object

Class for Stokes vector Parameters

Parameters:

Stokes_vector (Stokes_vector) – Stokes Vector

self.parent

parent object.

Type:

Stokes_vector

get_all(verbose=False, draw=False)

Creates a dictionary with all the parameters of Stokes vectors.

Parameters:

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

matrix(shape=None, shape_like=None)

Returns the numpy array of the Stokes object.

Parameters:

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

Returns:

(float or numpy.ndarray) 2xN numpy array.

global_phase(give_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Extracts the global phase of the Stokes vector.

Parameters:

• give_nan (bool) – If False, NaN values are transformed into 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

components(out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the $S_0$, $S_1$, $S_2$ and $S_3$ components of the Stokes vector.

Parameters:

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of total intensity. S1 (float or numpy.ndarray): Array of linearly horizontal or vertical polarized intensity. S2 (float or numpy.ndarray): Array of linearly 45º or 135º polarized intensity. S3 (float or numpy.ndarray): Array of circularly polarized intensity.

Return type:

S0 (float or numpy.ndarray)

intensity(out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the intensity of the Stokes vector ($S_0$).

References

Handbook of Optics vol 2. 22.16 (eq.2)

Parameters:

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

irradiance(n=1, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the irradiance of the Stokes vector ($S_0$).

References

Handbook of Optics vol 2. 22.16 (eq.2)

Parameters:

• n (float) – Refractive index. Default: 1.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

degree_polarization(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the degree of polarization (DP) of the Stokes vectors.

$DP=

rac{sqrt{S_{1}^{2}+S_{2}^{2}+S_{3}^{2}}}{S_{0}}$

References:

Handbook of Optics vol 2. 22.16 (eq.3)

Parameters:

use_nan (bool): If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True. out_number (bool): If True and the result is a 1x1 array, return a number instead. Default: True. shape_like (float or numpy.ndarray): Use the shape of this array. Default: None. shape (tuple or list): If no shape_like array is given, use this shape instead. Default: None. verbose (bool): If True prints the parameter. Default: False. draw (bool): If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

(float or numpy.ndarray): Result

degree_depolarization(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the degree of depolarization (DD) of the Stokes vectors.

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result

Return type:

(float or numpy.ndarray)

degree_linear_polarization(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the degree of linear polarization (DLP) of the Stokes vectors.

$DLP=

rac{sqrt{S_{1}^{2}+S_{2}^{2}{S_{0}}$

References:

Handbook of Optics vol 2. 22.16 (eq.4)

Parameters:

use_nan (bool): If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True. out_number (bool): If True and the result is a 1x1 array, return a number instead. Default: True. shape_like (float or numpy.ndarray): Use the shape of this array. Default: None. shape (tuple or list): If no shape_like array is given, use this shape instead. Default: None. verbose (bool): If True prints the parameter. Default: False. draw (bool): If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

(float or numpy.ndarray): Result

degree_circular_polarization(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the degree of circular polarization (DCP) of the Stokes vectors.

$DCP=

rac{S_{3}}{S_{0}}$

References:

Handbook of Optics vol 2. 22.16 (eq.5)

Parameters:

use_nan (bool): If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True. out_number (bool): If True and the result is a 1x1 array, return a number instead. Default: True. shape_like (float or numpy.ndarray): Use the shape of this array. Default: None. shape (tuple or list): If no shape_like array is given, use this shape instead. Default: None. verbose (bool): If True prints the parameter. Default: False. draw (bool): If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

(float or numpy.ndarray): Result

alpha(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the ratio angle between electric field amplitudes.

\[arcsin(E_y/Ex).\]

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

delay(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Phase shift between $E_x$ and $E_y$ electric field components.

\[\delta_2 - \delta_1.\]

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

delta(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Phase shift between $E_x$ and $E_y$ electric field components. This is the same as delay.

\[\delta_2 - \delta_1.\]

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

charac_angles(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the characteristic angles of the Stokes object.

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

[0, pi/2]: tan(alpha) is the ratio angle between amplitudes of the electric field. delay (float): [0, 2*pi]: phase difference between both components of the electric field.

Return type:

alpha (float)

ellipticity_param(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the ellipticity parameter: the ratio between the minor and major polarization ellipse axes. It takes only into account the fully polarized part of the Stokes vector. It goes from 0 for linearly polarized light to 1 for circulary polarized light. Positive sign means left-handed and negative values right-handed rotation direction.

References

Handbook of Optics vol 2. 22.16 (eq.7)

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

ellipticity_angle(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the ratio angle between the major and minor axis length. It goes from 0 degrees for linearly polarized light to 45 degrees for circular polarized light. Positive sign means left-handed and negative values right-handed rotation direction.

References

J.J. Gil, R. Ossikovsky “Polarized light and the Mueller Matrix approach”, CRC Press (2016) pp 13.

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – if True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

azimuth(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the rotation angle of the polarization elipse major axis. If S is not fully polarized, azimuth is computed on the fully polarized part of S. Azimuth ranges from 0 to 180 degres (not included this last value).

References

Handbook of Optics vol 2. 22.16 (eq.8)

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

azimuth_ellipticity(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates both the azimuth and ellipticity of the Stokes object.

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

[0, pi): Azimuth. ellipticity (float or numpy.ndarray): [-pi/4, pi/4]: Ellipticity angle.

Return type:

azimuth (float or numpy.ndarray)

eccentricity(use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

The eccentricity of the polarization ellipse (0 for circular polarization, 1 for linear).

References

Handbook of Optics vol 2. 22.16 (eq.9)

Parameters:

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to 0. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Result.

Return type:

(float or numpy.ndarray)

ellipse_axes(out_number=True, sort=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the length of major and minor axis (a,b) of the polarization ellipse. This is a wrapper around the Parameters_Jones_Vector.ellipse_axes function.

References

4. Golstein “Polarized light” 2nd ed Marcel Dekker (2003), 3.4 eq.3-30a and 3-30b

Parameters:

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• sort (bool) – If True, it sorts a and b to be the major and minor axis respectively. Default: True. TODO: Check why this is neccessary.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Major axis b (numpy.ndarray or float): Minor axis

Return type:

a (numpy.ndarray or float)

polarized_unpolarized(shape_like=None, shape=None, verbose=False)

Divides the Stokes vector in two, one totally polarized and the other totally unpolarized.

References

Handbook of Optics vol 2. 22.16 (eq.6)

Parameters:

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

Returns:

Totally polarized Stokes object. Su (Stokes): Totally unpolarized Stokes object.

Return type:

Sp (Stokes)

amplitudes(give_Ez=False, give_unpol=False, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the $E_x$ and $E_y$ field amplitudes of the polarized part of the Stokes vectos. It may also calculate $E_z$ and the field amplitude of the unpolarized part.

Parameters:

• give_Ez (bool) – If True, it returns the z component of the electric field (all values will be 0). Default: False.

• give_unpol (bool) – If True, it returns the unpolarized component of the electric field. Default: False.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of electric field amplitude along x axis. E0y (numpy.ndarray or float): Array of electric field amplitude along y axis. E0z (numpy.array, optional): Array of electric field amplitude along z axis.

Return type:

E0x (numpy.ndarray or float)

norm(out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates the algebraic norm of the Stokes vectors.

Parameters:

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (float or numpy.ndarray) – Use the shape of this array. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of total intensity.

Return type:

S0 (float or numpy.ndarray)

density(*args, **kwargs)

Maintained here just for compatibility. Look for Stokes.analysis.density instead.

class py_pol.stokes.Analysis_Stokes(parent)

Bases: object

Class for Analysis of Stokes vetors.

Parameters:

stokes_vector (Stokes) – Stokes vector

self.parent

Type:

Stokes

filter_physical_conditions(tol=1e-06, keep=False)

Function that filters experimental errors by forcing the Stokes vector to fulfill the conditions necessary for a vector to be real light.

Parameters:

• tol (float) – Tolerance in equalities. Default: tol_default = 1e-6.

• keep (bool) – If True, the object is updated to the filtered result. If false, a new fresh copy is created. Default: False.

Returns:

Filtered Stokes vector.

Return type:

S (Stokes)

density(radius=0.1, sampling=0.017453292519943295, draw=False, return_coor=False, return_fig=False, **kwargs)

Calculates the density of elements in the Poincare sphere. Unlike many other parameters methods, the return object is always a 2D object covering the whole Poincare Sphere.

Parameters:

• radius (number) – Unit radius to compute density. Must be positive and lower than 1. Default: 0.1.

• sampling (number) – Resolution in azimuth and ellipticity. Default: 1 degree.

• draw (bool) – If True, plot it. Default: False.

• return_coor (bool) – If True, it returns the x, y and z coordinates of the Poincare sphere. Default: False.

• return_fig (bool) – If True, the figure object will be returned. Default: False.

• **kwargs – If draw is True, these arguments will be passed to draw_poincare method.

Returns:

Result. Units: points / srad.

Return type:

density (np.ndarray)

existence(radius=0.1, sampling=0.017453292519943295, draw=False, return_coor=False, return_fig=False, **kwargs)

Calculates the density of elements in the Poincare sphere. Unlike many other parameters methods, the return object is always a 2D object covering the whole Poincare Sphere.

Parameters:

• radius (number) – Unit radius to compute density. Must be positive and lower than 1. Default: 0.1.

• sampling (number) – Resolution in azimuth and ellipticity. Default: 1 degree.

• draw (bool) – If True, plot it. Default: False.

• return_coor (bool) – If True, it returns the x, y and z coordinates of the Poincare sphere. Default: False.

• return_fig (bool) – If True, the figure object will be returned. Default: False.

• **kwargs – If draw is True, these arguments will be passed to draw_poincare method.

Returns:

Result. fig (plotly.graph_objects.Figure): Figure. Returned only if return_fig is True.

Return type:

existence (np.ndarray of bools)

class py_pol.stokes.Check_Stokes(parent)

Bases: object

Class for Check of Stokes vectors.

Parameters:

stokes_vector (Stokes) – Stokes vector

self.parent

Type:

Stokes

get_all(verbose=False, draw=False)

Creates a dictionary with all the checks of Stokes vectors.

Parameters:

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

is_physical(tol=1e-06, give_all=False, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Tests the conditions of physical realizability:

• Condition 1: All components must be real.

• Condition 2: S0 must be positive.

• Condition 3: The square sum of S1, S2 and S3 must be equal or lower than S0.

References

Handbook of Optics vol 2. 22.34 “Polarized light and the Mueller Matrix approach”, J. J. Gil, pp 187.

Parameters:

• tol (float) – Tolerance in equality conditions. Default: tol_default = 1e-6.

• give_all (bool) – If True, the function will return the individual conditions. Default: False.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Is real or not. ind (dictionary, optional): dictionary with condition, True/False, distance

Return type:

cond (bool)

is_linear(tol=1e-06, use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates if the Stokes vectors are linearly polarized.

Parameters:

• tol (float) – Tolerance. Default: tol_default = 1e-6.

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to False. Default: True.

• out_number (bool) – if True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – if True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of the condition.

Return type:

(numpy.ndarray or bool)

is_circular(tol=1e-06, use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates if the Stokes vectors are circularly polarized.

Parameters:

• tol (float) – Tolerance. Default: tol_default: 1e-6.

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to False. Default: True.

• out_number (bool) – if True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – if True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of the condition.

Return type:

(numpy.ndarray or bool)

is_right_handed(tol=1e-06, use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates if the polarization rotation direction is right-handed.

Parameters:

• tol (float) – Tolerance. Default: tol_default: 1e-6.

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to False. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of the condition.

Return type:

(numpy.ndarray or bool)

is_left_handed(tol=1e-06, use_nan=True, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates if the polarization rotation direction is left-handed.

Parameters:

• tol (float) – Tolerance. Default: tol_default: 1e-6.

• use_nan (bool) – If True, unknown values are set to np.nan, otherwise they are set to False. Default: True.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of the condition.

Return type:

(numpy.ndarray or bool)

is_polarized(tol=1e-06, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates if the Stokes vectors are at least partially polarized.

Parameters:

• tol (float) – Tolerance. Default: tol_default = 1e-6.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – if True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of the condition.

Return type:

(numpy.ndarray or bool)

is_totally_polarized(tol=1e-06, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates if the Stokes vectors are totally polarized.

Parameters:

• tol (float) – Tolerance. Default: tol_default: 1e-6.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of the condition.

Return type:

(numpy.ndarray or bool)

is_depolarized(tol=1e-06, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates if the Stokes vectors are at least partially depolarized.

Parameters:

• tol (float) – Tolerance. Default: tol_default: 1e-6.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of the condition.

Return type:

(numpy.ndarray or bool)

is_totally_depolarized(tol=1e-06, out_number=True, shape_like=None, shape=None, verbose=False, draw=False)

Calculates if the Stokes vectors are totally depolarized.

Parameters:

• tol (float) – Tolerance. Default: tol_default: 1e-6.

• out_number (bool) – If True and the result is a 1x1 array, return a number instead. Default: True.

• shape_like (numpy.ndarray or py_pol object) – Use the shape of this object. Default: None.

• shape (tuple or list) – If no shape_like array is given, use this shape instead. Default: None.

• verbose (bool) – If True prints the parameter. Default: False.

• draw (bool) – If True and the object is a 1D or 2D, plot it. Default: False.

Returns:

Array of the condition.

Return type:

(numpy.ndarray or bool)