miepython 2.5.4__tar.gz → 3.0.0__tar.gz

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

@@ -1,21 +1,35 @@
 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
+3.0.0 (3/16/2025)
+-------------------
+*   breaking api changes
+*   api is more sane: mie.efficiencies() instead of miepython.ez_mie()
+*   use core.py to cleanly separate jit and non-jit code
+*   new function to calculate mie coefficients inside sphere
+*   new function to calculate E-fields near and far from sphere (only works in far-field)
+*   new rayleigh.py
+*   new vsh.py to calculate vector spherical harmonics
+*   new util.py for printing complex numbers
+*   new bessel.py for complete spherical bessel function support
+*   put Monte Carlo routines into their own file
+*   use black for python formatting
+*   update all notebooks to use new api
+*   add more tests
+
+
+2.5.5 (12/01/2025)
+-------------------
+*   add support for specific spherical modes
+*   only branch is now 'main'
+
+2.5.4 (05/07/2024)
+-------------------
+*   add auto-dating in CITATION
+*   add python 3.12
+*   add ruff, pylint config
+*   simplify mie_cdf and fix notebook
+*   set 3.7 as earliest python version
 
 v2.5.3 (8/5/2023)
 -------------------

{miepython-2.5.4 → miepython-3.0.0}/CITATION.cff

@@ -4,8 +4,8 @@ authors:
   orcid: https://orcid.org/0000-0003-1468-6851
 cff-version: 1.2.0
 date-released: '2023-08-05'
-doi: 10.5281/zenodo.7949263
+doi: 10.5281/zenodo.7949264
 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
+url: https://doi.org/10.5281/zenodo.7949403
 version: v2.5.3

miepython-3.0.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.2
+Name: miepython
+Version: 3.0.0
+Summary: Mie scattering of a plane wave by a sphere
+Home-page: https://github.com/scottprahl/miepython.git
+Author: Scott Prahl
+Author-email: scott.prahl@oit.edu
+License: MIT License
+Keywords: mie,scattering,rainbow,droplet,backscatter,sphere,nanoparticle,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: Programming Language :: Python :: 3
+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.8
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: numba
+Requires-Dist: scipy
+Dynamic: author
+Dynamic: author-email
+Dynamic: home-page
+
+.. |pypi| image:: https://img.shields.io/pypi/v/miepython?color=68CA66
+   :target: https://pypi.org/project/miepython/
+   :alt: pypi
+
+.. |github| image:: https://img.shields.io/github/v/tag/scottprahl/miepython?label=github&color=68CA66
+   :target: https://github.com/scottprahl/miepython
+   :alt: github
+
+.. |conda| 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| image:: https://zenodo.org/badge/99259684.svg
+   :target: https://zenodo.org/badge/latestdoi/99259684
+   :alt: doi
+
+.. |license| image:: https://img.shields.io/github/license/scottprahl/miepython?color=68CA66
+   :target: https://github.com/scottprahl/miepython/blob/master/LICENSE.txt
+   :alt: License
+
+.. |test| 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| image:: https://readthedocs.org/projects/miepython/badge?color=68CA66
+   :target: https://miepython.readthedocs.io
+   :alt: Docs
+
+.. |downloads| image:: https://img.shields.io/pypi/dm/miepython?color=68CA66
+   :target: https://pypi.org/project/miepython/
+   :alt: Downloads
+
+.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+   :alt: code style: black
+
+miepython
+=========
+
+by Scott Prahl
+
+|pypi| |github| |conda| |doi|
+
+|license| |test| |docs| |downloads| |black|
+
+________
+
+``miepython`` is a pure Python module to calculate light scattering for
+non-absorbing, partially-absorbing, or perfectly-conducting spheres. 
+
+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.
+
+Mie computations are done following `the procedure described by Wiscombe
+<http://opensky.ucar.edu/islandora/object/technotes:232>`_. This code has
+been validated against his results. 
+
+Full documentation at <https://miepython.readthedocs.io>
+
+Version 3 changes
+-----------------
+
+This version contains major changes to the code base and **has API breaking changes**.
+If you don't need the new functionality for fields, then you can continue to use the
+last version with the old API: 2.5.5
+
+Version 3.0 has many changes, but the major ones are:
+
+    * a complete overhaul of API
+    * added support to calculate Mie coefficients for fields inside sphere
+    * future work will implement calculating electric and magnetic fields
+
+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*.  
+   Currently if you pass refractive indicies with a positive imaginary value, the refractive
+   index is silently converted to a negative value before calculation.
+
+#. The scattering phase function is normalized so it equals the *single scattering albedo* when 
+   integrated over 4π steradians.  The default normalization can now be changed.
+
+
+Installation
+---------------
+
+Use ``pip``::
+
+    pip install miepython
+
+or ``conda``::
+
+    conda install -c conda-forge miepython
+
+An example
+----------
+
+The following code::
+
+    import miepython as mie
+    
+    m = 1.5 - 1j      # refractive index of sphere
+    d = 100           # nm diameter of sphere
+    lambda0 = 314.15  # nm wavelength in vacuum
+
+    qext, qsca, qback, g = mie.efficiencies(m, d, lambda0)
+
+    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
+
+There are a few short python scripts in the github repository.
+
+* `Extinction Efficiency of Absorbing and Non-Absorbing Spheres <https://github.com/scottprahl/miepython/blob/master/miepython/examples/01_dielectric.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/01.svg
+   :alt: Absorbing and non-absorbing spheres
+ 
+* `Four Micron Glass Spheres <https://github.com/scottprahl/miepython/blob/master/miepython/examples/02_glass.py>`_ 
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/02.svg
+   :alt: Glass spheres with resonance spike
+
+* `One Micron Water Droplets <https://github.com/scottprahl/miepython/blob/master/miepython/examples/03_droplets.py>`_ 
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/03.svg
+   :alt: Water Droplets
+
+* `Gold Nanospheres <https://github.com/scottprahl/miepython/blob/master/miepython/examples/04_gold.py>`_ 
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/04.svg
+   :alt: Gold nanospheres
+
+License
+-------
+
+``miepython`` is licensed under the terms of the MIT license.

miepython-3.0.0/README.rst

@@ -0,0 +1,149 @@
+.. |pypi| image:: https://img.shields.io/pypi/v/miepython?color=68CA66
+   :target: https://pypi.org/project/miepython/
+   :alt: pypi
+
+.. |github| image:: https://img.shields.io/github/v/tag/scottprahl/miepython?label=github&color=68CA66
+   :target: https://github.com/scottprahl/miepython
+   :alt: github
+
+.. |conda| 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| image:: https://zenodo.org/badge/99259684.svg
+   :target: https://zenodo.org/badge/latestdoi/99259684
+   :alt: doi
+
+.. |license| image:: https://img.shields.io/github/license/scottprahl/miepython?color=68CA66
+   :target: https://github.com/scottprahl/miepython/blob/master/LICENSE.txt
+   :alt: License
+
+.. |test| 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| image:: https://readthedocs.org/projects/miepython/badge?color=68CA66
+   :target: https://miepython.readthedocs.io
+   :alt: Docs
+
+.. |downloads| image:: https://img.shields.io/pypi/dm/miepython?color=68CA66
+   :target: https://pypi.org/project/miepython/
+   :alt: Downloads
+
+.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+   :alt: code style: black
+
+miepython
+=========
+
+by Scott Prahl
+
+|pypi| |github| |conda| |doi|
+
+|license| |test| |docs| |downloads| |black|
+
+________
+
+``miepython`` is a pure Python module to calculate light scattering for
+non-absorbing, partially-absorbing, or perfectly-conducting spheres. 
+
+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.
+
+Mie computations are done following `the procedure described by Wiscombe
+<http://opensky.ucar.edu/islandora/object/technotes:232>`_. This code has
+been validated against his results. 
+
+Full documentation at <https://miepython.readthedocs.io>
+
+Version 3 changes
+-----------------
+
+This version contains major changes to the code base and **has API breaking changes**.
+If you don't need the new functionality for fields, then you can continue to use the
+last version with the old API: 2.5.5
+
+Version 3.0 has many changes, but the major ones are:
+
+    * a complete overhaul of API
+    * added support to calculate Mie coefficients for fields inside sphere
+    * future work will implement calculating electric and magnetic fields
+
+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*.  
+   Currently if you pass refractive indicies with a positive imaginary value, the refractive
+   index is silently converted to a negative value before calculation.
+
+#. The scattering phase function is normalized so it equals the *single scattering albedo* when 
+   integrated over 4π steradians.  The default normalization can now be changed.
+
+
+Installation
+---------------
+
+Use ``pip``::
+
+    pip install miepython
+
+or ``conda``::
+
+    conda install -c conda-forge miepython
+
+An example
+----------
+
+The following code::
+
+    import miepython as mie
+    
+    m = 1.5 - 1j      # refractive index of sphere
+    d = 100           # nm diameter of sphere
+    lambda0 = 314.15  # nm wavelength in vacuum
+
+    qext, qsca, qback, g = mie.efficiencies(m, d, lambda0)
+
+    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
+
+There are a few short python scripts in the github repository.
+
+* `Extinction Efficiency of Absorbing and Non-Absorbing Spheres <https://github.com/scottprahl/miepython/blob/master/miepython/examples/01_dielectric.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/01.svg
+   :alt: Absorbing and non-absorbing spheres
+ 
+* `Four Micron Glass Spheres <https://github.com/scottprahl/miepython/blob/master/miepython/examples/02_glass.py>`_ 
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/02.svg
+   :alt: Glass spheres with resonance spike
+
+* `One Micron Water Droplets <https://github.com/scottprahl/miepython/blob/master/miepython/examples/03_droplets.py>`_ 
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/03.svg
+   :alt: Water Droplets
+
+* `Gold Nanospheres <https://github.com/scottprahl/miepython/blob/master/miepython/examples/04_gold.py>`_ 
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/04.svg
+   :alt: Gold nanospheres
+
+License
+-------
+
+``miepython`` is licensed under the terms of the MIT license.

miepython-3.0.0/miepython/__init__.py

@@ -0,0 +1,85 @@
+"""
+Mie scattering calculations for perfect spheres.
+
+Extensive documentation is at <https://miepython.readthedocs.io>
+
+`miepython` is a pure Python module to calculate light scattering of
+a plane wave by non-absorbing, partially-absorbing, or perfectly conducting
+spheres.
+
+The extinction efficiency, scattering efficiency, backscattering, and
+scattering asymmetry for a sphere with complex index of refraction m,
+diameter d, and wavelength lambda can be found by::
+
+    import miepython as mie
+    qext, qsca, qback, g = mie.efficiencies(m, d, lambda0)
+
+The normalized scattering values for angles mu=cos(theta) are::
+
+    Ipar, Iper = mie.intensities(m, d, lambda0, mu)
+
+If the size parameter is known, then use::
+
+    mie.efficiencies_mx(m, x)
+
+Mie scattering amplitudes S1 and S2 (complex numbers):
+
+    mie.S1_S2(m, x, mu)
+
+Normalized Mie scattering intensities for angles mu=cos(theta)::
+
+    mie.i_per(m, x, mu)
+    mie.i_par(m, x, mu)
+    mie.i_unpolarized(m, x, mu)
+
+Mie scattering intensities normalized to one when integrated over all angles::
+
+    mie.i_per(m, x, mu, norm='one')
+    mie.i_par(m, x, mu, norm='one')
+    mie.i_unpolarized(m, x, mu, norm='one')
+
+The scattering matrix
+
+    mie.phase_matrix(m, x, mu)
+
+"""
+
+import os
+
+USE_JIT = os.environ.get("MIEPYTHON_USE_JIT", "1").lower() == "1"
+
+if USE_JIT:
+    from .mie_jit import _an_bn, _cn_dn, _S1_S2, _D_calc, _pi_tau
+
+else:
+    from .mie_nojit import _an_bn, _cn_dn, _S1_S2, _D_calc, _pi_tau
+
+from .core import efficiencies, intensities, i_par, i_per, i_unpolarized
+from .core import efficiencies_mx, S1_S2, phase_matrix, coefficients, an_bn, cn_dn
+
+# The only functions exposed to the user
+__all__ = (
+    "intensities",
+    "i_par",
+    "i_per",
+    "i_unpolarized",
+    "phase_matrix",
+    "coefficients",
+    "efficiencies",
+    "efficiencies_mx",
+    "an_bn",
+    "cn_dn",
+    "S1_S2",
+    "_an_bn",
+    "_cn_dn",
+    "_S1_S2",
+    "_D_calc",
+    "_pi_tau",
+)
+
+__version__ = "3.0.0"
+__author__ = "Scott Prahl"
+__email__ = "scott.prahl@oit.edu"
+__copyright__ = "2017-25, Scott Prahl"
+__license__ = "MIT"
+__url__ = "https://github.com/scottprahl/miepython.git"

miepython-3.0.0/miepython/bessel.py

@@ -0,0 +1,126 @@
+"""
+Module for Bessel and Riccati-Bessel functions.
+
+This module provides a collection of functions related to spherical Bessel functions,
+Hankel functions, Riccati-Bessel functions, and their derivatives.  This supplements
+those provided by `scipy.special`
+
+Functions provided:
+
+- Spherical Bessel functions:
+
+  - `spherical_h1`: Spherical Hankel function of the first kind h_n^{(1)}(z).
+  - `spherical_h2`: Spherical Hankel function of the second kind h_n^{(2)}(z).
+
+- Derivatives of Bessel functions:
+
+  - `d_spherical_jn`: Derivative of the spherical Bessel function j_n'(z).
+  - `d_spherical_h1`: Derivative of the spherical Hankel function of first kind h_n^{(1)}'(z).
+  - `d_spherical_h2`: Derivative of the spherical Hankel function of second kind h_n^{(2)}'(z).
+
+- Riccati-Bessel functions:
+
+  - `riccati_bessel_jn`: Riccati-Bessel function of the first kind ψ_n(z).
+  - `riccati_bessel_h1`: Riccati-Bessel function of the second kind ξ_n(z).
+  - `riccati_bessel_h2`: Riccati-Bessel function of the third kind ζ_n(z).
+
+
+- Derivatives of Riccati-Bessel functions:
+
+  - `d_riccati_bessel_jn`: Derivative of the Riccati-Bessel function of the first kind ψ_n'(z).
+  - `d_riccati_bessel_h1`: Derivative of the Riccati-Bessel function of the second kind ξ_n'(z).
+  - `d_riccati_bessel_h2`: Derivative of the Riccati-Bessel function of the third kind ζ_n'(z).
+"""
+
+__all__ = (
+    "spherical_h1",
+    "spherical_h2",
+    "riccati_bessel_jn",
+    "riccati_bessel_h1",
+    "riccati_bessel_h2",
+    "d_spherical_jn",
+    "d_spherical_h1",
+    "d_spherical_h2",
+    "d_riccati_bessel_jn",
+    "d_riccati_bessel_h1",
+    "d_riccati_bessel_h2",
+)
+
+from scipy.special import spherical_jn, spherical_yn
+
+
+def spherical_h1(n, z):
+    """
+    Spherical Hankel function of the first kind.
+    """
+    return spherical_jn(n, z) + 1j * spherical_yn(n, z)
+
+
+def spherical_h2(n, z):
+    """
+    Spherical Hankel function of the second kind.
+    """
+    return spherical_jn(n, z) - 1j * spherical_yn(n, z)
+
+
+def riccati_bessel_jn(n, z):
+    """
+    Riccati-Bessel function of the first kind ψ_n(z).
+    """
+    return z * spherical_jn(n, z)
+
+
+def riccati_bessel_h1(n, z):
+    """
+    Riccati-Bessel function of the second kind ξ_n(z).
+    """
+    return z * spherical_h1(n, z)
+
+
+def riccati_bessel_h2(n, z):
+    """
+    Riccati-Bessel function of the third kind ζ_n(z).
+    """
+    return z * spherical_h2(n, z)
+
+
+def d_spherical_jn(n, z):
+    """
+    Derivative of the spherical Bessel function of the first kind.
+    """
+    return n * spherical_jn(n, z) / z - spherical_jn(n + 1, z)
+
+
+def d_spherical_h1(n, z):
+    """
+    Derivative of the spherical Hankel function of the first kind h_n^{(1)}'(z).
+    """
+    return 0.5 * (spherical_h1(n - 1, z) - spherical_h1(n, z) / z - spherical_h1(n + 1, z))
+
+
+def d_spherical_h2(n, z):
+    """
+    Derivative of the spherical Hankel function of the second kind h_n^{(2)}'(z).
+    """
+    return 0.5 * (spherical_h2(n - 1, z) - spherical_h2(n, z) / z - spherical_h2(n + 1, z))
+
+
+def d_riccati_bessel_jn(n, z):
+    """
+    Derivative of the Riccati-Bessel function of the first kind ψ_n'(z).
+    """
+    return (n + 1) * spherical_jn(n, z) - z * spherical_jn(n + 1, z)
+
+
+def d_riccati_bessel_h1(n, z):
+    """
+    Derivative of the Riccati-Bessel function of the second kind ξ_n'(z).
+    """
+    return 0.5 * (z * spherical_h1(n - 1, z) + spherical_h1(n, z) - z * spherical_h1(n + 1, z))
+
+
+def d_riccati_bessel_h2(n, z):
+    """
+    Derivative of the Riccati-Bessel function of the third kind ζ_n'(z).
+    """
+    return 0.5 * (z * spherical_h2(n - 1, z) + spherical_h2(n, z) - z * spherical_h2(n + 1, z))