miepython 3.1.0__py3-none-any.whl → 3.3.0__py3-none-any.whl

miepython/__init__.py

@@ -42,6 +42,29 @@ The scattering matrix
 
     mie.phase_matrix(m, x, mu)
 
+Submodules
+----------
+
+``miepython.rayleigh`` is imported with the package and needs nothing beyond NumPy.
+It mirrors the API above using the small-sphere limit, which is handy for checking
+the full solution as x goes to zero::
+
+    mie.rayleigh.efficiencies_mx(1.5, 0.01)
+
+``miepython.vsh`` holds the vector spherical harmonics as a direct transcription of
+the textbook formulas.  It is a reference for development and cross-checking rather
+than a fast path, it requires the optional ``scipy`` dependency, and so it is bound
+only when scipy is installed::
+
+    mie.vsh.M_odd(1, k, d_sphere, r, theta, phi)
+
+``miepython.monte_carlo`` samples scattering angles from the Mie phase function.  It
+imports this package, so importing it from here would be circular; ask for it
+explicitly instead::
+
+    import miepython.monte_carlo as mc
+    mu, cdf = mc.mu_with_uniform_cdf(m, x, 100)
+
 Near-field calculations are provided by the ``miepython.field`` module::
 
     from miepython.field import e_near, h_near, eh_near
@@ -62,50 +85,69 @@ Example near-field usage::
 
 """
 
-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
-from .field import (
-    e_far,
-    e_near,
-    h_near,
-    eh_near,
-    e_near_cartesian,
-    h_near_cartesian,
-    eh_near_cartesian,
-)
 
-# functions exposed to the user
+from . import rayleigh
+
+_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
+    from . import vsh  # noqa: F401  reachable as miepython.vsh; needs scipy, so guarded here
+except ModuleNotFoundError as exc:
+    missing_module = str(getattr(exc, "name", "") or "")
+    if missing_module.startswith("scipy"):
+        _FIELD_IMPORT_ERROR = exc
+        # ``miepython.vsh`` is left unbound rather than stubbed out.  It is a
+        # reference implementation used for development and cross-checking, not part
+        # of the public surface, and every one of its functions needs scipy.
+        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
+
+# Names exposed to the user.  ``vsh`` is deliberately absent: it is bound only when
+# scipy is installed, and a star-import must not depend on that.
 __all__ = (
+    "rayleigh",
     "intensities",
     "i_par",
     "i_per",
@@ -127,15 +169,16 @@ __all__ = (
     "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.1.0"
+__version__ = "3.3.0"
 __author__ = "Scott Prahl"
 __email__ = "scott.prahl@oit.edu"
 __copyright__ = "2017-2026, Scott Prahl"

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__ = (
@@ -48,9 +47,28 @@ __all__ = (
     "S1_S2",
     "phase_matrix",
     "coefficients",
+    "wiscombe_terms",
+    "normalization_factor",
 )
 
 
+def wiscombe_terms(x):
+    """
+    Return the number of Mie series terms from Wiscombe's criterion.
+
+    The series is truncated after this many orders so that the summed scattering
+    quantities are accurate to about 1e-6.  The low-level ``an_bn`` and ``cn_dn``
+    kernels repeat this expression because numba cannot call back into Python.
+
+    Args:
+        x: the size parameter of the sphere
+
+    Returns:
+        number of terms, so orders 1 through the returned value
+    """
+    return int(x + 4.05 * x**0.33333 + 2.0)
+
+
 def coefficients(m, x, n_pole=0, internal=False):
     """
     Computes the Mie coefficients for a sphere.
@@ -74,30 +92,36 @@ def coefficients(m, x, n_pole=0, internal=False):
             calculate fields inside the sphere.
 
     Returns:
-        tuple:
-            - a (complex or array-like): The computed Mie coefficient A_n or an array of A_n values.
-            - b (complex or array-like): The computed Mie coefficient B_n or an array of B_n values.
+        ndarray: ``[a, b]``, or ``[a, b, c, d]`` when ``internal`` is True.  For
+            scalar ``m`` and ``x`` each entry is a 1-D array of coefficients, so
+            the result has shape ``(2, n_terms)`` or ``(4, n_terms)``.  For array
+            input each entry gains a leading axis over the spheres, giving
+            ``(2, n_spheres, n_pole)`` or ``(4, n_spheres, n_pole)``.
 
     Notes:
         - If the imaginary part of the refractive index is positive, it is
           automatically corrected to its conjugate value to ensure a valid input.
+        - Every returned coefficient is a real term; the arrays carry no padding.
 
     Examples:
         Compute coefficients for a single sphere:
