Pypolar
Python modules for polarization changes using Jones or Mueller calculus
Install / Use
/learn @scottprahl/PypolarREADME
.. |pypi| image:: https://img.shields.io/pypi/v/pypolar?color=68CA66 :target: https://pypi.org/project/pypolar/ :alt: PyPI
.. |github| image:: https://img.shields.io/github/v/tag/scottprahl/pypolar?label=github&color=v :target: https://github.com/scottprahl/pypolar :alt: GitHub
.. |conda| image:: https://img.shields.io/conda/v/conda-forge/pypolar?label=conda&color=68CA66 :target: https://github.com/conda-forge/pypolar-feedstock :alt: Conda
.. |doi| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.8358111.svg :target: https://doi.org/10.5281/zenodo.8358111 :alt: DOI
.. |license| image:: https://img.shields.io/github/license/scottprahl/pypolar?color=68CA66 :target: https://github.com/scottprahl/pypolar/blob/main/LICENSE.txt :alt: License
.. |test| image:: https://github.com/scottprahl/pypolar/actions/workflows/test.yaml/badge.svg :target: https://github.com/scottprahl/pypolar/actions/workflows/test.yaml :alt: Testing Status
.. |docs| image:: https://readthedocs.org/projects/pypolar/badge?color=68CA66 :target: https://pypolar.readthedocs.io :alt: Documentation
.. |down| image:: https://img.shields.io/pypi/dm/pypolar?color=68CA66 :target: https://pypi.org/project/pypolar/ :alt: Download Count
.. |lite| image:: https://img.shields.io/badge/try-JupyterLite-68CA66.svg :target: https://scottprahl.github.io/pypolar/ :alt: Try Online
pypolar
|pypi| |github| |conda| |doi|
|license| |test| |docs| |down|
|lite|
pypolar is a Python library for simulating, analyzing, and visualizing the polarization state of light as it propagates through optical systems. The package supports modeling with both Jones and Mueller calculus frameworks and includes functionality relevant to education, research, ellipsometry, and polarimetric system design.
The library provides computational tools, visualization utilities, and symbolic analysis support, making it suitable for laboratory instruction, computational optics coursework, and applied research in polarization optics.
Modules
pypolar is organized into several computational and symbolic components:
Numerical computation modules
-
pypolar.fresnel— Fresnel reflection and transmission calculations -
pypolar.jones— Analysis of polarization using Jones calculus -
pypolar.mueller— Polarization modeling using the Mueller calculus -
pypolar.ellipsometry— Ellipsometry modeling tools
Visualization support
-
pypolar.poincare— Dedicated Poincaré sphere plotting routines -
pypolar.visualization— Poincaré sphere and vector-based visualization routines
Symbolic computation
-
pypolar.sym_fresnel— Symbolic Fresnel reflection and transmission expressions -
pypolar.sym_jones— Symbolic polarization modeling using Jones calculus -
pypolar.sym_mueller— Symbolic Mueller matrix manipulation
Installation
pypolar may be installed via pip::
pip install pypolar
or using conda::
conda install -c conda-forge pypolar
Quickstart
This short example combines numerical Jones/Mueller calculations with a symbolic result.
.. code-block:: python
import numpy as np
import sympy
import pypolar.jones as jones
import pypolar.mueller as mueller
import pypolar.sym_jones as sym_jones
# Jones: left-circular light through a linear polarizer at 30 degrees
J = jones.op_linear_polarizer(np.pi / 6) @ jones.field_left_circular()
print("Jones output:", J)
# Mueller: unpolarized input through the same polarizer
S = mueller.op_linear_polarizer(np.pi / 6) @ mueller.stokes_unpolarized()
print("Stokes output:", S)
# Symbolic: Malus' law
theta = sympy.symbols("theta", real=True)
I = sympy.simplify(
sym_jones.intensity(sym_jones.op_linear_polarizer(theta) * sym_jones.field_horizontal())[0]
)
print("Symbolic intensity:", I)
Documentation and Examples
Comprehensive user documentation, theory notes, and executable Jupyter examples are available at:
📄 https://pypolar.readthedocs.io
or use immediately in your browser via the JupyterLite button below
|lite|
Examples
Circular Polarization Visualization
.. code-block:: python
from pypolar import jones
from pypolar import visualization as vis
v = jones.field_left_circular()
print("Jones vector for left circularly polarized light:", v)
ani = vis.draw_jones_animated(v, nframes=32)
ani
will produce something like
.. image:: https://raw.githubusercontent.com/scottprahl/pypolar/main/docs/images/circular.gif :width: 700px :alt: Left circular polarization
Optical Isolator
.. image:: https://raw.githubusercontent.com/scottprahl/pypolar/main/docs/images/isolator.png :width: 700px :alt: Optical isolator schematic
The following example demonstrates modeling an optical isolator using the Jones formalism.
.. code-block:: python
import numpy as np
import matplotlib.pyplot as plt
from pypolar import jones
from pypolar import visualization as vis
b = jones.op_linear_polarizer(0)
c = jones.op_quarter_wave_plate(np.pi / 4)
d = jones.op_mirror()
e = jones.op_quarter_wave_plate(-np.pi / 4)
fig = plt.figure(figsize=(8, 8))
ax = fig.add_subplot(111, projection="3d")
vis.draw_empty_sphere(ax)
j1 = jones.field_elliptical(np.pi / 6, np.pi / 6)
j2 = b @ j1
j3 = c @ j2
j4 = d @ j3
j5 = e @ j4
vis.draw_jones_poincare(j1, ax, label=" start", color="red", va="center")
vis.draw_jones_poincare(j2, ax, label=" after Polarizer", color="blue", va="center")
vis.draw_jones_poincare(j3, ax, label=" after QWP", color="blue", va="center")
vis.draw_jones_poincare(j4, ax, label=" after mirror", color="blue", va="center")
vis.draw_jones_poincare(j5, ax, label=" final", color="red", va="center")
vis.join_jones_poincare(j1, j2, ax, color="blue", lw=2, linestyle=":")
vis.join_jones_poincare(j2, j3, ax, color="blue", lw=2, linestyle=":")
vis.join_jones_poincare(j3, j4, ax, color="blue", lw=2, linestyle=":")
vis.join_jones_poincare(j4, j5, ax, color="blue", lw=2, linestyle=":")
plt.show()
.. image:: https://raw.githubusercontent.com/scottprahl/pypolar/main/docs/images/poincare1.svg :width: 700px :alt: Poincare sphere
Symbolic Jones: Half-Wave Plate Rotation
This symbolic example verifies a useful identity: a half-wave plate with fast
axis angle theta rotates linear polarization from alpha to
2*theta - alpha (up to a global phase factor, which does not affect the
physical polarization state). It also derives the analyzer transmission in
closed form.
.. code-block:: python
import sympy
import pypolar.sym_jones as sym_jones
theta, alpha = sympy.symbols("theta alpha", real=True)
J_in = sym_jones.field_linear(alpha)
# Pass through a half-wave plate with fast axis at theta
J_out = sympy.simplify(sym_jones.op_half_wave_plate(theta) * J_in)
# Identity check using half wave plate
J_expected = sympy.I * sym_jones.field_linear(2 * theta - alpha)
print("Identity check:", sympy.simplify(J_out - J_expected))
# Pass through a vertical analyzer and get intensity
J = sym_jones.op_linear_polarizer(sympy.pi / 2) * J_out
I = sym_jones.intensity(J)[0].simplify().trigsimp()
print("I(theta, alpha) =", I)
produces:
.. code-block:: text
Identity check: Matrix([[0], [0]])
I(theta, alpha) = sin(alpha - 2*theta)**2
Mueller Matrix Example
.. code-block:: python
import numpy as np
import pypolar.mueller as mueller
A = mueller.stokes_right_circular()
B = mueller.op_linear_polarizer(np.pi/4)
C = mueller.op_quarter_wave_plate(0)
D = mueller.op_mirror()
E = mueller.op_quarter_wave_plate(0)
F = mueller.op_linear_polarizer(-np.pi/4)
F @ E @ D @ C @ B @ A
produces:
.. code-block:: python
array([0., 0., 0., 0.])
Citation
If you use pypolar in academic, instructional, or applied technical work, please cite:
Prahl, S. (2026). pypolar: A Python module for polarization using Jones and Mueller calculus (Version 1.2.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.8358111
BibTeX ^^^^^^
.. code-block:: bibtex
@software{pypolar_prahl_2026, author = {Scott Prahl}, title = {pypolar: A Python module for polarization using Jones and Mueller calculus}, year = {2026}, version = {1.2.0}, doi = {10.5281/zenodo.8358111}, url = {https://github.com/scottprahl/pypolar}, publisher = {Zenodo} }
License
pypolar is distributed under the terms of the MIT License.
