Welcome to PyAstroPol’s documentation!

About the Package

The Python package PyAstroPol provides a simple way to perform instrumental polarization analysis of the astronomical optics. The package has one simple goal: compute 4x4 Mueller matrix for the given optical system. It is developed keeping astronomical optics in view. The geometric optics approach is used in the package hence all the analysis uses strictly ray treatment. Users should keep in mind that the software is NOT for the optical design purposes i.e., it is presumed that the user already knows the optical system that is to be analyzed. As it has minimal dependencies it can be easily used, or integrated/distributed with polarization calibration routines of the users.

PyAstroPol aims to provide better aspects of the existing polarization analysis approaches: open-source tools developed using scientific programming language, with a range of applications in modelling the astronomical optics. A variety of examples have been provided, and they should facilitate the quick-start. One of the examples also provides the comparison of the results with those of a popular commercial software Zemax OpticStudio®.

Salient features

  • Calculation of the Mueller matrix of a given optical system is a simple and only end goal. Rest are the by-products of such analysis. The system Mueller matrix is computed by coherently adding the electric field vectors after propagation. It implies that the system is imaging type, which is commonplace in astronomy.
  • Astronomical sources can be directly placed in the model using relevant coordinates, namely, declination, hour angle and latitude of the telescope site.
  • Off-axis components are facilitated, as they have a significant effect on polarization.
  • Effect of multi-layered coatings, such as oxide layers and protective coatings, on the state of polarization, is included. These are also significant in the polarization analysis of the astronomical optics.
  • All the data, such as points of incidence, polarization directions, complex electric field values and more, are readily available to the user for any further analysis.
  • Material refractive index information can be downloaded from the popular online source RefractiveIndexInfo as .csv. It can be formatted and used with this software.
  • Spot diagram is possible at any instance, as a by-product of ray tracing.

Important Limitations

  • All the analysis uses strictly the ray treatment. Hence, all the limitations of the rays optics shall be applicable.
  • Only circular optics (apertures) can be devised at the moment.
  • Incidentally, birefringent components are not included yet. The justification for this choice is that the behaviour of the birefringent components is fairly straightforward as they strongly polarize the light.
  • The visualization features are limited.
  • It is neither a design software nor interactive. That is, the user must know the optical system that is to be analyzed, and the system must be updated every time a component is changed.

Keywords

Python
Astronomy
Astronomical optics
Telescopes
Instrumentation
Polarization
Instrumental polarization
Polarimetry
Polarized ray tracing
Mueller matrix

PyAstroPol package

Submodules

PyAstroPol.Coating module

Author : Hemanth Pruthvi
File name : Coating.py
Package : PyAstroPol
Description : Coating and related classes
class PyAstroPol.Coating.Coating(RI, Thick)

Bases: object

Effects of multi-layer coating on polarization of transmission and reflections.
For geometric ray tracing purposes, their thickness will be neglected.
Attributes : General
Layers : String array (N,1) : Array of names of materials of all the layers
RI : Complex Float (N,1) : Array of refractive indiced of all the layers
Thick : Float (N,1) : Array of thicknesses of all the layers
Attributes : Polarization
rs : FloatComplex(N,1) : Complex coefficient of reflection for s-polarization of all Rays
rp : FloatComplex(N,1) : Complex coefficient of reflection for p-polarization of all Rays
ts : FloatComplex(N,1) : Complex coefficient of transmission for s-polarization of all Rays
tp : FloatComplex(N,1) : Complex coefficient of transmission for p-polarization of all Rays
applyToSurface(Surf)
Apply defined Coating to given surface, and compute the effects on transmission and reflection.
Input : Surface() to which coating it to be applied.
loadRefractiveIndex()
Load refractive index according to given information on layer material and wavelength.
reverseTheCoating()
Reverse the coating layers order along with their thicknesses.
This feature might be useful for elements such as coated lens.

PyAstroPol.Elements module

Author : Hemanth Pruthvi
File name : Elements.py
Package : PyAstroPol
Description : Detector, Lens and likewise classes of optical elelements
class PyAstroPol.Elements.Detector(Dia)

Bases: PyAstroPol.Surface.Surface

Plane Surface() with no special attributes.
Created for the purpose of easily specifying detector.
class PyAstroPol.Elements.UncoatedLens(Dia, Thick, R1=inf, R2=inf, K1=0.0, K2=0.0, n=(1.5+0j))

Bases: object