-        >>> m = 1.5 - 0.1j
-        >>> x = 0.1
-        >>> mie_coefficients(m, x)
-        (array([3.33370015e-05+1.97363100e-04j, 1.77504613e-08+1.11834113e-07j,
-        4.60529820e-12+2.97368373e-11j, 1.58460985e-28+1.25881287e-14j]),
-        array([6.67296256e-08+2.75469444e-07j, 1.90474848e-11+7.86835968e-11j,
-        3.02615454e-15+1.24937186e-14j, 1.58460985e-28+1.25881287e-14j]))
-
-        Compute first multipoles for multiple spheres:
-        >>> m = [1.5 + 0.1j, 1.4 + 0.05j]
-        >>> x = [2.0, 1.8]
-        >>> mie_coefficients(m, x, 1)
-        (array([0.44794644+0.38665192j, 0.27813728+0.38495241j]),
-        array([0.5621083 +0.25504616j, 0.20206531+0.29589842j]))
+
+        >>> import miepython as mie
+        >>> a, b = mie.coefficients(1.5 - 0.1j, 0.1)
+        >>> len(a), len(b)
+        (3, 3)
+        >>> print(f"{a[0]:.6e}")
+        3.333700e-05-1.973631e-04j
+        >>> print(f"{b[0]:.6e}")
+        6.672963e-08-2.754694e-07j
+
+        Keep only the dipole term for each of several spheres:
+
+        >>> a, b = mie.coefficients([1.5 - 0.1j, 1.4 - 0.05j], [2.0, 1.8], n_pole=1)
+        >>> a.shape
+        (2, 1)
+        >>> print(f"{a[0, 0]:.6f}")
+        0.447946-0.386652j
     """
     mlen = np.size(m) if np.ndim(m) > 0 else 0
     xlen = np.size(x) if np.ndim(x) > 0 else 0
@@ -156,8 +180,11 @@ def efficiencies_mx(m, x, n_pole=0, e_field=True):
             - If 0 (default), computes contributions from all multipoles.
             - If non-zero, computes contributions from the specified multipole order.
         e_field (boolean):
-            If n_pole>0, then True value returns the electric
-            multipole contribution otherwise the Magnetic field contribution
+            When n_pole>0, selects which multipole of that order contributes:
+            True gives the electric multipole a_n, False the magnetic
+            multipole b_n. The two add up to the full order-n_pole
+            contribution for qext and qsca. Ignored when n_pole is 0.
+
     Returns:
         tuple:
             qext (float or array-like):
@@ -171,7 +198,8 @@ def efficiencies_mx(m, x, n_pole=0, e_field=True):
                 scattered in the exact backward direction (theta = 180 degrees).
             g (float or array-like):
                 Asymmetry parameter, representing the average cosine of the scattering
-                angle over all angles.
+                angle over all angles. This is exactly zero when n_pole > 0, because a
+                single multipole of one parity scatters symmetrically about 90 degrees.
 
     Notes:
         - Ensure m and x have compatible dimensions if passed as arrays.
@@ -181,19 +209,24 @@ def efficiencies_mx(m, x, n_pole=0, e_field=True):
           non-absorbing medium.
 
     Examples:
-        Compute efficiencies for a sphere with fixed parameters:
+        Compute efficiencies for one sphere:
 
         >>> import miepython as mie
-        >>> mie.efficiencies(1.5 - 0.01j, 2.0, 0)
-        (qext: 1.81, qsca: 1.72, qback: 0.27, g: 0.63)
+        >>> qext, qsca, qback, g = mie.efficiencies_mx(1.5 - 0.01j, 2.0)
+        >>> print(f"{qext:.6f} {qsca:.6f} {qback:.6f} {g:.6f}")
+        1.812597 1.724396 0.266214 0.630214
 
-        Compute efficiencies for wavelength-dependent refractive indices:
+        Compute efficiencies for a wavelength-dependent refractive index:
 
-        >>> import miepython as mie
+        >>> import numpy as np
         >>> m_array = np.array([1.5 - 0.01j, 1.45 - 0.02j])
         >>> x_array = np.array([2.0, 2.5])
-        >>> mie.efficiencies(m_array, x_array, 0)
-        (qext: [1.81, 2.15], qsca: [1.72, 1.95], qback: [0.27, 0.31], g: [0.63, 0.70])
+        >>> qext, qsca, qback, g = mie.efficiencies_mx(m_array, x_array)
+        >>> np.round(qext, 6)
+        array([1.812597, 2.14972 ])
+
+        Use :func:`efficiencies` instead when the diameter and wavelength are
+        known rather than the size parameter.
     """
     # ensure imaginary part of refractive index is negative
     if np.isscalar(m):
@@ -235,7 +268,12 @@ def efficiencies_mx(m, x, n_pole=0, e_field=True):
     return qext, qsca, qback, g
 
 
-def normalization_factor(m, x, norm_str):
+def _mie_efficiencies(m, x):
+    """Return the full Mie efficiencies, the default source for normalization."""
+    return single_sphere(m, x, 0, True)
+
+
+def normalization_factor(m, x, norm_str, efficiency_source=_mie_efficiencies):
     """
     Figure out scattering function normalization.
 
@@ -243,6 +281,10 @@ def normalization_factor(m, x, norm_str):
         m: complex index of refraction of sphere
         x: dimensionless sphere size
         norm_str: string describing type of normalization
+        efficiency_source: callable returning ``(qext, qsca, qback, g)`` for ``m``
+            and ``x``.  Defaults to the full Mie solution; ``miepython.rayleigh``
+            passes its own so that the two share these rules rather than keeping
+            a second copy of them.
 
     Returns:
         scaling factor needed for scattering function
@@ -260,7 +302,16 @@ def normalization_factor(m, x, norm_str):
         factor = x * np.sqrt(np.pi)
 
     else:
-        qext, qsca, _, _ = single_sphere(m, x, 0, True)
+        qext, qsca, _, _ = efficiency_source(m, x)
+
+        # every remaining choice divides by qext or qsca
+        if qext <= 0 or qsca <= 0:
+            raise ValueError(
+                "normalization %r needs a sphere that scatters, but qext=%g and qsca=%g. "
+                "A sphere of zero size, or one whose index matches its surroundings, has "
+                "no scattering to normalize against. Use norm='wiscombe', 'bohren' or "
+                "'qsca' if an unnormalized amplitude is what you want." % (norm_str, qext, qsca)
+            )
 
         if norm in ["a", "albedo"]:
             factor = x * np.sqrt(np.pi * qext)
@@ -298,9 +349,15 @@ def S1_S2(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m: the complex index of refraction of the sphere
         x: the size parameter of the sphere
-        mu: the angles, cos(theta), to calculate scattering amplitudes
+        mu: the angles, cos(theta), to calculate scattering amplitudes. A scalar,
+            list, tuple or array is accepted; a scalar is treated as one angle,
+            so the returned amplitudes are still length-one arrays.
         norm: (optional) string describing scattering function normalization
-        n_pole: return n_pole term from series (default=0 means include all terms)
+        n_pole: isolate a single multipole order, 1=dipole, 2=quadrupole,
+            3=octupole (default=0 means include all terms). Summing over
+            every order reproduces the full series, so n_pole uses the same
+            convention as `efficiencies_mx`. Orders beyond the truncated
+            series raise a ValueError.
 
     Returns:
         S1, S2: the scattering amplitudes at each angle mu [sr**(-0.5)]
@@ -308,11 +365,11 @@ def S1_S2(m, x, mu, norm="albedo", n_pole=0):
     if np.imag(m) > 0:  # ensure imaginary part of refractive index is negative
         m = np.conj(m)
 
-    if np.isscalar(mu):
-        mu_array = np.array([mu], dtype=float)
-        S1, S2 = _S1_S2(m, x, mu_array, n_pole)
-    else:
-        S1, S2 = _S1_S2(m, x, mu, n_pole)
+    # The numba kernel is declared for float64[:], so a list or an integer array
+    # would be rejected there while numpy accepted it.  Coercing here keeps both
+    # backends callable with exactly the same arguments.
+    mu_array = np.atleast_1d(np.asarray(mu, dtype=float))
+    S1, S2 = _S1_S2(m, x, mu_array, n_pole)
 
     normalization = normalization_factor(m, x, norm)
 
@@ -346,7 +403,9 @@ def phase_matrix(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m: the complex index of refraction of the sphere
         x: the size parameter of the sphere
-        mu: the angles, cos(theta), of the phase scattering matrix
+        mu: the angles, cos(theta), of the phase scattering matrix. Unlike the
+            other angular functions this one squeezes a single angle away, so a
+            scalar gives a bare 4x4 matrix rather than 4x4x1.
         n_pole: return n_pole term from series (default=0 means include all terms)
         norm: (optional) string describing scattering function normalization
 
@@ -391,7 +450,9 @@ def i_per(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m (complex): Complex index of refraction of the sphere.
         x (float): Size parameter of the sphere.
-        mu (array-like): Cosine of the scattering angle(s), cos(θ), for which intensity is desired.
+        mu (array-like): Cosine of the scattering angle(s), cos(θ), for which
+            intensity is desired. A scalar counts as one angle and yields a
+            length-one array, not a bare number.
         norm (str, optional): Normalization method for the scattered intensity. Default is 'albedo'.
         n_pole (int, optional): If greater than zero, returns only the nth multipole term;
             default is 0, which returns the sum of all terms.
@@ -420,7 +481,9 @@ def i_par(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m (complex): Complex index of refraction of the sphere.
         x (float): Size parameter of the sphere.
-        mu (array-like): Cosine of the scattering angle(s), cos(θ), for which intensity is desired.
+        mu (array-like): Cosine of the scattering angle(s), cos(θ), for which
+            intensity is desired. A scalar counts as one angle and yields a
+            length-one array, not a bare number.
         norm (str, optional): Normalization method for the scattered intensity. Default is 'albedo'.
         n_pole (int, optional): If greater than zero, returns only the nth multipole term;
             default is 0, which returns the sum of all terms.
@@ -450,7 +513,8 @@ def i_unpolarized(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m: the complex index of refraction of the sphere
         x: the size parameter
-        mu: the cos(theta) of each direction desired
+        mu: the cos(theta) of each direction desired. A scalar counts as one
+            direction and yields a length-one array, not a bare number.
         norm: (optional) string describing scattering function normalization
         n_pole (int, optional): If greater than zero, returns only the nth multipole term;
             default is 0, which returns the sum of all terms.