pypolar

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.

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

Examples

Circular Polarization Visualization

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

Optical Isolator

The following example demonstrates modeling an optical isolator using the Jones formalism.

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()

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.

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:

Identity check: Matrix([[0], [0]])
I(theta, alpha) = sin(alpha - 2*theta)**2

Mueller Matrix Example

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:

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.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.8358111

BibTeX

@software{pypolar_prahl_2026,
  author    = {Scott Prahl},
  title     = {pypolar: A Python module for polarization using Jones and Mueller calculus},
  year      = {2026},
  version   = {1.1.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.