miepython 2.5.3__tar.gz → 2.5.4__tar.gz

{miepython-2.5.3 → miepython-2.5.4}/CHANGELOG.rst

@@ -1,6 +1,22 @@
 Changelog
 =========
 
+2.5.4 (5/7/2024)
+--------------------
+*   document normalization in docstrings
+*   add version and year to CITATION.cff
+*   remove 'v' from version numbers
+*   add github script and workflow to auto-update CITATION.cff
+*   add conda badge to readme
+*   clean up README.rst
+*   use svg images
+*   use a single tests/test_mie for jit and non-jit tests
+*   support ruff
+*   test python versions 3.7 to 3.12
+*   fix badges
+*   remove unused functions
+*   fix zenodo link
+
 v2.5.3 (8/5/2023)
 -------------------
 *   conda-forge fails because test files are not included

miepython-2.5.4/CITATION.cff

@@ -0,0 +1,11 @@
+authors:
+- family-names: Prahl
+  given-names: Scott
+  orcid: https://orcid.org/0000-0003-1468-6851
+cff-version: 1.2.0
+date-released: '2023-08-05'
+doi: 10.5281/zenodo.7949263
+message: If you use this software, please cite it as below.
+title: 'miepython: Pure python calculation of Mie scattering'
+url: https://doi.org/10.5281/zenodo.7949263
+version: v2.5.3

miepython-2.5.4/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.1
+Name: miepython
+Version: 2.5.4
+Summary: Mie scattering of a plane wave by a sphere
+Home-page: https://github.com/scottprahl/miepython
+Author: Scott Prahl
+Author-email: scott.prahl@oit.edu
+License: MIT
+Keywords: mie,scattering,rainbow,droplet,backscatter,sphere,nanoparticle,sphere,cloud,phase function,efficiency,rayleigh,backscattering
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: numba
+
+.. |pypi-badge| image:: https://img.shields.io/pypi/v/miepython?color=68CA66
+   :target: https://pypi.org/project/miepython/
+   :alt: pypi
+
+.. |github-badge| image:: https://img.shields.io/github/v/tag/scottprahl/miepython?label=github&color=68CA66
+   :target: https://github.com/scottprahl/miepython
+   :alt: github
+
+.. |conda-badge| image:: https://img.shields.io/conda/vn/conda-forge/miepython?label=conda&color=68CA66
+   :target: https://github.com/conda-forge/miepython-feedstock
+   :alt: conda
+
+.. |doi-badge| image:: https://zenodo.org/badge/99259684.svg
+   :target: https://zenodo.org/badge/latestdoi/99259684
+   :alt: doi
+
+.. |license-badge| image:: https://img.shields.io/github/license/scottprahl/miepython?color=68CA66
+   :target: https://github.com/scottprahl/miepython/blob/master/LICENSE.txt
+   :alt: License
+
+.. |testing-badge| image:: https://github.com/scottprahl/miepython/actions/workflows/test.yml/badge.svg
+   :target: https://github.com/scottprahl/miepython/actions/workflows/test.yml
+   :alt: Testing
+
+.. |docs-badge| image:: https://readthedocs.org/projects/miepython/badge?color=68CA66
+   :target: https://miepython.readthedocs.io
+   :alt: Docs
+
+.. |downloads-badge| image:: https://img.shields.io/pypi/dm/miepython?color=68CA66
+   :target: https://pypi.org/project/miepython/
+   :alt: Downloads
+
+miepython
+=========
+
+by Scott Prahl
+
+|pypi-badge| |github-badge| |conda-badge| |doi-badge|
+
+|license-badge| |testing-badge| |docs-badge| |downloads-badge|
+
+
+``miepython`` is a pure Python module to calculate light scattering for
+non-absorbing, partially-absorbing, or perfectly-conducting spheres. Mie
+theory is used, following `the procedure described by Wiscombe
+<http://opensky.ucar.edu/islandora/object/technotes:232>`_. This code has
+been validated against his work. 
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/mie-diagram2.svg
+   :width: 700px
+   :alt: scattering diagram
+
+This code provides functions for calculating the extinction efficiency,
+scattering efficiency, backscattering, and scattering asymmetry.
+Moreover, a set of angles can be given to calculate the scattering at various
+angles for a sphere.
+
+When comparing different Mie scattering codes, make sure that you're
+aware of the conventions used by each code.  ``miepython`` makes the
+following assumptions
+
+* the imaginary part of the complex index of refraction for absorbing spheres is *negative*.
+
+* the scattering phase function is normalized so it equals the *single scattering albedo* when integrated over 4π steradians by default.  This normalization can be changed (see the normalization notebook for details).
+
+This code provides functions for calculating the extinction efficiency, scattering efficiency, backscattering, and scattering asymmetry. Moreover, a set of angles can be given to calculate the scattering for a sphere at each of those
+angles.
+
+Full documentation at <https://miepython.readthedocs.io>
+
+Pay Attention!
+--------------
+
+When comparing different Mie scattering codes, make sure that you're aware of the conventions used by each code.  ``miepython`` makes the following assumptions
+
+#. the imaginary part of the complex index of refraction for absorbing spheres is *negative*.  
+
+#. the scattering phase function is normalized so it equals the *single scattering albedo* when integrated over 4π steradians.  As of version 2.3, this can be changed.
+
+
+Installation
+---------------
+
+Use ``pip``::
+
+    pip install miepython
+
+or ``conda``::
+
+    conda install -c conda-forge miepython
+
+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.
+
+Usage for those that don't do Jupyter
+--------------------------------------
+
+Basic Mie Calculations
+^^^^^^^^^^^^^^^^^^^^^^^
+
+    from miepython import mie
+    
+    complex_refractive_index = 1.5-1j    # convention is negative imaginary part
+    size_parameter = 1                   # 2𝜋(radius)/λ
+    qext, qsca, qback, g = mie(complex_refractive_index, size_parameter)
+
+    print("The extinction efficiency  is %.3f" % qext)
+    print("The scattering efficiency  is %.3f" % qsca)
+    print("The backscatter efficiency is %.3f" % qback)
+    print("The scattering anisotropy  is %.3f" % g)
+
+should produce::
+
+    The extinction efficiency  is 2.336
+    The scattering efficiency  is 0.663
+    The backscatter efficiency is 0.573
+    The scattering anisotropy  is 0.192
+
+
+Simple Dielectric
+^^^^^^^^^^^^^^^^^^
+
+The script `01_dielectric.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/01_dielectric.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/01_plot.svg
+
+Glass Spheres
+^^^^^^^^^^^^^^
+
+The script `02_glass.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/02_glass.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/02_plot.svg
+
+Water Droplets
+^^^^^^^^^^^^^^^
+
+The script `03_droplets.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/03_droplets.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/03_plot.svg
+
+Small Gold Spheres
+^^^^^^^^^^^^^^^^^^^
+
+The script `04_gold.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/04_gold.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/04_plot.svg
+
+
+Usage for those that use Jupyter
+---------------------------------
+
+All the Jupyter notebooks are available in the docs directory and they are all viewable at <https://miepython.readthedocs.io>
+
+
+Script Examples for those that don't do Jupyter
+-----------------------------------------------
+
+All the Jupyter notebooks are in the docs directory and shown at <https://miepython.readthedocs.io>
+
+You can also use a Jupyter notebook immediately (well, you do have wait a bit for everything to get uploaded) by clicking the Google Colaboratory button below
+
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target: https://colab.research.google.com/github/scottprahl/miepython/blob/master
+  :alt: Colab
+
+
+License
+-------
+
+``miepython`` is licensed under the terms of the MIT license.

miepython-2.5.4/README.rst

@@ -0,0 +1,169 @@
+.. |pypi-badge| image:: https://img.shields.io/pypi/v/miepython?color=68CA66
+   :target: https://pypi.org/project/miepython/
+   :alt: pypi
+
+.. |github-badge| image:: https://img.shields.io/github/v/tag/scottprahl/miepython?label=github&color=68CA66
+   :target: https://github.com/scottprahl/miepython
+   :alt: github
+
+.. |conda-badge| image:: https://img.shields.io/conda/vn/conda-forge/miepython?label=conda&color=68CA66
+   :target: https://github.com/conda-forge/miepython-feedstock
+   :alt: conda
+
+.. |doi-badge| image:: https://zenodo.org/badge/99259684.svg
+   :target: https://zenodo.org/badge/latestdoi/99259684
+   :alt: doi
+
+.. |license-badge| image:: https://img.shields.io/github/license/scottprahl/miepython?color=68CA66
+   :target: https://github.com/scottprahl/miepython/blob/master/LICENSE.txt
+   :alt: License
+
+.. |testing-badge| image:: https://github.com/scottprahl/miepython/actions/workflows/test.yml/badge.svg
+   :target: https://github.com/scottprahl/miepython/actions/workflows/test.yml
+   :alt: Testing
+
+.. |docs-badge| image:: https://readthedocs.org/projects/miepython/badge?color=68CA66
+   :target: https://miepython.readthedocs.io
+   :alt: Docs
+
+.. |downloads-badge| image:: https://img.shields.io/pypi/dm/miepython?color=68CA66
+   :target: https://pypi.org/project/miepython/
+   :alt: Downloads
+
+miepython
+=========
+
+by Scott Prahl
+
+|pypi-badge| |github-badge| |conda-badge| |doi-badge|
+
+|license-badge| |testing-badge| |docs-badge| |downloads-badge|
+
+
+``miepython`` is a pure Python module to calculate light scattering for
+non-absorbing, partially-absorbing, or perfectly-conducting spheres. Mie
+theory is used, following `the procedure described by Wiscombe
+<http://opensky.ucar.edu/islandora/object/technotes:232>`_. This code has
+been validated against his work. 
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/mie-diagram2.svg
+   :width: 700px
+   :alt: scattering diagram
+
+This code provides functions for calculating the extinction efficiency,
+scattering efficiency, backscattering, and scattering asymmetry.
+Moreover, a set of angles can be given to calculate the scattering at various
+angles for a sphere.
+
+When comparing different Mie scattering codes, make sure that you're
+aware of the conventions used by each code.  ``miepython`` makes the
+following assumptions
+
+* the imaginary part of the complex index of refraction for absorbing spheres is *negative*.
+
+* the scattering phase function is normalized so it equals the *single scattering albedo* when integrated over 4π steradians by default.  This normalization can be changed (see the normalization notebook for details).
+
+This code provides functions for calculating the extinction efficiency, scattering efficiency, backscattering, and scattering asymmetry. Moreover, a set of angles can be given to calculate the scattering for a sphere at each of those
+angles.
+
+Full documentation at <https://miepython.readthedocs.io>
+
+Pay Attention!
+--------------
+
+When comparing different Mie scattering codes, make sure that you're aware of the conventions used by each code.  ``miepython`` makes the following assumptions
+
+#. the imaginary part of the complex index of refraction for absorbing spheres is *negative*.  
+
+#. the scattering phase function is normalized so it equals the *single scattering albedo* when integrated over 4π steradians.  As of version 2.3, this can be changed.
+
+
+Installation
+---------------
+
+Use ``pip``::
+
+    pip install miepython
+
+or ``conda``::
+
+    conda install -c conda-forge miepython
+
+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.
+
+Usage for those that don't do Jupyter
+--------------------------------------
+
+Basic Mie Calculations
+^^^^^^^^^^^^^^^^^^^^^^^
+
+    from miepython import mie
+    
+    complex_refractive_index = 1.5-1j    # convention is negative imaginary part
+    size_parameter = 1                   # 2𝜋(radius)/λ
+    qext, qsca, qback, g = mie(complex_refractive_index, size_parameter)
+
+    print("The extinction efficiency  is %.3f" % qext)
+    print("The scattering efficiency  is %.3f" % qsca)
+    print("The backscatter efficiency is %.3f" % qback)
+    print("The scattering anisotropy  is %.3f" % g)
+
+should produce::
+
+    The extinction efficiency  is 2.336
+    The scattering efficiency  is 0.663
+    The backscatter efficiency is 0.573
+    The scattering anisotropy  is 0.192
+
+
+Simple Dielectric
+^^^^^^^^^^^^^^^^^^
+
+The script `01_dielectric.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/01_dielectric.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/01_plot.svg
+
+Glass Spheres
+^^^^^^^^^^^^^^
+
+The script `02_glass.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/02_glass.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/02_plot.svg
+
+Water Droplets
+^^^^^^^^^^^^^^^
+
+The script `03_droplets.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/03_droplets.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/03_plot.svg
+
+Small Gold Spheres
+^^^^^^^^^^^^^^^^^^^
+
+The script `04_gold.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/04_gold.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/04_plot.svg
+
+
+Usage for those that use Jupyter
+---------------------------------
+
+All the Jupyter notebooks are available in the docs directory and they are all viewable at <https://miepython.readthedocs.io>
+
+
+Script Examples for those that don't do Jupyter
+-----------------------------------------------
+
+All the Jupyter notebooks are in the docs directory and shown at <https://miepython.readthedocs.io>
+
+You can also use a Jupyter notebook immediately (well, you do have wait a bit for everything to get uploaded) by clicking the Google Colaboratory button below
+
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target: https://colab.research.google.com/github/scottprahl/miepython/blob/master
+  :alt: Colab
+
+
+License
+-------
+
+``miepython`` is licensed under the terms of the MIT license.