A simple singlet lens containing two uncoated surfaces
Attributes: General
S1 : Surface() : Front surface
S2 : Surface() : Back surface
Thick : Float : Thickness of the lens (redundant)
draw(Ax, **kwargs)
Draw the element in 3D.
Inputs : Pyplot Axis, kwargs that are directly pass to plot function.
drawRays(Ax, **kwargs)
Draw incident rays to the Surfaces of the element.
Inputs : Pyplot Axis, kwargs that are directly pass to plot function.
propagateRays(Rays)
Propagate given Rays through the element.
Specify a Rays() for the input.
rotateAboutX(ThetaX)
Rotate the element about global X-axis relative to present position.
Input : X-rotation angle in degrees
rotateAboutY(ThetaY)
Rotate the element about global Y-axis relative to present position.
Input : Y-rotation angle in degrees
rotateAboutZ(ThetaZ)
Rotate the element about global Z-axis relative to present position.
Input : Z-rotation angle in degrees
translateOrigin(x=0.0, y=0.0, z=0.0)
Translate the element relative to present position.
Inputs : X translation, Y translation and Z translation.

PyAstroPol.Functions module

Author : Hemanth Pruthvi
File name : Functions.py
Package : PyAstroPol
Description : Frequently used functions in other codes
PyAstroPol.Functions.MuellerRotationMatrix(Theta)
Compute Mueller matrix for rotation.
Input : Angle in degrees.
Returns : 4x4 Mueller matrix.
PyAstroPol.Functions.adjustAspect(Ax, L, x=0.0, y=0.0, z=0.0)
Set aspect ratio of 3d axes to 1:1:1, and specify the space to be displayed.
Inputs : Pyplot Axis, Size of space, X-coordinate of the center, Y-coordinate of the center, Z-coordinate of the center.
PyAstroPol.Functions.applyPointTransformation(P, M)
Apply transformation matrix to set of points.
Inputs : Array of points, and 4x4 transformation matrix.
Returns : Array of points, same size as input.
PyAstroPol.Functions.applyVectorTransformation(V, M)
Apply transformation matrix to set of vectors.
Inputs : Array of vectors, and 4x4 transformation matrix.
Returns : Array of vectors, same size as input.
PyAstroPol.Functions.dot3DVectors(V1, V2)
Dot product of two arrays of 3D vectors, formatted to match code’s convention.
Inputs : Array of 3d vectors, Array of 3d vectors.
Returns : Array of 3d vectors same size as input.
PyAstroPol.Functions.formatMaterialFile(Name)
Format the material file ‘.csv’ that is downloaded from refractiveindex.info, to comply with the code. The file should be copied into “Materials” folder.
Input : Material name without extension.
PyAstroPol.Functions.getTranslationMatrix(x=0.0, y=0.0, z=0.0)
Calculate 4x4 affine translation matrix, to move w.r.t. present position.
Inputs : X translation, Y translation and Z translation.
Returns : 4x4 transformation matrix.
PyAstroPol.Functions.getXRotationMatrix(ThetaX)
Calculate 4x4 affine rotation matrix, to rotate about X-axis.
Inputs : X rotation angle in degrees.
Returns : 4x4 transformation matrix.
PyAstroPol.Functions.getYRotationMatrix(ThetaY)
Calculate 4x4 affine rotation matrix, to rotate about Y-axis.
Inputs : Y rotation angle in degrees.
Returns : 4x4 transformation matrix.
PyAstroPol.Functions.getZRotationMatrix(ThetaZ)
Calculate 4x4 affine rotation matrix, to rotate about Z-axis.
Inputs : Z rotation angle in degrees.
Returns : 4x4 transformation matrix.
PyAstroPol.Functions.normalize3DVectors(V)
Normalize array of 3d vectors to get corresponding unit vectors.
Inputs : Array of 3D vectors.
Returns : Array of 3D vectors same size as input.
PyAstroPol.Functions.rotateMuellerMatrix(M, Theta)
Compute Mueller matrix after rotation.
Input : 4x4 Mueller matrix, Rotation angle in degrees.
Returns : 4x4 Mueller matrix.
PyAstroPol.Functions.roundOffDisplay(D)
Set the number of decimals to display while printing.
Input : Integer number of decimals.
PyAstroPol.Functions.vectorToAngles(V)
Rotation angles about Y and X axes (in that order) to rotate “Z” vector to “V” vector.
Input : Array of vectors.
Returns : Array of Y-rotation angles, Array of X-rotation angles in degrees.

PyAstroPol.Material module

