miepython 2.3.2__tar.gz → 2.5.0__tar.gz

{miepython-2.3.2 → miepython-2.5.0}/CHANGELOG.rst

@@ -1,6 +1,14 @@
 Changelog
 =========
 
+v2.5.0 (8/4/2023)
+-------------------
+*   fix scattering function for very small spheres
+
+v2.4.0 (6/10/2023)
+-------------------
+*   add mie_phase_matrix() to calculate scattering (Mueller) matrix
+
 v2.3.2
 -------------------
 *   fix typo in README.rst that prevented pypi upload

miepython-2.5.0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+title: 'miepython: Pure python implementation of Mie scattering'
+message: 'If you use this software, please cite it as below.'
+
+authors:
+  - given-names: Scott
+    family-names: Prahl
+    orcid: 'https://orcid.org/0000-0003-1468-6851'
+doi: 10.5281/zenodo.7949264
+url: 'https://doi.org/10.5281/zenodo.7949403'

{miepython-2.3.2 → miepython-2.5.0}/Makefile

@@ -19,7 +19,6 @@ rstcheck:
 	-rstcheck README.rst
 	-rstcheck CHANGELOG.rst
 	-rstcheck docs/index.rst
-	-rstcheck docs/changelog.rst
 	-rstcheck --ignore-directives automodapi docs/miepython.rst
 
 lintcheck:

{miepython-2.3.2/miepython.egg-info → miepython-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: miepython
-Version: 2.3.2
+Version: 2.5.0
 Summary: Mie scattering of a plane wave by a sphere
 Home-page: https://github.com/scottprahl/miepython.git
 Author: Scott Prahl
@@ -25,15 +25,9 @@ by Scott Prahl
 .. image:: https://img.shields.io/pypi/v/miepython.svg
    :target: https://pypi.org/project/miepython/
 
-.. image:: https://colab.research.google.com/assets/colab-badge.svg
-   :target: https://colab.research.google.com/github/scottprahl/miepython/blob/master
-
 .. image:: https://img.shields.io/badge/readthedocs-latest-blue.svg
    :target: https://miepython.readthedocs.io
 
-.. image:: https://img.shields.io/badge/github-code-green.svg
-   :target: https://github.com/scottprahl/miepython
-
 .. image:: https://img.shields.io/badge/MIT-license-yellow.svg
    :target: https://github.com/scottprahl/miepython/blob/master/LICENSE.txt
 

{miepython-2.3.2 → miepython-2.5.0}/README.rst

@@ -6,15 +6,9 @@ by Scott Prahl
 .. image:: https://img.shields.io/pypi/v/miepython.svg
    :target: https://pypi.org/project/miepython/
 
-.. image:: https://colab.research.google.com/assets/colab-badge.svg
-   :target: https://colab.research.google.com/github/scottprahl/miepython/blob/master
-
 .. image:: https://img.shields.io/badge/readthedocs-latest-blue.svg
    :target: https://miepython.readthedocs.io
 
-.. image:: https://img.shields.io/badge/github-code-green.svg
-   :target: https://github.com/scottprahl/miepython
-
 .. image:: https://img.shields.io/badge/MIT-license-yellow.svg
    :target: https://github.com/scottprahl/miepython/blob/master/LICENSE.txt
 

{miepython-2.3.2 → miepython-2.5.0}/docs/index.rst

@@ -1,24 +1,20 @@
 miepython
 =========
 
+by Scott Prahl
+
 .. image:: https://img.shields.io/pypi/v/miepython.svg
    :target: https://pypi.org/project/miepython/
 
-.. image:: https://colab.research.google.com/assets/colab-badge.svg
-   :target: https://colab.research.google.com/github/scottprahl/miepython/blob/master
-
-.. image:: https://img.shields.io/badge/readthedocs-latest-blue.svg
-   :target: https://miepython.readthedocs.io
-
 .. image:: https://img.shields.io/badge/github-code-green.svg
    :target: https://github.com/scottprahl/miepython
 
-.. image:: https://img.shields.io/badge/MIT-license-yellow.svg
-   :target: https://github.com/scottprahl/miepython/blob/master/LICENSE.txt
-
 .. image:: https://github.com/scottprahl/miepython/actions/workflows/test.yml/badge.svg
    :target: https://github.com/scottprahl/miepython/actions/workflows/test.yml
 
+.. image:: https://zenodo.org/badge/99259684.svg
+   :target: https://zenodo.org/badge/latestdoi/99259684
+
 ----
 
 ``miepython`` is a pure Python module to calculate light scattering by
@@ -47,7 +43,7 @@ Using miepython
 
 1. You can install locally using pip::
     
-    pip install --user miepython
+    pip install miepython
 
 2. or `run this code in the cloud using Google Collaboratory <https://colab.research.google.com/github/scottprahl/miepython/blob/master>`_ by selecting the Jupyter notebook that interests you.
 

{miepython-2.3.2 → miepython-2.5.0}/miepython/__init__.py

@@ -36,8 +36,13 @@ Mie scattering intensities normalized to one when integrated over all angles::
     miepython.i_per(m, x, mu, norm='one')
     miepython.i_par(m, x, mu, norm='one')
     miepython.i_unpolarized(m, x, mu, norm='one')
+
+The scattering matrix
+
+    miepython.mie_phase_matrix(m, x, mu)
+
 """
-__version__ = '2.3.2'
+__version__ = '2.5.0'
 __author__ = 'Scott Prahl'
 __email__ = 'scott.prahl@oit.edu'
 __copyright__ = 'Copyright 2017-23, Scott Prahl'

{miepython-2.3.2 → miepython-2.5.0}/miepython/miepython.py

@@ -50,6 +50,7 @@ __all__ = ('ez_mie',
            'i_unpolarized',
            'mie',
            'mie_S1_S2',
+           'mie_phase_matrix',
            'mie_cdf',
            'mie_mu_with_uniform_cdf',
            'generate_mie_costheta',
@@ -475,8 +476,8 @@ def _small_mie_S1_S2(m, x, mu):
     return [S1, S2]
 
 
-@njit((complex128[:], complex128[:], float64, int32), cache=True)
-def normalization_factor(a, b, x, norm_int):
+@njit((complex128, float64, int32), cache=True)
+def normalization_factor(m, x, norm_int):
     """
     Figure out scattering function normalization.
 
@@ -491,7 +492,7 @@ def normalization_factor(a, b, x, norm_int):
     """
     # Qsca normalization
     if norm_int == 3:
-        return np.sqrt(np.pi * x**2)
+        return x * np.sqrt(np.pi)
 
     # Bohren Normalization
     if norm_int == 5:
@@ -502,26 +503,23 @@ def normalization_factor(a, b, x, norm_int):
         return 1
 
     # calculate qsca and qext
-    n = np.arange(1, len(a) + 1)
-    cn = 2.0 * n + 1.0
-    qext = 2 * np.sum(cn * (a.real + b.real)) / x**2
-    qsca = 2 * np.sum(cn * (np.abs(a)**2 + np.abs(b)**2)) / x**2
+    qext, qsca, _, _ = _mie_scalar(m, x)
 
     # albedo Normalization
     if norm_int == 0:
-        return np.sqrt(np.pi * x**2 * qext)
+        return x * np.sqrt(np.pi * qext)
 
     # Unity normalization
     if norm_int == 1:
-        return np.sqrt(qsca * np.pi * x**2)
+        return x * np.sqrt(qsca * np.pi)
 
     # 4pi Normalization
     if norm_int == 2:
-        return np.sqrt(qsca * x**2 / 4)
+        return x * np.sqrt(qsca / 4)
 
     # Qext Normalization
     if norm_int == 4:  # 4pi
-        return np.sqrt(qsca * np.pi * x**2 / qext)
+        return x * np.sqrt(qsca * np.pi / qext)
 
     raise ValueError("norm-int must be in the range 0..6")
 
@@ -608,7 +606,7 @@ def _mie_S1_S2(m, x, mu, norm_int):
             pi_nm1 = ((2 * n + 1) * mu[k] * pi_nm1 - (n + 1) * pi_nm2) / n
             pi_nm2 = temp
 
-    normalization = normalization_factor(a, b, x, norm_int)
+    normalization = normalization_factor(m, x, norm_int)
 
     S1 /= normalization
     S2 /= normalization
@@ -642,6 +640,52 @@ def mie_S1_S2(m, x, mu, norm='albedo'):
     return _mie_S1_S2(m, x, mu, norm_int)
 
 
+def mie_phase_matrix(m, x, mu, norm='albedo'):
+    """
+    Calculate the scattering (Mueller) matrix.
+
+    If mu has length N, then the returned matrix is 4x4xN.  If mu is a scalar
+    then the matrix is 4x4
+
+    The phase scattering matrix is computed from the scattering amplitude
+    functions, according to equations 5.2.105-6 in K. N. Liou (**2002**) -
+    *An Introduction to Atmospheric Radiation*, Second Edition.
+
+    or
+
+    Bohren and Huffman, *Absorption and Scattering of Light by Small Particles*,
+    JOHN WILEY & SONS, page 112, (1983).
+
+    Args:
+        m: the complex index of refraction of the sphere
+        x: the size parameter of the sphere
+        mu: the angles, cos(theta), for the phase scattering matrix
+
+    Returns:
+        p: the phase scattering matrix [sr**(-1.0)]
+    """
+    s1, s2 = mie_S1_S2(m=m, x=x, mu=mu, norm=norm)
+
+    mu = np.atleast_1d(mu)
+    s1_star = np.conjugate(s1)
+    s2_star = np.conjugate(s2)
+    m1 = (s1 * s1_star).real
+    m2 = (s2 * s2_star).real
+    s21 = (0.5 * (s1 * s2_star + s2 * s1_star)).real
+    d21 = (-0.5j * (s1 * s2_star - s2 * s1_star)).real
+    phase = np.zeros(shape=(4, 4, mu.size))
+    phase[0, 0] = 0.5 * (m2 + m1)
+    phase[0, 1] = 0.5 * (m2 - m1)
+    phase[1, 0] = phase[0, 1]
+    phase[1, 1] = phase[0, 0]
+    phase[2, 2] = s21
+    phase[2, 3] = -d21
+    phase[3, 2] = d21
+    phase[3, 3] = s21
+
+    return phase.squeeze()
+
+
 def mie_cdf(m, x, num, norm='albedo'):
     """
     Create a CDF for unpolarized scattering uniformly spaced in cos(theta).

{miepython-2.3.2 → miepython-2.5.0}/miepython/miepython_nojit.py

@@ -49,6 +49,7 @@ __all__ = ('ez_mie',
            'i_unpolarized',
            'mie',
            'mie_S1_S2',
+           'mie_phase_matrix',
            'mie_cdf',
            'mie_mu_with_uniform_cdf',
            'generate_mie_costheta',
@@ -464,13 +465,12 @@ def _small_mie_S1_S2(m, x, mu):
     return [S1, S2]
 
 
-def normalization_factor(a, b, x, norm_str):
+def normalization_factor(m, x, norm_str):
     """
     Figure out scattering function normalization.
 
     Args:
-        a: complex array of An coefficients
-        b: complex array of Bn coefficients
+        m: complex index of refraction of sphere
         x: dimensionless sphere size
         norm_str: string describing type of normalization
 
@@ -485,26 +485,22 @@ def normalization_factor(a, b, x, norm_str):
     if norm in ['wiscombe']:
         return 1
 
-    n = np.arange(1, len(a) + 1)
-    cn = 2.0 * n + 1.0
-    qext = 2 * np.sum(cn * (a.real + b.real)) / x**2
+    if norm in ['qsca', 'scattering_efficiency']:
+        return x * np.sqrt(np.pi)
 
-    if norm in ['a', 'albedo']:
-        return np.sqrt(np.pi * x**2 * qext)
+    qext, qsca, _, _ = _mie_scalar(m, x)
 
-    qsca = 2 * np.sum(cn * (np.abs(a)**2 + np.abs(b)**2)) / x**2
+    if norm in ['a', 'albedo']:
+        return x * np.sqrt(np.pi * qext)
 
     if norm in ['1', 'one', 'unity']:
-        return np.sqrt(qsca * np.pi * x**2)
+        return x * np.sqrt(qsca * np.pi)
 
     if norm in ['four_pi', '4pi']:
-        return np.sqrt(qsca * x**2 / 4)
-
-    if norm in ['qsca', 'scattering_efficiency']:
-        return np.sqrt(np.pi * x**2)
+        return x * np.sqrt(qsca / 4)
 
     if norm in ['qext', 'extinction_efficiency']:
-        return np.sqrt(qsca * np.pi * x**2 / qext)
+        return x * np.sqrt(qsca * np.pi / qext)
 
     raise ValueError("normalization must be one of 'albedo' (default), 'one'"
                      "'4pi', 'qext', 'qsca', 'bohren', or 'wiscombe'")
@@ -548,7 +544,7 @@ def mie_S1_S2(m, x, mu, norm='albedo'):
             pi_nm1 = ((2 * n + 1) * mu[k] * pi_nm1 - (n + 1) * pi_nm2) / n
             pi_nm2 = temp
 
-    normalization = normalization_factor(a, b, x, norm)
+    normalization = normalization_factor(m, x, norm)
 
     S1 /= normalization
     S2 /= normalization
@@ -556,6 +552,52 @@ def mie_S1_S2(m, x, mu, norm='albedo'):
     return [S1, S2]
 
 
+def mie_phase_matrix(m, x, mu, norm='albedo'):
+    """
+    Calculate the scattering (Mueller) matrix.
+
+    If mu has length N, then the returned matrix is 4x4xN.  If mu is a scalar
+    then the matrix is 4x4
+
+    The phase scattering matrix is computed from the scattering amplitude
+    functions, according to equations 5.2.105-6 in K. N. Liou (**2002**) -
+    *An Introduction to Atmospheric Radiation*, Second Edition.
+
+    or
+
+    Bohren and Huffman, *Absorption and Scattering of Light by Small Particles*,
+    JOHN WILEY & SONS, page 112, (1983).
+
+    Args:
+        m: the complex index of refraction of the sphere
+        x: the size parameter of the sphere
+        mu: the angles, cos(theta), of the phase scattering matrix
+
+    Returns:
+        p: the phase scattering matrix [sr**(-1.0)]
+    """
+    mu = np.atleast_1d(mu)
+    s1, s2 = mie_S1_S2(m=m, x=x, mu=mu, norm=norm)
+
+    s1_star = np.conjugate(s1)
+    s2_star = np.conjugate(s2)
+    m1 = (s1 * s1_star).real
+    m2 = (s2 * s2_star).real
+    s21 = (0.5 * (s1 * s2_star + s2 * s1_star)).real
+    d21 = (-0.5j * (s1 * s2_star - s2 * s1_star)).real
+    phase = np.zeros(shape=(4, 4, mu.size))
+    phase[0, 0] = 0.5 * (m2 + m1)
+    phase[0, 1] = 0.5 * (m2 - m1)
+    phase[1, 0] = phase[0, 1]
+    phase[1, 1] = phase[0, 0]
+    phase[2, 2] = s21
+    phase[2, 3] = -d21
+    phase[3, 2] = d21
+    phase[3, 3] = s21
+
+    return phase.squeeze()
+
+
 def mie_cdf(m, x, num, norm='albedo'):
     """
     Create a CDF for unpolarized scattering uniformly spaced in cos(theta).

{miepython-2.3.2 → miepython-2.5.0/miepython.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: miepython
-Version: 2.3.2
+Version: 2.5.0
 Summary: Mie scattering of a plane wave by a sphere
 Home-page: https://github.com/scottprahl/miepython.git
 Author: Scott Prahl
@@ -25,15 +25,9 @@ by Scott Prahl
 .. image:: https://img.shields.io/pypi/v/miepython.svg
    :target: https://pypi.org/project/miepython/
 
-.. image:: https://colab.research.google.com/assets/colab-badge.svg
-   :target: https://colab.research.google.com/github/scottprahl/miepython/blob/master
-
 .. image:: https://img.shields.io/badge/readthedocs-latest-blue.svg
    :target: https://miepython.readthedocs.io
 
-.. image:: https://img.shields.io/badge/github-code-green.svg
-   :target: https://github.com/scottprahl/miepython
-
 .. image:: https://img.shields.io/badge/MIT-license-yellow.svg
    :target: https://github.com/scottprahl/miepython/blob/master/LICENSE.txt
 

miepython-2.3.2/CITATION.cff

@@ -1,40 +0,0 @@
-cff-version: 1.2.0
-title: miepython
-message: >-
-  If you use this software, please cite it using the
-  metadata from this file.
-type: software
-authors:
-  - given-names: Scott
-    name-particle: A
-    family-names: Prahl
-    email: scott.prahl@oit.edu
-    affiliation: Oregon Tech
-    orcid: 'https://orcid.org/0000-0003-1468-6851'
-identifiers:
-  - type: doi
-    value: 10.5281/zenodo.7949264
-repository-code: 'https://github.com/scottprahl/miepython.git'
-url: 'https://github.com/scottprahl/miepython'
-repository: 'https://miepython.readthedocs.io/en/latest/'
-abstract: >-
-  miepython is a pure Python module to calculate light
-  scattering by non-absorbing, partially-absorbing, or
-  perfectly conducting spheres. Mie theory is 
-  validated against published results by Wiscombe.
-  This code provides functions for calculating the
-  extinction efficiency, scattering efficiency,
-  backscattering, and scattering asymmetry.
-keywords:
-  - mie
-  - scattering
-  - rainbow
-  - droplet
-  - nanoparticle
-  - sphere
-  - cloud
-  - phase function
-  - efficiency
-  - rayleigh
-  - backscattering
-license: MIT