{miepython-2.5.3 → miepython-2.5.4}/miepython/__init__.py

@@ -42,11 +42,11 @@ The scattering matrix
     miepython.mie_phase_matrix(m, x, mu)
 
 """
-__version__ = '2.5.3'
+__version__ = '2.5.4'
 __author__ = 'Scott Prahl'
 __email__ = 'scott.prahl@oit.edu'
-__copyright__ = 'Copyright 2017-23, Scott Prahl'
+__copyright__ = '2017-24, Scott Prahl'
 __license__ = 'MIT'
-__url__ = 'https://github.com/scottprahl/miepython.git'
+__url__ = 'https://github.com/scottprahl/miepython'
 
 from .miepython import *

miepython-2.5.4/miepython/examples/01_dielectric.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+
+"""Plot the extinction efficiency as a function of particle size."""
+
+import numpy as np
+import matplotlib.pyplot as plt
+import miepython
+
+x = np.linspace(0.1, 100, 1000)
+
+plt.figure(figsize=(8, 4.5))
+qext, qsca, qback, g = miepython.mie(1.5, x)
+plt.plot(x, qext, color='red', label="$n=1.5$")
+
+qext, qsca, qback, g = miepython.mie(1.5 - 0.1j, x)
+plt.plot(x, qext, color='blue', label="$n=1.5-0.1j$")
+
+plt.title("Absorbing and Non-absorbing Spheres")
+plt.xlabel("Size Parameter [–]")
+plt.ylabel("Extinction Efficiency $Q_{ext}$ [–]")
+plt.legend()
+# plt.savefig('../../docs/01_plot.svg')
+plt.show()

miepython-2.5.4/miepython/examples/02_glass.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+
+"""Plot the scattering efficiency for 4 micron glass spheres."""
+import numpy as np
+import matplotlib.pyplot as plt
+import miepython
+
+
+def n_bk7(wavelength):
+    """
+    Refractive index of BK7 glass at a wavelength.
+
+    Equation is from https://refractiveindex.info/?shelf=glass&book=BK7&page=SCHOTT
+
+    Args:
+        wavelength: wavelength in microns
+    Returns:
+        index of refraction
+    """
+    m_squared = 1 + 1.03961212 / (1 - 0.00600069867 / lambda0**2)
+    m_squared += 0.231792344 / (1 - 0.0200179144 / lambda0**2)
+    m_squared += 1.01046945 / (1 - 103.560653 / lambda0**2)
+    refractive_index = np.sqrt(m_squared)
+    return refractive_index
+
+
+radius = 2                      # in microns
+lambda0 = np.linspace(0.2, 1.2, 1000)  # also in microns
+x = 2 * np.pi * radius / lambda0
+m = n_bk7(lambda0)
+
+plt.figure(figsize=(8, 4.5))
+qext, qsca, qback, g = miepython.mie(m, x)
+plt.plot(lambda0 * 1000, qsca)
+
+plt.title("4µm diameter BK7 glass spheres")
+plt.xlabel("Wavelength [nm]")
+plt.ylabel("Scattering Efficiency [–]")
+# plt.savefig('../../docs/02_plot.svg')
+plt.show()

miepython-2.5.4/miepython/examples/03_droplets.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+
+"""Plot the scattering cross section for 1 micron water droplets."""
+import numpy as np
+import matplotlib.pyplot as plt
+import miepython
+
+
+def n_water(wavelength):
+    """
+    Refractive index of water at wavelength.
+
+    Equation is from https://refractiveindex.info/?shelf=main&book=H2O&page=Daimon - 24.0C
+
+    Args:
+        wavelength: wavelength in microns
+    Returns:
+        index of refraction
+    """
+    m_squared = 1.0
+    m_squared += 5.666959820E-1 / (1.0 - 5.084151894E-3 / wavelength**2)
+    m_squared += 1.731900098E-1 / (1.0 - 1.818488474E-2 / wavelength**2)
+    m_squared += 2.095951857E-2 / (1.0 - 2.625439472E-2 / wavelength**2)
+    m_squared += 1.125228406E-1 / (1.0 - 1.073842352E1 / wavelength**2)
+    refractive_index = np.sqrt(m_squared)
+    return refractive_index
+
+
+diameter = 1                               # microns
+radius = diameter / 2                      # microns
+num = 200                                  # points to plot
+lambda_range = np.linspace(0.2, 1.2, num)
+ref_index = n_water(lambda_range)
+x = 2 * np.pi * radius / lambda_range
+
+qext, qsca, qback, g = miepython.mie(ref_index, x)
+
+plt.figure(figsize=(8, 4.5))
+plt.plot(lambda_range * 1000, qsca)
+plt.title("%.2f µm Diameter Water Droplets" % diameter)
+plt.xlabel("Wavelength [nm]")
+plt.ylabel("Scattering Cross Section [µm²]")
+# plt.savefig('../../docs/03_plot.svg')
+plt.show()

{miepython-2.5.3 → miepython-2.5.4}/miepython/examples/04_gold.py

@@ -1,10 +1,6 @@
 #!/usr/bin/env python3
 
-"""
-Plot the scattering cross section for 100nm gold spheres.
-
-The resulting graph is as a function of wavelength.
-"""
+"""Plot the scattering cross section for 100nm gold spheres."""
 
 import numpy as np
 import matplotlib.pyplot as plt
@@ -42,25 +38,24 @@ qext, qsca, qback, g = miepython.mie(m, x)
 sca_cross_section = qsca * cross_section_area
 abs_cross_section = (qext - qsca) * cross_section_area
 
-plt.subplots(3, 1, figsize=(9, 9))
+plt.subplots(3, 1, figsize=(8, 8))
 plt.subplot(311)
-plt.plot(ref_lam * 1000, ref_n, 'ob')
-plt.plot(ref_lam * 1000, -ref_k, 'sr')
+plt.plot(ref_lam * 1000, ref_n, 'ob', markersize=2)
+plt.plot(ref_lam * 1000, -ref_k, 'sr', markersize=2)
 plt.title("Gold Spheres 200nm diameter")
-plt.xticks([])
 plt.text(700, 1, "real refractive index", color='blue')
 plt.text(1100, -6, "imaginary refractive index", color='red')
 
 plt.subplot(312)
-plt.plot(ref_lam * 1000, 1000 / mu_a, 'ob')
+plt.plot(ref_lam * 1000, 1000 / mu_a, 'ob', markersize=2)
 plt.ylabel("Absorption Depth [nm]")
 
 plt.subplot(313)
-plt.plot(ref_lam * 1000, abs_cross_section, 'ob')
-plt.plot(ref_lam * 1000, sca_cross_section, 'sr')
+plt.plot(ref_lam * 1000, abs_cross_section, 'ob', markersize=2)
+plt.plot(ref_lam * 1000, sca_cross_section, 'sr', markersize=2)
 plt.xlabel("Wavelength (nm)")
-plt.ylabel("Cross Section (µm²)")
+plt.ylabel("Cross Section [µm²]")
 plt.text(700, 0.01, "absorption", color='blue')
 plt.text(750, 0.1, "scattering", color='red')
-plt.savefig("04_plot.png")
-# plt.show()
+# plt.savefig("../../docs/04_plot.svg")
+plt.show()