Author : Hemanth Pruthvi
File name : Material.py
Package : PyAstroPol
Description : Material class, for the sake of refractive index
class PyAstroPol.Material.Material(MaterialName)

Bases: object

Simple material definition, data is read from ‘.csv’ material file.
Attributes : General
Wavelength : Float(N, 1) : Wavelengths
RI : ComplexFloat(N, 1) : Refractive index at given wavelengths
getRefractiveIndexAt(Wave)
Calculate refractive index for a given wavelength by interpolation
Input : Wavelength
Returns : Complex refractive index

PyAstroPol.Source module

Author : Hemanth Pruthvi
File name : Source.py
Package : PyAstroPol
Description : Rays, Source and likewise classes
class PyAstroPol.Source.AstroSource(NRays, HA=0.0, Dec=0.0, Lat=30.0, Clear=1.0, Dist=1000.0)

Bases: PyAstroPol.Source.Source

AstroSource definition with Source() as parent
Attributes : Special
HourAngle : Float : Hour angle of the source
Declination : Float : Declination of the source
Latitude : Float : Latitute of observation
Distance : Float : Distance of the astronomcial source from the global origin
class PyAstroPol.Source.Rays(N)

Bases: object

Rays definition with Point-Eiknol formulation.

Attributes : General
NRays : Int : Number of rays
Wavelength : Float : Wavelength in microns
Attributes : References
Origin : Float(1,3) : Starting point of cheif-ray
xAxis : Float(1,3) : DC of supposed x-axis
yAxis : Float(1,3) : DC of supposed y-axis
oAxis : Float(1,3) : DC of optical axis i.e., direction of chief ray
Attributes : Set of points and cosines
Points : Float(N,3) : Starting points of rays
xCosines : Float(N,3) : DC of x-polarization direction for all rays
yCosines : Float(N,3) : DC of y-polarization direction for all rays
oCosines : Float(N,3) : DC of propagation direction for all rays
Attributes : Electric field
Ex : ComplexFloat(N,1) : Electric field for each ray, in x-direction
Ey : ComplexFloat(N,1) : Electric field for each ray, in y-direction
(x,y,o) are orthonormal basis for a right handed coordinate system
computeRMSRadius(Distance=0.0)
Computes RMS spot radius for the beam at a distance from the origin along the optical axis.
Inputs : Distance at which RMS spot is to be computed.
Returns : RMS spot radius.
createPolarization(Ex, Ey)
Assign given complex electric fields to all the rays to create polarized light.
Input : Complex electric field in X direction, Complex electric field in Y direction.
drawRays(Ax, Length, **kwargs)
Draw all the rays to a distance along the optical axis from the origin.
Input : Pyplot axis, Distance to which rays are to be drawn, kwargs are directly passed to plot function.
drawSpotDiagram(Ax, Length, **kwargs)
Draw the spot diagram, at a distance along the optical axis from the origin.
Input : Pyplot axis, Distance at which spot diagram is to be drawn, kwargs are directly passed to plot function.
drawXYAxes(Ax, LengthR, LengthP, **kwargs)
Draw the local X and Y axes for all the rays, at a distance along the optical axis from the origin.
Input : Pyplot axis, Distance at which axes are to be drawn, Length of axes, kwargs are directly passed to plot function.
getStokesVector()
Compute Stokes vector for the whole beam.
Returns : Normalized Stokes vector, total intenisty
propagateRays(Distance=0.0)
Propagates all the rays to a distance along the optical axis from the origin.
Input : Distance to which rays are to be propagated.
class PyAstroPol.Source.Source(NRays, Type='Collimated', Clear=1.0, FNum=1.0, Random=False)

Bases: PyAstroPol.Source.Rays

Source definition with Rays() as parent
Attributes : Special
Type : Enumerated string : “collimated” or “point” sources
FNum : Float : Focal ratio of the beam, only used for point sources
Clear : Float : Clear aperture for the distribution of rays, only used in collimated sources
Random : Bool : Ray distrbution, if not True rays are distributed in ring fashion with quasi-uniform density
applyTransformation(M)
Apply affine transformation to the Source and its constitutents.
Input : 4x4 matrix.
makeOrigin(NewOrigin)
Translate the Source in such a way that its Origin is at the given point.
Input : Coordinates of the new Origin.
pointToDirection(NewNormal)
Rotate the Source in such a way that its oAxis is along the given normal.
Input : Direction cosines of the new oAxis.
rotateAboutX(ThetaX)
Rotate the Source and its constitutents about global X-axis.
Input : X rotation angle in degrees.
rotateAboutY(ThetaY)
Rotate the Source and its constitutents about global Y-axis.
Input : Y rotation angle in degrees.
rotateAboutZ(ThetaZ)
Rotate the Source and its constitutents about global Z-axis.
Input : Z rotation angle in degrees.
translateOrigin(x=0.0, y=0.0, z=0.0)
Move the Source and its constitutents relative to their current position.
Shifting the Origin of this Source.
Inputs : X translation, Y translation and Z translation.

PyAstroPol.Surface module

Author : Hemanth Pruthvi
File name : Surface.py
Package : PyAstroPol
Description : Surface class, basis for all the elements.
class PyAstroPol.Surface.Surface(Dia, R=inf, K=0, Mirror=False, iDia=0.0, OffAxis=False, OffAxDist=0.0, OffAxAz=0.0, n1=(1+0j), n2=(1.5+0j))

Bases: object

General purpose Surface definition.
Attributes : General
Aperture : Float : Diameter size (only circular is considered)
Origin : Float(1,3) : Center of the aperture (circle)
oAxis : Float(1,3) : DC of Optical axis i.e., normal to surface, at Origin, pointing towards the direction of the incidence
Curvature : Float : Radius of curvature of the surface
Conic : Float : Conic constant of the surface
SurfaceMatrix : Float(4,4) : Matrix representation of coefficients of the surface equation
iRI : FloatComplex : Refractive index of the incident medium
tRI : FloatComplex : Refrative index of the transmitting medium
iMU : FloatComplex : Magnetic permeability of the incident medium
tMU : FloatComplex : Magnetic permeability of the transmitting medium
Mirror : Bool : Is it only reflecting or only transmitting?
IncidentPoints : Float(N,3) : Points on the surface corresponding to incidence of Rays
nCosines : Float(N,3) : DC of the normals to the surface at the points of ray incidences
tCosines : Float(N,3) : DC of the tangents to the surface at the points of ray incidences
Mask : Bool(N,1) : Array representing whether given rays are hitting the surface or not
Attributes : Polarization
sCosines : Float(N,3) : DC of the s-polarization direction to the surface for the Rays
pCosines_i : Float(N,3) : DC of the p-polarization direction to the surface, for the incident rays
pCosines_r : Float(N,3) : DC of the p-polarization direction to the surface, for the reflected rays
pCosines_t : Float(N,3) : DC of the p-polarization direction to the surface, for the transmitted rays
rs : FloatComplex(N,1) : Complex coefficient of reflection for s-polarization of all Rays
rp : FloatComplex(N,1) : Complex coefficient of reflection for p-polarization of all Rays
ts : FloatComplex(N,1) : Complex coefficient of transmission for s-polarization of all Rays
tp : FloatComplex(N,1) : Complex coefficient of transmission for p-polarization of all Rays
Attributes : Objects
iRays : Rays() : Incident rays
rRays : Rays() : Reflected rays
tRays : rays() : Transmitted rays
Attributes : Only for drawing
X : Float(N,1) : X-coordinates of the points used for rendering the surface
Y : Float(N,1) : Y-coordinates of the points used for rendering the surface
Z : Float(N,1) : Z-coordinates of the points used for rendering the surface
applyTransformation(M)
Apply affine transformation to the Surface and its constitutents.
Input : 4x4 matrix.
computeIncidence(Rays)
Computes the parameters related to ray incidence on the Surfce, points and angles etc.
Internal function for computations.
Input : Rays() object.
computeNormals()
Computes the Normal vectors on the Surfce at the points of incidence of Rays.
Internal function for computations.
draw(Ax, **kwargs)
Draw the Surface using points computed for its rendering.
Input : Pyplot axis, kwargs are directly passed to plot function.
drawPolarizationDirection(Ax, LengthR, **kwargs)
Draw the s- and p-polarization directions for all the Rays at the Surface.
Input : Pyplot axis, Length of vectors, kwargs are directly passed to plot function.
drawRays(Ax, **kwargs)
Draw the Rays to the Surface after propagation.
Input : Pyplot axis, kwargs are directly passed to plot function.
drawSurfaceNormals(Ax, Length, **kwargs)
Draw the normal vectors to the Surface at the points of incidence of Rays.
Input : Pyplot axis, Length of the normal vector, kwargs are directly passed to plot function.
loadRefractiveIndex(Wave)
Loads the refractive index for the given wavelength from Material.
Internal function for computations.
makeOrigin(NewOrigin)
Translate the Surface in such a way that its Origin is at the given point.
Input : Coordinates of the new Origin.
pointToDirection(NewNormal)
Rotate the Surface in such a way that its oAxis is along the given normal.
Input : Direction cosines of the new oAxis.
propagatePolarization()
Computes the effects of propagation on the state of polarization of the Rays.
Internal function for computations.
propagateRays(Rays)
Propagates the Rays through the Surface considering a number of effects.
Input : Rays() object.
propagateReflectedRays()
Computes the parameters for the reflected part of Rays from the Surface.
Internal function for computations.
propagateTransmittedRays()
Computes the parameters for the transmitted part of Rays from the Surface.
Internal function for computations.
renderSurface(rRes, thetaRes)
Calculate points on the Surface that can be used to render it.
It is an internal function used by code.
Inputs : Number of radial segments (resolution), Number of angular segments.
rotateAboutX(ThetaX)
Rotate the Surface and its constitutents about global X-axis.
Input : X rotation angle in degrees.
rotateAboutY(ThetaY)
Rotate the Surface and its constitutents about global Y-axis.
Input : Y rotation angle in degrees.
rotateAboutZ(ThetaZ)
Rotate the Surface and its constitutents about global Z-axis.
Input : Z rotation angle in degrees.
translateOrigin(x=0.0, y=0.0, z=0.0)
Move the Surface and its constitutents relative to their current position.
Shifting the Origin of this Surface.
Inputs : X translation, Y translation and Z translation.

