Stokes#
Overview#
This module collects Stokes- and Mueller-related calculations.
The functions are roughly organized into groups:
1) Polarimeter instrument matrix functions S2I = calculate_stokes_to_intensity_matrix(swing, scheme=”5-State”) I2S = calculate_intensity_to_stokes_matrix(swing, scheme=”5-State”)
2) Forward functions (Stokes parameters following a optical element) s0, s1, s2, s3 = stokes_after_adr(retardance, orientation, transmittance, depolarization, input=”cpl”) s0, s1, s2 = stokes012_after_ar(retardance, orientation, transmittance, input=”cpl”)
3) Inverse functions (optical elements from Stokes parameters) retardance, orientation, transmittance, depolarization = estimate_adr_from_stokes(s0, s1, s2, s3, input=”cpl”) retardance, orientation, transmittance = estimate_ar_from_stokes012(s0, s1, s2, input=”cpl”)
4) A function for recovering Mueller matrices from Stokes vector M = mueller_from_stokes(
s0, s1, s2, s3, model=”ar”, direction=”forward”, input=”cpl”
)
5) A convenience function for applying Mueller and instrument matrices y = mmul(A, x)
Usage#
All functions are intended to be used with torch.Tensors with Stokes- or Mueller-indices as the first axes.
For example, the following usage modes of stokes_after_adr are valid:
>>> stokes_after_adr(1, 1, 1, 1)
>>> retardance = torch.ones((2,3,4,5))
>>> orientation = torch.ones((2,3,4,5))
>>> transmittance = torch.ones((2,3,4,5))
>>> depolarization = torch.ones((2,3,4,5))
>>> stokes_after_adr(retardance, orientation, transmittance, depolarization)
>>> adr_params = torch.ones((4,2,3,4,5)) # first axis contains the Stokes indices
>>> stokes_after_adr(*adr_params) # * expands along the first axis
- waveorder.stokes.apply_orientation_offset(orientation, rotate, flip)[source]#
Applies a rotation and/or flip to each voxel of an orientation map while keeping the output range within 0 <= orientation < pi.
- Parameters:
- orientationtorch.Tensor
Array of orientations measured in radians
- rotatebool
If True, rotate orientation pi/2 radians (90 degrees)
- flipbool
If True, flip the orientation
- Returns:
- torch.Tensor with same shape as input
- Transformed array of orientations measured in radians
- with range 0 <= orientation < pi
- waveorder.stokes.calculate_intensity_to_stokes_matrix(swing, scheme='5-State')[source]#
Calculate the inverse polarimeter system matrix for a swing and calibration scheme.
- Parameters:
- swingfloat
Result is periodic on the integers, e.g. I2S_matrix(0.1) = I2S_matrix(1.1)
- scheme“4-State” or “5-State”
Corresponds to the calibration scheme used to acquire data, by default “5-State”
- Returns:
- torch.Tensor
Returns different shapes depending on the scheme
I2S.shape = (5, 4) for scheme = “5-State” I2S.shape = (4, 4) for scheme = “4-State”
- waveorder.stokes.calculate_stokes_to_intensity_matrix(swing, scheme='5-State')[source]#
Calculate the polarimeter system matrix for a swing and calibration scheme.
- Parameters:
- swingfloat
Result is periodic on the integers, e.g. calculate_stokes_to_intensity_matrix(0.1) ==
calculate_stokes_to_intensity_matrix(1.1)
- scheme“4-State” or “5-State”
Corresponds to the calibration scheme used to acquire data, by default “5-State”
- Returns:
- torch.Tensor
Returns different shapes depending on the scheme
S2I.shape = (5, 4) for scheme = “5-State” S2I.shape = (4, 4) for scheme = “4-state”
- waveorder.stokes.estimate_adr_from_stokes(s0, s1, s2, s3, input='cpl')[source]#
Inverse of stokes_after_adr.
When light with input polarization state (default = circularly polarized light = “cpl”) has passed through an attenuating depolarizing retarder (adr), its Stokes parameters can be passed to this function to estimate the parameters of the adr, specifically its retardance, slow-axis orientation, transmittance, and depolarization.
Note: this function is commonly used in QLIPP-type reconstructions. After converting raw intensities into Stokes parameters by applying an I2S_matrix, the Stokes parameters are used to estimate the parameters of the sample adr in a single step with this function.
- Parameters:
- s0, s1, s2, s3: torch.Tensor, identical shapes
Stokes parameters
- input“cpl”
Input polarization state
- Returns:
- retardance, orientation, transmittance, depolarization: torch.Tensor
retardance: retardance of adr, 2*pi periodic orientation: slow-axis orientation of adr, 2*pi periodic transmittance: transmittance of adr, 0 <= transmittance <= 1 depolarization: depolarization of adr, 0 <= depolarization <= 1
- waveorder.stokes.estimate_ar_from_stokes012(s0, s1, s2, input='cpl')[source]#
Inverse of stokes012_after_adr.
When light with input polarization state (default = circularly polarized light = “cpl”) has passed through an attenuating retarder (ar), its Stokes parameters can be passed to this function to estimate the parameters of the ar, specifically its retardance, slow-axis orientation, and transmittance.
- Parameters:
- s0, s1, s2: torch.Tensor, identical shapes
First three Stokes parameters
- Returns:
- retardance, orientation, transmittance: torch.Tensor, identical shapes
retardance: retardance of ar, 2*pi periodic orientation: slow-axis orientation of ar, 2*pi periodic transmittance: transmittance of ar, 0 <= transmittance <= 1
- waveorder.stokes.mmul(matrix, vector)[source]#
- Convenient matrix-multiply used for
applying Mueller matrices to Stokes vectors
applying intensity_to_stokes matrices to intensities
- Parameters:
- matrixtorch.Tensor, shape = (N, M, …)
- vectortorch.Tensor, shape = (M, …)
- Returns:
- torch.Tensor, shape = (N, …)
- waveorder.stokes.mueller_from_stokes(s0, s1, s2, s3, input='cpl', model='adr', direction='inverse')[source]#
When light with input polarization state (default = circularly polarized light = “cpl”) has passed through a polarization element of a specific type (default = attenuating depolarizing retarder = “adr”), its Stokes parameters can be passed to this function to estimate the complete Mueller matrix of the polarization element.
- Parameters:
- s0, s1, s2, s3torch.Tensor, identical shapes
Stokes parameters
- input“cpl”
Input polarization state
- model“adr”
The type of polarization element
- direction“forward” or “inverse”
Return the Mueller matrix (forward) or its inverse
- Returns:
- torch.tensor, float, M.shape = (4, 4,) + s0.shape
Mueller matrix on the same device as s0
- waveorder.stokes.stokes012_after_ar(retardance, orientation, transmittance, input='cpl')[source]#
Returns the first three Stokes parameters of the input polarization state (default = circularly polarized light = “cpl”) that has passed through an attenuating retarder (ar) parametrized by its retardance, slow-axis orientation, and transmittance.
This model is used to model non-depolarizing samples, or situations where depolarization information is unavailable…e.g. when only a linear Stokes polarimeter is available.
- Parameters:
- retardance, orientation, transmittance: torch.Tensor, identical shapes
retardance: retardance of ar, 2*pi periodic orientation: slow-axis orientation of ar, 2*pi periodic transmittance: transmittance of ar, 0 <= transmittance <= 1
- input“cpl”
Input polarization state
- Returns:
- s0, s1, s2: torch.Tensor
First three Stokes parameters
- waveorder.stokes.stokes_after_adr(retardance, orientation, transmittance, depolarization, input='cpl')[source]#
Returns the Stokes parameters of the input polarization state (default = circularly polarized light = “cpl”) that has passed through an attenuating depolarizing retarder (adr) parametrized by its retardance, slow-axis orientation, transmittance, and depolarization.
Note: all four parameters can be torch.Tensor, but they must be the same size. If your parameters are in a tensor with shape = (4, …), use the * operator to expand over the first dimension.
e.g. stokes_after_adr(*array) is identical to stokes_after_adr(array[0], array[1], array[2], array[3]).
- Parameters:
- retardance, orientation, transmittance, depolarizationtorch.Tensor, identical shapes
retardance: retardance of adr, 2*pi periodic orientation: slow-axis orientation of adr, 2*pi periodic transmittance: transmittance of adr, 0 <= transmittance <= 1 depolarization: depolarization of adr, 0 <= depolarization <= 1
- input“cpl”
Input polarization state
- Returns:
- s0, s1, s2, s3: torch.Tensor, identical shapes
Stokes parameters