miepython 3.0.5__tar.gz → 3.2.0__tar.gz

{miepython-3.0.5 → miepython-3.2.0}/CHANGELOG.rst

@@ -1,6 +1,22 @@
 Changelog
 =========
 
+3.2.0 (03/06/2026)
+-------------------
+*   fix error in E & H calculations in the near field when y≠0 (thanks @dorianherle)
+*   add regression test
+
+3.1.0 (02/07/2026)
+-------------------
+*   add near-field E and H field APIs, fix boundary continuity/medium handling, and expand validation tests
+*   add field calculation utilities, field module cleanup/help text improvements, and precomputed E/H reference data (via scattnlay)
+*   improve performance: ~20% speedups in Mie backends and faster near-field calculations; add speed benchmarks
+*   documentation updates: new/updated notebooks (boundary conditions, 2D fields, performance), clarified conventions
+*   refresh docs/README visuals and assets; add custom CSS for docs images
+*   jupyterlite/RTD updates: config moves, build modernizations, and avoid numba install in JupyterLite
+*   packaging/CI: pyproject and requirements cleanup, improved PyPI workflow, updated citation automation/config
+*   misc cleanups: remove unused files/images, minor typos, Makefile and docs config tidy-ups, CITATION.cff refresh
+
 3.0.5 (1/2/2026)
 -------------------
 *   fix versioning

{miepython-3.0.5 → miepython-3.2.0}/CITATION.cff

@@ -2,9 +2,9 @@ cff-version: 1.2.0
 type: software
 message: If you use this software, please cite it as below.
 title: 'miepython: Pure python calculation of Mie scattering'
-version: 3.0.5
+version: 3.1.0
 doi: 10.5281/zenodo.7949264
-date-released: '2026-01-03'
+date-released: '2026-02-08'
 url: https://doi.org/10.5281/zenodo.7949264
 repository-code: https://github.com/scottprahl/miepython
 license: MIT
@@ -33,7 +33,7 @@ preferred-citation:
   type: software
   title: 'miepython: Pure python calculation of Mie scattering'
   year: 2026
-  version: 3.0.5
+  version: 3.1.0
   doi: 10.5281/zenodo.7949264
   url: https://doi.org/10.5281/zenodo.7949264
   authors:

{miepython-3.0.5 → miepython-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: miepython
-Version: 3.0.5
+Version: 3.2.0
 Summary: Mie scattering of a plane wave by a sphere
 Author-email: Scott Prahl <scott.prahl@oit.edu>
 License-Expression: MIT
@@ -14,17 +14,45 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-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.9
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 Requires-Dist: numpy
 Requires-Dist: matplotlib
-Requires-Dist: numba
 Requires-Dist: scipy
+Requires-Dist: numba; sys_platform != "emscripten"
+Provides-Extra: docs
+Requires-Dist: Sphinx>=8.1.3; extra == "docs"
+Requires-Dist: nbsphinx>=0.9.7; extra == "docs"
+Requires-Dist: ipython; extra == "docs"
+Requires-Dist: sphinx_automodapi; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: imageio; extra == "dev"
+Requires-Dist: requests; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: yamllint; extra == "dev"
+Requires-Dist: rstcheck[sphinx,toml]; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pyroma; extra == "dev"
+Requires-Dist: black[jupyter]; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: check-manifest; extra == "dev"
+Requires-Dist: libarchive-c; extra == "dev"
+Requires-Dist: pyyaml; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Requires-Dist: jupyterlab; extra == "dev"
+Requires-Dist: nbconvert; extra == "dev"
+Requires-Dist: nbformat; extra == "dev"
+Provides-Extra: lite
+Requires-Dist: jupyterlite-core<0.8,>=0.7; extra == "lite"
+Requires-Dist: jupyterlite-pyodide-kernel<0.8,>=0.7; extra == "lite"
 Dynamic: license-file
 
 .. |pypi| image:: https://img.shields.io/pypi/v/miepython?color=68CA66
@@ -47,8 +75,8 @@ Dynamic: license-file
    :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
+.. |test| image:: https://github.com/scottprahl/miepython/actions/workflows/test.yaml/badge.svg
+   :target: https://github.com/scottprahl/miepython/actions/workflows/test.yaml
    :alt: Testing
 
 .. |docs| image:: https://readthedocs.org/projects/miepython/badge?color=68CA66
@@ -86,11 +114,13 @@ The library implements the full Mie solution, including:
 - angle-resolved scattering intensities
 - Mie expansion coefficients
 - complex amplitude functions and Mueller matrices
+- E-field and H-field calculations in the near-field around a sphere
 
 The implementation is numerically stable for a wide range of size parameters and refractive indices, including lossy materials and high-index contrasts.
 
-Immediate Use in the Browser
-----------------------------
+
+JupyterLite Implementation
+--------------------------
 
 The entire package can be used **immediately** in a browser — without installation — using the JupyterLite interface:
 
@@ -138,33 +168,10 @@ A typical calculation is straightforward:
 Documentation and Examples
 --------------------------
 
-The full documentation is available as:
+The full documentation is available on ReadTheDocs:
 
-Interactive documentation (JupyterLite):
-    |lite|
-
-Static Jupyter notebooks on ReadTheDocs:
     |docs|
 
-Among other things the documentation discusses:
-
-- **Mathematical formulation of Mie theory**  
-  https://miepython.readthedocs.io/en/latest/01_theory.html
-
-- **Normalization conventions and units**  
-  https://miepython.readthedocs.io/en/latest/02_normalization.html
-
-- **Numerical stability considerations**  
-  https://miepython.readthedocs.io/en/latest/03_stability.html
-
-- **Validation against MIEV0 and other reference implementations**  
-  https://miepython.readthedocs.io/en/latest/04_validation.html
-
-- **Guidelines for parameter choices and truncation order**  
-  https://miepython.readthedocs.io/en/latest/05_truncation.html
-
-- **Physical interpretation, resonances, and comparison plots**  
-  https://miepython.readthedocs.io/en/latest/06_examples.html
 
 Representative results simple examples:
 
@@ -174,6 +181,7 @@ Representative results simple examples:
 .. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/images/02.svg
 .. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/images/03.svg
 .. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/images/04.svg
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/images/05.svg
 
 Performance and Acceleration
 ----------------------------
@@ -202,19 +210,19 @@ Citation
 
 If you use ``laserbeamsize`` in academic, instructional, or applied technical work, please cite:
 
-Prahl, S. (2026). *miepython: Pure python calculation of Mie scattering* (Version 3.0.5) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
+Prahl, S. (2026). *miepython: Pure python calculation of Mie scattering* (Version 3.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
 
 BibTeX:
 
 .. code-block:: bibtex
 
-    @software{prahl_miepython_2025,
+    @software{prahl_miepython_2026,
       author  = {Scott Prahl},
       title   = {{miepython}: A Python library for Mie scattering calculations},
       url     = {https://github.com/scottprahl/miepython},
       doi     = {10.5281/zenodo.7949263},
       year    = {2026},
-      version = {3.0.5},
+      version = {3.1.0},
       publisher = {Zenodo}
     }
 

{miepython-3.0.5 → miepython-3.2.0}/README.rst

@@ -18,8 +18,8 @@
    :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
+.. |test| image:: https://github.com/scottprahl/miepython/actions/workflows/test.yaml/badge.svg
+   :target: https://github.com/scottprahl/miepython/actions/workflows/test.yaml
    :alt: Testing
 
 .. |docs| image:: https://readthedocs.org/projects/miepython/badge?color=68CA66
@@ -57,11 +57,13 @@ The library implements the full Mie solution, including:
 - angle-resolved scattering intensities
 - Mie expansion coefficients
 - complex amplitude functions and Mueller matrices
+- E-field and H-field calculations in the near-field around a sphere
 
 The implementation is numerically stable for a wide range of size parameters and refractive indices, including lossy materials and high-index contrasts.
 
-Immediate Use in the Browser
-----------------------------
+
+JupyterLite Implementation
+--------------------------
 
 The entire package can be used **immediately** in a browser — without installation — using the JupyterLite interface:
 
@@ -109,33 +111,10 @@ A typical calculation is straightforward:
 Documentation and Examples
 --------------------------
 
-The full documentation is available as:
+The full documentation is available on ReadTheDocs:
 
-Interactive documentation (JupyterLite):
-    |lite|
-
-Static Jupyter notebooks on ReadTheDocs:
     |docs|
 
-Among other things the documentation discusses:
-
-- **Mathematical formulation of Mie theory**  
-  https://miepython.readthedocs.io/en/latest/01_theory.html
-
-- **Normalization conventions and units**  
-  https://miepython.readthedocs.io/en/latest/02_normalization.html
-
-- **Numerical stability considerations**  
-  https://miepython.readthedocs.io/en/latest/03_stability.html
-
-- **Validation against MIEV0 and other reference implementations**  
-  https://miepython.readthedocs.io/en/latest/04_validation.html
-
-- **Guidelines for parameter choices and truncation order**  
-  https://miepython.readthedocs.io/en/latest/05_truncation.html
-
-- **Physical interpretation, resonances, and comparison plots**  
-  https://miepython.readthedocs.io/en/latest/06_examples.html
 
 Representative results simple examples:
 
@@ -145,6 +124,7 @@ Representative results simple examples:
 .. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/images/02.svg
 .. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/images/03.svg
 .. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/images/04.svg
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/main/docs/images/05.svg
 
 Performance and Acceleration
 ----------------------------
@@ -173,19 +153,19 @@ Citation
 
 If you use ``laserbeamsize`` in academic, instructional, or applied technical work, please cite:
 
-Prahl, S. (2026). *miepython: Pure python calculation of Mie scattering* (Version 3.0.5) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
+Prahl, S. (2026). *miepython: Pure python calculation of Mie scattering* (Version 3.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
 
 BibTeX:
 
 .. code-block:: bibtex
 
-    @software{prahl_miepython_2025,
+    @software{prahl_miepython_2026,
       author  = {Scott Prahl},
       title   = {{miepython}: A Python library for Mie scattering calculations},
       url     = {https://github.com/scottprahl/miepython},
       doi     = {10.5281/zenodo.7949263},
       year    = {2026},
-      version = {3.0.5},
+      version = {3.1.0},
       publisher = {Zenodo}
     }
 

miepython-3.2.0/miepython/__init__.py

@@ -0,0 +1,155 @@
+"""
+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)
+
+Near-field calculations are provided by the ``miepython.field`` module::
+
+    from miepython.field import e_near, h_near, eh_near
+    from miepython.field import e_near_cartesian, h_near_cartesian, eh_near_cartesian
+    from miepython.field import e_far
+
+Example near-field usage::
+
+    import numpy as np
+    from miepython.field import eh_near_cartesian
+
+    u = np.linspace(-1.5, 1.5, 101)
+    X, Z = np.meshgrid(u, u, indexing='xy')
+    E_xyz, H_xyz = eh_near_cartesian(
+        lambda0=1.0, d_sphere=1.0, m_sphere=1.5 + 0.0j, n_env=1.0,
+        x=X, y=np.zeros_like(X), z=Z
+    )
+
+"""
+
+from ._backend import D_calc, USE_JIT, _D_downwards, _D_upwards, _Lentz_Dn, _S1_S2, an_bn, cn_dn, pi_tau
+from ._backend import single_sphere, small_conducting_sphere, small_sphere
+
+from .core import efficiencies, intensities, i_par, i_per, i_unpolarized
+from .core import efficiencies_mx, S1_S2, phase_matrix, coefficients
+
+_FIELD_IMPORT_ERROR = None
+
+
+def _raise_field_import_error():
+    """Raise a consistent error when optional near-field dependencies are missing."""
+    raise ModuleNotFoundError(
+        "Near-field functions require the optional dependency 'scipy'. "
+        "Install miepython with SciPy support to use e_far/e_near/h_near/eh_near."
+    ) from _FIELD_IMPORT_ERROR
+
+
+def _missing_field_function(name):
+    """Create a placeholder near-field function when SciPy is unavailable."""
+
+    def _missing(*_args, **_kwargs):
+        _raise_field_import_error()
+
+    _missing.__name__ = name
+    _missing.__qualname__ = name
+    _missing.__doc__ = f"{name} requires the optional dependency 'scipy'."
+    return _missing
+
+
+try:
+    from . import field as _field
+except ModuleNotFoundError as exc:
+    missing_module = str(getattr(exc, "name", "") or "")
+    if missing_module.startswith("scipy"):
+        _FIELD_IMPORT_ERROR = exc
+        e_far = _missing_field_function("e_far")
+        e_near = _missing_field_function("e_near")
+        h_near = _missing_field_function("h_near")
+        eh_near = _missing_field_function("eh_near")
+        e_near_cartesian = _missing_field_function("e_near_cartesian")
+        h_near_cartesian = _missing_field_function("h_near_cartesian")
+        eh_near_cartesian = _missing_field_function("eh_near_cartesian")
+    else:
+        raise
+else:
+    e_far = _field.e_far
+    e_near = _field.e_near
+    h_near = _field.h_near
+    eh_near = _field.eh_near
+    e_near_cartesian = _field.e_near_cartesian
+    h_near_cartesian = _field.h_near_cartesian
+    eh_near_cartesian = _field.eh_near_cartesian
+
+# functions exposed to the user
+__all__ = (
+    "intensities",
+    "i_par",
+    "i_per",
+    "i_unpolarized",
+    "phase_matrix",
+    "coefficients",
+    "efficiencies",
+    "efficiencies_mx",
+    "e_far",
+    "e_near",
+    "h_near",
+    "eh_near",
+    "e_near_cartesian",
+    "h_near_cartesian",
+    "eh_near_cartesian",
+    "an_bn",
+    "cn_dn",
+    "S1_S2",
+    "single_sphere",
+    "small_sphere",
+    "small_conducting_sphere",
+    "USE_JIT",
+    "D_calc",
+    "pi_tau",
+    "_S1_S2",
+    "_Lentz_Dn",
+    "_D_upwards",
+    "_D_downwards",
+)
+
+__version__ = "3.2.0"
+__author__ = "Scott Prahl"
+__email__ = "scott.prahl@oit.edu"
+__copyright__ = "2017-2026, Scott Prahl"
+__license__ = "MIT"
+__url__ = "https://github.com/scottprahl/miepython.git"

miepython-3.2.0/miepython/_backend.py

@@ -0,0 +1,49 @@
+"""Select and expose the active low-level backend implementation.
+
+This module centralizes JIT vs no-JIT backend selection so other modules can
+import backend callables without importing ``miepython`` package root.
+"""
+
+import os
+
+USE_JIT = os.environ.get("MIEPYTHON_USE_JIT", "0") == "1"
+
+if USE_JIT:
+    from .mie_jit import _D_calc_nb as D_calc
+    from .mie_jit import _D_downwards
+    from .mie_jit import _D_upwards
+    from .mie_jit import _Lentz_Dn
+    from .mie_jit import _S1_S2_nb as _S1_S2
+    from .mie_jit import _an_bn_nb as an_bn
+    from .mie_jit import _cn_dn_nb as cn_dn
+    from .mie_jit import _pi_tau_nb as pi_tau
+    from .mie_jit import _single_sphere_nb as single_sphere
+    from .mie_jit import _small_conducting_sphere_nb as small_conducting_sphere
+    from .mie_jit import _small_sphere_nb as small_sphere
+else:
+    from .mie_nojit import _D_calc_py as D_calc
+    from .mie_nojit import _D_downwards
+    from .mie_nojit import _D_upwards
+    from .mie_nojit import _Lentz_Dn
+    from .mie_nojit import _S1_S2_py as _S1_S2
+    from .mie_nojit import _an_bn_py as an_bn
+    from .mie_nojit import _cn_dn_py as cn_dn
+    from .mie_nojit import _pi_tau_py as pi_tau
+    from .mie_nojit import _single_sphere_py as single_sphere
+    from .mie_nojit import _small_conducting_sphere_py as small_conducting_sphere
+    from .mie_nojit import _small_sphere_py as small_sphere
+
+__all__ = (
+    "USE_JIT",
+    "D_calc",
+    "an_bn",
+    "cn_dn",
+    "pi_tau",
+    "single_sphere",
+    "small_sphere",
+    "small_conducting_sphere",
+    "_S1_S2",
+    "_Lentz_Dn",
+    "_D_upwards",
+    "_D_downwards",
+)

{miepython-3.0.5 → miepython-3.2.0}/miepython/core.py

@@ -34,8 +34,7 @@ Normalized Mie scattering intensities for angles mu=cos(theta)::
 """
 
 import numpy as np
-from miepython import an_bn, cn_dn, single_sphere, _S1_S2
-
+from ._backend import _S1_S2, an_bn, cn_dn, single_sphere
 
 # not really needed but included for clarity
 __all__ = (
@@ -382,7 +381,7 @@ def i_per(m, x, mu, norm="albedo", n_pole=0):
     This function calculates the angular distribution of the scattered intensity from a sphere
     for incident light with its electric field vector perpendicular to the scattering plane
     (the plane defined by the incident direction and the scattered direction).
-    This corresponds to the |S₁(θ)|² term in Mie theory.
+    This corresponds to the :math:`|S₁(θ)|²` term in Mie theory.
 
     The result is normalized according to the specified method. The normalization affects
     the total integrated intensity over 4π steradians. Accepted normalization options include:
@@ -411,7 +410,7 @@ def i_par(m, x, mu, norm="albedo", n_pole=0):
     This function calculates the angular distribution of the scattered intensity from a sphere
     for incident light with its electric field vector parallel to the scattering plane
     (the plane defined by the incident direction and the scattered direction).
-    This corresponds to the |S₂(θ)|² term in Mie theory.
+    This corresponds to the :math:`|S₂(θ)|²` term in Mie theory.
 
     The result is normalized according to the specified method. The normalization affects
     the total integrated intensity over 4π steradians. Accepted normalization options include: