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¶
PyAstroPol package¶
Submodules¶
PyAstroPol.Coating module¶
-
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 : GeneralLayers : String array (N,1) : Array of names of materials of all the layersRI : Complex Float (N,1) : Array of refractive indiced of all the layersThick : Float (N,1) : Array of thicknesses of all the layersAttributes : Polarizationrs : FloatComplex(N,1) : Complex coefficient of reflection for s-polarization of all Raysrp : FloatComplex(N,1) : Complex coefficient of reflection for p-polarization of all Raysts : FloatComplex(N,1) : Complex coefficient of transmission for s-polarization of all Raystp : 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¶
-
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 surfacesAttributes: GeneralS1 : Surface() : Front surfaceS2 : Surface() : Back surfaceThick : 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¶
-
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¶
-
class
PyAstroPol.Material.
Material
(MaterialName)¶ Bases:
object
Simple material definition, data is read from ‘.csv’ material file.Attributes : GeneralWavelength : Float(N, 1) : WavelengthsRI : ComplexFloat(N, 1) : Refractive index at given wavelengths-
getRefractiveIndexAt
(Wave)¶ - Calculate refractive index for a given wavelength by interpolationInput : WavelengthReturns : Complex refractive index
-
PyAstroPol.Source module¶
-
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 parentAttributes : SpecialHourAngle : Float : Hour angle of the sourceDeclination : Float : Declination of the sourceLatitude : Float : Latitute of observationDistance : Float : Distance of the astronomcial source from the global origin
-
class
PyAstroPol.Source.
Rays
(N)¶ Bases:
object
Rays definition with Point-Eiknol formulation.
Attributes : GeneralNRays : Int : Number of raysWavelength : Float : Wavelength in micronsAttributes : ReferencesOrigin : Float(1,3) : Starting point of cheif-rayxAxis : Float(1,3) : DC of supposed x-axisyAxis : Float(1,3) : DC of supposed y-axisoAxis : Float(1,3) : DC of optical axis i.e., direction of chief rayAttributes : Set of points and cosinesPoints : Float(N,3) : Starting points of raysxCosines : Float(N,3) : DC of x-polarization direction for all raysyCosines : Float(N,3) : DC of y-polarization direction for all raysoCosines : Float(N,3) : DC of propagation direction for all raysAttributes : Electric fieldEx : ComplexFloat(N,1) : Electric field for each ray, in x-directionEy : 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 parentAttributes : SpecialType : Enumerated string : “collimated” or “point” sourcesFNum : Float : Focal ratio of the beam, only used for point sourcesClear : Float : Clear aperture for the distribution of rays, only used in collimated sourcesRandom : 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¶
-
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 : GeneralAperture : 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 incidenceCurvature : Float : Radius of curvature of the surfaceConic : Float : Conic constant of the surfaceSurfaceMatrix : Float(4,4) : Matrix representation of coefficients of the surface equationiRI : FloatComplex : Refractive index of the incident mediumtRI : FloatComplex : Refrative index of the transmitting mediumiMU : FloatComplex : Magnetic permeability of the incident mediumtMU : FloatComplex : Magnetic permeability of the transmitting mediumMirror : Bool : Is it only reflecting or only transmitting?IncidentPoints : Float(N,3) : Points on the surface corresponding to incidence of RaysnCosines : Float(N,3) : DC of the normals to the surface at the points of ray incidencestCosines : Float(N,3) : DC of the tangents to the surface at the points of ray incidencesMask : Bool(N,1) : Array representing whether given rays are hitting the surface or notAttributes : PolarizationsCosines : Float(N,3) : DC of the s-polarization direction to the surface for the RayspCosines_i : Float(N,3) : DC of the p-polarization direction to the surface, for the incident rayspCosines_r : Float(N,3) : DC of the p-polarization direction to the surface, for the reflected rayspCosines_t : Float(N,3) : DC of the p-polarization direction to the surface, for the transmitted raysrs : FloatComplex(N,1) : Complex coefficient of reflection for s-polarization of all Raysrp : FloatComplex(N,1) : Complex coefficient of reflection for p-polarization of all Raysts : FloatComplex(N,1) : Complex coefficient of transmission for s-polarization of all Raystp : FloatComplex(N,1) : Complex coefficient of transmission for p-polarization of all RaysAttributes : ObjectsiRays : Rays() : Incident raysrRays : Rays() : Reflected raystRays : rays() : Transmitted raysAttributes : Only for drawingX : Float(N,1) : X-coordinates of the points used for rendering the surfaceY : Float(N,1) : Y-coordinates of the points used for rendering the surfaceZ : 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¶
-
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: ObjectsSource : Source() : Source for analysis purposesComponents : N x Surface() : Surface/Lens/ComponentDetector : Detector() : DetectordRays : Source() : Source for display puposesAttributes : GeneralMuellerMatrix : Float(4,4) : Mueller matrix of the whole systemTransmission : 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.0jIn_2 : [1, -1, 0, 0], Ex_1 = 0.0 + 0.0j, Ey_1 = 1.0 + 0.0jIn_3 : [1, 0, 1, 0], Ex_1 = 0.707 + 0.0j, Ey_1 = 0.707 + 0.0jIn_4 : [1, 0, 0, 1], Ex_1 = 0.707 + 0.0j, Ey_1 = 0.0 - 0.707jFour 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.
-