PyAstroPol.System module

Author : Hemanth Pruthvi
File name : System.py
Package : PyAstroPol
Description : Optical system class
class PyAstroPol.System.System(Source, Components, Detector, dRays=None)

Bases: object

System class it provided to do all the propagation related activites as once.
Once the Source, Elements and Detector are defined, they are to be passed to this calss.
There a provision to provide a seperate Source for the sake of display.
In this way, analysis can be done with large number of rays and fewer rays can be used for display.
Attributes: Objects
Source : Source() : Source for analysis purposes
Components : N x Surface() : Surface/Lens/Component
Detector : Detector() : Detector
dRays : Source() : Source for display puposes
Attributes : General
MuellerMatrix : Float(4,4) : Mueller matrix of the whole system
Transmission : Float : Total fractional throughput of the system.
draw(Ax, clear=False)
Draw the optical System.
Input : Pyplot axis, option to clear the previous plots.
drawSpotDiagram(Ax, **kwargs)
Draw the spot diagram as seen on the detector.
Input : Pyplot axis, kwargs are directly passed to plot function.
getOutputPositionAngle()
Computes the position angle difference between the detector and output rays.
Returns : Position angle in degrees
getSystemMuellerMatrix()
Computes the Mueller matrix for the System with following formulation.
Four minimum Stokes inputs :
In_1 : [1, 1, 0, 0], Ex_1 = 1.0 + 0.0j, Ey_1 = 0.0 + 0.0j
In_2 : [1, -1, 0, 0], Ex_1 = 0.0 + 0.0j, Ey_1 = 1.0 + 0.0j
In_3 : [1, 0, 1, 0], Ex_1 = 0.707 + 0.0j, Ey_1 = 0.707 + 0.0j
In_4 : [1, 0, 0, 1], Ex_1 = 0.707 + 0.0j, Ey_1 = 0.0 - 0.707j
Four Stokes outputs as linear combination of Mueller matrix elements :
Out_1 : [M_00+M_10, M_01+M_11, M_02+M_12, M_03+M_13]
Out_2 : [M_00-M_10, M_01-M_11, M_02-M_12, M_03-M_13]
Out_3 : [M_00+M_20, M_01+M_21, M_02+M_22, M_03+M_23]
Out_4 : [M_00+M_30, M_01+M_31, M_02+M_32, M_03+M_33]
System Mueller matrix elements :
[M_00, M_01, M_02, M_03] = 0.5*(Out_1 + Out_2)
[M_10, M_11, M_12, M_13] = 0.5*(Out_1 - Out_2)
[M_20, M_21, M_22, M_23] = Out_3 - 0.5*(Out_1 + Out_2)
[M_30, M_31, M_32, M_33] = Out_4 - 0.5*(Out_1 + Out_2)
Returns : 4x4 Mueller matrix of the System, Transmitted fractional intensity
propagateRays()
Propagates the Rays through the System considering a number of effects.

Module contents