miepython 3.0.5__py3-none-any.whl → 3.2.0__py3-none-any.whl

miepython/__init__.py

@@ -42,41 +42,79 @@ 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
+    )
+
 """
 
-import os
-
-USE_JIT = os.environ.get("MIEPYTHON_USE_JIT", "0") == "1"
-
-if USE_JIT:
-    # pull in the jit‐compiled backends under the "private" names core.py expects
-    from .mie_jit import _an_bn_nb as an_bn
-    from .mie_jit import _cn_dn_nb as cn_dn
-    from .mie_jit import _single_sphere_nb as single_sphere
-    from .mie_jit import _small_sphere_nb as small_sphere
-    from .mie_jit import _small_conducting_sphere_nb as small_conducting_sphere
-    from .mie_jit import _pi_tau_nb as _pi_tau
-    from .mie_jit import _D_calc_nb as _D_calc
-    from .mie_jit import _S1_S2_nb as _S1_S2
-    from .mie_jit import _Lentz_Dn
-    from .mie_jit import _D_upwards
-    from .mie_jit import _D_downwards
-else:
-    from .mie_nojit import _an_bn_py as an_bn
-    from .mie_nojit import _cn_dn_py as cn_dn
-    from .mie_nojit import _single_sphere_py as single_sphere
-    from .mie_nojit import _small_sphere_py as small_sphere
-    from .mie_nojit import _small_conducting_sphere_py as small_conducting_sphere
-    from .mie_nojit import _pi_tau_py as _pi_tau
-    from .mie_nojit import _D_calc_py as _D_calc
-    from .mie_nojit import _S1_S2_py as _S1_S2
-    from .mie_nojit import _Lentz_Dn
-    from .mie_nojit import _D_upwards
-    from .mie_nojit import _D_downwards
+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",
@@ -87,23 +125,31 @@ __all__ = (
     "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",
-    "_D_calc",
-    "_pi_tau",
     "_Lentz_Dn",
     "_D_upwards",
     "_D_downwards",
 )
 
-__version__ = "3.0.5"
+__version__ = "3.2.0"
 __author__ = "Scott Prahl"
 __email__ = "scott.prahl@oit.edu"
-__copyright__ = "2017-26, Scott Prahl"
+__copyright__ = "2017-2026, Scott Prahl"
 __license__ = "MIT"
 __url__ = "https://github.com/scottprahl/miepython.git"

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/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: