miepython 2.5.5__tar.gz → 3.0.2__tar.gz

{miepython-2.5.5 → miepython-3.0.2}/CHANGELOG.rst

@@ -1,27 +1,47 @@
 Changelog
 =========
 
-2.5.5 (12/1/2024)
---------------------
-*   add ability to get individual multipole intensities
-*   add 12_multipoles.ipynb as documentation
-*   improve github workflows
-
-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.1 (5/25/2025)
+-------------------
+*   fix JIT regression (thanks @avgeiss)
+*   clarify polarization in docstrings
+*   improve README.rst
+*   fix git branches
+*   rename mie.mie_scalar to mie.single_sphere
+*   rename small_mie_sphere to small_sphere
+*   rename small_conducting_mie to small_conducting_sphere
+*   rationalize importing of jit and non-jit code
+*   add test_jit_speed.py and test_nojit_speed.py
+
+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.5 → miepython-3.0.2}/CITATION.cff

@@ -3,9 +3,9 @@ authors:
   given-names: Scott
   orcid: https://orcid.org/0000-0003-1468-6851
 cff-version: 1.2.0
-date-released: '2024-05-07'
-doi: 10.5281/zenodo.7949263
+date-released: '2025-05-25'
+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
-version: 2.5.4
+url: https://doi.org/10.5281/zenodo.7949403
+version: 3.0.2

miepython-3.0.2/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: miepython
+Version: 3.0.2
+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
+Dynamic: license-file
+
+.. |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
+=========
+
+|pypi| |github| |conda| |doi|
+
+|license| |test| |docs| |downloads| |black|
+
+``miepython`` is a pure‑Python implementation of Mie theory for spherical
+scatterers, validated against Wiscombe's reference results.  The library is
+lightweight, extensively tested, and—thanks to an *optional* Numba backend—can
+process nearly a million particles per second.
+
+Overview
+--------
+
+- **Non-absorbing spheres** (dielectric particles)
+- **Partially-absorbing spheres** (lossy dielectrics)  
+- **Perfectly-conducting spheres** (metallic particles)
+
+Key Features
+~~~~~~~~~~~~
+
+- ✅ **Pure Python** - No external dependencies beyond NumPy
+- ✅ **Validated algorithms** - Follows Wiscombe's trusted implementation
+- ✅ **Comprehensive outputs** - Extinction, scattering, backscattering, asymmetry
+- ✅ **Angular distributions** - Full scattering phase functions
+- ✅ **Flexible normalization** - Multiple conventions supported
+- ✅ **Code Jitting** - the python Numba package enables 10-50X speedup
+- ✅ **Field calculations** - Internal field coefficients coming!
+
+
+Documentation
+-------------
+
+- **Full Documentation**: `miepython.readthedocs.io <https://miepython.readthedocs.io>`_
+- **API Reference**: `miepython api <https://miepython.readthedocs.io/en/latest/#api-reference>`_
+- **Jupyter Notebooks**: `Interactive Jupyter notebooks <https://github.com/scottprahl/miepython/tree/main/docs>`_
+- **Theory Background**: `Mathematical foundations and validation <https://miepython.readthedocs.io/en/latest/07_algorithm.html>`_
+
+Version 3.0 Breaking Changes
+----------------------------
+
+Version 3.0 introduced significant API changes and new functionality:
+
+- **Internal field calculations** - Compute electromagnetic fields inside spheres
+- **Enhanced coefficient access** - Direct access to Mie expansion coefficients
+- **Future-ready architecture** - Foundation for full field calculations
+
+If you need the old API, pin to version 2.5.5::
+
+    pip install miepython==2.5.5
+
+Installation
+~~~~~~~~~~~~
+
+Using pip::
+
+    pip install miepython
+
+Using conda::
+
+    conda install -c conda-forge miepython
+
+Basic Example
+~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    import miepython as mie
+
+    # Define sphere properties
+    m = 1.5 - 1j       # Complex refractive index
+    d = 100            # Diameter (nm)
+    lambda0 = 314.15   # Wavelength in vacuum (nm)
+
+    # Calculate efficiencies
+    qext, qsca, qback, g = mie.efficiencies(m, d, lambda0)
+
+    print(f"Extinction efficiency:  {qext:.3f}")
+    print(f"Scattering efficiency:  {qsca:.3f}")  
+    print(f"Backscatter efficiency: {qback:.3f}")
+    print(f"Scattering anisotropy:  {g:.3f}")
+
+**Output:**
+
+.. code-block:: text
+
+    Extinction efficiency:  2.336
+    Scattering efficiency:  0.663
+    Backscatter efficiency: 0.573
+    Scattering anisotropy:  0.192
+
+
+API Reference
+-------------
+
+Basic Functions
+~~~~~~~~~~~~~~~
+
+============================================ ===========================================================
+Function                                     Purpose
+============================================ ===========================================================
+``efficiencies(m, d, lambda0, n_env=1)``     Calculate extinction, scattering, backscattering, asymmetry
+``intensities(m, d, lambda0, mu, n_env=1)``  Angular scattering intensities for parallel/perpendicular polarization
+``S1_S2(m, x, mu)``                          Complex scattering amplitudes
+``coefficients(m, x)``                       Mie coefficients for field calculations
+``phase_matrix(m, x, mu)``                   Mueller matrix for sphere
+============================================ ===========================================================
+
+Parameters
+~~~~~~~~~~
+
+- **m** (complex): Complex refractive index of sphere
+- **n_env** (complex): Real refractive index of medium
+- **d** (float): Sphere diameter [same units as wavelength]
+- **lambda0** (float): Wavelength in vacuum [same units as diameter]
+- **x** (float): Size parameter (π×diameter/wavelength)
+- **mu** (array): Cosine of scattering angles
+
+
+Important Conventions
+---------------------
+
+   1. **Negative imaginary refractive index**: For absorbing materials, use ``m = n - ik`` where k > 0
+   2. **Albedo normalization**: Scattering phase functions integrate to the single scattering albedo over 4π steradians (customizable)
+
+   These latter may be mitigated using custom normalization
+
+.. code-block:: python
+
+    # Different scattering function normalizations
+    I_albedo = mie.i_unpolarized(m, x, mu, norm='albedo')  # Default
+    I_unity = mie.i_unpolarized(m, x, mu, norm='one')      # Normalized to 1
+    I_4pi = mie.i_unpolarized(m, x, mu, norm='4pi')        # 4π normalization
+
+
+
+Performance & JIT Compilation
+-----------------------------
+
+``miepython`` supports **Just-In-Time (JIT) compilation** via Numba for dramatic performance improvements on large datasets. This is especially beneficial for batch calculations with thousands of particles.
+
+Enabling JIT
+~~~~~~~~~~~~
+
+.. code-block:: python
+
+    import os
+    os.environ["MIEPYTHON_USE_JIT"] = "1"  # Must be set before importing
+    import miepython as mie
+
+Performance Comparison
+~~~~~~~~~~~~~~~~~~~~~~
+
+JIT compilation provides substantial speedups for large-scale calculations:
+
+=========== ============== ================== ==========
+Version     JIT Status     Time (N=100,000)   Speedup
+=========== ============== ================== ==========
+v3.0.1      Disabled       4.00 seconds       1×
+v3.0.1      **Enabled**    **0.15 seconds**   **27×**
+=========== ============== ================== ==========
+
+Benchmark Example
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    import os
+    import numpy as np
+    from time import time
+
+    os.environ["MIEPYTHON_USE_JIT"] = "1"  # must be before import miepython
+    import miepython as mie
+
+    # Generate random particle ensemble
+    N = 100_000
+    refr = np.random.uniform(1.0, 2.0, N)
+    refi = np.exp(np.random.uniform(np.log(1e-4), np.log(1.0), N))
+    x = np.exp(np.random.uniform(np.log(0.01), np.log(100), N))
+    m = refr - 1j * refi
+
+    # Benchmark calculation
+    t0 = time()
+    qext, qsca, qback, g = mie.efficiencies_mx(m, x)
+    elapsed = time() - t0
+
+    print(f"JIT enabled: {os.environ.get('MIEPYTHON_USE_JIT') == '1'}")
+    print(f"Calculated {N:,} particles in {elapsed:.3f} seconds")
+    print(f"Rate: {N/elapsed:,.0f} particles/second")
+
+.. note::
+   The first JIT-compiled call includes compilation overhead (~1-2 seconds). Subsequent calls achieve full performance.
+
+Examples Gallery
+----------------
+
+The repository includes several `example scripts <https://github.com/scottprahl/miepython/tree/master/miepython/examples>`_ demonstrating different applications:
+
+Dielectric vs. Absorbing Spheres
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/01.svg
+   :alt: Dielectric vs Absorbing
+
+Glass Microspheres with Resonances
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/02.svg
+   :alt: Glass Spheres
+
+Water Droplets
+~~~~~~~~~~~~~~
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/03.svg
+   :alt: Water Droplets
+
+Gold Nanoparticles
+~~~~~~~~~~~~~~~~~~
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/04.svg
+   :alt: Gold Nanoparticles
+
+
+
+
+Citing `miepython`
+--------------------
+
+If this library contributes to your research, please cite the `relevant doi release
+on zenodo <https://zenodo.org/badge/latestdoi/99259684>`_
+
+* **Generic DOI (always the newest release)** — `10.5281/zenodo.7949263`.  The
+  badge at the top of this file resolves to that record.
+* **Version‑specific DOIs** — click the Zenodo badge |doi| and choose the DOI that
+  corresponds to the exact version you want to cite (e.g.
+  `10.5281/zenodo.14257432 for v2.5.5`).
+
+For example::
+
+    S. Prahl, *miepython — Pure‑Python Mie scattering calculations*, Zenodo,
+    16 March 2025. doi:10.5281/zenodo.7949263
+
+.. code-block:: bibtex
+
+    @software{prahl_miepython_2025,
+      author  = {Prahl, Scott},
+      title   = {{miepython}: A Python library for Mie scattering calculations},
+      url     = {https://github.com/scottprahl/miepython},
+      doi     = {10.5281/zenodo.7949263},
+      year    = {2025},
+      version = {latest}
+    }
+
+
+License
+-------
+
+``miepython`` is licensed under the `MIT License <LICENSE.txt>`_.
+
+--------
+
+**Maintained by** `Scott Prahl <https://github.com/scottprahl>`_