MuellerKit

muellerkit provides vectorized Lu-Chipman polar decomposition for individual Mueller matrices and batches such as Mueller-matrix images. The decomposition uses the convention

M = M_delta @ M_R @ M_D

where M_delta is the depolarizer, M_R is the retarder, and M_D is the diattenuator.

The implementation follows S.-Y. Lu and R. A. Chipman, “Interpretation of Mueller matrices based on polar decomposition,” J. Opt. Soc. Am. A 13, 1106–1113 (1996), doi:10.1364/JOSAA.13.001106.

Installation

Install the project from a checkout with:

python -m pip install .

For development and testing:

python -m pip install -e '.[test]'
python -m pytest

Usage

import numpy as np
import muellerkit

M = np.eye(4)
M_delta, M_R, M_D = (
    muellerkit.decompose_depolarizer_retarder_diattenuator(M)
)

parameters = muellerkit.extract_parameters(M_delta, M_R, M_D)
print(parameters.total_retardance)
print(parameters.diattenuation)

np.testing.assert_allclose(M_delta @ M_R @ M_D, M)

Inputs may have shape (4, 4) or (..., 4, 4). Outputs preserve all leading batch dimensions. All angular parameters are returned in radians.

extract_parameters returns a frozen PolarizationParameters object with the following fields:

The Ghosh and Qi-Elson quantities intentionally remain separate. Under the Qi-Elson retarder-matrix convention used here, circular_phase_retardance is the full rotation in the S1-S2 plane and equals -2 * optical_rotation.

Parameter equations follow N. Ghosh, M. F. G. Wood, and I. A. Vitkin, “Mueller matrix decomposition for extraction of individual polarization parameters from complex turbid media exhibiting multiple scattering, optical activity, and linear birefringence,” J. Biomed. Opt. 13, 044036 (2008), doi:10.1117/1.2960934, and J. Qi and D. S. Elson, “Mueller polarimetric imaging for surgical and diagnostic applications: a review,” J. Biophotonics 10, 950–982 (2017), doi:10.1002/jbio.201600152.

Input assumptions and edge cases

• Decomposition inputs must be finite, real arrays with trailing shape (4, 4) and non-negative M[0, 0].
• A matrix with M[0, 0] == 0 is accepted only when the complete matrix is zero. It is represented by identity depolarizer and retarder factors and a zero diattenuator factor.
• Diattenuation magnitudes greater than one, beyond numerical tolerance, are rejected.
• The package does not perform a complete physical-realizability test for a Mueller matrix. Supplying a finite matrix that satisfies the checks above does not guarantee that its factors represent a physical optical system.
• Singular decompositions are not unique. The implementation selects the canonical proper rotations described by the Lu-Chipman Appendix B branches.

Development status

This is research software and the first public API release. Numerical results should be validated for the conventions and measurement regime of the application. Tests include nonsingular Eq. (52), singular Appendix B cases, batched inputs, unit diattenuation, the Ghosh and Qi-Elson parameter equations, and invalid inputs.

Attribution and license

The project is distributed under the MIT License. Portions are modified, vectorized Python derivatives of public-domain NIST SCATMECH/pySCATMECH code; see NOTICE for attribution and the upstream disclaimer.